hecks 0.2.0 → 1.0.0

data/lib/hecks/bluebook/smoke_test.rb

@@ -0,0 +1,166 @@
+require_relative "synthesizer"
+require "tmpdir"
+require "fileutils"
+
+module Hecks
+  module Bluebook
+    # BOOTS A REAL BLUEBOOK AND ACTUALLY DISPATCHES AGAINST IT — the
+    # sibling `bin/model_check` never had: that tool proves a bluebook
+    # is STRUCTURALLY sound (no dead states, no unreachable transitions)
+    # without ever running a single command; this proves it WORKS,
+    # catching exactly the class of bug static analysis structurally
+    # cannot see. Built and proved inside `bin/interview`'s own `smoke`
+    # command, where it first found two real bugs — a lifecycle field
+    # colliding with an explicit attribute, and a non-creating command
+    # missing `Command.ActsOn` — that reloaded clean, checked clean,
+    # and only broke once something actually dispatched against them.
+    #
+    # SYNTHESIZED ARGS, NEVER RANDOM (`Synthesizer`) — a String becomes
+    # a fixed marker, a closed set uses its own first admitted member, a
+    # reference reuses whatever this same run already minted for that
+    # target. ONE call per declared command, ONE call per declared
+    # report, per created root; every failure is collected and reported
+    # together rather than stopping at the first.
+    #
+    # WHAT THIS CANNOT CATCH: a call that dispatches cleanly but answers
+    # WRONG — the read-model join bug this exact tool's own first user
+    # hit is the textbook case, a query that silently returned an empty
+    # array rather than raising. Smoke-testing proves nothing crashes;
+    # it does not prove the answer is the right one.
+    #
+    # A FAILURE HERE IS NOT NECESSARILY A DOMAIN BUG, either — it may
+    # just be `Synthesizer`'s own naive values (0, an empty list,
+    # "smoke-test") not satisfying a real invariant this simple
+    # generator was never built to reason about (a positive amount, a
+    # non-empty topping list, an email pattern). Confirmed against
+    # Banking and Pizzas: both real domains, both showing exactly that
+    # class of failure, neither one an actual bug. Building a
+    # synthesizer that respects arbitrary declared invariants is real
+    # constraint-aware generation — a separate, larger tool than this.
+    module SmokeTest
+      Failure = Struct.new(:domain, :aggregate, :command, :error, keyword_init: true) do
+        def to_s = "#{domain}::#{aggregate}.#{command}: #{error}"
+      end
+
+      module_function
+
+      # `dir` is any real, bootable hecks app directory — a saved
+      # domain, or a throwaway one a caller rendered into a temp dir
+      # for exactly this purpose. Plain `Hecks.boot`, not
+      # `Router.boot` — proven all night, and it works against a
+      # domain with framework-attached chapters (`uses_framework
+      # "Governance"`, say) that `Router.boot` refuses outright: those
+      # chapters carry no `.world` of their own, which `Router`'s
+      # per-domain realm resolution requires and a plain boot never
+      # did. Reports are reachable the identical way regardless of
+      # boot path — `dispatcher.query("Domain.report_name", **args)`
+      # is the SAME `Dispatcher#query` either boot hands back; Router
+      # was never actually required for this, only its OWN namespace
+      # SUGAR (`Domain.report_name(...)` as a bare method call) was.
+      #
+      # NEVER BOOTS `dir`'S OWN REAL BINDINGS — measured, not a
+      # precaution taken on spec: pointed at `examples/pizzas` (a real,
+      # persistent store carrying real accumulated records), a
+      # synthesized `CreatePizza` collided with an actual pre-existing
+      # record literally named "smoke-test" — a coincidence this time,
+      # data pollution the next. `isolate!` copies only the `.bluebook`
+      # (and `.world`, for its realm) into a throwaway directory and
+      # deliberately leaves the real `.hecksagon` behind — with none
+      # present, `Ports::Persistence::BindingPolicy.default_binding`
+      # binds every aggregate to Memory on its own, no settings needed.
+      # Whatever `dir` is really bound to in production is never
+      # touched.
+      # `install_facade: false` — this only ever dispatches by FQN string
+      # (below), so it never needs the `Widget::Item.Add(...)` Ruby
+      # sugar `Hecks.boot` installs by default. Skipping it matters
+      # here specifically: that sugar lands as a BARE global constant on
+      # `Object` per domain and per aggregate name, with no scoping and
+      # no cleanup — and this tool boots throwaway domains under
+      # whatever generic names the caller's `.bluebook` happens to use
+      # ("Widget", "Item", "Tag" in this tool's own specs). Installing
+      # the facade would leak those names into the rest of the process —
+      # measured, not hypothetical: it once left a stale `Widget` constant
+      # that corrupted an unrelated spec's own unrelated use of the same
+      # bare name.
+      def call(dir)
+        Dir.mktmpdir("hecks-smoke-") do |scratch|
+          isolate!(dir, scratch)
+          dispatcher = Hecks.boot(scratch, install_facade: false)
+          domain     = dispatcher.registry.bluebooks.keys.first
+          next [] unless domain
+
+          smoke_domain(dispatcher, domain)
+        end
+      end
+
+      # ONLY THE `.bluebook`, NEVER `.world` EITHER — a real world's own
+      # settings (`persisted_by("Heki") { dir "..." }`) are keyed to the
+      # REAL adapter it names, not to Memory; copied verbatim, they
+      # apply to the wrong binding and refuse with a `WiringError`
+      # ("Memory does not declare :dir") — measured, not assumed, the
+      # first time this ran against Banking. A plain `Hecks.boot`
+      # needs no realm to address anything (unlike `Router.boot`), so
+      # leaving the world out entirely is the correct minimal isolation,
+      # not a workaround. `translations/*.bluebook` also deliberately
+      # excluded — those are earlier, superseded versions of the same
+      # domain; smoke-testing the current declaration is the point, not
+      # its whole history.
+      def isolate!(dir, scratch)
+        source = Adapters::Folder.new.bluebook_directory(dir)
+        target = File.join(scratch, "bluebook")
+        FileUtils.mkdir_p(target)
+        Dir.glob(File.join(source, "*.bluebook")).each { |file| FileUtils.cp(file, target) }
+      end
+
+      # AGGREGATES WALKED IN DECLARATION ORDER, on purpose — so whatever
+      # a LATER aggregate's own shape needs from an EARLIER one (a
+      # `TripItem` needing a real `PackingItem`, say) already exists by
+      # the time that aggregate's own turn comes, the same reason
+      # `Synthesizer#args_for`'s `created` map is threaded through in
+      # this same order.
+      def smoke_domain(dispatcher, domain)
+        chapter = dispatcher.registry.bluebook(domain)
+        return [] unless chapter
+
+        created  = {}
+        failures = []
+
+        chapter.aggregates.each do |aggregate|
+          creating, noncreating = aggregate.commands.partition(&:creates?)
+
+          creating.each do |command|
+            args = Synthesizer.args_for(chapter, aggregate, command, created)
+            begin
+              result = dispatcher.dispatch("#{domain}::#{aggregate.name}.#{command.hecks_name}", **args)
+              created[aggregate.name] = result.instance.id
+            rescue StandardError => e
+              failures << Failure.new(domain: domain, aggregate: aggregate.name, command: command.hecks_name,
+                                      error: "#{e.class}: #{e.message}")
+              next
+            end
+
+            noncreating.each do |nc_command|
+              nc_args = Synthesizer.args_for(chapter, aggregate, nc_command, created).merge(id: created[aggregate.name])
+              dispatcher.dispatch("#{domain}::#{aggregate.name}.#{nc_command.hecks_name}", **nc_args)
+            rescue StandardError => e
+              failures << Failure.new(domain: domain, aggregate: aggregate.name, command: nc_command.hecks_name,
+                                      error: "#{e.class}: #{e.message}")
+            end
+          end
+        end
+
+        chapter.read_models.each do |model|
+          root_id = created[model.reference_target]
+          next unless root_id # nothing was created for this root — nothing to smoke-test yet, not a failure
+
+          dispatcher.query("#{domain}.#{model.query_name}", model.reference_name => root_id)
+        rescue StandardError => e
+          failures << Failure.new(domain: domain, aggregate: model.name, command: "report(#{model.name})",
+                                  error: "#{e.class}: #{e.message}")
+        end
+
+        failures
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/synthesizer.rb

