hecks 0.2.0 → 1.0.0

data/lib/hecks/bluebook/process_manager.rb

@@ -0,0 +1,128 @@
+require_relative "behaviour/process_manager"
+require_relative "../ir"
+
+module Hecks
+  module Bluebook
+    # `compensates` — a SECOND `DispatchSpec`, shape-identical to this
+    # one, naming the command that undoes THIS dispatch specifically
+    # (see `ProcessManagerBuilder::HandlerBuilder#dispatch_impl`'s own
+    # comment). `nil` for a dispatch with nothing to undo (a pure
+    # bookkeeping mark, or one whose own effect is superseded by a later
+    # command rather than needing its own compensation). Never nested
+    # further — a compensation is not itself compensable; no known
+    # corpus need, and ADR 0025's own "a word earns its place by being
+    # used" bar would refuse a second level speculatively.
+    DispatchSpec = Struct.new(:command_name, :with_spec, :compensates, keyword_init: true) do
+      # A Struct already answers to_h; including the mixin puts the
+      # DECLARED emission ahead of Struct's own in the ancestry, which
+      # is what makes the shape data rather than a method body.
+      include Hecks::IR
+
+      emits_ir(
+        command_name: -> { command_name.to_s },
+        with_spec:    -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } },
+        compensates:  one(:compensates)
+      )
+    end
+
+    ProcessManagerHandler = Struct.new(:event_type, :from_state, :to_state,
+                                       :dispatches, keyword_init: true) do
+      include Hecks::IR
+
+      emits_ir(
+        event_type: -> { event_type.to_s },
+        from_state: -> { from_state.to_s },
+        to_state:   -> { to_state.to_s },
+        dispatches: many(:dispatches)
+      )
+    end
+
+    # The compensation half of a procedure, as its own thing.
+    #
+    # A PROCESS MANAGER coordinates: legs, states, an opinion about who goes
+    # next. A SAGA undoes: what makes the world good again when a leg it
+    # dispatched is refused. Two concepts, and the industry slurs them into one
+    # word — so here they are two objects, and a procedure either has a saga or
+    # does not.
+    #
+    # `undoes` is the ordered list of commands the compensation sends — a
+    # STATIC PREVIEW, declaration order (`Behaviour::ProcessManager#saga`),
+    # not one instance's own runtime history. Per-dispatch compensation
+    # (`compensates`, on the step it compensates for) moved most of what
+    # a saga undoes off this leg's own hand-written body and onto
+    # whichever forward dispatch each one undoes — this reads every
+    # declared `compensates` across the WHOLE saga first, then whatever
+    # this leg's own hand-written body still lists, for compensation
+    # that isn't expressible as "undo command X." WHICH of a declared
+    # `compensates` actually fires for one instance, and in what order
+    # (newest-first, completed-legs-only), is `SagaInterpreter`'s own
+    # dynamic `completed_compensations` — a per-instance runtime fact
+    # this declaration-only object could never hold.
+    #
+    # NAMING COLLISION, ONCE FLAGGED, NOW RESOLVED — `command`'s own
+    # `corrects event, reverses: true` (docs/implemented/decisions/0036-
+    # corrects-is-an-appended-fact-not-a-rewrite.md) already claimed
+    # `reverses` for a different meaning: auto-deriving a command's OWN
+    # corrective mutation from a past EVENT, not a saga's own
+    # compensating leg from a past DISPATCH. This feature keeps
+    # `reverses` reserved for `corrects` and uses `compensates` for
+    # per-dispatch saga compensation instead — a deliberate choice, not
+    # an accidental collision.
+    Saga = Struct.new(:trigger, :from_state, :to_state, :compensations, keyword_init: true) do
+      def undoes = compensations.map(&:command_name)
+
+      def to_s = "#{trigger} → #{to_state} (#{undoes.join(', ')})"
+    end
+
+    class ProcessManager
+      # The BLUEBOOK's name for this construct, asked the same way of a class
+      # that has crossed over and of an IR object that has not. Collapses into
+      # Construct when this one crosses.
+      # The trigger of a compensating leg. Not an event name — no aggregate
+      # announces that a leg the procedure dispatched was declined — so it lives
+      # here beside the thing it triggers rather than in the runtime that
+      # notices it. Declared in the language's Trigger vocabulary, which
+      # spec/vocabulary_conformance_spec holds to this constant.
+      REFUSED = Hecks::Vocabulary.fetch("Trigger").first
+
+      include Hecks::IR
+      include Behaviour::ProcessManager
+
+      emits_ir(
+        name:          :name,
+        # M11 — `&.`, not `.`: a DSL-built process manager always carries
+        # a real `correlates_by` (`ProcessManagerBuilder#build` refuses to
+        # mint one without it), but the IR class itself defaults it to
+        # `nil` and is what `Assembly::Build`'s `:identity` reader
+        # (`value&.to_sym`) round-trips against. A bare `.to_s` mapped
+        # that absent case to `""`, indistinguishable on the wire from a
+        # real empty name and read back as the wrong, non-nil `:""`
+        # instead of `nil` — the same nil-erasure S1 fixed for
+        # `render_value`, one field over. `correlates_by` is always a
+        # bare Symbol (`SagaInterpreter` hash-looks-up a payload by it),
+        # never a `Literal`-encoded polymorphic value, so this stays a
+        # local `&.` rather than routing through `Literal.render` — that
+        # would wrap a real value in a leading `:` and break both the
+        # `:identity` reader's plain `to_sym` and the pinned golden IR
+        # fixtures' bare-string spelling (`"reference.value"`).
+        correlates_by: -> { correlates_by&.to_s },
+        starts_on:     :starts_on,
+        ends_on:       :ends_on,
+        states:        :states,
+        handlers:      many(:handlers)
+      )
+
+      attr_reader :name, :correlates_by, :starts_on, :ends_on, :states, :handlers
+
+      def initialize(name:, correlates_by: nil, starts_on: nil, ends_on: nil,
+                     states: [], handlers: [])
+        @name          = name.to_s
+        @correlates_by = correlates_by
+        @starts_on     = starts_on
+        @ends_on       = ends_on
+        @states        = states
+        @handlers      = handlers
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/project_discovery.rb

