hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,169 @@
+require_relative "../../../../ports/persistence"
+require_relative "../../../../ports/persistence/binding_policy"
+require_relative "lineage"
+require_relative "../../../../naming"
+require_relative "../../../../framework"
+require_relative "../../../../runtime/registry"
+
+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.
+    module EraCheck
+      module_function
+
+      # 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.
+      def check!(registry, directory)
+        check_compute_rules_for_registry!(registry)
+        check_lineage!(registry, directory)
+      end
+
+      # 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.
+      def check_compute_rules_for_registry!(registry)
+        registry.bluebooks.each_value { |bluebook| check_compute_rules!(registry, bluebook) }
+      end
+
+      # 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.
+      def check_lineage!(registry, directory)
+        registry.bluebooks.each_value do |bluebook|
+          check_bluebook!(registry, bluebook, source_text_for(bluebook, directory), directory: directory)
+        end
+      end
+
+      # 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.
+      def lineage_capable_registry?(registry)
+        registry.bluebooks.each_value.any? do |bluebook|
+          first = bluebook.aggregates.first
+          next false unless first
+
+          lineage_capable?(registry, adapter_for(registry, bluebook.name, first))
+        end
+      end
+
+      # 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 can no longer 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, in which case that
+      # one file is certainly some OTHER domain's, not this one's, and
+      # the framework registry is asked instead — the only other place a
+      # bluebook in this registry could have come from, per
+      # `uses_framework`.
+      def source_text_for(bluebook, directory)
+        domain_files = Dir[File.join(directory, "*.bluebook")]
+        own = domain_files.select do |path|
+          File.foreach(path, encoding: "UTF-8").any? { |line| line.match?(/\A\s*Hecks\.bluebook\s+#{Regexp.escape(bluebook.name.inspect)}/) }
+        end
+        own = domain_files if own.empty? && domain_files.size == 1 && !Framework.members.key?(bluebook.name)
+        own = [Framework.members[bluebook.name]].compact if own.empty?
+        return if own.empty?
+
+        own.map { |path| File.read(path, encoding: "UTF-8") }.join("\n")
+      end
+
+      def check_bluebook!(registry, bluebook, current_text, directory: nil)
+        first = bluebook.aggregates.first
+        return unless first
+
+        adapter_name = adapter_for(registry, bluebook.name, first)
+        return unless lineage_capable?(registry, adapter_name)
+
+        unless current_text
+          raise WiringError,
+                "cannot boot #{bluebook.name}: bound to a lineage-capable adapter, but no source file for " \
+                "it could be found (checked #{directory.inspect} and the framework registry)"
+        end
+
+        settings = registry.world(bluebook.name)&.for_binding(Ports::Persistence::VERB, adapter_name) || {}
+        registry.adapter_class(adapter_name).era_check!(
+          registry: registry, bluebook: bluebook, current_text: current_text, settings: settings,
+          directory: directory
+        )
+      end
+
+      # 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.
+      def check_compute_rules!(registry, bluebook)
+        bluebook.aggregates.each do |aggregate|
+          lineage = Ports::Persistence::Lineage.for(registry, bluebook.name, aggregate)
+          next unless lineage&.computes?
+
+          adapter = adapter_for(registry, bluebook.name, aggregate)
+          next if lineage_capable?(registry, adapter)
+
+          raise WiringError, "compute rules require the Postgres adapter; #{aggregate.name} is bound to #{adapter}"
+        end
+      end
+
+      def adapter_for(registry, domain, aggregate)
+        Ports::Persistence::BindingPolicy.resolve(registry, domain, aggregate).adapter
+      end
+
+      # 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.
+      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?
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+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.
+      module ShapeDiff
+        def shape(aggregate)
+          aggregate.attributes.map { |attribute|
+            [attribute.name, attribute_signature(aggregate, attribute.type)]
+          }.sort_by(&:first)
+        end
+
+        # 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.
+        def attribute_signature(aggregate, type_name, seen = [])
+          container = nested_type(aggregate, type_name)
+          return type_name if container.nil? || seen.include?(type_name)
+
+          members = container.attributes.map { |member|
+            [member.name, attribute_signature(aggregate, member.type, seen + [type_name])]
+          }.sort_by(&:first)
+          [type_name, members]
+        end
+
+        def nested_type(aggregate, type_name)
+          aggregate.value_object(type_name) || aggregate.entities.find { |entity| entity.name == type_name }
+        end
+
+        # Attributes present now that the held shape never had — the
+        # addition side of drift, which `uncovered_attributes` above 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").
+        def unsafe_additions(aggregate, held_aggregate, lineage)
+          held_names = held_aggregate.attributes.map(&:name)
+
+          aggregate.attributes
+                   .reject { |attribute| held_names.include?(attribute.name) }
+                   .select { |attribute| possibly_absent?(aggregate, attribute) }
+                   .reject { |attribute| lineage&.fills?(attribute.name.to_s) }
+                   .map(&:name)
+        end
+
+        # 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.
+        def possibly_absent?(aggregate, attribute)
+          return false if attribute.optional?
+          return false unless attribute.default.nil?
+          return false if attribute.list?
+
+          value_object = aggregate.value_object(attribute.type)
+          return false if value_object && value_object.attributes.all? { |field| !field.default.nil? }
+
+          true
+        end
+
+        # 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.
+        def uncovered_attributes(aggregate, held_aggregate, lineage)
+          paths = held_aggregate.attributes.flat_map do |held_attribute|
+            current_attribute = aggregate.attribute(held_attribute.name)
+            next [held_attribute.name.to_s] unless current_attribute
+
+            diff_type(held_attribute.name.to_s, held_attribute.type, current_attribute.type, held_aggregate, aggregate, lineage)
+          end
+
+          return paths unless lineage
+
+          paths.reject { |path| lineage.explains?(path) }
+        end
+
+        # `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.
+        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.
+            return [path] unless lineage&.retype?(held_type, current_type)
+          end
+          return [] if seen.include?(current_type)
+
+          held_container = nested_type(held_aggregate, held_type)
+          current_container = nested_type(aggregate, current_type)
+          return [] unless held_container && current_container
+
+          held_container.attributes.flat_map do |held_member|
+            current_member = current_container.attribute(held_member.name)
+            next ["#{path}.#{held_member.name}"] unless current_member
+
+            diff_type("#{path}.#{held_member.name}", held_member.type, current_member.type, held_aggregate, aggregate, lineage,
+                      seen + [current_type])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,161 @@
+require_relative "era_guard/shape_diff"
+require_relative "../../../../bluebook/dsl/malformed"
+require_relative "../../../../bluebook/meta_validator"
+require_relative "../../../../ports/loading"
+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.
+    #
+    # A prior version of this module ALSO drove its own top-level check —
+    # `check!`/`check_bluebook!`, walking a registry and reading/writing a
+    # held snapshot under `data/eras/*.bluebook` — duplicating, on its own,
+    # the same per-aggregate walk `CoverageCheck` already performs against
+    # `PostgresEra`'s own DB-held shapes. Nothing in production ever called
+    # it (only a direct unit spec did); deleted rather than kept unwired,
+    # per ADR 0032. Wanted again, it's rebuilt informed by `CoverageCheck`'s
+    # real orchestration, not resurrected from here.
+    module EraGuard
+      extend ShapeDiff
+
+      module_function
+
+      # 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.
+      def check_vanished_aggregates!(registry, bluebook, held_bluebook)
+        held_bluebook.aggregates.each do |held_aggregate|
+          claimed = bluebook.aggregates.any? do |aggregate|
+            aggregate.name == held_aggregate.name ||
+              registry.translations.any? do |translation|
+                translation.domain == bluebook.name &&
+                  translation.for_aggregate(aggregate.name)&.was == held_aggregate.name
+              end
+          end
+          claimed ||= registry.translations.any? do |translation|
+            translation.domain == bluebook.name && translation.retired.include?(held_aggregate.name)
+          end
+          next if claimed
+
+          raise WiringError,
+                "cannot boot #{bluebook.name}: #{held_aggregate.name} existed and now doesn't, " \
+                "and nothing declares was: #{held_aggregate.name.inspect} to explain where its data went."
+        end
+      end
+
+      # The Layer-1 coverage refusal — one wording, shared with whoever
+      # calls it (today, `PostgresEra::LineageManager::CoverageCheck`'s
+      # own mint-time coverage check).
+      def refuse_uncovered!(bluebook, aggregate, uncovered)
+        raise WiringError,
+              "cannot boot #{bluebook.name}::#{aggregate.name}: its shape changed and " \
+              "#{uncovered.map { |path| render_path(path) }.join(', ')} #{uncovered.size == 1 ? 'is' : 'are'} not " \
+              "explained by any rename, move, convert, retype, or drop. Update bluebook/translations/*.bluebook, e.g. " \
+              "#{suggestion(uncovered.first)}."
+      end
+
+      # The addition-side sibling of refuse_uncovered! above — same
+      # wording shape, different cause: nothing vanished or changed type,
+      # something new arrived that an existing record has no way to hold.
+      def refuse_unsafe_addition!(bluebook, aggregate, unsafe)
+        raise WiringError,
+              "cannot boot #{bluebook.name}::#{aggregate.name}: #{unsafe.map { |name| ":#{name}" }.join(', ')} " \
+              "#{unsafe.size == 1 ? 'is new and required' : 'are new and required'}, with no default: to fill " \
+              "an existing record and no translation explaining what one should read there. Give it a " \
+              "default:, make it optional: true or list_of, or declare bluebook/translations/*.bluebook, e.g. " \
+              "`backfill :#{unsafe.first}, default: ...`."
+      end
+
+      def render_path(path) = path.include?(".") ? path.inspect : ":#{path}"
+
+      def suggestion(path)
+        if path.include?(".")
+          "`move #{path.inspect}, to: #{path.inspect}` or `drop #{path.inspect}`"
+        else
+          "`rename :#{path}, to: :new_name` or `drop :#{path}`"
+        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.
+      #
+      # NORMAL PARSE FIRST, shadow only as a FALLBACK — not shadow-parsing
+      # unconditionally, which is what this used to do. A handful of DSL
+      # defaults fork on `MetaValidator.shadow_parsing?` for a reason
+      # that has NOTHING to do with syntax the live grammar can no longer
+      # 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)
+      # changed from `_id`-suffixed to bare under ADR 0025, 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; only the reference-naming DEFAULT differed
+      # once shadow mode engaged unconditionally, so it silently
+      # reconstructed 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 doesn't exist anymore" — fall back to the legacy
+      # grammar, exactly as before this change. 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.
+      def shadow_parse(source, path)
+        parse_bluebook(source, path, shadow: false)
+      rescue Hecks::Bluebook::DSL::Malformed
+        parse_bluebook(source, path, shadow: true)
+      end
+
+      def parse_bluebook(source, path, shadow:)
+        scratch = Registry.new
+        loading = Ports::Loading.bootstrap
+        run = lambda do
+          Hecks.with_registry(scratch) do
+            loading.load_library
+            Kernel.eval(source, TOPLEVEL_BINDING, path, 1)
+          end
+        end
+        shadow ? Hecks::Bluebook::MetaValidator.while_shadow_parsing(&run) : run.call
+        scratch.bluebooks.values.first
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+require "json"
+require "tempfile"
+require_relative "era_guard"
+require_relative "storage_shape"
+
+module Hecks
+  module Runtime
+    # The refusal wording for a held era whose digest no longer matches 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.
+    #
+    # 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.
+    #
+    # Used to also distinguish a cosmetic edit from a real shape change
+    # here, by re-parsing the edited text — a pure quality-of-message
+    # nicety, not a safety property, since dropped: every tamper refusal
+    # reaches the same generic wording now, the one this already fell to
+    # whenever it couldn't classify an edit anyway. An operator judges
+    # "did this matter" themselves,
+    # reading the still-archived original — an anomalous recovery moment
+    # already, not a normal boot path.
+    module EraTamper
+      module_function
+
+      def refusal(domain:, ordinal:)
+        "cannot boot #{domain}: the held text of era #{ordinal} was edited after it was frozen — " \
+          "held era texts are storage facts; restore the original text, or reset the data"
+      end
+
+      # The storage-shape projection of a bluebook text, 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.
+      def project(text, _source_path = nil)
+        file = Tempfile.new(["hecks-tamper-", ".bluebook"])
+        begin
+          file.write(text)
+          file.flush
+          bluebook = EraGuard.shadow_parse(text, file.path)
+        ensure
+          file.close!
+        end
+        return nil unless bluebook
+
+        JSON.parse(JSON.generate(StorageShape.project(bluebook)))
+      rescue StandardError, SyntaxError
+        nil
+      end
+    end
+  end
+end