hecks 0.2.0 → 0.3.0

data/lib/hecks/bluebook/translation.rb

@@ -0,0 +1,92 @@
+module Hecks
+  module Bluebook
+    # One field crossing a value-object boundary: a scalar becoming a VO
+    # member, a VO member becoming a scalar, or a rename across the move.
+    # Paths are dotted ("price.cents") for a VO member, bare otherwise.
+    TranslationMove = Struct.new(:from, :to)
+
+    # One field whose VALUE, not just its name or position, changed —
+    # an old value has nothing in common with a new one, so the only
+    # honest way to bridge it is a declared, exhaustive lookup table.
+    # Paths follow `TranslationMove`'s convention (dotted reaches a VO
+    # member); `values` maps every old-era value that can appear to its
+    # new-era replacement.
+    TranslationConvert = Struct.new(:from, :to, :values)
+
+    # A value object's or entity's own TYPE NAME changed with its member
+    # structure unchanged — the one drift `rename`/`move` cannot express,
+    # because the attribute kept its name and only the type it points at
+    # was renamed. Mirrors `was:` one level deeper.
+    TranslationRetype = Struct.new(:from, :to)
+
+    # A computed transform — rescale, reformat, split, merge — whose only
+    # implementation is the SQL expression itself, evaluated exclusively
+    # inside the compiled Postgres head. No in-process reference exists
+    # to check it against; any aggregate carrying one refuses to boot on
+    # every other adapter.
+    TranslationCompute = Struct.new(:from, :to, :sql)
+
+    # The aggregate's own IDENTITY changed what it's computed from — not
+    # a field crossing a boundary (that's `move`), a value objects's type
+    # name (`retype`), or a value transform (`compute`): the record's own
+    # key. No `from:`/`to:` path, unlike every other rule here, because
+    # nothing is being consumed from or moved into `state` — the state
+    # a record already holds is untouched; only what identifies it is
+    # recomputed. Same SQL-only, Postgres-only, no-in-process-reference
+    # shape `compute` already has, and for the same reason: there is
+    # nothing to check this against outside the compiled head.
+    TranslationRekey = Struct.new(:sql)
+
+    # A newly added, required attribute with no source in old data at
+    # all — not a rename, move, or convert, all of which need a FROM
+    # path in the old shape. `default` is the value an existing record
+    # reads until the next command against it writes a real one; unlike
+    # `compute`, this is adapter-agnostic — applied in-process by
+    # `Lineage#translate`, the same as rename/move/drop, because there is
+    # nothing to compute, only a value to declare.
+    TranslationBackfill = Struct.new(:name, :default)
+
+    # One aggregate's part of a translation: which attributes were
+    # renamed, moved, converted, or deliberately dropped on the way from
+    # the old era to the new one. `drops` exists so data loss is a
+    # declared decision, not a field that quietly stopped being
+    # explained.
+    class TranslationAggregate
+      attr_reader :name, :was, :renames, :moves, :converts, :drops, :retypes, :computes, :rekeys, :backfills
+
+      def initialize(name:, was: nil, renames: {}, moves: [], converts: [], drops: [], retypes: [],
+                     computes: [], rekeys: [], backfills: [])
+        @name      = name.to_s
+        @was       = was&.to_s
+        @renames   = renames
+        @moves     = moves
+        @converts  = converts
+        @drops     = drops
+        @retypes   = retypes
+        @computes  = computes
+        @rekeys    = rekeys
+        @backfills = backfills
+      end
+    end
+
+    # A declared map from one era of a domain's storage shape to the
+    # next. Renames and moves — the smallest slice that proves the
+    # concept: old records are translated when they are replayed, never
+    # rewritten. `retired` acknowledges aggregates that are gone
+    # outright — not renamed — so their disappearance is a decision,
+    # not an accident.
+    class Translation
+      attr_reader :domain, :from, :to, :aggregates, :retired
+
+      def initialize(domain:, from:, to:, aggregates: [], retired: [])
+        @domain     = domain.to_s
+        @from       = from
+        @to         = to
+        @aggregates = aggregates
+        @retired    = retired
+      end
+
+      def for_aggregate(name) = @aggregates.find { |aggregate| aggregate.name == name.to_s }
+    end
+  end
+end

