hecks 2.8.0 → 2.9.0

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

@@ -8,52 +8,23 @@ require_relative "expected_era"
 
 module Hecks
   module Runtime
-    # The boot-time era gate, run for the adapters that have eras — the
-    # lineage-capable ones. An era is a fact about stored data that some
-    # adapter can carry across a shape change; an adapter that cannot
-    # translate has no era to hold, and holding one for it would record
-    # history about data nothing can act on.
-    #
-    # The whole domain is handed to the capable adapter's own era check
-    # (Postgres: hold, recognize, mint, or refuse toward the scaffold),
-    # which keeps its era facts as rows beside its data. That
-    # co-location is load-bearing — a watermark only means something
-    # against the journal it was cut from, and an approval recorded
-    # anywhere but the reviewed database binds to nothing.
-    #
-    # The capability is asked of the adapter, never of its name: a
-    # second adapter that grows an era story declares lineage_capable?
-    # and era_check! and needs no change here.
-    #
-    # Detection and identity are separate jobs: this check never hashes
-    # anything — era names come from the store, already minted (by the
-    # scaffold) or absent. Refusal wordings are contract, pinned by the
-    # corpus.
+    # The boot-time era gate for lineage-capable adapters (Postgres today):
+    # each capable adapter's own era_check! decides hold, recognize, mint, or refuse.
     module EraCheck
       module_function
 
       # Runs both halves of the era gate over every bluebook in a registry.
       #
-      # Each bluebook's own source, not one file read once and reused
-      # for every bluebook in the registry — true as long as a domain
-      # directory only ever held exactly one, and silently wrong the
-      # moment `uses_framework` made a second, differently-sourced
-      # bluebook (Governance, Identity — `lib/hecks/framework/bluebook/`,
-      # not the domain's own directory) share a boot with the first.
-      # Caught the hard way: three domains booted together, one real
-      # source text (the domain's own), and every other domain's era-1
-      # held that text under its own name — a shadow-parse of it later
-      # reconstructs a completely different shape, and every boot after
-      # the first refuses toward a scaffold that was never the real
-      # drift.
+      # Looks up each bluebook's own source separately: `uses_framework` can share a boot between
+      # the domain's own bluebook and a differently-sourced one, so one file read once and reused
+      # for every bluebook would attribute the wrong text.
       #
       # @param registry [Runtime::Registry] the registry being booted
-      # @param directory [String] path of the domain's own bluebook directory, searched for
-      #   each bluebook's `.bluebook` source
+      # @param directory [String] the domain's bluebook directory, searched for each source
       # @return [void]
-      # @raise [Runtime::WiringError] if a compute rule is bound to an adapter that is not
-      #   lineage-capable, a persistence binding cannot be resolved, a lineage-bound bluebook
-      #   has no findable source, or the adapter's own `era_check!` refuses the boot
+      # @raise [Runtime::WiringError] if a compute rule is bound to a non-lineage-capable adapter,
+      #   a persistence binding cannot be resolved, a lineage-bound bluebook has no findable
+      #   source, or `era_check!` refuses the boot
       def check!(registry, directory)
         check_compute_rules_for_registry!(registry)
         check_lineage!(registry, directory)
@@ -61,12 +32,8 @@ module Hecks
 
       # Refuses the boot when any bluebook's compute rule is bound away from Postgres.
       #
-      # The domain-agnostic half, split out for ADR 0031's boot-gate
-      # registry: a compute rule requires Postgres whatever adapter is
-      # actually bound, so this must run for every registry, the same way
-      # `registry.verify!` does — it is not conditional on any adapter
-      # being lineage-capable, and must never be skipped by
-      # `check_lineage!`'s own capability gate below.
+      # Runs unconditionally for every registry, unlike check_lineage!'s
+      # capability-gated pass below (ADR 0031).
       #
       # @param registry [Runtime::Registry] the registry whose bluebooks are all checked
       # @return [void]
@@ -78,11 +45,8 @@ module Hecks
 
       # Hands every bluebook, with its own source text, to its adapter's era check.
       #
