hecks 0.2.0 → 0.3.0

data/lib/hecks/grammar/grammar.hecksagon

@@ -0,0 +1,20 @@
+# The expression and translation grammars, bound so they boot standing
+# alone. Both are read-only in practice — Hecks::Grammar parses
+# against them — but a binding is declared rather than defaulted.
+Hecks.hecksagon "Expression" do
+  # Every command here declares `role "Language designer"` — only real
+  # access control once Governance can check it against something (S8).
+  uses_framework "Governance"
+  persisted_by "Memory"
+end
+
+Hecks.hecksagon "Translation" do
+  # Same reason as Expression, above — S8.
+  uses_framework "Governance"
+  persisted_by "Memory"
+end
+
+Hecks.hecksagon "Governance" do
+  Governance::RoleAssignment.persisted_by("Memory")
+  Governance::RoleTransition.persisted_by("Memory")
+end

data/lib/hecks/grammar/oidc.json

@@ -0,0 +1,69 @@
+{
+  "audience": "Expression",
+  "scopes": [
+    {
+      "scope": "expression:expression.admit",
+      "verb": "Expression::Expression.Admit",
+      "role": "System"
+    },
+    {
+      "scope": "expression:expression.extract",
+      "verb": "Expression::Expression.Extract",
+      "role": "System"
+    },
+    {
+      "scope": "expression:expression.note",
+      "verb": "Expression::Expression.Note",
+      "role": "System"
+    },
+    {
+      "scope": "expression:expression.reject",
+      "verb": "Expression::Expression.Reject",
+      "role": "System"
+    },
+    {
+      "scope": "expression:normalisation.admit",
+      "verb": "Expression::Normalisation.Admit",
+      "role": "Language designer"
+    },
+    {
+      "scope": "expression:normalisation.propose",
+      "verb": "Expression::Normalisation.Propose",
+      "role": "Language designer"
+    },
+    {
+      "scope": "expression:normalisation.read",
+      "verb": "Expression::Normalisation.Read",
+      "role": "Language designer"
+    },
+    {
+      "scope": "expression:normalisation.retire",
+      "verb": "Expression::Normalisation.Retire",
+      "role": "Language designer"
+    },
+    {
+      "scope": "expression:operator.admit",
+      "verb": "Expression::Operator.Admit",
+      "role": "Language designer"
+    },
+    {
+      "scope": "expression:operator.propose",
+      "verb": "Expression::Operator.Propose",
+      "role": "Language designer"
+    },
+    {
+      "scope": "expression:operator.render",
+      "verb": "Expression::Operator.Render",
+      "role": "Language designer"
+    },
+    {
+      "scope": "expression:operator.retire",
+      "verb": "Expression::Operator.Retire",
+      "role": "Language designer"
+    }
+  ],
+  "roles": [
+    "Language designer",
+    "System"
+  ]
+}

data/lib/hecks/grammar/translation.bluebook

