hecks 0.2.0 → 0.3.0

data/lib/hecks/translation/scaffold/differ.rb

@@ -0,0 +1,183 @@
+require_relative "../../runtime/storage_shape"
+
+module Hecks
+  module Translation
+    module Scaffold
+      # Diff two eras' storage-shape projections into the edge's
+      # declarations — confident rules by unique signature pairing,
+      # everything ambiguous left unresolved for a human.
+      module Differ
+        # Diff two bluebook IRs into the edge's declarations.
+        def diff(held_bluebook, current_bluebook)
+          held_shapes = projections(held_bluebook)
+          current_shapes = projections(current_bluebook)
+
+          matched = match_aggregates(held_shapes, current_shapes)
+          aggregates = current_bluebook.aggregates.filter_map do |aggregate|
+            held_name = matched[:pairs][aggregate.name]
+            next unless held_name
+
+            rules = attribute_rules(held_shapes[held_name], current_shapes[aggregate.name])
+            was = held_name == aggregate.name ? nil : held_name
+            next if rules.empty? && was.nil?
+
+            ScaffoldedAggregate.new(name: aggregate.name, was: was, rules: rules)
+          end
+
+          { aggregates: aggregates, retired: matched[:retired], unclaimed: matched[:unclaimed] }
+        end
+
+        def projections(bluebook)
+          Runtime::StorageShape.project(bluebook)["aggregates"].to_h { |shape| [shape["name"], shape] }
+        end
+
+        # A vanished aggregate whose full shape reappears under exactly one
+        # new name was renamed. `retired` is only confident when NOTHING
+        # remains it could plausibly have become — a vanished aggregate
+        # beside an unmatched new one might be a rename-plus-reshape, and
+        # writing `retired` there would be a guess that strands data.
+        # Anything ambiguous stays unclaimed, and the coverage gate names
+        # it until a human decides.
+        def match_aggregates(held_shapes, current_shapes)
+          pairs = {}
+          current_shapes.each_key { |name| pairs[name] = held_shapes.key?(name) ? name : nil }
+
+          vanished = held_shapes.keys - current_shapes.keys
+          appeared = current_shapes.keys.select { |name| pairs[name].nil? }
+          unclaimed = []
+          vanished.each do |old_name|
+            old_shape = held_shapes[old_name].merge("name" => nil)
+            candidates = appeared.select { |name| current_shapes[name].merge("name" => nil) == old_shape }
+            if candidates.size == 1
+              pairs[candidates.first] = old_name
+              appeared -= candidates
+            else
+              unclaimed << old_name
+            end
+          end
+
+          retired = appeared.empty? ? unclaimed : []
+          { pairs: pairs, retired: retired, unclaimed: retired.empty? ? unclaimed : [] }
+        end
+
+        # Every changed path in one aggregate, resolved into rules by
+        # signature matching over the FULL path set — top-level names and
+        # dotted members alike. Unique signature pair: a rename (both
+        # top-level) or a move (any dotted end). Same path, same members,
+        # new type name: a retype. Anything else: unresolved, carrying its
+        # type-compatible candidates (an empty list is the arrow toward
+        # compute, or drop).
+        def attribute_rules(held_shape, current_shape)
+          rules = []
+          rules << identity_hint(held_shape, current_shape)
+          rules.compact!
+          held_attrs = (held_shape["attributes"] || []).to_h { |attribute| [attribute["name"], attribute] }
+          current_attrs = (current_shape["attributes"] || []).to_h { |attribute| [attribute["name"], attribute] }
+
+          # retype pass: same attribute name, same member structure, the
+          # TYPE's own name changed
+          (held_attrs.keys & current_attrs.keys).each do |name|
+            held = held_attrs[name]
+            current = current_attrs[name]
+            next if held == current
+            next unless container?(held) && container?(current)
+            next unless held["type"]["members"] == current["type"]["members"] && held["list"] == current["list"]
+
+            rules << { kind: :retype, from: held["type"]["type"], to: current["type"]["type"] }
+          end
+          retyped = rules.filter_map { |rule| rule[:from] if rule[:kind] == :retype }
+
+          vanished = vanished_paths(held_attrs, current_attrs, retyped)
+          appeared = appeared_paths(held_attrs, current_attrs, retyped)
+
+          vanished.each do |path, signature|
+            matches = appeared.select { |_, candidate| candidate == signature }.keys
+            taken = rules.filter_map { |rule| rule[:to] if %i[rename move].include?(rule[:kind]) }
+            matches -= taken
+            if matches.size == 1 && vanished.count { |_, other| other == signature } == 1
+              target = matches.first
+              kind = path.include?(".") || target.include?(".") ? :move : :rename
+              rules << { kind: kind, from: path, to: target }
+            else
+              candidates = matches.empty? ? compatible_candidates(appeared, signature) : matches
+              rules << { kind: :unresolved, from: path, candidates: candidates }
+            end
+          end
+          rules
+        end
+
+        # Held paths that need explaining: whole attributes that vanished,
+        # and members that vanished (or changed type) inside a kept
+        # attribute — mirroring exactly what EraGuard will demand coverage
+        # for.
+        def vanished_paths(held_attrs, current_attrs, retyped)
+          paths = {}
+          held_attrs.each do |name, held|
+            next if retyped.include?(container?(held) ? held["type"]["type"] : nil)
+
+            current = current_attrs[name]
+            if current.nil?
+              paths[name] = held["type"]
+              next
+            end
+            next if held == current
+
+            held_members = members_of(held)
+            current_members = members_of(current)
+            held_members.each do |member, signature|
+              paths["#{name}.#{member}"] = signature if current_members[member] != signature
+            end
+          end
+          paths
+        end
+
+        def appeared_paths(held_attrs, current_attrs, retyped)
+          paths = {}
+          current_attrs.each do |name, current|
+            next if retyped.include?(container?(current) ? current["type"]["type"] : nil)
+
+            held = held_attrs[name]
+            if held.nil?
+              paths[name] = current["type"]
+              next
+            end
+            next if held == current
+
+            held_members = members_of(held)
+            members_of(current).each do |member, signature|
+              paths["#{name}.#{member}"] = signature if held_members[member] != signature
+            end
+          end
+          paths
+        end
+
+        # THE ONE THING `attribute_rules` COULD NOT SEE BEFORE — the shape
+        # projection already carries `"identity"` (`StorageShape
+        # .project_aggregate`), it was simply never read here. An
+        # unresolved placeholder, not a guess: `coverage_check.rb`'s own
+        # `check_identity_unchanged!` is the real gate this only hints
+        # toward, the same "tool proactively guides you" pattern the
+        # generic unresolved message already gives unfed fields.
+        def identity_hint(held_shape, current_shape)
+          return if held_shape["identity"] == current_shape["identity"]
+
+          { kind: :unresolved, from: :identity, candidates: [] }
+        end
+
+        def compatible_candidates(appeared, signature)
+          appeared.select { |_, candidate| scalar_of(candidate) == scalar_of(signature) }.keys
+        end
+
+        def scalar_of(signature) = signature.is_a?(Hash) ? signature["members"] : signature
+
+        def members_of(attribute)
+          return {} unless container?(attribute)
+
+          attribute["type"]["members"].to_h { |member| [member["name"], member["type"]] }
+        end
+
+        def container?(attribute) = attribute["type"].is_a?(Hash)
+      end
+    end
+  end
+end