-      # The capability-gated half — ADR 0031's registered `:era_check`
-      # gate. Registration is conditional on `lineage_capable_registry?`;
-      # `check_bluebook!` below still carries its own per-bluebook
-      # `lineage_capable?` return-early, unchanged, for a registry with a
-      # mix of lineage-capable and plain-adapter bluebooks.
+      # Capability-gated (ADR 0031): check_bluebook! below still returns
+      # early for any bluebook whose own binding isn't lineage-capable.
       #
       # @param registry [Runtime::Registry] the registry being booted
       # @param directory [String] path of the domain's own bluebook directory
@@ -98,12 +62,9 @@ module Hecks
 
       # Decides whether a registry binds anything that carries eras.
       #
-      # The `:era_check` gate's own registration predicate: true iff at
-      # least one bluebook's own anchor (first) aggregate resolves to a
-      # lineage-capable adapter — mirrors `check_bluebook!`'s existing
-      # per-bluebook anchor check, just asked once, up front, of the
-      # whole registry, so a registry with nothing lineage-capable bound
-      # anywhere never registers the gate at all.
+      # Mirrors check_bluebook!'s own per-bluebook anchor check, asked
+      # once up front so a registry with nothing lineage-capable never
+      # registers the `:era_check` gate at all.
       #
       # @param registry [Runtime::Registry] the registry whose bluebooks are asked
       # @return [Boolean] true when some bluebook's first aggregate is bound to a
@@ -121,51 +82,15 @@ module Hecks
 
       # Reads the source text one bluebook was declared in, wherever that source lives.
       #
-      # The domain's own directory first, matched by name — a real app's
-      # directory may hold more than one file once `uses_framework`
-      # exists, so ".first" alone cannot be trusted, the exact
-      # way it silently wasn't the day this was found: three domains
-      # booted together, one real source text read once (the domain's
-      # own, ".first"'d), and every other domain's era-1 held that text
-      # under its own name — a later shadow-parse of it reconstructs a
-      # completely different shape, and every boot after the first
-      # refuses toward a scaffold that was never the real drift.
-      #
-      # A single-file directory whose one file names something else
-      # falls back to it anyway (a fixture may legitimately name its
-      # file differently from the `Hecks.bluebook` it declares) — unless
-      # this bluebook is a known framework member or a vendored
-      # embryonaut bluebook (see `vendored_source_for` below), in which
-      # case that one file is certainly some other domain's, not this
-      # one's, and the real registry is asked instead — the only other
-      # two places a bluebook in this registry could have come from, per
-      # `uses_framework` and `uses_embryonaut_bluebook`.
-      #
-      # The bug this guards against, found live: `Framework.members` was
-      # the only exclusion checked here, so a domain attaching a
-      # vendored bluebook instead (`uses_embryonaut_bluebook`, which has
-      # no equivalent registry — see embryonaut_bluebook.rb's own
-      # header) fell straight through the single-file fallback: a
-      # directory holding exactly one `.bluebook` file (the target
-      # domain's own) handed that same text back for the vendored
-      # bluebook's era check too. PostgresEra minted era 1 for the
-      # vendored domain with the target's own source stamped as its
-      # `held_text` — the label computed from it, too — so the very
-      # next boot re-derived the vendored domain's real shape, found it
-      # didn't match what got (wrongly) stored, and refused to boot
-      # toward a scaffold for drift that never actually happened.
-      # `registry:` is what lets this check the one thing
-      # `Framework.members` cannot: whether some hecksagon in this
-      # registry declared `uses_embryonaut_bluebook` for this exact
-      # bluebook name, the same way `EmbryonautBluebook.load!` itself
-      # already resolves the vendored package's own directory.
+      # Matched by declared name, not position: a domain directory using
+      # `uses_framework` may hold more than one file, and a framework
+      # member or vendored bluebook is excluded from the single-file
+      # fallback so its own real source is read, not a sibling's.
       #
       # @param bluebook [Bluebook::Chapter] the bluebook whose source is wanted
       # @param directory [String] path of the domain's own bluebook directory