@@ -0,0 +1,95 @@
+module Hecks
+  module Bluebook
+    # ONE SYNTHESIZED ARGUMENT PER DECLARED ATTRIBUTE — never a random
+    # guess. Reads only real `IR` (`Aggregate`, `Command`,
+    # `Attribute`, `ValueObject`), so it works against ANY
+    # loaded bluebook, not one particular domain: a String becomes a
+    # fixed marker; an Integer becomes 0; a closed set uses ITS OWN
+    # first admitted member (never a value a real `one_of` would
+    # legitimately refuse); a reference uses whatever id the CALLER
+    # already knows for that target (`created`), so a command whose
+    # own shape depends on an earlier-created record — a `TripItem`
+    # needing a real `PackingItem`, say — gets something real to work
+    # with instead of a guess that would only ever fail.
+    #
+    # Extracted from `bin/interview`'s own smoke test, where this first
+    # got built and proved — the logic never actually knew anything
+    # about the Interview domain or any one app; it only ever read IR.
+    module Synthesizer
+      # THE ONLY TYPE NAMES THAT ARE EVER TRULY SCALAR — anything else
+      # a value object's own field names is ANOTHER value object,
+      # nested (`Pizza.price_cents: Price`, itself wrapping `cents:
+      # Integer` — a real, ordinary shape, not an edge case). Missing
+      # this the first time round meant a nested field silently
+      # synthesized as the bare string `"smoke-test"` instead of the
+      # real nested structure a command actually declares — caught
+      # only by testing against Pizzas instead of re-testing against
+      # the one simpler domain this was first built for, where every
+      # value object happened to be single-field and primitive-typed.
+      # THE SAME LIST `Attribute::PRIMITIVES` holds, referenced rather
+      # than repeated. It was a second, byte-identical copy — and only
+      # the Attribute one is held to `vocabulary.bluebook` by
+      # spec/vocabulary_conformance_spec, so this copy could drift from
+      # the language and nothing would say so.
+      PRIMITIVES = Attribute::PRIMITIVES
+
+      module_function
+
+      # `chapter`/`aggregate` are the real `Bluebook`/`Aggregate`
+      # the command belongs to — needed to resolve a value object type
+      # name back to its own declared shape. `created` maps an
+      # aggregate NAME to a real id already minted for it earlier in
+      # the same run; a reference whose target isn't in there yet gets
+      # a placeholder instead of failing outright, since the caller may
+      # not care about that particular argument's real value.
+      def args_for(chapter, aggregate, command, created = {})
+        command.attributes.to_h do |attribute|
+          if attribute.reference?
+            [attribute.name, created.fetch(attribute.type.target_name, "smoke-test-id")]
+          else
+            [attribute.name, value_for(chapter, aggregate, attribute.type)]
+          end
+        end
+      end
+
+      # A value object's OWN synthesized value — its first admitted
+      # member if it's a closed set (the one value guaranteed not to be
+      # refused), otherwise one synthesized scalar per declared field.
+      # Falls back to searching every aggregate in the chapter, the
+      # same tolerance `bin/interview shape`'s own lookup already
+      # needed: a value object referenced by name doesn't have to be
+      # declared on the SAME aggregate using it.
+      def value_for(chapter, aggregate, type_name)
+        value_object = aggregate.value_object(type_name) ||
+                       chapter.aggregates.filter_map { |a| a.value_object(type_name) }.first
+        return "smoke-test" unless value_object
+
+        return value_object.members.first.to_h if value_object.respond_to?(:closed_set?) && value_object.closed_set? && value_object.members.any?
+
+        value_object.attributes.to_h { |field| [field.name, field_value_for(chapter, aggregate, field.type)] }
+      end
+
+      # A single field's own synthesized value — a plain scalar if its
+      # type is one of the true primitives, otherwise that type names
+      # ANOTHER value object, resolved the identical way `value_for`
+      # resolves any other one (its own closed set or its own nested
+      # fields, however deep that nesting actually goes).
+      def field_value_for(chapter, aggregate, type_name)
+        PRIMITIVES.include?(type_name.to_s) ? scalar_for(type_name) : value_for(chapter, aggregate, type_name)
+      end
+
+      # A bare primitive's own synthesized value. Never used for a
+      # closed set's OWN field (that's `value_for`'s job, reading the
+      # set's real first member) — only for a plain scalar field with
+      # no declared vocabulary to respect.
+      def scalar_for(primitive)
+        case primitive.to_s
+        when "Integer" then 0
+        when "Float" then 0.0
+        when "TrueClass", "FalseClass" then false
+        else "smoke-test"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/translation.rb