@@ -0,0 +1,30 @@
+require "find"
+
+module Hecks
+  module Bluebook
+    # Finds domain declaration folders without loading or executing them.
+    class ProjectDiscovery
+      SKIPPED_DIRECTORIES = %w[.git .bundle data node_modules target tmp vendor generated coverage].freeze
+
+      attr_reader :root
+
+      def initialize(root)
+        @root = File.expand_path(root)
+      end
+
+      def bluebook_directories
+        found = []
+        Find.find(root) do |path|
+          if File.directory?(path)
+            if SKIPPED_DIRECTORIES.include?(File.basename(path))
+              Find.prune
+            elsif File.basename(path) == "bluebook" && Dir.glob(File.join(path, "*.bluebook")).any?
+              found << path
+            end
+          end
+        end
+        found.sort
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/project_loader.rb

@@ -0,0 +1,40 @@
+require_relative "project_discovery"
+require_relative "project_register"
+
+module Hecks
+  module Bluebook
+    # Boots each discovered directory and feeds its declarations into the
+    # deterministic project register. Discovery and FQN registration live in
+    # their own objects so either can be used without executing domains.
+    class ProjectLoader
+      Entry          = ProjectRegister::Entry
+      DuplicateFqn   = ProjectRegister::DuplicateFqn
+      MissingRealm   = ProjectRegister::MissingRealm
+      LatestMismatch = ProjectRegister::LatestMismatch
+
+      attr_reader :root, :discovery, :register
+
+      def self.load(root) = new(root).load
+
+      def initialize(root, discovery: ProjectDiscovery.new(root), register: ProjectRegister.new)
+        @root      = File.expand_path(root)
+        @discovery = discovery
+        @register  = register
+      end
+
+      def load
+        discovery.bluebook_directories.each do |directory|
+          runtime = Runtime.boot(directory)
+          register.register(runtime.registry.bluebooks.values, runtime.registry, runtime, directory)
+        end
+        self
+      end
+
+      def entries = register.entries
+      def fetch(address) = register.fetch(address)
+      def include?(address) = register.include?(address)
+      def commands = register.commands
+      def queries  = register.queries
+    end
+  end
+end

data/lib/hecks/bluebook/project_register.rb