-      # @param registry [Runtime::Registry, nil] the registry asked whether some hecksagon
-      #   vendored this bluebook; nil skips the vendored lookup
-      # @return [String, nil] the UTF-8 text of every matching file joined with `"\n"`; nil
-      #   when no source file could be found
+      # @param registry [Runtime::Registry, nil] nil skips the vendored-bluebook lookup
+      # @return [String, nil] UTF-8 text of every matching file joined with `"\n"`, or nil
       def source_text_for(bluebook, directory, registry: nil)
         domain_files = Dir[File.join(directory, "*.bluebook")]
         own = domain_files.select { |path| declares_bluebook?(path, bluebook.name) }
@@ -190,13 +115,8 @@ module Hecks
 
       # Picks the files to read for a bluebook no file in the domain directory declares.
       #
-      # Only reached once nothing in the domain's own directory actually
-      # declares this bluebook by name. Three remaining sources, in
-      # order: a genuinely single-file domain directory whose one file
-      # just happens to name something else (but only when this
-      # bluebook isn't already known to come from somewhere else
-      # entirely — the exact guard the bug below was missing half of);
-      # a framework member; a vendored embryonaut bluebook.
+      # Tries, in order: the domain's own single remaining file, a framework member, then a
+      # vendored embryonaut bluebook.
       #
       # @param bluebook [Bluebook::Chapter] the bluebook whose source is wanted
       # @param directory [String] path of the domain's own bluebook directory
@@ -222,13 +142,8 @@ module Hecks
 
       # Recovers the vendored package name behind a bluebook, if some hecksagon vendored it.
       #
-      # The name `uses_embryonaut_bluebook` was actually called with —
-      # recovered from whichever hecksagon in this registry recorded it
-      # (`HecksagonBuilder#uses_embryonaut_bluebook`'s own
-      # `@vendored_bluebooks`), matched the same way
-      # `EmbryonautBluebook.load!` itself decides idempotency: the
-      # vendored name Pascal-cases to this bluebook's own declared name.
-      # Nil for an ordinary bluebook nothing ever vendored.
+      # Matched by Pascal-casing: the vendored name Pascal-cases to this
+      # bluebook's own declared name.
       #
       # @param registry [Runtime::Registry] the registry whose hecksagons are searched
       # @param bluebook_name [String] the bluebook's declared Pascal-case name
@@ -244,17 +159,9 @@ module Hecks
 
       # Lists the `.bluebook` files a vendored embryonaut package ships.
       #
-      # The same path `EmbryonautBluebook.load!` itself resolves from —
-      # `<registry.root>/vendor/embryonaut_bluebooks/<name>/bluebook/`,
-      # rebuilt here from `directory` (the domain's own bluebook
-      # directory, always `registry.root`'s immediate child — see
-      # `Runtime::Loader.boot`) rather than threading `registry.root`
-      # through as a second parameter. Every `.bluebook` file the
-      # package ships, in the same `Dir.glob` order actually loaded at
-      # boot time — order matters here because this text is later
-      # re-parsed whole (`EraCheck::shadow`) to reconstruct the shape a
-      # held era claims, and that reconstruction must see the files in
-      # the order that actually built the live shape.
+      # Listed in `Dir.glob` order, matching load order at boot, since a
+      # later reconstruction of this text depends on seeing files in the
+      # order that built the live shape.
       #
       # @param directory [String] path of the domain's own bluebook directory, whose parent
       #   holds `vendor/embryonaut_bluebooks`
@@ -269,16 +176,12 @@ module Hecks
 
       # Hands one bluebook to its adapter's `era_check!`, when that adapter carries eras.
       #
-      # The bluebook's first aggregate is the anchor: its binding alone decides
-      # which adapter is asked, and a bluebook with no aggregates, or one bound
-      # to an adapter that is not lineage-capable, is skipped without a word.
+      # The first aggregate is the anchor: its binding alone decides the adapter asked.
       #
       # @param registry [Runtime::Registry] the registry being booted
       # @param bluebook [Bluebook::Chapter] the bluebook to check
-      # @param current_text [String, nil] the bluebook's source, as `source_text_for` found
-      #   it; nil means no source file was found
-      # @param directory [String, nil] the domain's bluebook directory, named in the
-      #   missing-source refusal and passed through to the adapter
+      # @param current_text [String, nil] the bluebook's source; nil means none was found
+      # @param directory [String, nil] the domain's bluebook directory, named in the refusal
       # @return [void]
       # @raise [Runtime::WiringError] if the first aggregate's binding cannot be resolved,
       #   `current_text` is nil for a lineage-bound bluebook, or the adapter's `era_check!`
