hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,120 @@
+require "json"
+require "digest"
+
+module Hecks
+  module Runtime
+    # The storage-shape projection of a bluebook: exactly the parts of
+    # the IR that decide what persisted data looks like — aggregates,
+    # their attributes (with full value-object/entity structure and
+    # cardinality), references, the lifecycle field, and the identity
+    # paths. Everything behavioral — commands, invariants, queries,
+    # policies, lifecycle transitions, defaults, descriptions, comments,
+    # the declared routing `version:` — is excluded, so editing behavior
+    # never bumps an era and editing shape always does.
+    #
+    # Three attribute facts on the wire are constraints on PERSISTED
+    # VALUES, not behavior, and are still excluded — each decided, not
+    # overlooked:
+    #
+    #   `optional`  — required-ness is enforced at dispatch; stored rows
+    #                 are never re-validated on read, so flipping it
+    #                 strands nothing already written. Excluded.
+    #   `pattern`   — same argument: a fact about what may be WRITTEN
+    #                 next, not about what was stored. Excluded.
+    #   `admits`    — the sharpest of the three: narrowing a closed set
+    #                 CAN strand stored rows outside it, and the wire
+    #                 carries only the set's NAME, so a set whose members
+    #                 changed under a stable name is invisible even to a
+    #                 projection that included the fact (the same lesson
+    #                 recursive value-object drift taught). Excluded, and
+    #                 NAMED as a gap: constraint tightening has no
+    #                 translation-rule vocabulary to acknowledge it yet,
+    #                 so including it would mint era bumps nothing can
+    #                 explain. When the translation language grows a
+    #                 constraint-acknowledgment rule, `admits` (by member
+    #                 list, not by name) is first in line, and that
+    #                 change bumps FORM_VERSION.
+    #
+    # Projection runs over the canonical dump form (`to_h`, JSON
+    # round-tripped), so a verdict depends only on the IR — never on live
+    # object graphs. Structural comparison only, never a hash comparison.
+    module StorageShape
+      module_function
+
+      def project(bluebook)
+        domain = JSON.parse(JSON.generate(bluebook.to_h))
+        {
+          "name"       => bluebook.name,
+          "aggregates" => (domain["aggregates"] || [])
+                          .map { |aggregate| project_aggregate(aggregate) }
+                          .sort_by { |aggregate| aggregate["name"] }
+        }
+      end
+
+      def same?(held, current) = project(held) == project(current)
+
+      # The canonical serialization the Ruby scaffold hashes at MINT time
+      # — the one moment identity is computed. Nothing ever recomputes a
+      # stored era name to verify it, so this form can evolve freely.
+      def canonical(bluebook) = JSON.generate(project(bluebook))
+
+      def mint_hash(bluebook) = Digest::SHA256.hexdigest(canonical(bluebook))
+
+      LABEL_LENGTH = 6
+      def mint_label(bluebook) = mint_hash(bluebook)[0, LABEL_LENGTH]
+
+      # The version of the canonical serialization above. Minted-once
+      # means a stored name stays valid across form changes — but only
+      # if each name records WHICH form minted it, so v1-named and
+      # v2-named eras coexist legibly. Stored beside every minted hash
+      # (names.tsv fourth field / hecks_eras.canon_form); bump this in
+      # the same change that alters project/canonical output.
+      FORM_VERSION = 1
+
+      def project_aggregate(aggregate)
+        {
+          "name"            => aggregate["name"],
+          # The declared identity paths, AS A LIST, in declaration order —
+          # order is semantic (the paths join in order to form the id).
+          # No "id" fallback: an aggregate that declares nothing has [],
+          # and that is a real declared state, distinct from an aggregate
+          # identified by a field named "id".
+          "identity"        => Array(aggregate["identified_by"]).map(&:to_s),
+          "lifecycle_field" => aggregate.dig("lifecycle", "field"),
+          "attributes"      => (aggregate["attributes"] || [])
+                               .map { |attribute| project_attribute(aggregate, attribute, []) }
+                               .sort_by { |attribute| attribute["name"] }
+        }
+      end
+
+      def project_attribute(aggregate, attribute, seen)
+        {
+          "name" => attribute["name"].to_s,
+          "list" => attribute["list"] ? true : false,
+          "type" => type_signature(aggregate, attribute["type"].to_s, seen)
+        }
+      end
+
+      # A plain type name for a primitive; the type name plus its
+      # members' full signatures for a value object or entity — so two
+      # attributes with the same declared type name but different
+      # internals are never mistaken for unchanged.
+      def type_signature(aggregate, type_name, seen)
+        container = nested_type(aggregate, type_name)
+        return type_name if container.nil? || seen.include?(type_name)
+
+        {
+          "type"    => type_name,
+          "members" => (container["attributes"] || [])
+                       .map { |member| project_attribute(aggregate, member, seen + [type_name]) }
+                       .sort_by { |member| member["name"] }
+        }
+      end
+
+      def nested_type(aggregate, type_name)
+        (aggregate["value_objects"] || []).find { |vo| vo["name"] == type_name } ||
+          (aggregate["entities"] || []).find { |entity| entity["name"] == type_name }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+require "digest"
+require_relative "../../../../../../projector/exporter"
+
+module Hecks
+  module Translation
+    module Audit
+      # ── the human gate, made real ──────────────────────────────────
+      #
+      # For the five portable rule kinds the mint verifies the edge
+      # mechanically (Layer 2 IS the cross-execution equivalence gate).
+      # A compute has no mechanical verification — the Layer-3 sample a
+      # human reads is the only one there is — so a compute edge cannot
+      # mint until someone has run `bin/translation_audit … --approve`.
+      #
+      # The approval binds to WHAT WAS ACTUALLY REVIEWED, on both axes:
+      # a content digest of the parsed edge (change the edge's meaning
+      # and the approval lapses; a comment does not), and the journal's
+      # high-water ordinal at review time, recorded IN the target
+      # database — a token in the repo could not bind to the data, and
+      # samples reviewed against staging or against production-as-of-T
+      # say nothing about a database that has moved on. Mint stays
+      # non-interactive and its lock stays short; the human decision
+      # happens in the audit tool, where the samples are.
+      module ApprovalDigest
+        def edge_digest(edge)
+          Digest::SHA256.hexdigest(JSON.generate(Projector::Exporter.translation_hash(edge)))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+require_relative "../../../../../../runtime/errors"
+require_relative "../../../../../../runtime/instance"
+require_relative "../../../../../../runtime/value/invariant_violation"
+require_relative "../../../../../../bluebook/model_check"
+
+module Hecks
+  module Translation
+    module Audit
+      # Layer 1 — from the bluebook alone: every translated state must
+      # pass the new era's types, value-object invariants, and lifecycle.
+      # This is also where a NEW, stricter invariant that old records
+      # violate surfaces — there is no "grandfather old records"
+      # construct, and the remedy is relaxing the invariant or explicit
+      # remediation, never a translation rule.
+      module LayerOne
+        def layer_one!(violations, aggregate, after)
+          after.each do |id, state|
+            begin
+              symbolized = JSON.parse(JSON.generate(state), symbolize_names: true)
+              instance = Runtime::Instance.new(aggregate: aggregate, id: id, state: symbolized)
+              lifecycle = aggregate.lifecycle
+              next unless lifecycle
+
+              held = instance[lifecycle.field]
+              # `Lifecycle#states` answers default+targets only — a state
+              # legitimately declared just as a `from:` (a terminal
+              # transition's source, never anyone's target) is real and
+              # reachable but invisible to it. `ModelCheck.full_states`
+              # is the full declared set (default, every target, AND
+              # every from) that `fuzzing/properties.rb`'s own replay
+              # check already uses for this identical question — see its
+              # comment on this same hole.
+              allowed = Bluebook::ModelCheck.full_states(lifecycle)
+              unless held.nil? || allowed.include?(held.to_s)
+                violations << "#{aggregate.name}##{id}: #{lifecycle.field} is #{held.inspect}, " \
+                              "a state this era's lifecycle never reaches"
+              end
+            rescue Runtime::InvariantViolation, Runtime::TypeMismatch => error
+              violations << "#{aggregate.name}##{id}: #{error.message}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+require_relative "../../../../../../ports/persistence/append_only"
+require_relative "../../lineage"
+
+module Hecks
+  module Translation
+    module Audit
+      # Layer 2 — from the edge alone: per-rule value preservation, no
+      # leftover source keys, and id-set conservation across the edge.
+      module LayerTwo
+        # Per-rule value preservation and leftover source keys are checked
+        # against the reference transform IN FULL — never rule by rule in
+        # isolation, because rules interact (a rename whose value a later
+        # move partially consumes preserves exactly what the transform
+        # says it preserves, no more). This makes every mint a run of the
+        # cross-execution equivalence gate for the five portable rule
+        # kinds: the compiled SQL produced `after`; the port's entry-JSON
+        # transform produces `expected`; they must agree byte-for-byte on
+        # every path a compute doesn't own. Compute paths are exempt — the
+        # SQL is their only implementation, and the Layer-3 sample is
+        # their only review. A rekeyed aggregate is exempt from this WHOLE
+        # per-record check, for the same reason and one more: there is no
+        # old-id → new-id correspondence to look `after` up by once the id
+        # itself is what changed.
+        def layer_two!(violations, aggregate, declared, before, after)
+          rekeyed = declared && !declared.rekeys.empty?
+
+          # A rekey legitimately changes the id SET (that's the entire
+          # point) — set-equality would flag every honest rekey as data
+          # loss. What must still hold is RECORD COUNT: a botched rekey
+          # colliding two distinct old ids onto one new id, or dropping one
+          # (its SQL returning NULL), shows up as the count going down —
+          # caught here without needing to track the old→new mapping
+          # itself.
+          if rekeyed
+            unless before.keys.size == after.keys.size
+              violations << "#{aggregate.name}: the record count changed across a rekeying edge " \
+                            "(#{before.keys.size} before, #{after.keys.size} after) — a rekey must not " \
+                            "collide two distinct ids onto one, or drop one"
+            end
+          elsif before.keys.sort != after.keys.sort
+            gained = after.keys - before.keys
+            lost = before.keys - after.keys
+            violations << "#{aggregate.name}: the id set changed across the edge " \
+                          "(lost #{lost.sort.inspect}, gained #{gained.sort.inspect})"
+          end
+          return unless declared
+          # No correspondence between an old id and its rekeyed row exists
+          # in Ruby (the rekey's SQL is its only implementation, same as
+          # compute's) — exempt from the per-record equivalence gate for
+          # the same reason compute paths already are, extended to the
+          # whole record since an old-id lookup into `after` can never
+          # succeed once the id itself has changed.
+          return if rekeyed
+
+          rules = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
+          compute_paths = declared.computes.flat_map { |compute| [compute.from, compute.to] }.map(&:to_s)
+
+          before.each do |id, state|
+            next unless after.key?(id)
+
+            entry = Ports::Persistence::Entry.new(operation: "save", id: id, state: state.transform_keys(&:to_sym))
+            expected = strip_compute_paths(normalize(rules.translate(entry).state), compute_paths)
+            actual = strip_compute_paths(normalize(after[id]), compute_paths)
+            next if expected == actual
+
+            diverged = (expected.keys | actual.keys).select { |key| expected[key] != actual[key] }
+            violations << "#{aggregate.name}##{id}: the translated state diverges from the reference " \
+                          "transform at #{diverged.sort.join(', ')}"
+          end
+        end
+
+        def normalize(state) = JSON.parse(JSON.generate(state))
+
+        # Exempts exactly the paths a compute owns, not the whole
+        # top-level attribute it happens to live under. A bare path
+        # ("price_cents") is itself the compute's entire value — dropping
+        # the whole top-level key is correct, there's nothing else there
+        # to check. A DOTTED path ("price.cents") only owns that one
+        # member of the value object it reaches into; every sibling
+        # member (e.g. "price.currency") is untouched by the compute and
+        # must stay subject to the equivalence check below. Blanket-
+        # dropping the whole top-level key for a dotted compute used to
+        # exempt the entire attribute — silent data loss elsewhere in the
+        # same value object (a migration that nulls or drops a sibling
+        # field) produced zero violations, defeating the one gate whose
+        # entire purpose is to catch exactly that.
+        def strip_compute_paths(state, paths)
+          paths.each do |path|
+            segments = path.split(".")
+            if segments.length == 1
+              state.delete(segments.first)
+            else
+              parent = segments[0..-2].reduce(state) { |node, segment| node.is_a?(Hash) ? node[segment] : nil }
+              parent.delete(segments.last) if parent.is_a?(Hash)
+            end
+          end
+          state
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+module Hecks
+  module Translation
+    module Audit
+      # New-era attributes that nothing feeds: absent from every
+      # translated state, produced by no rule, and carrying no default.
+      # A report, not a violation — the remedy is a `default:` on the
+      # attribute, and the loud refusal for a REQUIRED one comes from
+      # Layer 1 the moment an invariant reads it.
+      module UnfedReport
+        def unfed(aggregate, declared, after)
+          fed = if declared
+                  (declared.renames.values.map(&:to_s) +
+                   declared.moves.map(&:to) +
+                   declared.converts.map(&:to) +
+                   declared.computes.map(&:to)).map { |path| path.to_s.split(".").first }
+                else
+                  []
+                end
+          aggregate.attributes.filter_map do |attribute|
+            name = attribute.name.to_s
+            next if fed.include?(name)
+            next unless attribute.default.nil?
+            next if after.any? { |_, state| !dig_path(state, name).nil? }
+            next if after.empty?
+
+            name
+          end
+        end
+
+        def dig_path(state, path)
+          return nil if state.nil?
+
+          path.to_s.split(".").reduce(state) do |node, segment|
+            break nil unless node.is_a?(Hash)
+
+            # `key?` decides which spelling answers, never `||` — a
+            # `false` genuinely held at this path must not fall through
+            # to the other spelling (usually absent) and read as `nil`,
+            # which would wrongly mark a `false`-valued attribute "unfed".
+            node.key?(segment) ? node[segment] : node[segment.to_sym]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+require "json"
+
+require_relative "audit/layer_one"
+require_relative "audit/layer_two"
+require_relative "audit/unfed_report"
+require_relative "audit/approval_digest"
+
+module Hecks
+  module Translation
+    # The audit derives its assertions; nobody hand-lists them. One file
+    # per layer beside this one: audit/layer_one.rb (the bluebook's own
+    # rules), audit/layer_two.rb (the edge against the reference
+    # transform), audit/unfed_report.rb (what nothing feeds), and
+    # audit/approval_digest.rb (the human gate's binding). Layer 3 — the
+    # before/after sample a HUMAN approves, intent not being derivable —
+    # is assembled right here in `check`.
+    module Audit
+      Verdict = Struct.new(:violations, :dropped, :unfed, :samples, keyword_init: true) do
+        def ok? = violations.empty?
+      end
+
+      SAMPLE_SIZE = 5
+
+      extend LayerOne
+      extend LayerTwo
+      extend UnfedReport
+      extend ApprovalDigest
+
+      module_function
+
+      # aggregate — the CURRENT era's IR; declared — this edge's rules
+      # for it (may be nil); before/after — {id => state hash}, source
+      # era's latest vs translated.
+      def check(aggregate:, declared:, before:, after:)
+        violations = []
+
+        layer_one!(violations, aggregate, after)
+        layer_two!(violations, aggregate, declared, before, after)
+
+        Verdict.new(
+          violations: violations,
+          dropped:    declared ? declared.drops.map(&:to_s) : [],
+          unfed:      unfed(aggregate, declared, after),
+          samples:    samples_for(declared, before, after)
+        )
+      end
+
+      def samples_for(declared, before, after)
+        return rekeyed_samples(before, after) if declared && !declared.rekeys.empty?
+
+        before.keys.sort.first(SAMPLE_SIZE).map { |id| { id: id, before: before[id], after: after[id] } }
+      end
+
+      # A rekey changes the id itself, so `before`'s and `after`'s
+      # keyspaces share nothing — pairing by matching id (the ordinary
+      # path above) would show every `after` as nil, telling a human
+      # nothing. Nothing in-process can compute the old→new
+      # correspondence either (the rekey's SQL is its only
+      # implementation, same as compute's own). Shown side by side
+      # instead, each labelled by its OWN id: real records going in,
+      # real records coming out — not claimed to correspond one-to-one,
+      # but enough for the human this rule's only verification depends
+      # on to actually see real shapes and values, not a wall of null.
+      def rekeyed_samples(before, after)
+        before.keys.sort.first(SAMPLE_SIZE).map { |id| { id: "#{id} (before)", before: before[id], after: nil } } +
+          after.keys.sort.first(SAMPLE_SIZE).map { |id| { id: "#{id} (after)", before: nil, after: after[id] } }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+require "tempfile"
+require_relative "../era_guard"
+require_relative "../../../../../runtime/registry"
+require_relative "../storage_shape"
+
+module Hecks
+  module Translation
+    # The question re-attestation must answer before anything else: did
+    # the edit change the era's SHAPE, or only its text? Cosmetic edits
+    # (comments, whitespace, behavior) re-freeze safely; a shape change
+    # would retroactively redefine what era N *meant* for data already
+    # written under it, and refuses hard — there is no --accept past
+    # this guard.
+    #
+    # This does not violate minted-once. That prohibition exists so
+    # boot-time RECOGNITION never depends on canonicalization stability;
+    # this is operator-initiated repair, where a false negative is a
+    # loud refusal, never a silent misread.
+    module Reattest
+      module_function
+
+      def shape_guard!(domain:, ordinal:, text:, stored_hash:, stored_projection: nil)
+        bluebook = shadow(text)
+        unless bluebook
+          raise Runtime::WiringError,
+                "cannot re-attest era #{ordinal} of #{domain}: the edited text does not load as a " \
+                "bluebook — a held era text is bootable source; restore a loadable text"
+        end
+
+        # The stored PROJECTION is the preferred comparison: structural,
+        # version-free, and the same mechanism every boot trusts — so
+        # this guard never depends on canonicalization stability, and a
+        # future canonical-form version cannot make cosmetic edits to
+        # old-form eras false-refuse as shape changes. The hash path
+        # survives only as a fallback for stores that predate stored
+        # projections.
+        if stored_projection
+          edited = JSON.parse(JSON.generate(Runtime::StorageShape.project(bluebook)))
+          return :cosmetic if edited == stored_projection
+
+          raise Runtime::WiringError,
+                "cannot re-attest era #{ordinal} of #{domain}: the edit changed the era's SHAPE, not just " \
+                "its text — the text no longer projects to the shape frozen for era #{ordinal}. " \
+                "Attesting would retroactively redefine what era #{ordinal} meant for data already written " \
+                "under it; restore a text with the original shape"
+        end
+        return :unnamed unless stored_hash
+
+        computed = Runtime::StorageShape.mint_hash(bluebook)
+        return :cosmetic if computed == stored_hash
+
+        raise Runtime::WiringError,
+              "cannot re-attest era #{ordinal} of #{domain}: the edit changed the era's SHAPE, not just " \
+              "its text — its name #{stored_hash[0, Runtime::StorageShape::LABEL_LENGTH]} was minted from " \
+              "a different shape (the text now projects to #{computed[0, Runtime::StorageShape::LABEL_LENGTH]}). " \
+              "Attesting would retroactively redefine what era #{ordinal} meant for data already written " \
+              "under it; restore a text with the original shape"
+      end
+
+      def shadow(source)
+        file = Tempfile.new(["hecks-reattest-", ".bluebook"])
+        file.write(source)
+        file.flush
+        Runtime::EraGuard.shadow_parse(source, file.path)
+      rescue StandardError, SyntaxError
+        nil
+      ensure
+        file&.close!
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+require "json"
+
+module Hecks
+  module Translation
+    # The closed, PURE half of Postgres's own SQL compiler
+    # (adapters/driven/postgres_era/lineage/head_compiler.rb) — the part
+    # that turns one TranslationAggregate's declared rules into a
+    # jsonb-transforming SQL expression. No database connection, no
+    # watermark, no era chain, no catalog lookup: those stay exactly
+    # where they were, in head_compiler.rb's own per-mint assembly,
+    # which calls into this module instead of defining these methods
+    # itself.
+    #
+    # Extracted here — not left as private methods on
+    # Adapters::PostgresEra::Lineage — so a SECOND, adapter-agnostic
+    # caller (Exporter.translation_aggregate's build-time SQL export,
+    # feeding rust/host's own future boot-time mint) can call the exact
+    # SAME code Ruby's own mint path runs, not a hand-ported duplicate
+    # that could silently drift the way `Exporter.translation_hash`
+    # drifted from `hecks_eras`/`hecks_approvals`' real schema before
+    # this file existed (rekeys/backfills were missing for years).
+    module RuleCompiler
+      module_function
+
+      # One edge's rules over one jsonb state, compiled as a nested
+      # expression tree — hecks_tr_* helpers composed innermost-first
+      # in the reference transform's phase order (renames, moves,
+      # converts, drops), computes last. `retype` compiles to nothing:
+      # stored state never carries a type name.
+      def compile_rules(declared)
+        expression = "state"
+        declared.renames.each do |old_name, new_name|
+          expression = "hecks_tr_rename(#{expression}, #{text_literal(old_name)}, #{text_literal(new_name)})"
+        end
+        declared.moves.each do |move|
+          expression = "hecks_tr_move(#{expression}, #{path_literal(move.from)}, #{path_literal(move.to)}, " \
+                       "#{text_literal("move #{move.from} to: #{move.to}")})"
+        end
+        declared.converts.each do |convert|
+          pairs = JSON.generate(convert.values.map { |key, value| [key, value] })
+          expression = "hecks_tr_convert(#{expression}, #{path_literal(convert.from)}, #{path_literal(convert.to)}, " \
+                       "#{text_literal(pairs)}::jsonb, #{text_literal(convert.from)}, " \
+                       "#{text_literal("convert #{convert.from} to: #{convert.to}")})"
+        end
+        declared.drops.each do |name|
+          expression = "hecks_tr_drop(#{expression}, #{path_literal(name)})"
+        end
+        declared.computes.each do |compute|
+          expression = compile_compute(expression, compute)
+        end
+        expression
+      end
+
+      # Whether THIS edge's declared rules for this aggregate include a
+      # rekey — checked directly off the raw IR object, the same way
+      # every other rule kind is already read in `compile_rules`
+      # (`declared.computes`, `declared.moves`, ...), not through the
+      # `Ports::Persistence::Lineage` wrapper the app-level consumers
+      # (coverage_check.rb, minter.rb, layer_two.rb) go through — this
+      # module builds SQL straight off the IR either way.
+      def rekeyed?(declared) = declared && !declared.rekeys.empty?
+
+      # THE ONLY TWO PLACES `aggregate_id` NEEDS TO CHANGE — guarded so
+      # the generated SQL for the overwhelming common case (no rekey
+      # declared) stays the bare `aggregate_id` passthrough it always
+      # was — this CASE only appears in an edge that actually declares
+      # one.
+      def id_case(guard, declared)
+        "CASE WHEN #{guard} THEN #{compile_id_expression(declared)} ELSE aggregate_id END AS aggregate_id"
+      end
+
+      # THE REKEY'S OWN SQL — reading `state` directly, not the
+      # progressively-built `expression` chain `compile_compute` reads
+      # from. A rekey doesn't consume or move any field the way a move
+      # or compute does, so there is no same-edge rename/move ordering
+      # it needs to see first — it reads the record's stored fields
+      # exactly as they already are, the same `__s` convention
+      # `compile_compute` exposes.
+      def compile_id_expression(declared)
+        rekey = declared.rekeys.first
+        "(SELECT (#{rekey.sql}) FROM (SELECT (state) AS __s) __outer)"
+      end
+
+      # A compute is the one rule whose SQL is its only implementation
+      # — evaluated exclusively inside the compiled head, never
+      # in-process. The old field is exposed under its own name (as
+      # text, exactly as the author's expression expects to cast it).
+      def compile_compute(expression, compute)
+        from = compute.from.to_s
+        to = compute.to.to_s
+        "(SELECT CASE WHEN __s ? #{text_literal(from)} THEN " \
+          "hecks_tr_insert(__s - #{text_literal(from)}, #{path_literal(to)}, to_jsonb((#{compute.sql})), " \
+          "#{text_literal("compute #{from} to: #{to}")}) " \
+          "ELSE __s END " \
+          "FROM (SELECT (#{expression}) AS __s) __outer, " \
+          "LATERAL (SELECT (__s ->> #{text_literal(from)}) AS #{quote(from)}) __fields)"
+      end
+
+      # `PG::Connection.quote_ident` needs the `pg` gem LOADED, not
+      # connected — required here, lazily, the same "a domain that
+      # never wires PostgresEra should never need the gem" reasoning
+      # `PostgresEra.connect_for`'s own `require "pg"` already holds
+      # itself to, so a build tool that exports translations for a
+      # non-Postgres-bound domain (there are none today, but nothing
+      # here should assume there never will be) doesn't gain a hard
+      # dependency on `pg` just by loading this file.
+      def quote(name)
+        require "pg"
+        PG::Connection.quote_ident(name.to_s)
+      end
+
+      def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
+
+      def path_literal(path)
+        segments = path.to_s.split(".").map { |segment| text_literal(segment) }
+        "ARRAY[#{segments.join(', ')}]::text[]"
+      end
+    end
+  end
+end