@@ -0,0 +1,82 @@
+module Hecks
+  module Bluebook
+    # The callable catalogue for a discovered project. It knows how Bluebook
+    # declarations become public FQNs, but never searches or boots folders.
+    class ProjectRegister
+      Entry = Struct.new(:fqn, :source_directory, :dispatcher, :declared_verb, :domain_version, keyword_init: true) do
+        def command? = fqn.command?
+        def query?   = fqn.query?
+      end
+
+      class DuplicateFqn < StandardError; end
+      class MissingRealm < StandardError; end
+      class LatestMismatch < StandardError; end
+
+      attr_reader :entries
+
+      def initialize
+        @entries = {}
+      end
+
+      def fetch(address) = entries.fetch(address.to_s)
+      def include?(address) = entries.key?(address.to_s)
+      def commands = entries.values.select(&:command?)
+      def queries  = entries.values.select(&:query?)
+
+      def register(bluebooks, registry, dispatcher, directory)
+        bluebooks.each do |bluebook|
+          world = registry.world(bluebook.name)
+          realm = world&.realm
+          raise MissingRealm, "#{bluebook.name} in #{directory} has no world realm" if realm.to_s.empty?
+          if world.latest && bluebook.version && world.latest != bluebook.version
+            raise LatestMismatch,
+                  "#{bluebook.name} in #{directory} declares latest #{world.latest.inspect}, not #{bluebook.version.inspect}"
+          end
+
+          bluebook.aggregates.each do |aggregate|
+            aggregate.commands.each do |command|
+              add(Fqn.command(realm: realm, domain: bluebook.name, version: bluebook.version,
+                              aggregate: aggregate.hecks_name, command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version) if bluebook.version
+              add(Fqn.command(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
+                              command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version) if current?(
+                                bluebook, world
+                              )
+            end
+            aggregate.queries.each do |query|
+              name = Naming.snake(query.name)
+              add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
+                            aggregate: aggregate.hecks_name, query: name), directory, dispatcher, query.name, bluebook.version) if bluebook.version
+              add(Fqn.query(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
+                            query: name), directory, dispatcher, query.name, bluebook.version) if current?(bluebook, world)
+            end
+          end
+          bluebook.read_models.each do |model|
+            add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
+                          query: model.query_name), directory, dispatcher, model.query_name, bluebook.version) if bluebook.version
+            add(Fqn.query(realm: realm, domain: bluebook.name, query: model.query_name),
+                directory, dispatcher, model.query_name, bluebook.version) if current?(bluebook, world)
+          end
+        end
+        self
+      end
+
+      private
+
+      def current?(bluebook, world)
+        bluebook.version.nil? || world.latest == bluebook.version
+      end
+
+      def add(fqn, directory, dispatcher, declared_verb, domain_version)
+        existing = entries[fqn.to_s]
+        if existing
+          raise DuplicateFqn, "#{fqn} is declared in both #{existing.source_directory} and #{directory}"
+        end
+
+        entries[fqn.to_s] = Entry.new(
+          fqn: fqn, source_directory: directory, dispatcher: dispatcher,
+          declared_verb: declared_verb, domain_version: domain_version
+        )
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/query.rb

@@ -0,0 +1,61 @@
+require_relative "behaviour/query"
+
+module Hecks
+  module Bluebook
+    def self.render_value(value) = Literal.render(value)
+
+    # A query — an ASK, declared on an aggregate or on one of its entities.
+    #
+    # It crosses over as an INSTANCE rather than a class, and the reason is worth
+    # stating because it is the boundary of the pattern. A query inherits its
+    # whole body from `QuerySpecification::Common::Options` — `wheres`,
+    # `order_by`, `limit`, `offset`, `cursor`,
+    # `authorization`, `null_semantics`, `inspection` — and those
+    # are INSTANCE methods that the runtime and the SQLite adapter both read.
+    # Hoisting the declaration onto a metaclass would put the identity and the
+    # specification on opposite sides of the object.
+    #
+    # And nothing is lost, because `Class#name` was the only reason a construct
+    # ever needed a second word for its own name. An instance answers `name`
+    # truthfully. So a query gains an owner and an identity — which is what the
+    # graph is for — and keeps the name it always had.
+    class Query < QuerySpecification::Common::Options
+      include Construct
+
+      include Hecks::IR
+      include Behaviour::Query
+
+      emits_ir(
+        name:        :name,
+        description: :description,
+        attributes:  many(:attributes),
+        wheres:      many(:wheres),
+        order_by:    one(:order_by),
+        limit:       one(:limit)
+      )
+
+      attr_reader :name, :description, :attributes
+
+      def initialize(name:, description: nil, attributes: [], wheres: [],
+                     order_by: nil, limit: nil, offset: nil, cursor: nil,
+                     authorization: nil, null_semantics: nil,
+                     inspection: nil)
+        null_semantics ||= QuerySpecification::Common::NullSemantics.default
+        super(wheres: wheres, order_by: order_by, limit: limit, offset: offset, cursor: cursor,
+              authorization: authorization,
+              null_semantics: null_semantics, inspection: inspection)
+        @name        = name.to_s
+        @hecks_name  = @name
+        @description = description
+        @attributes  = attributes
+      end
+
+      # A query's shape is NOT fixed — `extra_options_to_h` carries
+      # whatever options the specification layer grew (count, median,
+      # group_by, scope_to). Declared emission covers the settled part
+      # and `super` hands it over; the tail stays dynamic, which is the
+      # honest description of it.
+      def to_h = super.merge(extra_options_to_h)
+    end
+  end
+end