@@ -0,0 +1,92 @@
+module Hecks
+  module Bluebook
+    # One field crossing a value-object boundary: a scalar becoming a VO
+    # member, a VO member becoming a scalar, or a rename across the move.
+    # Paths are dotted ("price.cents") for a VO member, bare otherwise.
+    TranslationMove = Struct.new(:from, :to)
+
+    # One field whose VALUE, not just its name or position, changed —
+    # an old value has nothing in common with a new one, so the only
+    # honest way to bridge it is a declared, exhaustive lookup table.
+    # Paths follow `TranslationMove`'s convention (dotted reaches a VO
+    # member); `values` maps every old-era value that can appear to its
+    # new-era replacement.
+    TranslationConvert = Struct.new(:from, :to, :values)
+
+    # A value object's or entity's own TYPE NAME changed with its member
+    # structure unchanged — the one drift `rename`/`move` cannot express,
+    # because the attribute kept its name and only the type it points at
+    # was renamed. Mirrors `was:` one level deeper.
+    TranslationRetype = Struct.new(:from, :to)
+
+    # A computed transform — rescale, reformat, split, merge — whose only
+    # implementation is the SQL expression itself, evaluated exclusively
+    # inside the compiled Postgres head. No in-process reference exists
+    # to check it against; any aggregate carrying one refuses to boot on
+    # every other adapter.
+    TranslationCompute = Struct.new(:from, :to, :sql)
+
+    # The aggregate's own IDENTITY changed what it's computed from — not
+    # a field crossing a boundary (that's `move`), a value objects's type
+    # name (`retype`), or a value transform (`compute`): the record's own
+    # key. No `from:`/`to:` path, unlike every other rule here, because
+    # nothing is being consumed from or moved into `state` — the state
+    # a record already holds is untouched; only what identifies it is
+    # recomputed. Same SQL-only, Postgres-only, no-in-process-reference
+    # shape `compute` already has, and for the same reason: there is
+    # nothing to check this against outside the compiled head.
+    TranslationRekey = Struct.new(:sql)
+
+    # A newly added, required attribute with no source in old data at
+    # all — not a rename, move, or convert, all of which need a FROM
+    # path in the old shape. `default` is the value an existing record
+    # reads until the next command against it writes a real one; unlike
+    # `compute`, this is adapter-agnostic — applied in-process by
+    # `Lineage#translate`, the same as rename/move/drop, because there is
+    # nothing to compute, only a value to declare.
+    TranslationBackfill = Struct.new(:name, :default)
+
+    # One aggregate's part of a translation: which attributes were
+    # renamed, moved, converted, or deliberately dropped on the way from
+    # the old era to the new one. `drops` exists so data loss is a
+    # declared decision, not a field that quietly stopped being
+    # explained.
+    class TranslationAggregate
+      attr_reader :name, :was, :renames, :moves, :converts, :drops, :retypes, :computes, :rekeys, :backfills
+
+      def initialize(name:, was: nil, renames: {}, moves: [], converts: [], drops: [], retypes: [],
+                     computes: [], rekeys: [], backfills: [])
+        @name      = name.to_s
+        @was       = was&.to_s
+        @renames   = renames
+        @moves     = moves
+        @converts  = converts
+        @drops     = drops
+        @retypes   = retypes
+        @computes  = computes
+        @rekeys    = rekeys
+        @backfills = backfills
+      end
+    end
+
+    # A declared map from one era of a domain's storage shape to the
+    # next. Renames and moves — the smallest slice that proves the
+    # concept: old records are translated when they are replayed, never
+    # rewritten. `retired` acknowledges aggregates that are gone
+    # outright — not renamed — so their disappearance is a decision,
+    # not an accident.
+    class Translation
+      attr_reader :domain, :from, :to, :aggregates, :retired
+
+      def initialize(domain:, from:, to:, aggregates: [], retired: [])
+        @domain     = domain.to_s
+        @from       = from
+        @to         = to
+        @aggregates = aggregates
+        @retired    = retired
+      end
+
+      def for_aggregate(name) = @aggregates.find { |aggregate| aggregate.name == name.to_s }
+    end
+  end
+end