data/lib/hecks/bluebook/value_object.rb

@@ -0,0 +1,58 @@
+require_relative "behaviour/value_object"
+
+module Hecks
+  module Bluebook
+    Invariant = Struct.new(:description, :canonical, :predicate, keyword_init: true)
+
+    # A value object — a DECLARATION HOLDER, never instantiated.
+    #
+    # `ValueObjectBuilder` returns an anonymous subclass whose singleton
+    # carries the declaration : attributes, invariants, members. Nothing ever
+    # calls `.new` on one — coercion builds `Runtime::Value` wrappers, and
+    # invariants run as canonical text through the Evaluator. The runtime
+    # reaches a shape through `aggregate.value_object(name)`, the IR's own
+    # finder ; there is no constant nesting and no second index.
+    #
+    # `to_h` does not move. It is a byte-for-byte contract pinned by the
+    # golden fixtures, so it keeps spelling the short declared name, which
+    # is what `hecks_name` carries. DECLARATIONS IN THE GRAPH, STRINGS IN THE
+    # EXPORT.
+    class ValueObject
+      extend Construct
+      # EXTENDED, not included — this construct is a class, so its
+      # emission is a class method. See Hecks::IR's own note on
+      # the two shapes.
+      extend Hecks::IR
+      extend Behaviour::ValueObject
+
+      emits_ir(
+        name:       :hecks_name,
+        attributes: many(:attributes),
+        invariants: -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        closed_set: :closed_set?,
+        members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value.to_s] } } }
+      )
+
+      class << self
+        attr_reader :attributes, :invariants, :members
+
+        # One declared shape — a subclass rather than an instance, so the thing
+        # the bluebook declares and the thing Ruby holds are one object.
+        def declare(name:, attributes: [], invariants: [], members: [], closed_set: !members.empty?)
+          shape = Class.new(self)
+          shape.hecks_name = name.to_s
+          shape.absorb(attributes: attributes, invariants: invariants,
+                       members: members, closed_set: closed_set)
+          shape
+        end
+
+        def absorb(attributes:, invariants:, members:, closed_set:)
+          @attributes = attributes
+          @invariants = invariants
+          @members    = members
+          @closed_set = closed_set
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook.rb

@@ -0,0 +1,74 @@
+# Hecks::Bluebook
+#
+# Everything a .bluebook file becomes on its way to running: the expression
+# language (expression/), the model itself (the chapter class plus
+# everything it declares), the assembly that turns
+# declarations back into that graph (assembly.rb + assembly/), the authoring
+# DSL (dsl/), and the meta-validator that judges a chapter against the
+# language's own grammar (meta_validator.rb + meta_validator/).
+#
+# The require order below preserves the boot order the flat list in
+# lib/hecks.rb used to spell: expression and IR first (pure
+# declarations), assembly's collaborators before its face, the DSL before
+# the meta-validator that its builders call at build time.
+
+module Hecks
+  # Declared as a CLASS, not a module — `Hecks::Bluebook` IS a
+  # chapter (bluebook/chapter.rb carries its body). Everything a chapter
+  # declares nests under it, as do the ways to build one (`DSL`) and to
+  # judge one (`MetaValidator`). Reopening this anywhere must say `class`.
+  module Bluebook
+  end
+end
+
+# What the chapter's own files lean on at class-body level (`extend
+# Construct`, the assembly's QuerySpecification marks) — required here
+# because those files' contents are frozen and cannot say so themselves.
+require_relative "construct"
+require_relative "literal"
+require_relative "query_specification"
+
+require_relative "bluebook/expression"
+# THE MODEL ITSELF — the chapter class's own body first, then everything
+# a chapter declares. Order matters only for reading: each is a bag of
+# declarations with no load-time cross-references.
+require_relative "bluebook/chapter"
+require_relative "bluebook/reference"
+require_relative "bluebook/attribute"
+require_relative "bluebook/value_object"
+require_relative "bluebook/command"
+require_relative "bluebook/lifecycle"
+require_relative "bluebook/query"
+require_relative "bluebook/read_model"
+require_relative "bluebook/entity"
+require_relative "bluebook/domain_port"
+require_relative "bluebook/policy"
+require_relative "bluebook/process_manager"
+require_relative "bluebook/aggregate"
+require_relative "bluebook/hexagon"
+require_relative "bluebook/translation"
+
+require_relative "bluebook/assembly/contract"
+require_relative "bluebook/assembly/contracts"
+require_relative "bluebook/assembly/specializer"
+require_relative "bluebook/assembly/build"
+require_relative "bluebook/assembly/marks"
+require_relative "bluebook/assembly/aggregate_assembly"
+require_relative "bluebook/assembly"
+
+require_relative "bluebook/project_loader"
+
+require_relative "bluebook/dsl"
+require_relative "bluebook/pattern_subset"
+
+require_relative "bluebook/meta_validator"
+require_relative "bluebook/meta_validator/plan"
+require_relative "bluebook/meta_validator/readings"
+require_relative "bluebook/meta_validator/judge"
+require_relative "bluebook/meta_validator/shapes"
+require_relative "bluebook/meta_validator/reconstruction"
+require_relative "bluebook/meta_validator/world_judge"
+require_relative "bluebook/meta_validator/port_judge"
+require_relative "bluebook/meta_validator/adapter_judge"
+require_relative "bluebook/meta_validator/translation_judge"
+require_relative "bluebook/meta_validator/syntax_boot"