@@ -305,10 +208,8 @@ module Hecks
 
       # Refuses the boot when one bluebook's compute rule is bound away from Postgres.
       #
-      # The per-rule capability gate — not an era fact, and so it
-      # survives on every adapter: a compute rule's SQL is its only
-      # implementation, so an aggregate carrying one cannot boot
-      # anywhere but Postgres, whatever any shape comparison would say.
+      # A compute rule's SQL is its only implementation, so it cannot
+      # boot on any adapter but Postgres, independent of shape checks.
       #
       # @param registry [Runtime::Registry] the registry holding the declared translations
       #   and the aggregate's bindings
@@ -343,17 +244,13 @@ module Hecks
 
       # Asks a named adapter whether it carries eras.
       #
-      # The capability idiom: an adapter class that answers
-      # lineage_capable? with true carries eras and may act on drift
-      # (translate, fork, merge). Postgres alone does today; the seam is
-      # what lets a second one arrive without touching this file.
+      # Postgres alone answers true today; the seam lets a second
+      # lineage-capable adapter arrive without touching this file.
       #
       # @param registry [Runtime::Registry] the registry whose `adapters` must list the name
       # @param adapter_name [String] the adapter's name, as `adapter_for` returns it
-      # @return [Boolean] the adapter's own `lineage_capable?` answer; false when the registry
-      #   does not list the adapter, the adapter does not respond to `lineage_capable?`, or
-      #   any `StandardError` is raised on the way (including an adapter with no Ruby
-      #   implementation)
+      # @return [Boolean] the adapter's own answer; false if unlisted, not lineage-capable, or
+      #   any `StandardError` is raised
       def lineage_capable?(registry, adapter_name)
         adapter_class = registry.adapters[adapter_name] && registry.adapter_class(adapter_name)
         adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?

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

@@ -1,37 +1,18 @@
 module Hecks
   module Runtime
     module EraGuard
-      # The pure half: computing an aggregate's structural signature and
-      # diffing two eras' shapes. No file I/O — everything here answers
-      # from the IR it is handed, which is why the Postgres mint path can
-      # call it too.
+      # Structural signature and diff of aggregate shapes, computed from the IR alone
+      # (no file I/O), so the Postgres mint path can call it too.
       module ShapeDiff
-        # Computes an aggregate's structural signature, for comparing two eras of it.
-        #
-        # @param aggregate [Bluebook::Aggregate] the aggregate to describe
-        # @return [Array<Array>] one `[name, signature]` pair per attribute, sorted by name;
-        #   `name` is a Symbol and `signature` is whatever `attribute_signature` returns
+        # Structural signature of an aggregate: sorted `[name, signature]` pairs per attribute.
         def shape(aggregate)
           aggregate.attributes.map do |attribute|
             [attribute.name, attribute_signature(aggregate, attribute.type)]
           end.sort_by(&:first)
         end
 
-        # Expands a declared type into a signature that exposes its members.
-        #
-        # A plain type name for a primitive; `[type_name, member_signatures]`
-        # for a value object or entity, walked recursively — so two
-        # attributes with the same declared type name but a different
-        # internal shape are never mistaken for unchanged.
-        #
-        # @param aggregate [Bluebook::Aggregate] the aggregate whose value objects and entities
-        #   are searched for `type_name`
-        # @param type_name [String, Bluebook::Reference] the attribute's declared type
-        # @param seen [Array<String, Bluebook::Reference>] types already being expanded, which
-        #   stops a self-referencing type from recursing forever
-        # @return [String, Bluebook::Reference, Array] `type_name` itself for a primitive, a
-        #   reference, or a type already in `seen`; otherwise `[type_name, members]`, where
-        #   `members` is an Array of `[member_name, signature]` pairs sorted by member name
+        # Expands a declared type so same-named types with different members never compare equal.
+        # Primitives and references come back as-is; `seen` stops self-referencing types.
         def attribute_signature(aggregate, type_name, seen = [])
           container = nested_type(aggregate, type_name)
           return type_name if container.nil? || seen.include?(type_name)