data/lib/hecks/bluebook/value_object.rb

@@ -0,0 +1,66 @@
+require_relative "behaviour/value_object"
+
+module Hecks
+  module Bluebook
+    Invariant = Struct.new(:description, :canonical, :predicate, keyword_init: true)
+
+    # A value object — a DECLARATION HOLDER, never instantiated.
+    #
+    # `ValueObjectBuilder` returns an anonymous subclass whose singleton
+    # carries the declaration : attributes, invariants, members. Nothing ever
+    # calls `.new` on one — coercion builds `Runtime::Value` wrappers, and
+    # invariants run as canonical text through the Evaluator. The runtime
+    # reaches a shape through `aggregate.value_object(name)`, the IR's own
+    # finder ; there is no constant nesting and no second index.
+    #
+    # `to_h` does not move. It is a byte-for-byte contract pinned by the
+    # golden fixtures, so it keeps spelling the short declared name, which
+    # is what `hecks_name` carries. DECLARATIONS IN THE GRAPH, STRINGS IN THE
+    # EXPORT.
+    class ValueObject
+      extend Construct
+      # EXTENDED, not included — this construct is a class, so its
+      # emission is a class method. See Hecks::IR's own note on
+      # the two shapes.
+      extend Hecks::IR
+      extend Behaviour::ValueObject
+
+      emits_ir(
+        name:       :hecks_name,
+        attributes: many(:attributes),
+        invariants: -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        closed_set: :closed_set?,
+        # THE FIELD NAME IS STRINGIFIED, NEVER THE VALUE. A `member` row can
+        # hold any of the scalar types an attribute declares — `Integer 84`
+        # (`StatementFrequency#retention_months`, statements.bluebook), not
+        # only `String` — and `value.to_s` used to erase that on the way
+        # out, so `84` and `"84"` (a member some other row might
+        # legitimately spell as text) became indistinguishable once they
+        # reached `to_h`. The declared name still moves (`field.to_s`) —
+        # that half was never a Ruby object with a type to lose.
+        members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value] } } }
+      )
+
+      class << self
+        attr_reader :attributes, :invariants, :members
+
+        # One declared shape — a subclass rather than an instance, so the thing
+        # the bluebook declares and the thing Ruby holds are one object.
+        def declare(name:, attributes: [], invariants: [], members: [], closed_set: !members.empty?)
+          shape = Class.new(self)
+          shape.hecks_name = name.to_s
+          shape.absorb(attributes: attributes, invariants: invariants,
+                       members: members, closed_set: closed_set)
+          shape
+        end
+
+        def absorb(attributes:, invariants:, members:, closed_set:)
+          @attributes = attributes
+          @invariants = invariants
+          @members    = members
+          @closed_set = closed_set
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook.rb