data/lib/hecks/bluebook/read_model.rb

@@ -0,0 +1,109 @@
+require_relative "behaviour/read_model"
+
+module Hecks
+  module Bluebook
+    # A read model — an ask that gathers heads from more than one aggregate.
+    #
+    # Like a query it crosses over as an INSTANCE, and for the same reason: its
+    # body is inherited from `QuerySpecification::ReadModel::Specification`, whose
+    # readers the runtime and the SQLite adapter both call on the object. It gains
+    # an identity and an owner ; it keeps the name it always had, because only a
+    # CLASS ever had a competing answer for `name`.
+    class ReadModel < QuerySpecification::ReadModel::Specification
+      include Construct
+
+      include Hecks::IR
+      include Behaviour::ReadModel
+
+      emits_ir(
+        name:             :name,
+        description:      :description,
+        reference_name:   :reference_name,
+        reference_target: :reference_target,
+        query_name:       :query_name,
+        wheres:           many(:wheres),
+        order_by:         one(:order_by),
+        limit:            one(:limit)
+      )
+
+      attr_reader :name, :description, :reference_name, :reference_target, :aggregate_heads, :group_by,
+                  :count, :median_field
+
+      # `reference_name:`/`reference_target:` are nil for a ROOTLESS read
+      # model (no `reference_to` declared) — `&.` throughout, rather than
+      # the `.to_s`/`.to_sym` this used to require unconditionally, so
+      # `reference_target.nil?` stays a real, checkable fact for the
+      # interpreter instead of silently becoming `""`.
+      def initialize(name:, description: nil, reference_name: nil, reference_target: nil, aggregate_heads: [],
+                     group_by: [], count: nil, median_field: nil, **options)
+        super(joins: aggregate_heads, **options)
+        @name             = name.to_s
+        @hecks_name       = @name
+        @description      = description
+        @reference_name   = reference_name&.to_sym
+        @reference_target = reference_target&.to_s
+        @aggregate_heads  = aggregate_heads
+        # Hash rows (`{field: :agg}`), same shape as `aggregate_heads` —
+        # `group_by_fields` is the convenience reader everything but
+        # `to_h`/the Judge's own generic walk actually wants.
+        @group_by         = group_by
+        # ABSENT IS NOT FALSE. `@count` stays nil rather than becoming
+        # `false` when undeclared — the same "if you declare it, declare
+        # something" reading `Lifecycle`'s own optional fields rely on
+        # (MetaValidator::Judge#setters skips a setter whose every
+        # source is `nil`, so an ALWAYS-false `@count` would dispatch
+        # `ReadModel.Count` on every read model that never wrote the
+        # word at all). `!!count` collapses a truthy DSL `true` (or a
+        # reconstructed `true`) to the same `true`/`nil` pair either path
+        # produces — never `false`.
+        @count            = count ? true : nil
+        @median_field     = median_field&.to_sym
+      end
+
+      # `.to_sym` regardless of source — the DIRECT builder path stores
+      # symbols, but `Reconstruction::Shapes#group_by_field` (the
+      # replayed-from-the-meta-domain path every REAL boot actually
+      # goes through) reads the field back as a String, the same way
+      # `aggregate_heads`' own `:as` does. Row hash KEYS built by
+      # `Value.materialize_unwrapped` are symbols (`attr.name`), so
+      # this has to be too, or `row[field]` in `nest` silently misses.
+
+      # `wheres`/`order_by`/`limit` are spelled explicitly here, the SAME
+      # mechanism `Query#to_h` already uses (query.rb, read directly
+      # before this was written) — always present, `wheres` a (possibly
+      # empty) array and `order_by`/`limit` nil when undeclared, exactly
+      # like a Query's. `extra_options_to_h` still excludes these three by
+      # name (options.rb), so nothing here double-spells them; the two
+      # constructs now share one encoding for the same three words rather
+      # than a reader needing to learn a second one. See this file's own
+      # `filtered_head_name` and language/bluebook/syntax.bluebook's
+      # `ReadModel` `where`/`order_by`/`limit` member rows for the history
+      # of why this WAS narrower, and 2026-08-11's read-model where/
+      # order_by/limit task for why it stopped being.
+      # Same dynamic tail as a Query's, plus two collections whose
+      # ROWS are plain hashes rather than constructs — they are
+      # normalised here rather than by `many`, which recurses through
+      # `to_h` and would have nothing to call.
+      # `count`/`median_field` are ABSENT (no key at all), not `nil`,
+      # when undeclared — unlike `group_by` (always a `[]`, never
+      # missing) they are the FIRST fields this construct has ever
+      # added that no OLDER real corpus member could possibly carry, so
+      # merging them unconditionally would have put a `null` onto every
+      # existing read model's own wire shape (banking's
+      # `ComplianceDashboard`/`CustomerPortfolio`, the language's own
+      # `WholeBluebook`, ...) for a fact nothing about them changed —
+      # the exact `extra_options_to_h` reads for `cursor`/`offset`/etc,
+      # applied here for the same reason.
+      def to_h
+        reductions = {}
+        reductions[:count] = true if @count
+        reductions[:median_field] = @median_field.to_s if @median_field
+        super
+          .merge(aggregate_heads: @aggregate_heads.map { |head| head.merge(as: head[:as].to_s) })
+          .merge(group_by: @group_by.map { |row| row.merge(field: row[:field].to_s) })
+          .merge(reductions)
+          .merge(extra_options_to_h)
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/reference.rb