@@ -0,0 +1,203 @@
+
+Hecks.bluebook "Translation" do
+  vision "The declared bridge from one era of a domain's storage shape to the next — every rule checkable, every loss written down, carried as one edge file."
+  generic
+
+  aggregate "Rule" do
+    description "One admitted way a value survives a shape change — its kind, where it reads from, where it writes to, and how it executes in every target that must apply it."
+
+    identified_by :source
+
+    attribute :kind,        Kind
+    attribute :source,      SourcePath
+    attribute :destination, DestinationPath
+    attribute :executions,  list_of(Execution)
+
+    lifecycle :status, default: "proposed" do
+      transition "Admit"  => "admitted", from: "proposed"
+      transition "Retire" => "retired",  from: "admitted"
+    end
+
+    # THE CLOSED SET OF RULE KINDS — declared as members, not a hand-rolled
+    # OR-chain, so the set is data a conformance spec can hold the live
+    # builder to (spec/translation_vocabulary_conformance_spec.rb). Nine of
+    # these are TranslationAggregateBuilder's own rule methods ; "retired" is
+    # the edge-level declaration (TranslationBuilder#retired), in the set
+    # because it is one admitted way a shape survives — by not surviving.
+    value_object "Kind" do
+      attribute :value, String,
+                one_of: ["rename", "move", "convert", "drop", "retype", "retired", "compute", "rekey",
+                         "backfill", "unresolved"]
+    end
+
+    value_object "SourcePath" do
+      attribute :value, String
+      invariant("a rule reads from somewhere") { !value.to_s.empty? }
+    end
+
+    value_object "DestinationPath" do
+      attribute :value, String
+    end
+
+    value_object "Target" do
+      attribute :value, String
+    end
+
+    value_object "Form" do
+      attribute :value, String
+    end
+
+    value_object "Execution" do
+      attribute :target, String
+      attribute :form,   String
+
+      invariant("an execution must name its target") { !target.to_s.empty? }
+      invariant("an execution must have a form")     { !form.to_s.empty? }
+    end
+
+    command "Propose" do
+      role "Author"
+      goal "Put one way of surviving a shape change forward"
+
+      attribute :kind,        Kind
+      attribute :source,      SourcePath
+      attribute :destination, DestinationPath
+
+      emits "RuleProposed"
+    end
+
+    command "Execute" do
+      role "Author"
+      goal "Declare how this rule runs in one target"
+
+      reference_to Rule
+      attribute :target, Target
+      attribute :form,   Form
+
+      given("a retired rule takes no new executions") { status != "retired" }
+
+      sets :executions, append: { target: :target, form: :form }
+
+      emits "RuleExecuted"
+    end
+
+    command "Admit" do
+      role "Author"
+      goal "Accept the rule — it executes identically in every target"
+
+      reference_to Rule
+
+      given("a rule must execute in every target before it is admitted") { executions.size >= 2 }
+
+      emits "RuleAdmitted"
+    end
+
+    command "Retire" do
+      role "Author"
+      goal "Remove the rule from the language"
+
+      reference_to Rule
+
+      emits "RuleRetired"
+    end
+  end
+
+  aggregate "Map" do
+    description "One translation edge between two minted eras — the ordered declarations that carry a domain's data across one shape change, sealed before anything boots through it."
+
+    identified_by :domain
+
+    attribute :domain,       DomainName
+    attribute :from_shape,   ShapeHash
+    attribute :to_shape,     ShapeHash
+    attribute :declarations, list_of(Declaration)
+
+    lifecycle :status, default: "drafted" do
+      transition "Seal"      => "sealed",     from: "drafted"
+      transition "Supersede" => "superseded", from: "sealed"
+    end
+
+    value_object "DomainName" do
+      attribute :value, String
+      invariant("an edge names the domain it translates") { !value.to_s.empty? }
+    end
+
+    value_object "ShapeHash" do
+      attribute :value, String
+      invariant("an era is named by its minted hash") { !value.to_s.empty? }
+    end
+
+    value_object "Kind" do
+      attribute :value, String
+    end
+
+    value_object "SourcePath" do
+      attribute :value, String
+    end
+
+    value_object "DestinationPath" do
+      attribute :value, String
+    end
+
+    value_object "Reason" do
+      attribute :value, String
+      invariant("a superseded edge says why") { !value.to_s.empty? }
+    end
+
+    value_object "Declaration" do
+      attribute :kind,        String
+      attribute :source,      String
+      attribute :destination, String
+
+      invariant("a declaration knows its kind") { !kind.to_s.empty? }
+    end
+
+    command "Draft" do
+      role "Author"
+      goal "Open the edge between two eras"
+
+      attribute :domain,     DomainName
+      attribute :from_shape, ShapeHash
+      attribute :to_shape,   ShapeHash
+
+      emits "MapDrafted"
+    end
+
+    command "Declare" do
+      role "Author"
+      goal "Write one rule into the edge"
+
+      reference_to Map
+      attribute :kind,        Kind
+      attribute :source,      SourcePath
+      attribute :destination, DestinationPath
+
+      given("a sealed edge takes no further declarations") { status == "drafted" }
+
+      sets :declarations, append: { kind: :kind, source: :source, destination: :destination }
+
+      emits "RuleDeclared"
+    end
+
+    command "Seal" do
+      role "Author"
+      goal "Declare the edge complete — data can cross it"
+
+      reference_to Map
+
+      given("an empty edge explains nothing") { declarations.size >= 1 }
+
+      emits "MapSealed"
+    end
+
+    command "Supersede" do
+      role "Author"
+      goal "Record that a corrected edge replaced this one"
+
+      reference_to Map
+      attribute :reason, Reason
+
+      emits "MapSuperseded"
+    end
+  end
+end

data/lib/hecks/grammar.rb