@@ -0,0 +1,74 @@
+# Hecks::Bluebook
+#
+# Everything a .bluebook file becomes on its way to running: the expression
+# language (expression/), the model itself (the chapter class plus
+# everything it declares), the assembly that turns
+# declarations back into that graph (assembly.rb + assembly/), the authoring
+# DSL (dsl/), and the meta-validator that judges a chapter against the
+# language's own grammar (meta_validator.rb + meta_validator/).
+#
+# The require order below preserves the boot order the flat list in
+# lib/hecks.rb used to spell: expression and IR first (pure
+# declarations), assembly's collaborators before its face, the DSL before
+# the meta-validator that its builders call at build time.
+
+module Hecks
+  # Declared as a CLASS, not a module — `Hecks::Bluebook` IS a
+  # chapter (bluebook/chapter.rb carries its body). Everything a chapter
+  # declares nests under it, as do the ways to build one (`DSL`) and to
+  # judge one (`MetaValidator`). Reopening this anywhere must say `class`.
+  module Bluebook
+  end
+end
+
+# What the chapter's own files lean on at class-body level (`extend
+# Construct`, the assembly's QuerySpecification marks) — required here
+# because those files' contents are frozen and cannot say so themselves.
+require_relative "construct"
+require_relative "literal"
+require_relative "query_specification"
+
+require_relative "bluebook/expression"
+# THE MODEL ITSELF — the chapter class's own body first, then everything
+# a chapter declares. Order matters only for reading: each is a bag of
+# declarations with no load-time cross-references.
+require_relative "bluebook/chapter"
+require_relative "bluebook/reference"
+require_relative "bluebook/attribute"
+require_relative "bluebook/value_object"
+require_relative "bluebook/command"
+require_relative "bluebook/lifecycle"
+require_relative "bluebook/query"
+require_relative "bluebook/read_model"
+require_relative "bluebook/entity"
+require_relative "bluebook/domain_port"
+require_relative "bluebook/policy"
+require_relative "bluebook/process_manager"
+require_relative "bluebook/aggregate"
+require_relative "bluebook/hexagon"
+require_relative "bluebook/translation"
+
+require_relative "bluebook/assembly/contract"
+require_relative "bluebook/assembly/contracts"
+require_relative "bluebook/assembly/specializer"
+require_relative "bluebook/assembly/build"
+require_relative "bluebook/assembly/marks"
+require_relative "bluebook/assembly/aggregate_assembly"
+require_relative "bluebook/assembly"
+
+require_relative "bluebook/project_loader"
+
+require_relative "bluebook/dsl"
+require_relative "bluebook/pattern_subset"
+
+require_relative "bluebook/meta_validator"
+require_relative "bluebook/meta_validator/plan"
+require_relative "bluebook/meta_validator/readings"
+require_relative "bluebook/meta_validator/judge"
+require_relative "bluebook/meta_validator/shapes"
+require_relative "bluebook/meta_validator/reconstruction"
+require_relative "bluebook/meta_validator/world_judge"
+require_relative "bluebook/meta_validator/port_judge"
+require_relative "bluebook/meta_validator/adapter_judge"
+require_relative "bluebook/meta_validator/translation_judge"
+require_relative "bluebook/meta_validator/syntax_boot"