data/lib/hecks/codemod.rb

@@ -0,0 +1,342 @@
+require_relative "bluebook/meta_validator"
+
+module Hecks
+  # SHARED MACHINERY for a codemod that migrates real `.bluebook` source
+  # once a DSL builder change makes some previously-required declaration
+  # optional/redundant — pulled out of `bin/codemod_implicit_append_fields`
+  # (the first one built), which needed three real, hard-won fixes before
+  # it could be trusted: a process-lifetime AST cache with no
+  # invalidation, a batch-revert granularity that let one unsafe
+  # candidate sink every other safe one sharing its boot, and (in the
+  # SPINE the codemod migrates FOR, not here) an append-at-end insertion
+  # that only round-tripped correctly for whichever field happened to be
+  # last. None of those are guessable in advance; they only surface by
+  # actually running a real edit against real self-hosted code. This
+  # module is that lesson, kept — the NEXT codemod plugs in two rule-
+  # specific procs (`find_candidates`, `apply_candidate`) and inherits
+  # the boot/safety-net machinery rather than rediscovering it.
+  #
+  # A CODEMOD IS NOT PATTERN-MATCHING ALONE. Deciding "is this line safe
+  # to delete" means knowing what the RUNTIME would resolve it to — so
+  # every codemod built on this module follows the same three steps:
+  #   1. Boot the real domain (or the self-hosted meta-domain) and read
+  #      its IR to find CANDIDATES — provided by the caller's own
+  #      `find_candidates`, since the actual redundancy rule is specific
+  #      to whichever spine change this migration serves.
+  #   2. Locate and remove each candidate's own source text — the
+  #      caller's own `apply_candidate`.
+  #   3. Re-boot from the edited text and diff the full IR export
+  #      against the pre-edit export. Byte-identical -> keep. Anything
+  #      else (including a RAISED exception — the self-hosted
+  #      meta-domain DISPATCHES itself into being, S14, so a bad edit
+  #      can surface as a runtime refusal, not just a differing export)
+  #      -> revert and report SKIPPED, never silently guessed past.
+  #
+  # DESIGN-TIME CHECKLIST for the SPINE change a future codemod migrates
+  # corpus text for — both items below are real bugs THIS module's own
+  # first use found, not hypothetical:
+  #   - Does the resolved value get inserted into an ORDER-SENSITIVE
+  #     list (the exported IR is array-order-sensitive throughout)? If
+  #     so, the spine's own insertion must preserve the ORIGINAL
+  #     position, not just append — an append-at-end insertion only
+  #     round-trips correctly for a value that already happened to be
+  #     last.
+  #   - Does resolution depend on ANOTHER construct already being
+  #     declared (the aggregate/entity a `sets`/`append:` field resolves
+  #     against)? If a creator command can be declared BEFORE the
+  #     construct it creates (real, live: `command "Handler"` before
+  #     `entity "Handler"`, one file down), one-pass resolution
+  #     genuinely cannot see it yet — not a codemod bug, a structural
+  #     limit worth naming rather than working around.
+  module Codemod
+    ROOT = File.expand_path("../..", __dir__)
+
+    EXAMPLE_ROOTS = Dir.glob(File.join(ROOT, "examples", "*")).select { |p| File.directory?(p) }.sort
+    META_FILES    = (Dir.glob(File.join(ROOT, "lib/hecks/grammar/*.bluebook")) +
+                      Dir.glob(File.join(ROOT, "lib/hecks/framework/bluebook/*.bluebook")) +
+                      Dir.glob(File.join(ROOT, "lib/hecks/language/bluebook/**/*.bluebook"))).sort
+
+    # THE SAME LIGHTWEIGHT PATH `spec/spec_helper.rb`'s own
+    # `boot_in_memory` uses — `Hecks.with_registry` satisfies
+    # `Hecks.bluebook`'s own `collect`'s "loaded outside a boot" check
+    # without `Hecks.boot`'s full era-check/adapter-wiring path, which
+    # needs a LIVE Postgres connection for `compliance` and would make
+    # every codemod depend on a database it has no reason to touch — a
+    # codemod only ever reads a chapter's own declared IR, never a
+    # stored record.
+    PERSISTENCE_PORT = File.join(ROOT, "lib/hecks/ports/persistence.port")
+    EXTRACTION_PORT  = File.join(ROOT, "lib/hecks/ports/extraction.port")
+    MEMORY_ADAPTER   = File.join(ROOT, "lib/hecks/adapters/driven/memory.adapter")
+    PRISM_ADAPTER    = File.join(ROOT, "lib/hecks/adapters/driven/prism.adapter")
+
+    def self.export_json(registry) = Hecks::Projector::Exporter.json(registry)
+
+    # `Hecks::Adapters::Prism` caches a file's parsed AST for the
+    # life of the PROCESS, keyed by path — fine for every existing
+    # caller (a file loads once per process: one `bin/ir` run, one
+    # rspec worker), but a codemod legitimately reloads the SAME path
+    # after editing it, and a stale cached tree reports a
+    # `given`/`ensures` block at its OLD line number, which no longer
+    # matches the freshly re-executed file's own `block.source_location`
+    # — surfacing as "did not survive extraction" on a perfectly valid
+    # file. `Prism.forget` is the real invalidation API this module's
+    # own first use motivated (found here, fixed at the source rather
+    # than left as a private `TREES.clear` poke from outside).
+    def self.load_bluebook(path)
+      paths = if path.is_a?(Array)
+                path
+              elsif File.directory?(path)
+                Dir.glob(File.join(path, "*.bluebook"))
+              else
+                [path]
+              end
+      paths.each { |file| Hecks::Adapters::Prism.forget(file) }
+
+      registry = Hecks::Runtime::Registry.new
+      Hecks.with_registry(registry) do
+        Kernel.load(PERSISTENCE_PORT)
+        Kernel.load(EXTRACTION_PORT)
+        Kernel.load(MEMORY_ADAPTER)
+        Kernel.load(PRISM_ADAPTER)
+        Hecks::Bluebook::MetaValidator.defer { paths.each { |file| Kernel.load(file) } }
+        Hecks::Bluebook::MetaValidator.judge_deferred!(registry)
+      end
+      registry
+    end
+
+    # `forget_all`, not a single `forget` — the meta-domain is NINE
+    # files (`MetaValidator::GRAMMAR_FILES`) merged into one registry,
+    # and a caller here (the codemod runner) doesn't generally know in
+    # advance which ONE it just edited.
+    def self.boot_meta
+      Hecks::Adapters::Prism.forget_all
+      Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
+      export_json(Hecks::Bluebook::MetaValidator.grammar_registry)
+    end
+
+    def self.meta_registry
+      Hecks::Adapters::Prism.forget_all
+      Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
+      Hecks::Bluebook::MetaValidator.grammar_registry
+    end
+
+    # Walks every aggregate (and every nested entity, recursively)
+    # across every chapter in a booted registry, yielding [owning
+    # construct, command] pairs — `construct` is whichever
+    # Aggregate/Entity actually OWNS the command, the same distinction
+    # `AggregateBuilder#command` vs `EntityBuilder#command` already
+    # draws. Generic enough for any rule that needs to walk real
+    # commands, not specific to the attribute-redundancy rule.
+    def self.each_command(registry)
+      registry.bluebooks.each_value do |chapter|
+        chapter.aggregates.each do |aggregate|
+          walk = lambda do |construct|
+            construct.commands.each { |command| yield construct, command }
+            construct.entities.each(&walk) if construct.respond_to?(:entities)
+          end
+          walk.call(aggregate)
+        end
+      end
+    end
+
+    def self.owner_attribute(construct, name)
+      construct.attributes.find { |attr| attr.name.to_s == name.to_s }
+    end
+
+    # A LIST attribute's own element construct — the value object or
+    # entity `list_of(...)` names, resolved by `hecks_name` the same way
+    # `AttributeCollector#resolve_identity_field!` already does. Shared
+    # because "what does this list actually hold" is a question any
+    # append-shaped rule needs answered, not just this one.
+    def self.element_construct_for(construct, list_field)
+      list_attr = owner_attribute(construct, list_field)
+      return nil unless list_attr&.list?
+
+      pool = construct.respond_to?(:value_objects) ? construct.value_objects.dup : []
+      pool.concat(construct.entities) if construct.respond_to?(:entities)
+      pool.find { |c| c.hecks_name.to_s == list_attr.type.to_s }
+    end
+
+    # Either a raised exception OR a differing export counts as unsafe
+    # — see the module header on why the meta-domain specifically can
+    # raise. Returns [value_or_nil, error_message_or_nil].
+    def self.safely
+      [yield, nil]
+    rescue StandardError => e
+      [nil, "#{e.class}: #{e.message}"]
+    end
+
+    # THE REUSABLE RUNNER — every real bug fix this module carries lives
+    # here, not in a caller's own script. A caller supplies:
+    #
+    #   find_candidates: ->(registry) { [...] }
+    #     Given a booted registry, return every CANDIDATE this rule
+    #     could migrate. A candidate is whatever shape the caller wants
+    #     — `apply_candidate` is the only other thing that reads it.
+    #
+    #   apply_candidate: ->(text, candidate) { [new_text, changed_bool] }
+    #     Given one file's current text and one candidate, return the
+    #     edited text and whether a match was actually found/removed —
+    #     `false` (text unchanged) when the candidate doesn't apply to
+    #     THIS file, which is how the meta-domain's multi-file search
+    #     below finds the right one without the caller needing to know
+    #     which file a candidate lives in ahead of time.
+    #
+    #   label: ->(candidate) { "..." }
+    #     One-line description for the results report.
+    class Runner
+      def initialize(find_candidates:, apply_candidate:, label:)
+        @find_candidates = find_candidates
+        @apply_candidate = apply_candidate
+        @label = label
+      end
+
+      def run(dry_run: false)
+        results = { applied: [], skipped: [], clean: [] }
+        run_example_domains(results, dry_run)
+        run_meta_domain(results, dry_run)
+        results
+      end
+
+      def report(results, dry_run:)
+        puts "== results (#{dry_run ? 'DRY RUN — nothing written' : 'applied'}) =="
+        puts "clean (no candidates): #{results[:clean].join(', ')}" unless results[:clean].empty?
+        results[:applied].each { |r| puts "APPLIED  #{r[:file]}: #{r[:candidates].join(', ')}" }
+        results[:skipped].each { |r| puts "SKIPPED  #{r[:file]} (#{r[:reason]}): #{Array(r[:candidates]).join(', ')}" }
+      end
+
+      private
+
+      def apply_many(text, candidates)
+        applied = []
+        candidates.each do |c|
+          text, changed = @apply_candidate.call(text, c)
+          applied << c if changed
+        end
+        [text, applied]
+      end
+
+      # The per-candidate write/verify/revert sequence below is one
+      # coherent unit (see the comment ahead of the candidates.each
+      # loop for why it can't batch) — splitting it across methods just
+      # to satisfy the line count would scatter state four ways for no
+      # readability gain.
+      # rubocop:disable-next Metrics/BlockLength
+      def run_example_domains(results, dry_run)
+        Codemod::EXAMPLE_ROOTS.each do |domain_dir|
+          bluebook_files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
+          next if bluebook_files.empty?
+
+          before_json = Codemod.export_json(Codemod.load_bluebook(bluebook_files))
+          candidates  = @find_candidates.call(Codemod.load_bluebook(bluebook_files))
+
+          if candidates.empty?
+            results[:clean] << domain_dir
+            next
+          end
+
+          live = bluebook_files.to_h { |file| [file, File.read(file)] }
+          applied_by_file = Hash.new { |hash, file| hash[file] = [] }
+
+          candidates.each do |candidate|
+            target_file = bluebook_files.find { |file| apply_many(live[file], [candidate]).last.any? }
+            unless target_file
+              results[:skipped] << { file: domain_dir, reason: "no matching source line", candidates: [@label.call(candidate)] }
+              next
+            end
+
+            original_text = live[target_file]
+            text, = apply_many(original_text, [candidate])
+            live[target_file] = text
+            File.write(target_file, text)
+            after_json, error = Codemod.safely do
+              Codemod.export_json(Codemod.load_bluebook(bluebook_files))
+            end
+
+            if after_json == before_json && !dry_run
+              applied_by_file[target_file] << candidate
+            elsif after_json == before_json
+              live[target_file] = original_text
+              File.write(target_file, original_text)
+              Codemod.safely { Codemod.load_bluebook(bluebook_files) }
+              applied_by_file[target_file] << candidate
+            else
+              live[target_file] = original_text
+              File.write(target_file, original_text)
+              Codemod.safely { Codemod.load_bluebook(bluebook_files) }
+              reason = error ? "reboot raised after edit (#{error}) — reverted" : "IR changed after edit — reverted"
+              results[:skipped] << { file: target_file, reason: reason, candidates: [@label.call(candidate)] }
+            end
+          end
+
+          applied_by_file.each do |file, applied|
+            results[:applied] << { file: file, candidates: applied.map(&@label) }
+          end
+        end
+      end
+
+      # PER-CANDIDATE, not one batched write-then-verify — the
+      # meta-domain is ONE shared registry (SyntaxBoot DISPATCHES it
+      # into itself, S14), so a single unsafe candidate among many would
+      # otherwise sink every OTHER, genuinely safe candidate in the same
+      # run: this module's first real run found exactly that (25
+      # candidates, one dispatch-time break, all 25 reverted as a batch
+      # before this per-candidate loop existed). `before_meta` stays the
+      # fixed reference throughout — a truly safe candidate never
+      # changes the IR, so the running state's own export should always
+      # still equal the pristine original after each kept edit, by
+      # definition, no moving target needed.
+      def run_meta_domain(results, dry_run)
+        before_meta     = Codemod.boot_meta
+        meta_candidates = @find_candidates.call(Codemod.meta_registry)
+
+        if meta_candidates.empty?
+          results[:clean] << "meta-domain"
+          return
+        end
+
+        live_meta = Codemod::META_FILES.to_h { |f| [f, File.read(f)] }
+        applied_by_file = Hash.new { |h, k| h[k] = [] }
+
+        meta_candidates.each do |candidate|
+          target_file = Codemod::META_FILES.find { |f| apply_many(live_meta[f], [candidate]).last.any? }
+          unless target_file
+            results[:skipped] << { file: "meta-domain", reason: "no matching source line", candidates: [@label.call(candidate)] }
+            next
+          end
+
+          text, = apply_many(live_meta[target_file], [candidate])
+          original_text = live_meta[target_file]
+          live_meta[target_file] = text
+          Codemod::META_FILES.each { |f| File.write(f, live_meta[f]) }
+
+          # DRY RUN STILL VERIFIES — see run_example_domains' own
+          # comment; the edit is always written and rebooted for real,
+          # then always reverted afterward when dry-run (whether or not
+          # it was safe) so the next candidate is judged against the
+          # true original state, never an accumulated hypothetical.
+          after_meta, error = Codemod.safely { Codemod.boot_meta }
+
+          if after_meta == before_meta && !dry_run
+            applied_by_file[target_file] << candidate
+          elsif after_meta == before_meta # dry-run, safe — revert, but count as applied
+            live_meta[target_file] = original_text
+            File.write(target_file, original_text)
+            Codemod.safely { Codemod.boot_meta }
+            applied_by_file[target_file] << candidate
+          else
+            live_meta[target_file] = original_text
+            File.write(target_file, original_text)
+            Codemod.safely { Codemod.boot_meta } # restore cache/memoized state to the reverted text
+            reason = error ? "reboot raised (#{error})" : "IR changed"
+            results[:skipped] << { file: "meta-domain", reason: reason, candidates: [@label.call(candidate)] }
+          end
+        end
+
+        applied_by_file.each do |file, candidates|
+          results[:applied] << { file: file, candidates: candidates.map(&@label) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/construct.rb

@@ -0,0 +1,71 @@
+module Hecks
+  # The invisible field a built construct carries.
+  #
+  # A construct is a RECORD WITH AN OWNER CHAIN — the chapter (Bluebook)
+  # owns its aggregates, an aggregate owns everything declared on it — and the
+  # bluebook identity is carried in its own field, under a `hecks_` prefix that
+  # no domain attribute can collide with. Invisible means exactly that: not an
+  # attribute, not a key in `to_h`, not a reader on instances. Framework
+  # metadata about the construct, not part of the domain it describes.
+  #
+  # The identity is COMPUTED by walking owners rather than stamped, so nothing
+  # has to be re-stamped when a chapter is assembled after its aggregates:
+  #
+  #     Pizzas                     the chapter — no owner
+  #     Pizzas::Pizza              an aggregate joins its chapter with ::
+  #     Pizzas::Pizza.Price        everything else joins its owner with .
+  #
+  # That spelling is not invented here. It is the id `MetaValidator::Judge`
+  # already mints in `#identify`, so a construct and the meta-domain's
+  # record OF that construct carry the same identity, and there is no
+  # translation table between them to be quietly wrong in.
+  #
+  # Usage:
+  #
+  #     price = Class.new(ValueObject)   # a declaration holder
+  #     price.hecks_name  = "Price"
+  #     price.hecks_owner = pizza_ir         # the Aggregate that declares it
+  #     price.hecks_fqn                      # => "Pizzas::Pizza.Price"
+  module Construct
+    # A construct asked for an identity it cannot compute.
+    class Unowned < StandardError; end
+
+    # What declares this one — the chapter above an aggregate, the aggregate
+    # above a value object. nil for a chapter, which is the top.
+    attr_accessor :hecks_owner
+
+    attr_writer :hecks_name
+
+    # A chapter is the only construct that legitimately has no owner. Everything
+    # else is DECLARED IN something, so a missing owner is an unstamped construct
+    # rather than a top — see hecks_fqn.
+    attr_writer :hecks_root
+
+    def hecks_root? = @hecks_root ? true : false
+
+    # The name as the bluebook declares it, never the constant path.
+    def hecks_name = @hecks_name
+
+    # How this construct joins its owner. An aggregate is a member of its
+    # chapter's namespace (`::`) ; everything else is declared ON its owner
+    # (`.`). Overridden by Aggregate, defaulted here for every other construct.
+    def hecks_separator = "."
+
+    # REFUSES rather than guesses. A construct with no owner and no claim to be a
+    # chapter has simply not been stamped yet — entity commands are in that state
+    # while entities are still IR objects — and answering the bare name would be a
+    # plausible half-truth that no test would notice. That shape of falsehood is
+    # what this repo keeps finding, so it goes red instead.
+    def hecks_fqn
+      return hecks_name.to_s if hecks_root?
+
+      unless hecks_owner
+        raise Construct::Unowned,
+              "#{hecks_name.inspect} cannot say what declares it, so it has no " \
+              "identity — it was never stamped with an owner"
+      end
+
+      "#{hecks_owner.hecks_fqn}#{hecks_separator}#{hecks_name}"
+    end
+  end
+end