@@ -0,0 +1,178 @@
+require "json"
+
+# The whole framework, deliberately: booting a grammar chapter exercises
+# the DSL, the meta-validator, and the runtime — and nothing the entry
+# point loads ever requires this file back, so the require is acyclic.
+require_relative "../hecks"
+
+module Hecks
+  # The sublanguage grammar domains (grammar/*.bluebook) and the one boot
+  # path for reading them as DATA — the expression chapter replayed
+  # through its own admission ledger, so anything derived from it (the
+  # operator projections, the conformance specs) reads the set that
+  # actually survived the Admit gates, never a hand-copied list.
+  #
+  # Booted on CALL, never at require: the Prism adapter normalises every
+  # predicate through CanonicalForm while a bluebook loads, so the
+  # expression machinery cannot boot the chapter that configures it —
+  # this module exists precisely so generators and specs boot it in a
+  # scratch registry instead.
+  module Grammar
+    DIR    = File.expand_path("grammar", __dir__)
+    LEDGER = File.join(DIR, "expression_operators.json")
+
+    module_function
+
+    # Boot the expression chapter and replay the admission ledger through
+    # its real commands. A refused step raises — a generator running off
+    # a half-admitted ledger would project a table the gates never
+    # accepted.
+    def expression
+      registry = Runtime::Registry.new
+      root = File.expand_path("../..", __dir__)
+      Hecks.with_registry(registry) do
+        Kernel.load(File.join(root, "lib/hecks/ports/persistence.port"))
+        Kernel.load(File.join(root, "lib/hecks/ports/extraction.port"))
+        Kernel.load(File.join(root, "lib/hecks/adapters/driven/memory.adapter"))
+        Kernel.load(File.join(root, "lib/hecks/adapters/driven/prism.adapter"))
+        Kernel.load(File.join(DIR, "expression.bluebook"))
+      end
+      dispatcher = Runtime::Dispatcher.new(registry)
+
+      JSON.parse(File.read(LEDGER)).fetch("steps").each do |step|
+        args = symbolize(step.fetch("args"))
+        begin
+          dispatcher.dispatch(step.fetch("verb"), **args)
+        rescue *Runtime::DOMAIN_REFUSALS => refusal
+          raise Runtime::WiringError,
+                "the admission ledger refused at #{step['verb']} #{step['args']} — #{refusal.message}"
+        end
+      end
+
+      dispatcher
+    end
+
+    def admitted_operators(dispatcher = expression)
+      records(dispatcher, "Operator").select { |op| op[:status] == "admitted" }.map do |op|
+        { symbol: op[:symbol].value, category: op[:category].value,
+          precedence: op[:precedence].value, arity: op[:arity].value,
+          renderings: Array(op[:renderings]).map { |r| { target: r[:target], form: r[:form] } } }
+      end
+    end
+
+    def admitted_normalisations(dispatcher = expression)
+      records(dispatcher, "Normalisation")
+        .select { |rule| rule[:status] == "admitted" }
+        .sort_by { |rule| rule[:position].value }
+        .map do |rule|
+          { strategy: rule[:strategy].value, source_token: rule[:source_token].value,
+            replacement: rule[:replacement].value, boundary: rule[:boundary].value,
+            position: rule[:position].value }
+        end
+    end
+
+    def records(dispatcher, aggregate_name)
+      registry  = dispatcher.registry
+      aggregate = registry.bluebook("Expression").aggregate(aggregate_name)
+      registry.repository("Expression", aggregate).all
+    end
+
+    # THE OPERATORS THE LANGUAGE STANDS ON. Every guard and invariant in
+    # the language's own chapters — the meta-domain (Bluebook, World) and
+    # the grammar chapters beside this file — evaluates through the very
+    # operator table the ledger admits. An operator one of those
+    # predicates uses is SELF-BEARING: retire it and the language can no
+    # longer read its own rules — found the hard way, as a projection
+    # missing `!=` that could not boot the chapter to fix itself. This
+    # derives the set, with a usage site per operator, so the generator
+    # and the conformance spec can refuse the retirement BY NAME instead
+    # of wedging.
+    def self_bearing_operators
+      sites = Hash.new { |h, k| h[k] = [] }
+
+      chapters = Bluebook::MetaValidator.grammar_registry
+                                        .then { |reg| %w[Bluebook World].map { |name| reg.bluebook(name) } }
+      chapters += grammar_chapters
+
+      chapters.compact.each do |chapter|
+        chapter.aggregates.each do |aggregate|
+          aggregate.commands.each do |command|
+            command.givens.each do |given|
+              operators_in(given.canonical).each do |symbol|
+                sites[symbol] << "#{chapter.name} #{aggregate.name}.#{command.hecks_name}"
+              end
+            end
+          end
+          aggregate.value_objects.each do |value_object|
+            value_object.invariants.each do |invariant|
+              operators_in(invariant.canonical).each do |symbol|
+                sites[symbol] << "#{chapter.name} #{aggregate.name}::#{value_object.hecks_name}"
+              end
+            end
+          end
+        end
+      end
+
+      sites.transform_values(&:uniq)
+    end
+
+    # Every grammar/*.bluebook chapter, booted the same way the corpus
+    # boots them — each alone, in a scratch registry.
+    def grammar_chapters
+      Dir[File.join(DIR, "*.bluebook")].sort.map do |chapter|
+        registry = Runtime::Registry.new
+        root = File.expand_path("../..", __dir__)
+        Hecks.with_registry(registry) do
+          Kernel.load(File.join(root, "lib/hecks/ports/persistence.port"))
+          Kernel.load(File.join(root, "lib/hecks/ports/extraction.port"))
+          Kernel.load(File.join(root, "lib/hecks/adapters/driven/memory.adapter"))
+          Kernel.load(File.join(root, "lib/hecks/adapters/driven/prism.adapter"))
+          Kernel.load(chapter)
+        end
+        registry.bluebooks.values.first
+      end
+    end
+
+    # Which admitted operators one canonical text evaluates through —
+    # the evaluator's own parse, walked for its operator nodes, leaves
+    # walked for the resolver's arithmetic.
+    def operators_in(canonical)
+      evaluator = Bluebook::Expression::Evaluator
+      node = begin
+        evaluator.parse(canonical)
+      rescue StandardError
+        return []
+      end
+      walk_operators(node, evaluator).uniq
+    end
+
+    def walk_operators(node, evaluator)
+      resolver = Bluebook::Expression::Resolver
+      case node
+      when evaluator::Or  then ["||"] + walk_operators(node.left, evaluator) + walk_operators(node.right, evaluator)
+      when evaluator::And then ["&&"] + walk_operators(node.left, evaluator) + walk_operators(node.right, evaluator)
+      when evaluator::Not then ["!"] + walk_operators(node.node, evaluator)
+      when evaluator::Compare
+        [node.operator.symbol] + walk_operators(node.left, evaluator) + walk_operators(node.right, evaluator)
+      when evaluator::Include
+        [".include?"] + walk_operators(node.haystack, evaluator) + walk_operators(node.needle, evaluator)
+      when evaluator::Resolve then walk_operators(node.expr, evaluator)
+      when resolver::Addition then ["+"] + walk_operators(node.left, evaluator) + walk_operators(node.right, evaluator)
+      when resolver::Modulo   then [".modulo"] + walk_operators(node.receiver,
+                                                                evaluator) + walk_operators(node.divisor, evaluator)
+      when Struct
+        node.members.flat_map { |member| walk_operators(node[member], evaluator) }
+      else
+        []
+      end
+    end
+
+    def symbolize(value)
+      case value
+      when Hash  then value.to_h { |k, v| [k.to_sym, symbolize(v)] }
+      when Array then value.map { |v| symbolize(v) }
+      else value
+      end
+    end
+  end
+end