@@ -42,42 +23,13 @@ module Hecks
           [type_name, members]
         end
 
-        # Looks a type name up among an aggregate's value objects, then its entities.
-        #
-        # @param aggregate [Bluebook::Aggregate] the aggregate to search
-        # @param type_name [String, Bluebook::Reference] the declared type to find
-        # @return [Bluebook::ValueObject, Bluebook::Entity, nil] the matching declaration; nil
-        #   when the type is a primitive, a reference, or nothing this aggregate declares
         def nested_type(aggregate, type_name)
           aggregate.value_object(type_name) || aggregate.entities.find { |entity| entity.name == type_name }
         end
 
-        # Lists the new attributes that would leave an existing record with a required gap.
-        #
-        # Attributes present now that the held shape never had — the
-        # addition side of drift, which `uncovered_attributes` below never
-        # looks at, since it only walks the held shape (vanish/retype).
-        # Most additions are free (ADR 0025, "Added attributes and
-        # absence"): a default:, a list_of (frozen []), or a value object
-        # whose fields all default fill an existing record automatically
-        # via `Instance.hydrate_with_defaults`. Only the fourth case — a
-        # non-optional attribute with no way to fill itself — can leave an
-        # existing record with the field genuinely absent, and that is
-        # what this reports: unfilled by a declared translation's own
-        # `backfill`, or by a move/convert that lands an old field inside
-        # this brand-new attribute (`Lineage#fills?` — the destination-
-        # side question, never `explains?`'s source-side one, since a
-        # rename from Crate to Bin can introduce a top-level attribute
-        # name that never existed to have "vanished").
-        #
-        # @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 lineage [Ports::Persistence::Lineage, nil] the edge's rules for this aggregate; nil
-        #   when the edge declares none, so nothing can fill an addition
-        # @return [Array<Symbol>] names of new, non-optional attributes with no default, no
-        #   list cardinality, no fully-defaulted value object and no rule filling them; `[]`
-        #   when every addition is safe
+        # Names of new, non-optional attributes that no default, list, defaulted value object
+        # or translation rule (`Lineage#fills?`) can fill on an existing record.
+        # Destination-side check: a rename can add a name that never existed to "vanish".
         def unsafe_additions(aggregate, held_aggregate, lineage)
           held_names = held_aggregate.attributes.map(&:name)
 
@@ -88,17 +40,7 @@ module Hecks
                    .map(&:name)
         end
 
-        # Decides whether a new attribute could be genuinely absent from an existing record.
-        #
-        # The four-row table, as a predicate over the fourth row only — the
-        # other three (default:, list_of, a fully-defaulted value object)
-        # all fill an existing record for free and never reach here.
-        #
-        # @param aggregate [Bluebook::Aggregate] the aggregate declaring the attribute, searched
-        #   for the value object its type may name
-        # @param attribute [Bluebook::Attribute] the newly added attribute
-        # @return [Boolean] false when the attribute is optional, has a default, is a list, or
-        #   is a value object whose every field has a default; true otherwise
+        # True when a new attribute could be genuinely absent from an existing record (ADR 0025).
         def possibly_absent?(aggregate, attribute)
           return false if attribute.optional?
           return false unless attribute.default.nil?
@@ -110,24 +52,8 @@ module Hecks
           true
         end
 
-        # Lists the held paths that vanished or changed type with no rule explaining them.
-        #
-        # Paths the translation needs to explain: attributes that vanished
-        # by name, attributes that kept their name but changed type (a
-        # `convert` is what lets that be declared at all), and — recursing
-        # into a same-named, same-typed value object — its own members
-        # vanishing or changing type one level down, reported as a dotted
-        # path ("price.currency"). A pure addition, at any depth, never
-        # needs covering; only vanish-or-retype does, matching the
-        # top-level rule at every depth.
-        #
-        # @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 lineage [Ports::Persistence::Lineage, nil] the edge's rules for this aggregate; nil
-        #   when the edge declares none, so every vanished or retyped path is reported
-        # @return [Array<String>] bare attribute names and dotted member paths such as
-        #   `"price.currency"`; `[]` when the whole diff is explained
+        # Held attribute paths that vanished or changed type with no rule explaining them,
+        # recursing into value objects as dotted paths ("price.currency"). Additions never count.
         def uncovered_attributes(aggregate, held_aggregate, lineage)
           paths = held_aggregate.attributes.flat_map do |held_attribute|
             current_attribute = aggregate.attribute(held_attribute.name)
