hecks 0.2.0 → 0.3.0

data/lib/hecks/runtime.rb

@@ -0,0 +1,95 @@
+# Hecks::Runtime
+#
+# The runtime layer's face. `lib/hecks/runtime/` held thirteen files and
+# no parent, so the layer had no surface of its own : `lib/hecks.rb`
+# required each file by hand, and the runtime's own state — the registry a
+# declaration is being collected into — sat on the top-level Hecks module
+# beside the DSL words.
+#
+# What lives here is what RUNS a domain :
+#
+#   Runtime.boot(path)          load a directory and return its Dispatcher
+#   Runtime.with_registry(r)    bind the ambient registry for the duration of a load
+#   Runtime.current_registry    the registry a declaration is landing in, or nil
+#
+# What does NOT live here is what DECLARES one — `Hecks.bluebook`,
+# `.hecksagon`, `.port`, `.adapter`, `.world` are loading words and stay on the
+# top-level module, which now reads as a facade over this.
+#
+#   runtime = Hecks::Runtime.boot("examples/pizzas/bluebook")
+#   runtime.dispatch("Pizzas::Pizza.CreatePizza", name: "Margherita")
+#
+# NOTE, and it is the reason this file exists : `current_registry` is still
+# process-global. Each boot builds a fresh Registry, and `Loader.bind_runtime`
+# installs a fresh facade door whose modules close over THAT boot's dispatcher
+# — no class-level runtime binding remains, so two boots in one process no
+# longer share dispatch state, only the top-level NAME (the last-bound door
+# wins the constant, which is what per-boot install means). Owning the state
+# here was the first move ; the dispatcher reachable per-runtime rather than
+# through a constant was the second, and it is done — the door is the only
+# constant left, and it is a projection, not the runtime.
+
+require_relative "runtime/event"
+require_relative "runtime/value"
+require_relative "runtime/identity"
+require_relative "runtime/instance"
+require_relative "runtime/registry"
+require_relative "runtime/capability_graph"
+require_relative "runtime/errors"
+require_relative "runtime/refusal_wording"
+require_relative "runtime/caller"
+require_relative "runtime/routing"
+require_relative "runtime/command_rules"
+require_relative "runtime/dependency_planning"
+require_relative "runtime/command_interpreter"
+require_relative "runtime/port_operation_interpreter"
+require_relative "runtime/entity_interpreter"
+require_relative "runtime/query_interpreter"
+require_relative "runtime/read_model_interpreter"
+require_relative "runtime/policy_interpreter"
+require_relative "runtime/saga_interpreter"
+require_relative "runtime/dispatcher"
+require_relative "runtime/rebuild_sweep"
+require_relative "runtime/era_guard"
+require_relative "runtime/storage_shape"
+require_relative "runtime/era_tamper"
+require_relative "runtime/era_check"
+require_relative "runtime/tenant_check"
+require_relative "runtime/loader"
+
+module Hecks
+  module Runtime
+    class << self
+      # The registry declarations are currently landing in, or nil outside a
+      # boot. Read by the DSL collectors on the top-level module and by the
+      # extraction port.
+      attr_reader :current_registry
+
+      # Load a bluebook directory and return the Dispatcher bound to it.
+      # `install_facade:`, `environment:` — see Loader.boot.
+      def boot(path, shared: nil, install_facade: true, environment: nil)
+        Loader.boot(path, shared: shared, install_facade: install_facade, environment: environment)
+      end
+
+      # `paths` form — see Loader.boot_files.
+      def boot_files(paths, shared: nil, install_facade: true, environment: nil)
+        Loader.boot_files(paths, shared: shared, install_facade: install_facade, environment: environment)
+      end
+
+      # Bind the ambient registry for the duration of the block, restoring
+      # whatever was there before. Nesting is safe ; a raise still restores.
+      def with_registry(registry)
+        previous          = @current_registry
+        @current_registry = registry
+        yield
+      ensure
+        @current_registry = previous
+      end
+
+      # Bind the ambient caller (see Runtime::Caller) for the duration of
+      # the block — who a command's declared `role`, if any, is checked
+      # against.
+      def as_caller(role:, actor_id: nil, &block) = Caller.as(role: role, actor_id: actor_id, &block)
+    end
+  end
+end

data/lib/hecks/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/translation/audit/layer_one.rb

@@ -0,0 +1,37 @@
+require_relative "../../runtime/errors"
+require_relative "../../runtime/instance"
+require_relative "../../runtime/value/invariant_violation"
+
+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]
+              allowed = lifecycle.states | [lifecycle.default]
+              unless held.nil? || allowed.include?(held)
+                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/translation/audit/layer_two.rb

@@ -0,0 +1,77 @@
+require_relative "../../ports/persistence/append_only"
+require_relative "../../ports/persistence/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_tops = declared.computes.flat_map { |compute| [compute.from, compute.to] }
+                                 .map { |path| path.to_s.split(".").first }
+
+          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 = normalize(rules.translate(entry).state).reject { |key, _| compute_tops.include?(key) }
+            actual = normalize(after[id]).reject { |key, _| compute_tops.include?(key) }
+            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))
+      end
+    end
+  end
+end

data/lib/hecks/translation/audit/unfed_report.rb

@@ -0,0 +1,42 @@
+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)
+
+            node[segment] || node[segment.to_sym]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/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/translation/reattest.rb

@@ -0,0 +1,72 @@
+require "tempfile"
+require_relative "../runtime/era_guard"
+require_relative "../runtime/registry"
+require_relative "../runtime/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/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