data/lib/hecks/translation/scaffold/renderer.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Translation
+    module Scaffold
+      # Render an edge into .bluebook text — confident rules inline,
+      # ambiguities as parse-refusing `unresolved` constructs, never
+      # comments, so an unresolved file can only boot into a refusal.
+      module Renderer
+        def render(edge)
+          lines = ["Hecks.data_translation #{edge.domain.inspect}, from: #{edge.from.inspect}, to: #{edge.to.inspect} do"]
+          edge.aggregates.each do |aggregate|
+            header = "  aggregate #{aggregate.name.inspect}"
+            header += ", was: #{aggregate.was.inspect}" if aggregate.was
+            if aggregate.rules.empty?
+              lines << "#{header} do"
+            else
+              lines << "#{header} do"
+              aggregate.rules.each { |rule| lines << "    #{render_rule(rule)}" }
+            end
+            lines << "  end"
+          end
+          edge.retired.each { |name| lines << "  retired #{name.inspect}" }
+          lines << "end"
+          "#{lines.join("\n")}\n"
+        end
+
+        def render_rule(rule)
+          case rule[:kind]
+          when :rename then "rename :#{rule[:from]}, to: :#{rule[:to]}"
+          when :move then "move #{rule[:from].inspect}, to: #{rule[:to].inspect}"
+          when :retype then "retype #{rule[:from].inspect}, to: #{rule[:to].inspect}"
+          when :unresolved
+            candidates = rule[:candidates].map { |candidate| render_path(candidate) }.join(", ")
+            "unresolved #{render_path(rule[:from])}, candidates: [#{candidates}]"
+          end
+        end
+
+        def render_path(path) = path.to_s.include?(".") ? path.to_s.inspect : ":#{path}"
+      end
+    end
+  end
+end