@@ -142,38 +68,12 @@ module Hecks
         end
 
         # Compares one path's held and current types, recursing into shared members.
-        #
-        # `held_type`/`current_type` are type names, resolved against each
-        # side's own value_object and entity declarations — neither is ever
-        # nested in the DSL, only in the type graph, so both are always
-        # looked up flat off their respective aggregate. A `list_of` entity
-        # is only reached here to detect a member vanish-or-retype; there is
-        # no per-element translation machinery yet (`move`/`convert`/`drop`
-        # only reach into a single nested hash, not each element of an
-        # array) — the only way to satisfy a refusal on an entity path
-        # today is a top-level `drop` of the whole list attribute, which
-        # `explains?` already recognizes as covering everything nested
-        # under it. Blunt, but loud beats silent.
-        #
-        # @param path [String] the bare or dotted path being compared, reported on a mismatch
-        # @param held_type [String, Bluebook::Reference] the type the held era declares there
-        # @param current_type [String, Bluebook::Reference] the type declared there now
-        # @param held_aggregate [Bluebook::Aggregate] the held aggregate, searched for
-        #   `held_type`'s declaration
-        # @param aggregate [Bluebook::Aggregate] the current aggregate, searched for
-        #   `current_type`'s declaration
-        # @param lineage [Ports::Persistence::Lineage, nil] the edge's rules, asked whether a retype
-        #   pairs the two type names; nil means no retype is accepted
-        # @param seen [Array<String, Bluebook::Reference>] current types already being
-        #   expanded, which stops a self-referencing type from recursing forever
-        # @return [Array<String>] `[path]` when the types differ with no retype declared; the
-        #   dotted paths of members that vanished or changed type beneath it; `[]` when
-        #   nothing differs or either type is not a value object or entity
+        # A `list_of` entity is diffed only for member drift; no per-element translation exists, so
+        # only a top-level `drop` of the whole list satisfies it.
         def diff_type(path, held_type, current_type, held_aggregate, aggregate, lineage, seen = [])
           if held_type != current_type
-            # A declared retype says the two type names mean the same shape
-            # — accept the pair, but still recurse into the members so a
-            # member drift hiding beneath the rename is caught by name.
+            # A declared retype accepts the pair but members are still compared, so drift
+            # hidden under the rename is caught.
             return [path] unless lineage&.retype?(held_type, current_type)
           end
           return [] if seen.include?(current_type)

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

@@ -6,23 +6,8 @@ require_relative "../../../../runtime/registry"
 
 module Hecks
   module Runtime
-    # The shape-drift coverage primitives — ADR 0032. Not a driver: nothing
-    # here walks a registry or reads/writes a held snapshot on its own.
-    # `PostgresEra::LineageManager::CoverageCheck` calls `uncovered_
-    # attributes`/`unsafe_additions`/`refuse_uncovered!`/`refuse_unsafe_
-    # addition!`/`check_vanished_aggregates!` directly, per translation
-    # edge, over its own DB-held shapes; `Translation::Reattest` and
-    # `PostgresEra::LineageManager` call `shadow_parse` directly, to read
-    # historical bluebook text under old grammar defaults. Both are real,
-    # independent, currently-shipped consumers.
-    #
-    # There is deliberately no top-level `check!`/`check_bluebook!` here
-    # walking a registry and reading/writing a held snapshot under
-    # `data/eras/*.bluebook`: it would duplicate, on its own, the same
-    # per-aggregate walk `CoverageCheck` already performs against
-    # `PostgresEra`'s own DB-held shapes, and nothing in production would
-    # call it — an unwired driver is not kept, per ADR 0032. If one is
-    # wanted, it is built informed by `CoverageCheck`'s real orchestration.
+    # Shape-drift coverage primitives (ADR 0032). Not a driver: callers own
+    # walking a registry and reading/writing held snapshots; nothing here does either.
     module EraGuard
       extend ShapeDiff
 
@@ -30,20 +15,16 @@ module Hecks
 
       # Refuses the boot when a held aggregate is gone and no translation says where it went.
       #