data/lib/hecks/ir.rb

@@ -0,0 +1,126 @@
+module Hecks
+  # WHAT A CONSTRUCT EMITS, DECLARED RATHER THAN WRITTEN OUT.
+  #
+  # `IR` is a thing this framework PRODUCES, not a thing its model IS.
+  # The language self-hosts, and its own bluebook declares aggregates
+  # named `Bluebook`, `Aggregate`, `Command`, `Entity`, `ValueObject`,
+  # `Policy`, `ReadModel` — there is no `IR` aggregate anywhere in the
+  # grammar. Where the grammar's own vision line does say IR it means the
+  # emission: "the IR it STORES must equal the IR the DSL builder
+  # PRODUCES". `IR_VERSION` says the same thing structurally — a version
+  # stamped on `to_h`'s output rather than on the object is a version of
+  # the EMISSION, which only makes sense if the two are different things.
+  #
+  # So emitting IR is a CAPABILITY a construct has, and this is that
+  # capability: `include Hecks::IR` and declare the shape once.
+  # The model it emits FROM is `Hecks::Bluebook` — a chapter class
+  # nesting everything a chapter declares. It is deliberately not named
+  # after this, its own output.
+  #
+  # Before this, eighteen constructs each hand-wrote a `to_h` that said
+  # the same four things in the same order — read a field, recurse into a
+  # child, recurse into a list, or compute something — and the shape of a
+  # construct was knowable only by reading a method body. Declared, it is
+  # data: `ir_spec` can be walked by anything that wants to know what a
+  # construct carries, which is the whole point of hanging emission off
+  # the model rather than burying it.
+  #
+  #   include Hecks::IR            # an instance-shaped construct
+  #
+  #   emits_ir(
+  #     name:           :name,                   # send it
+  #     identified_by:  :identity_paths,         # ...under a different key
+  #     list:           :list?,                  # ...predicates are fine
+  #     attributes:     many(:attributes),       # map(&:to_h)
+  #     lifecycle:      one(:lifecycle),         # &.to_h, nil-safe
+  #     canonical_form: -> { CanonicalForm.table } # anything else
+  #   )
+  #
+  # KEY ORDER IS THE DECLARATION ORDER, and that is load-bearing rather
+  # than cosmetic: `spec/golden/ir/*.json` pins the emitted form exactly,
+  # so a reordered declaration is a changed artifact and the golden specs
+  # will say so.
+  module IR
+    # THE TWO SHAPES A CONSTRUCT COMES IN, and why this module has two
+    # doors instead of hiding the difference.
+    #
+    # `Bluebook`/`Aggregate`/`Policy`/`ReadModel` are ordinary objects —
+    # metadata records, one instance per declaration. `Command`/`Entity`/
+    # `ValueObject` are anonymous CLASSES (`Class.new(self)`, see
+    # `Command.declare`), because those three are referenced as TYPES in
+    # a bluebook (`attribute :price, Money`) and a type has to be a real
+    # Ruby constant to be named.
+    #
+    # That split is real and not worth papering over, so:
+    #
+    #   include Hecks::IR   # instance-shaped — to_h is an instance method
+    #   extend  Hecks::IR   # class-shaped    — to_h is a class method
+    #
+    # Both get the same `emits_ir` and the same emission rules.
+    def self.included(base)
+      base.extend(Declares)
+      base.include(Emits)
+    end
+
+    def self.extended(base)
+      base.extend(Declares)
+      base.extend(Emits)
+    end
+
+    # A field that holds a list of constructs — each one emits itself.
+    Many = Struct.new(:source)
+    # A field that holds one construct, or nothing. `&.to_h`, never a
+    # crash on an undeclared lifecycle.
+    One  = Struct.new(:source)
+
+    module Declares
+      def emits_ir(**spec)
+        @ir_spec = spec
+      end
+
+      def many(source) = Many.new(source)
+      def one(source)  = One.new(source)
+
+      # Walks the superclass chain so a `Class.new(ValueObject)` — which
+      # is what every declared value object actually IS — inherits the
+      # shape its base declared, rather than each anonymous subclass
+      # having to redeclare it.
+      def ir_spec
+        return @ir_spec if defined?(@ir_spec) && @ir_spec
+
+        superclass.ir_spec if respond_to?(:superclass) && superclass.respond_to?(:ir_spec)
+      end
+    end
+
+    module Emits
+      def to_h
+        spec = ir_spec_for(self)
+        raise Undeclared, "#{self} emits IR but never declared its shape with emits_ir" unless spec
+
+        spec.to_h { |key, rule| [key, emit(rule)] }
+      end
+
+      private
+
+      # An instance reads its class's declaration; a class-shaped
+      # construct IS the declaration holder.
+      def ir_spec_for(construct)
+        return construct.ir_spec if construct.respond_to?(:ir_spec)
+
+        construct.class.ir_spec
+      end
+
+      def emit(rule)
+        case rule
+        when Many   then public_send(rule.source).map(&:to_h)
+        when One    then public_send(rule.source)&.to_h
+        when Symbol then public_send(rule)
+        when Proc   then instance_exec(&rule)
+        else raise Undeclared, "#{rule.inspect} is not a way to emit a field"
+        end
+      end
+    end
+
+    class Undeclared < StandardError; end
+  end
+end