data/lib/hecks/translation/scaffold/writer.rb

@@ -0,0 +1,28 @@
+require "fileutils"
+
+module Hecks
+  module Translation
+    module Scaffold
+      # Put the rendered edge on disk, regenerating in place when a file
+      # for the same shape pair already exists.
+      module Writer
+        # The edge file, regenerated in place when one for the same shape
+        # pair already exists (matched textually — an unresolved file
+        # cannot be LOADED to ask, that being the whole point of
+        # unresolved).
+        def write!(directory, edge)
+          translations_dir = File.join(directory, "translations")
+          FileUtils.mkdir_p(translations_dir)
+
+          existing = Dir[File.join(translations_dir, "*.bluebook")].find do |path|
+            text = File.read(path)
+            text.include?("from: #{edge.from.inspect}") && text.include?("to: #{edge.to.inspect}")
+          end
+          path = existing || File.join(translations_dir, "#{edge.ordinal}-#{edge.label}.bluebook")
+          File.write(path, render(edge))
+          path
+        end
+      end
+    end
+  end
+end

data/lib/hecks/translation/scaffold.rb

@@ -0,0 +1,30 @@
+require_relative "scaffold/differ"
+require_relative "scaffold/renderer"
+require_relative "scaffold/writer"
+
+module Hecks
+  module Translation
+    # The scaffold writes translations; humans resolve ambiguity. It
+    # diffs the held era's storage-shape projection against the current
+    # one (scaffold/differ.rb) and WRITES the edge file
+    # (scaffold/renderer.rb, scaffold/writer.rb): confident rules inline
+    # (unique signature pairs → rename/move, aggregate renames → `was:`,
+    # type renames with identical members → retype, aggregates gone
+    # without a successor → retired), ambiguities as parse-refusing
+    # `unresolved` constructs — never comments, so an unresolved file can
+    # only boot into a refusal, never a guess. It NEVER proposes a
+    # `compute` (a computation takes domain judgment no mechanical diff
+    # can infer) — an empty-candidate `unresolved` is what points the
+    # author there. It never proposes a `drop` either: data loss is a
+    # decision, not a default. Re-running regenerates the file, matched
+    # by shape pair.
+    module Scaffold
+      Edge = Struct.new(:domain, :from, :to, :ordinal, :label, :aggregates, :retired, keyword_init: true)
+      ScaffoldedAggregate = Struct.new(:name, :was, :rules, keyword_init: true)
+
+      extend Differ
+      extend Renderer
+      extend Writer
+    end
+  end
+end

data/lib/hecks/translation.rb

@@ -0,0 +1,11 @@
+module Hecks
+  # The era-translation toolchain: scaffold drafts a translation from two
+  # eras' shapes, audit judges a written one, reattest re-seals it.
+  module Translation
+  end
+end
+
+require_relative "translation/rule_compiler"
+require_relative "translation/scaffold"
+require_relative "translation/audit"
+require_relative "translation/reattest"