-      # An aggregate that existed in the held text and answers to no
-      # current name — renamed silently, with nothing declaring `was:` to
-      # explain where its data went — is exactly the disease this guards
-      # against, and a plain per-aggregate diff would never see it: the
-      # current aggregate simply has no held counterpart to compare to.
+      # A held aggregate matching no current name has no counterpart for a
+      # plain per-aggregate diff to compare against; only a `was:` or
+      # `retired` translation can explain it.
       #
-      # @param registry [Runtime::Registry] the registry whose declared translations are
-      #   searched for a `was:` or a `retired` entry naming the held aggregate
+      # @param registry [Runtime::Registry] the registry searched for a `was:`/`retired` entry
       # @param bluebook [Bluebook::Chapter] the bluebook booting now
       # @param held_bluebook [Bluebook::Chapter] the bluebook parsed from the held era's text
       # @return [void]
-      # @raise [Runtime::WiringError] if a held aggregate matches no current aggregate by
-      #   name, no current aggregate's translation declares it as `was:`, and no translation
-      #   for this domain retires it
+      # @raise [Runtime::WiringError] if a held aggregate matches no current aggregate, no
+      #   `was:` declares it, and no translation retires it
       def check_vanished_aggregates!(registry, bluebook, held_bluebook)
         held_bluebook.aggregates.each do |held_aggregate|
           claimed = bluebook.aggregates.any? do |aggregate|
@@ -125,65 +106,16 @@ module Hecks
         end
       end
 
-      # Parses held source into its own IR, in a scratch registry so a past
-      # era's text never touches the one actually booting.
+      # Parses held source into its own IR, in a throwaway registry.
       #
-      # Normal parse first, shadow only as a fallback — never shadow-parsing
-      # unconditionally. A handful of DSL
-      # defaults fork on `MetaValidator.shadow_parsing?` for a reason
-      # that has nothing to do with syntax the live grammar cannot
-      # read at all (`identified_by { }`, `belongs_to`, `has_one`,
-      # `has_many` — genuinely removed spellings, exactly what shadow-
-      # parsing exists to keep readable): `reference_to`'s own default
-      # mint name (`default_reference_name`, attribute_collector.rb)
-      # is bare under ADR 0025 and `_id`-suffixed under shadow mode, and
-      # that fork applies even to text using nothing but current, live
-      # syntax. Held text minted under the current grammar — every real
-      # era in this corpus today, since nothing has ever minted a second
-      # one — parses fine normally; under unconditional shadow mode only
-      # the reference-naming default differs, so it silently
-      # reconstructs a different shape (and hash) than a fresh parse of
-      # the identical text — the same text hashing two different ways
-      # depending on which code path read it, breaking `ensure_named!`'s
-      # own from/to edge lookup with a spurious "no translation edge
-      # covers it" refusal that has nothing to do with any real
-      # translation gap.
-      #
-      # A normal parse can only ever succeed on text the live grammar
-      # fully understands — there is no way for it to silently produce a
-      # wrong-but-plausible answer for genuinely legacy text, since every
-      # removed spelling refuses loudly (`Malformed`) rather than
-      # degrading. So: try normal first — if the ordinary grammar reads
-      # this text without complaint, that is the canonical, unambiguous
-      # interpretation, the same one `label_of`/`mint_hash` on the same
-      # source text always computes, whoever's asking. Only on a
-      # `Malformed` refusal — the one signal that actually means "this
-      # spelling is not in the live grammar" — fall back to the legacy
-      # grammar. Any other exception (a
-      # genuine syntax error, an unrelated validation refusal) propagates
-      # unchanged; swallowing it here to retry under shadow mode would
-      # risk masking a real defect in the held text behind a confusing
-      # second failure instead of the original, more specific one.
-      #
-      # `MetaValidator.while_shadow_parsing` (ADR 0025, docs/dsl-work-
-      # slices.md's S0a) is what makes the fallback a legacy grammar
-      # rather than just a second copy of today's: it stops
-      # `BluebookBuilder.build` from judging this text against the
-      # grammar as it stands now, which is the one thing that would make
-      # a removed spelling refuse history the day it is removed from
-      # live source. The scratch registry is throwaway either way —
-      # nothing here is dispatched against or exposed to the real one —
-      # so skipping the judge/assemble round-trip changes nothing this
-      # method reads: `shape`, `uncovered_attributes`, and friends only
-      # ever ask the built IR for its own structure.
+      # Tries the live grammar first, falling back to the shadow one only
+      # on `Malformed` — the one signal meaning "not in the live grammar"
+      # (ADR 0025); any other exception propagates unchanged.
       #
       # @param source [String] the held bluebook text to evaluate