@@ -0,0 +1,74 @@
+module Hecks
+  module Bluebook
+    # An attribute that points at another aggregate's head.
+    #
+    # This used to be the STRING `"Reference<Customer>"`, minted by
+    # `AggregateBuilder#reference_to` and `CommandBuilder#cross_reference` from
+    # a real constant that had just been handed in, and then parsed back apart
+    # by a regex in the command interpreter, by string equality in the read-model
+    # interpreter and the SQLite adapter, and by `delete_prefix` in the bluebook
+    # builder. Five readers of a spelling one writer invented.
+    #
+    # It holds the TARGET instead, and answers `resolve` with the target's
+    # Aggregate. Resolution is LAZY and deliberately so: `reference_to
+    # Customer` may name an aggregate declared lower in the file — banking's
+    # Account points at Customer and survives only because Customer happens to
+    # be written above — so the edge cannot be resolved at declaration time.
+    # It resolves through the chapter's own IR (`Bluebook#aggregate`),
+    # which is scoped by construction : the lookup cannot walk anywhere but
+    # this chapter's declared heads, so a same-named aggregate in another
+    # loaded domain is unreachable rather than defended against.
+    #
+    # `to_s` still spells `"Reference<Customer>"`, because `Attribute#to_h` is
+    # part of the pinned byte-for-byte export contract. IR objects in
+    # the graph, strings in the export.
+    class Reference
+      attr_reader :target_name
+
+      # The Aggregate whose declaration carries this reference — the way
+      # up to the chapter, stamped once every sibling has been read.
+      attr_accessor :declared_in
+
+      def initialize(target_name)
+        @target_name = Naming.demodulise(target_name).to_s
+      end
+
+      # The Aggregate this points at, or nil when the target belongs to
+      # ANOTHER domain — a cross-domain target may legitimately not be loaded,
+      # the same reading `across` policies get.
+      def resolve
+        unless declared_in
+          raise DSL::Malformed,
+                "#{self} cannot say which aggregate declares it, so it cannot " \
+                "resolve — a reference that resolves to nothing is checked " \
+                "against nothing"
+        end
+
+        declared_in.hecks_owner&.aggregate(@target_name)
+      end
+
+      # The IR spelling, the one the export carries.
+      def to_s = "Reference<#{@target_name}>"
+      def inspect = "#<Reference #{@target_name}>"
+
+      # VALUE EQUALITY, not identity — without this, two references to
+      # the SAME target, parsed from two SEPARATE bluebook reads (era
+      # N's own boot and a held era's own shadow reconstruction,
+      # coverage_check.rb's own comparison), are different objects and
+      # compare unequal by Ruby's default `==`. `EraGuard::ShapeDiff
+      # #diff_type`'s `held_type != current_type` check then reads as
+      # true for EVERY reference_to attribute on EVERY mint, regardless
+      # of whether the reference actually changed — a real refusal for
+      # attributes nothing about. `declared_in` (which aggregate carries
+      # this reference) is deliberately excluded: the same reference
+      # attribute exists once, but its `held_type`/`current_type` come
+      # from separately-parsed bluebooks with structurally different
+      # (if same-shaped) owning aggregates, and `declared_in` is a
+      # cross-reference for `resolve`, not part of what this attribute
+      # itself IS.
+      def ==(other) = other.is_a?(Reference) && target_name == other.target_name
+      alias eql? ==
+      def hash = [self.class, target_name].hash
+    end
+  end
+end