data/lib/hecks/version.rb

@@ -0,0 +1,16 @@
+module Hecks
+  # ISOLATED, ON PURPOSE — the gemspec reads this file directly rather
+  # than `require_relative "lib/hecks"` (the whole framework),
+  # specifically so evaluating the gemspec never triggers ANY of this
+  # gem's own dependencies (prism among them) before Bundler has even
+  # resolved what to install. A real, live chicken-and-egg bug caught
+  # deploying to a Ruby version that doesn't bundle prism for free
+  # (AWS Lambda's ruby3.2): the gemspec's own `require_relative
+  # "lib/hecks"` pulled in adapters/driven/prism.rb's
+  # unconditional `require "prism"`, which failed before Bundler ever
+  # read what the gemspec itself declared as a dependency — declaring
+  # it there, or even in the consuming Gemfile, never closed the gap,
+  # because gemspec evaluation happens before anything Bundler
+  # resolves is actually loadable yet.
+  VERSION = "0.3.0"
+end

data/lib/hecks/vocabulary.rb

@@ -0,0 +1,213 @@
+# GENERATED — projected from the language's own Vocabulary aggregate
+# (lib/hecks/language/bluebook/vocabulary.bluebook).
+#
+# DO NOT EDIT. spec/vocabulary_table_spec.rb re-projects this in memory
+# and refuses a diff, so an edit here fails the ordinary suite.
+#
+# Plain data on purpose — no requires, no dependency on the model —
+# because several of these sets are read while a bluebook is still
+# being parsed. A table that needed the framework to load could not
+# be the table the framework loads with.
+
+module Hecks
+  module Vocabulary
+    TABLES = {
+      "AggregateDispatchOrder" => [
+        {"step"=>"refuse_unknown_arguments"}.freeze,
+        {"step"=>"refuse_absent_arguments"}.freeze,
+        {"step"=>"normalize_args"}.freeze,
+        {"step"=>"refuse_role_mismatch"}.freeze,
+        {"step"=>"resolve_references"}.freeze,
+        {"step"=>"hydrate"}.freeze,
+        {"step"=>"enforce_givens"}.freeze,
+        {"step"=>"admissible_transition"}.freeze,
+        {"step"=>"assign_creation_attributes"}.freeze,
+        {"step"=>"apply_mutations"}.freeze,
+        {"step"=>"advance_lifecycle"}.freeze,
+        {"step"=>"delegate_to_entity"}.freeze,
+        {"step"=>"enforce_ensures"}.freeze,
+        {"step"=>"enforce_invariants"}.freeze,
+        {"step"=>"save"}.freeze,
+        {"step"=>"emit"}.freeze
+      ].freeze,
+      "Comparison" => [
+        {"symbol"=>">=", "compares_less_than"=>"true", "compares_equal"=>"false", "negated"=>"true"}.freeze,
+        {"symbol"=>"<=", "compares_less_than"=>"true", "compares_equal"=>"true", "negated"=>"false"}.freeze,
+        {"symbol"=>"<", "compares_less_than"=>"true", "compares_equal"=>"false", "negated"=>"false"}.freeze,
+        {"symbol"=>">", "compares_less_than"=>"true", "compares_equal"=>"true", "negated"=>"true"}.freeze,
+        {"symbol"=>"==", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"false"}.freeze,
+        {"symbol"=>"!=", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"true"}.freeze
+      ].freeze,
+      "DomainRefusal" => [
+        {"name"=>"AbsentArgument"}.freeze,
+        {"name"=>"AlreadyExists"}.freeze,
+        {"name"=>"AttributeAbsent"}.freeze,
+        {"name"=>"EnsuresNotMet"}.freeze,
+        {"name"=>"GivenNotMet"}.freeze,
+        {"name"=>"InvariantViolation"}.freeze,
+        {"name"=>"LifecycleRefused"}.freeze,
+        {"name"=>"NotFound"}.freeze,
+        {"name"=>"ProjectionAbsent"}.freeze,
+        {"name"=>"RemoteRefusal"}.freeze,
+        {"name"=>"TypeMismatch"}.freeze,
+        {"name"=>"Unauthorized"}.freeze,
+        {"name"=>"UnknownArgument"}.freeze,
+        {"name"=>"UnknownVerb"}.freeze
+      ].freeze,
+      "EntityDispatchOrder" => [
+        {"step"=>"normalize_args"}.freeze,
+        {"step"=>"refuse_role_mismatch"}.freeze,
+        {"step"=>"resolve_references"}.freeze,
+        {"step"=>"hydrate_parent"}.freeze,
+        {"step"=>"locate_element"}.freeze,
+        {"step"=>"enforce_givens"}.freeze,
+        {"step"=>"admissible_transition"}.freeze,
+        {"step"=>"apply_mutations"}.freeze,
+        {"step"=>"advance_lifecycle"}.freeze,
+        {"step"=>"enforce_ensures"}.freeze,
+        {"step"=>"enforce_invariants"}.freeze,
+        {"step"=>"save"}.freeze,
+        {"step"=>"emit"}.freeze
+      ].freeze,
+      "FieldHint" => [
+        {"name"=>"email", "pattern"=>"email", "resolves_to"=>"html_type"}.freeze,
+        {"name"=>"url", "pattern"=>"\\b(url|uri|website|link)\\b", "resolves_to"=>"html_type"}.freeze,
+        {"name"=>"tel", "pattern"=>"phone|\\btel(ephone)?\\b", "resolves_to"=>"html_type"}.freeze,
+        {"name"=>"textarea", "pattern"=>"\\b(text|body|note|notes|description|message|comment)\\b", "resolves_to"=>"kind"}.freeze
+      ].freeze,
+      "IncludeHaystack" => [
+        {"type"=>"Array", "strategy"=>"membership"}.freeze,
+        {"type"=>"String", "strategy"=>"substring"}.freeze
+      ].freeze,
+      "LoadOrder" => [
+        {"glob"=>"*.port"}.freeze,
+        {"glob"=>"*.adapter"}.freeze,
+        {"glob"=>"*.bluebook"}.freeze,
+        {"glob"=>"translations/*.bluebook"}.freeze,
+        {"glob"=>"*.hecksagon"}.freeze,
+        {"glob"=>"*.world"}.freeze
+      ].freeze,
+      "MutationOp" => [
+        {"name"=>"set", "sign"=>""}.freeze,
+        {"name"=>"append", "sign"=>""}.freeze,
+        {"name"=>"increment", "sign"=>"1"}.freeze,
+        {"name"=>"decrement", "sign"=>"-1"}.freeze,
+        {"name"=>"multiply", "sign"=>""}.freeze,
+        {"name"=>"clamp", "sign"=>""}.freeze,
+        {"name"=>"remove", "sign"=>""}.freeze,
+        {"name"=>"delegate", "sign"=>""}.freeze
+      ].freeze,
+      "NormalisationStrategy" => [
+        {"name"=>"collapse_whitespace"}.freeze,
+        {"name"=>"replace"}.freeze
+      ].freeze,
+      "Primitive" => [
+        {"name"=>"String"}.freeze,
+        {"name"=>"Integer"}.freeze,
+        {"name"=>"Float"}.freeze,
+        {"name"=>"TrueClass"}.freeze,
+        {"name"=>"FalseClass"}.freeze
+      ].freeze,
+      "QueryComparator" => [
+        {"name"=>"eq"}.freeze,
+        {"name"=>"ne"}.freeze,
+        {"name"=>"gt"}.freeze,
+        {"name"=>"gte"}.freeze,
+        {"name"=>"lt"}.freeze,
+        {"name"=>"lte"}.freeze,
+        {"name"=>"in"}.freeze,
+        {"name"=>"contains"}.freeze,
+        {"name"=>"none_in_state"}.freeze
+      ].freeze,
+      "RefusalTemplate" => [
+        {"refusal"=>"NotFound", "site"=>"creating_no_identity", "template"=>"{command} creates a {aggregate} — pass {identity}:"}.freeze,
+        {"refusal"=>"AlreadyExists", "site"=>"creating_duplicate", "template"=>"{command} creates a {aggregate} that already exists — {identity} {offered}"}.freeze,
+        {"refusal"=>"AlreadyExists", "site"=>"entity_duplicate", "template"=>"a {entity} already exists on {aggregate} — {identity} {offered}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"acting_no_identity", "template"=>"{command} acts on an existing {aggregate} — pass {identity}:"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"record_missing", "template"=>"no {aggregate} with {identity} {offered}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"entity_parent_no_identity", "template"=>"{command} acts on a {aggregate}'s {entity} — pass {identity}:"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"entity_unknown", "template"=>"{aggregate} has no entity {entity}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"entity_element_no_identity", "template"=>"{command} acts on one {entity} — pass {identity}:"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"entity_element_missing", "template"=>"no {entity} with {identity} {wants} on {aggregate} {parent_id}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"reference_target_missing", "template"=>"no {target} with {heads} {key}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"read_model_reference_missing", "template"=>"no {aggregate} with reference {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"read_model_object_reference", "template"=>"{query} refused — a reference is an id, and {field} arrived as an object"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"no_query", "template"=>"{aggregate} has no query {query}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"entity_query_missing", "template"=>"{entity} has no query {query}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"entity_holds_no_list", "template"=>"{aggregate} holds no list of {entity}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"entity_no_command", "template"=>"{entity} has no command {command}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"aggregate_no_command", "template"=>"{aggregate} has no command {command}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"port_no_operation", "template"=>"{port} has no operation {operation}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"no_domain", "template"=>"no domain {domain} loaded (verb {verb})"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"no_read_model", "template"=>"{domain} has no read model {query}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"not_fully_qualified", "template"=>"{verb} is not a fully-qualified verb (Domain::Aggregate.Command)"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"no_aggregate", "template"=>"{domain} has no aggregate {aggregate}"}.freeze,
+        {"refusal"=>"LifecycleRefused", "site"=>"transition_blocked", "template"=>"{command} refused — {field} is {current}, and {command} moves it only from {allowed}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"value_object_shape", "template"=>"{name} is a {type} — pass its fields as an object, not {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"reference_as_object", "template"=>"{command} refused — a reference is an id, and {attribute} arrived as an object{known_by}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"multi_field_scalar", "template"=>"{type} has multiple fields and cannot stand in for a scalar"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"composite_identity", "template"=>"{type} is a composite identity — an identity must have exactly one field"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"numeric_field", "template"=>"{type}.{field} expects {expected}, got {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"pattern_mismatch", "template"=>"{type}.{field} must match {pattern}, got {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"arithmetic_amount", "template"=>"{op} of {target} needs an Integer, got {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"arithmetic_current", "template"=>"{op} of {target} needs an Integer {target}, got {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"arithmetic_shared_field", "template"=>"{op} of {target} needs a value object with one shared Integer field"}.freeze,
+        {"refusal"=>"UnknownArgument", "site"=>"unknown_args", "template"=>"{command} does not declare {unknown} — it takes {declared}"}.freeze,
+        {"refusal"=>"AbsentArgument", "site"=>"absent_args", "template"=>"{command} was not given {absent} — it takes {declared}"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"closed_set_member", "template"=>"{type} admits {admitted} — got {offered}"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"value_object_invariant", "template"=>"{name} invariant violated — {description} (given {offered})"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"admits_declared_set", "template"=>"{name} admits {admits} — {admitted} — got {offered}"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"undeclared_set", "template"=>"{name} admits {admits}, which this chapter does not declare — a closed set is named Aggregate::SetName, and it must be one the bluebook actually holds"}.freeze,
+        {"refusal"=>"Unauthorized", "site"=>"tenant_required", "template"=>"{query} declares authorize with tenant: {field} — pass {field}: to name which {field} this ask is scoped to"}.freeze,
+        {"refusal"=>"Unauthorized", "site"=>"role_mismatch", "template"=>"{command} refused — role: {role}, and the caller stated {caller_role}"}.freeze,
+        {"refusal"=>"AttributeAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it in a translation (backfill :{field}, default: ...), or declare it optional: true"}.freeze,
+        {"refusal"=>"ProjectionAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is not yet projected on this record — declared via projects :{field}, but no rebuild sweep has populated it. Run the sweep, or read {reference}.{remote_field} directly if this rule cannot wait"}.freeze
+      ].freeze,
+      "SignTest" => [
+        {"name"=>"positive?", "compares_via"=>">"}.freeze,
+        {"name"=>"negative?", "compares_via"=>"<"}.freeze,
+        {"name"=>"zero?", "compares_via"=>"=="}.freeze
+      ].freeze,
+      "SizedType" => [
+        {"type"=>"Array"}.freeze,
+        {"type"=>"String"}.freeze,
+        {"type"=>"Hash"}.freeze
+      ].freeze,
+      "ToStringType" => [
+        {"type"=>"String"}.freeze,
+        {"type"=>"Integer"}.freeze,
+        {"type"=>"Float"}.freeze,
+        {"type"=>"TrueClass"}.freeze,
+        {"type"=>"FalseClass"}.freeze,
+        {"type"=>"NilClass"}.freeze
+      ].freeze,
+      "Trigger" => [
+        {"name"=>"refused"}.freeze
+      ].freeze,
+      "VocabularyName" => [
+
+      ].freeze
+    }.freeze
+
+    # THE TERMS — the first field of each row, which for a
+    # one-field vocabulary is the whole of it. Derived ONCE and
+    # frozen rather than mapped per call: these are constant
+    # tables, and a constant that allocates a new array every
+    # time it is read is not one.
+    TERMS = TABLES.transform_values { |rows| rows.map { |row| row.values.first }.freeze }.freeze
+
+    module_function
+
+    # Refuses an unknown name rather than answering nil: a set
+    # the language does not declare is a typo, not an empty set.
+    def fetch(name) = TERMS.fetch(name)
+
+    # The rows whole, for the vocabularies that carry more than
+    # a term — Comparison's own algebra, RefusalTemplate's text.
+    def rows(name) = TABLES.fetch(name)
+
+    def symbols(name) = fetch(name).map(&:to_sym)
+
+    def names = TABLES.keys
+  end
+end

data/lib/hecks.rb

@@ -1,6 +1,118 @@
-# frozen_string_literal: true
-require 'thor'
-require 'hecks-adapters-dynamodb'
-require 'hecks-plugins-json-validator'
-require_relative 'cli/hecks-cli'
-require_relative 'console/hecks-console'
+require_relative "hecks/version"
+# The closed sets the runtime computes with, generated from
+# vocabulary.bluebook. Plain data, required first, because some of
+# them are read while a bluebook is still being parsed.
+require_relative "hecks/vocabulary"
+require_relative "hecks/rendering"
+require_relative "hecks/naming"
+require_relative "hecks/fqn"
+require_relative "hecks/freezer"
+require_relative "hecks/construct"
+# Before `bluebook` — every construct under `Bluebook` includes or
+# extends this to declare what it emits.
+require_relative "hecks/ir"
+require_relative "hecks/literal"
+require_relative "hecks/facade"
+require_relative "hecks/query_specification"
+
+require_relative "hecks/ports"
+require_relative "hecks/bluebook"
+require_relative "hecks/router"
+
+require_relative "hecks/runtime"
+require_relative "hecks/translation"
+require_relative "hecks/adapters"
+require_relative "hecks/projector"
+# AFTER the projector registry and its `Target` mixin are both real —
+# every target registers itself as it loads, so this require IS the
+# installation of them.
+require_relative "hecks/projections"
+# AFTER `Projector` (dispatches against the `:cli` projection) and
+# `Ports::Clock` (fills a staleness rule's `now` at the door) both exist.
+require_relative "hecks/facade/cli_door"
+require_relative "hecks/facade/cli_runner"
+require_relative "hecks/framework"
+require_relative "hecks/embryonaut_bluebook"
+
+module Hecks
+  class LoadOutsideBoot < StandardError; end
+
+  class << self
+    attr_reader :current_registry
+
+    # The loading words below collect into the registry the RUNTIME is
+    # holding open ; booting and that ambient state belong to the runtime
+    # layer, so this module is their facade and Hecks::Runtime is where
+    # they live.
+    # `install_facade:` — see Runtime::Loader.boot. Defaults on; a caller
+    # that only dispatches by FQN string can skip the global sugar.
+    #
+    # `environment:` — RECOVERED, not new: this parameter (and the
+    # `environments/<name>.hecksagon` / `.world` overlay it loads —
+    # see Adapters::Folder#load_domain) existed on a prior commit of
+    # this repo (933d1dd), was vendored out to a real consumer
+    # (lifeadelics/domain), and was then lost from this repo's own
+    # history (no branch here reaches that commit). Ported forward
+    # from the consumer's vendor snapshot — the only surviving copy —
+    # and generalized: the original only loaded a `.hecksagon`
+    # overlay; this also loads a same-named `.world` overlay, both
+    # merged into the base rather than replacing it (Registry#add_hecksagon
+    # / #add_world). hecks never reads ENV itself — a caller
+    # resolves its own env var name and passes the resulting string
+    # straight through, e.g. `Hecks.boot(path, environment:
+    # ENV.fetch("MYAPP_ENV", "development"))`.
+    def boot(path, shared: nil, install_facade: true, environment: nil)
+      Runtime.boot(path, shared: shared, install_facade: install_facade, environment: environment)
+    end
+
+    # `paths` — an explicit list of files to boot (a `.bluebook`, its
+    # `.hecksagon`, optionally a `.world`), loaded in place from wherever
+    # they actually live — see Runtime::Loader.boot_files's own header for
+    # why this exists beside `boot` rather than as a special case of it.
+    def boot_files(paths, shared: nil, install_facade: true, environment: nil)
+      Runtime.boot_files(paths, shared: shared, install_facade: install_facade, environment: environment)
+    end
+
+    def with_registry(registry, &block) = Runtime.with_registry(registry, &block)
+
+    def current_registry = Runtime.current_registry
+
+    # Bind who is dispatching for the duration of the block — checked
+    # against a command's declared `role`, if it has one. Unbound (the
+    # default), a command's role stays exactly what it is without this:
+    # decoration.
+    #
+    # `actor_id` is OPTIONAL — a caller naming only a role is checked by
+    # string equality against the command's own `role`, exactly as
+    # before. A caller that also names WHO it is lets the check run
+    # against a real Governance `RoleAssignment` instead, once the
+    # command's domain has Governance attached — see
+    # `CommandRules::Authorization`'s own header.
+    def as_caller(role:, actor_id: nil, &block) = Runtime.as_caller(role: role, actor_id: actor_id, &block)
+
+    def bluebook(name, version: nil, &block)
+      collect(:add_bluebook, Bluebook::DSL::BluebookBuilder.build(name, version: version, &block))
+    end
+
+    def hecksagon(name, &block) = collect(:add_hecksagon, Bluebook::DSL::HecksagonBuilder.build(name, &block))
+    def port(name, &block) = collect(:add_port, Bluebook::DSL::PortBuilder.build(name, &block))
+    def adapter(name, &block)   = collect(:add_adapter, Bluebook::DSL::AdapterBuilder.build(name, &block))
+    def world(name, &block)     = collect(:add_world, Bluebook::DSL::WorldBuilder.build(name, &block))
+
+    def data_translation(name, from:, to:, &block)
+      collect(:add_translation, Bluebook::DSL::TranslationBuilder.build(name, from: from, to: to, &block))
+    end
+
+    private
+
+    def collect(method, item)
+      unless Runtime.current_registry
+        raise LoadOutsideBoot,
+              "declaration loaded outside a boot — use Hecks.boot(path) rather than requiring the file directly"
+      end
+
+      Runtime.current_registry.public_send(method, item)
+      item
+    end
+  end
+end