-      # @param path [String] the file path the text is evaluated as, which the predicate
-      #   extractor reads from disk; callers pass a tempfile holding the same text
-      # @return [Bluebook::Chapter, nil] the first bluebook the text declares; nil when it
-      #   declares none
-      # @raise [Bluebook::DSL::Malformed] if the text parses under neither the live grammar
-      #   nor the legacy one
+      # @param path [String] the file path reported as the text's origin
+      # @return [Bluebook::Chapter, nil] the first bluebook declared; nil when it declares none
+      # @raise [Bluebook::DSL::Malformed] if neither grammar accepts the text
       # @raise [SyntaxError] if the text is not valid Ruby
       def shadow_parse(source, path)
         parse_bluebook(source, path, shadow: false)
@@ -196,7 +128,7 @@ module Hecks
       # @param source [String] the bluebook text to evaluate
       # @param path [String] the file path reported to `Kernel.eval` as the text's origin
       # @param shadow [Boolean] true evaluates inside `MetaValidator.while_shadow_parsing`
-      #   (the legacy grammar); false evaluates under the live grammar
+      #   (the shadow grammar); false evaluates under the live grammar
       # @return [Bluebook::Chapter, nil] the first bluebook the text registered in the scratch
       #   registry; nil when it declares none
       # @raise [Bluebook::DSL::Malformed] if the chosen grammar refuses the text

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

@@ -5,26 +5,11 @@ require_relative "storage_shape"
 
 module Hecks
   module Runtime
-    # The refusal wording for a held era whose digest does not match its
-    # frozen text — the digest mismatch alone is what detects tampering (a
-    # plain SHA256 comparison over raw bytes, unrelated to any of this);
-    # this only supplies the wording once that's already fired.
+    # Wording for the boot refusal when a held era's frozen text was
+    # edited after freezing (detected elsewhere via a digest mismatch).
     #
-    # Lives here, not under `Ports::Persistence` — `project` below directly
-    # calls `Runtime::EraGuard.shadow_parse`/`Runtime::StorageShape.project`
-    # (DSL-execution machinery), the "an adapter/port reaches into the
-    # runtime instead of being handed already-computed data" shape that
-    # has caused trouble here before. A capability this dependent on the
-    # runtime is a runtime-owned one that the Postgres adapter calls, not
-    # a ports-level module that happens to reach sideways into it.
-    #
-    # Every tamper refusal reaches the same generic wording, cosmetic edit
-    # or real shape change alike: telling the two apart by re-parsing the
-    # edited text is a pure quality-of-message nicety, not a safety
-    # property, and an edit that cannot be classified has to fall to the
-    # generic wording anyway. An operator judges "did this matter"
-    # themselves, reading the still-archived original — an anomalous
-    # recovery moment already, not a normal boot path.
+    # Lives here, not under `Ports::Persistence`, because `project` below
+    # calls runtime DSL-execution machinery (`EraGuard`, `StorageShape`) directly.
     module EraTamper
       module_function
 
@@ -40,12 +25,8 @@ module Hecks
 
       # Parses a bluebook text and returns its storage-shape projection.
       #
-      # The projection is JSON-normalized for structural comparison
-      # against a stored projection; nil when the text does not load.
-      # Always parsed through a fresh tempfile, never the held file's own
-      # path: the predicate extractor caches source by path, and a held
-      # path whose content has changed (the very situation this module
-      # exists for) would hand it stale lines.
+      # Always parsed from a fresh tempfile, never the held file's own path,
+      # since the predicate extractor caches source by path and would see stale lines there.
       #
       # @param text [String] the bluebook source to parse
       # @param _source_path [String, nil] ignored; the text is always parsed from a tempfile