hecks 2.8.0 → 3.0.0

data/lib/hecks/bench/suite.rb

@@ -0,0 +1,98 @@
+module Hecks
+  module Bench
+    # Runs every requested target against every requested domain and aggregates the runs.
+    # Runs are interleaved across targets so unrelated machine load lands on all of them.
+    module Suite
+      TARGETS = %w[ruby:memory ruby:sqlite ruby:postgres ruby:postgres_era rust].freeze
+
+      # What to measure; `rust_binary` needs a single domain, since a binary embeds exactly one.
+      Config = Struct.new(:domains, :targets, :warmup, :iterations, :runs, :rust_binary, keyword_init: true)
+
+      module_function
+
+      def call(config, log: $stderr)
+        validate(config)
+        load_before = Environment.load_average
+        skipped = unavailable_targets(config)
+        active = config.targets - skipped.map { |entry| entry[:target] }
+        skipped.each { |entry| log.puts "skip #{entry[:target]}: #{entry[:reason]}" }
+        results = config.domains.flat_map { |domain| measure_domain(Workload.fetch(domain), active, config, log) }
+        environment = Environment.describe
+        environment[:load_average] = { before: load_before, after: environment[:load_average] }
+        { environment: environment.merge(postgres: postgres_version(active)),
+          config: config.to_h, results: results, skipped: skipped }
+      end
+
+      def validate(config)
+        unknown = config.targets - TARGETS
+        raise ArgumentError, "unknown target #{unknown.first.inspect} — one of #{TARGETS.join(', ')}" if unknown.any?
+
+        config.domains.each { |domain| Workload.fetch(domain) }
+        if config.iterations < 1 || config.runs < 1 || config.warmup.negative?
+          raise ArgumentError, "iterations and runs must be at least 1, and warmup at least 0"
+        end
+        return unless config.rust_binary && config.domains.size > 1
+
+        raise ArgumentError, "--rust-binary embeds one domain, so it needs exactly one --domain"
+      end
+
+      def unavailable_targets(config)
+        postgres = PostgresProbe.unavailable_reason if config.targets.any? { |t| t.start_with?("ruby:postgres") }
+        rust = RustRunner.unavailable_reason(binary: config.rust_binary) if config.targets.include?("rust")
+        config.targets.filter_map do |target|
+          reason = target == "rust" ? rust : (postgres if target.start_with?("ruby:postgres"))
+          { target: target, reason: reason } if reason
+        end
+      end
+
+      def measure_domain(workload, targets, config, log)
+        binaries = {}
+        summaries = Hash.new { |hash, target| hash[target] = [] }
+        config.runs.times do |index|
+          targets.each do |target|
+            run = measure_once(workload, target, config, binaries)
+            summaries[target] << run.summary
+            log.puts progress_line("#{workload.name} #{target}", "run #{index + 1}/#{config.runs}", summaries[target].last)
+          end
+        end
+        targets.map { |target| aggregate(workload.name, target, summaries[target]) }
+      end
+
+      def progress_line(label, position, summary)
+        "#{label.ljust(27)} #{position}  #{summary[:throughput_per_s].round.to_s.rjust(8)} cmds/s  " \
+          "p50 #{summary[:p50_us].to_s.rjust(9)} us  p99 #{summary[:p99_us].to_s.rjust(9)} us"
+      end
+
+      def measure_once(workload, target, config, binaries)
+        if target == "rust"
+          binary = config.rust_binary || (binaries[workload.name] ||= RustRunner.build(workload.name))
+          RustRunner.call(workload, binary: binary, warmup: config.warmup, iterations: config.iterations)
+        else
+          RubyRunner.call(workload, adapter: target.delete_prefix("ruby:").to_sym,
+                                    warmup: config.warmup, iterations: config.iterations)
+        end
+      end
+
+      def aggregate(domain, target, summaries)
+        rates = summaries.map { |summary| summary[:throughput_per_s] }
+        median = %i[throughput_per_s p50_us p99_us mean_us max_us drift].to_h do |key|
+          [key, Stats.median(summaries.filter_map { |summary| summary[key] })]
+        end
+        median[:roundtrip_floor_p50_us] = Stats.median(summaries.filter_map { |s| s[:roundtrip_floor_p50_us] })
+        median[:by_verb] = median_by_verb(summaries)
+        { domain: domain, target: target, runs: summaries, median: median.compact,
+          throughput_range: rates.minmax }
+      end
+
+      def median_by_verb(summaries)
+        summaries.first[:by_verb].keys.to_h do |verb|
+          [verb, %i[p50_us p99_us].to_h { |key| [key, Stats.median(summaries.map { |s| s[:by_verb][verb][key] })] }]
+        end
+      end
+
+      def postgres_version(active)
+        PostgresProbe.server_version if active.any? { |target| target.start_with?("ruby:postgres") }
+      end
+    end
+  end
+end

data/lib/hecks/bench/workload.rb

@@ -0,0 +1,89 @@
+require "json"
+
+module Hecks
+  module Bench
+    # A fixed command sequence for one example domain, identical for every runtime.
+    # Cycles name their records by `n`, so no command is refused and none times a rejection path.
+    class Workload
+      Step = Struct.new(:verb, :args) do
+        def to_json_line
+          JSON.generate("verb" => verb, "args" => args)
+        end
+
+        def ruby_args
+          args.transform_keys(&:to_sym)
+        end
+      end
+
+      # The example domain's directory name, also its Cargo feature.
+      attr_reader :name
+
+      # The absolute path of the example domain directory.
+      attr_reader :domain_path
+
+      # The commands run once, untimed, before any cycle.
+      attr_reader :setup
+
+      def initialize(name:, setup:, cycle:)
+        @name = name
+        @domain_path = File.expand_path("../../../examples/#{name}", __dir__)
+        @setup = setup
+        @cycle = cycle
+      end
+
+      def cycle(number) = @cycle.call(number)
+
+      def commands_per_cycle = cycle(0).size
+
+      def self.all
+        { "pizzas" => pizzas, "banking" => banking }
+      end
+
+      def self.fetch(name)
+        all.fetch(name) do
+          raise ArgumentError, "unknown domain #{name.inspect} — one of #{all.keys.join(', ')}"
+        end
+      end
+
+      def self.pizzas
+        new(name: "pizzas", setup: [], cycle: lambda { |n|
+          pizza = "pizza-#{n}"
+          [
+            Step.new("Pizzas::Order.CreatePizza",
+                     { "name"  => { "value" => pizza },
+                       "pizza" => { "price_cents" => { "cents" => 1200 }, "size" => { "value" => "large" } } }),
+            Step.new("Pizzas::Order.AddTopping",
+                     { "name" => pizza, "topping" => { "value" => "Basil" }, "amount" => { "value" => 3 } }),
+            Step.new("Pizzas::Order.AddTopping",
+                     { "name" => pizza, "topping" => { "value" => "Olive" }, "amount" => { "value" => 2 } }),
+            Step.new("Pizzas::Order.Purchase",
+                     { "name" => pizza, "customer_name" => { "value" => "Chris" },
+                       "amount" => { "cents" => 1200 } })
+          ]
+        })
+      end
+
+      def self.banking
+        register = Step.new("Banking::Customer.Register",
+                            { "reference" => { "value" => "CUST-0001" },
+                              "name"      => { "given" => "Ada", "family" => "Lovelace" },
+                              "email"     => { "address" => "ada@example.com" } })
+        new(name: "banking", setup: [register], cycle: lambda { |n|
+          number = { "value" => "acct-#{n}" }
+          money = ->(cents) { { "cents" => cents, "currency" => "USD" } }
+          [
+            Step.new("Banking::Account.Open",
+                     { "number" => number, "kind" => { "name" => "current" },
+                       "daily_limit" => { "cents" => 50_000 }, "customer" => "CUST-0001" }),
+            Step.new("Banking::Account.Credit",
+                     { "number" => number, "amount" => money.call(10_000), "narrative" => { "text" => "Deposit" } }),
+            Step.new("Banking::Account.Credit",
+                     { "number" => number, "amount" => money.call(5000), "narrative" => { "text" => "Deposit" } }),
+            Step.new("Banking::Account.Debit",
+                     { "number" => number, "amount" => money.call(2500), "narrative" => { "text" => "Groceries" } })
+          ]
+        })
+      end
+    end
+  end
+end

data/lib/hecks/bench.rb

@@ -0,0 +1,17 @@
+module Hecks
+  # Throughput and latency harness behind `hecks bench`; see `docs/benchmarks.md`.
+  # Not required by `lib/hecks.rb`: a booted domain never needs it.
+  module Bench
+  end
+end
+
+require_relative "bench/stats"
+require_relative "bench/workload"
+require_relative "bench/environment"
+require_relative "bench/postgres_probe"
+require_relative "bench/run"
+require_relative "bench/ruby_runner"
+require_relative "bench/rust_runner"
+require_relative "bench/suite"
+require_relative "bench/report"
+require_relative "bench/cli"

data/lib/hecks/bluebook/aggregate.rb

@@ -3,32 +3,12 @@ require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
-    # A field read through a `reference_to`, held locally (S12, ADR 0025
-    # — "Consistency across aggregate boundaries") — `projects
-    # :customer_status, from: :"customer.status"` declares that this
-    # aggregate's own `:customer_status` is a copy of the target's own
-    # `:status`, kept fresh by a rebuild sweep rather than read live at
-    # rule-evaluation time. `reference` names the local reference
-    # attribute to walk through (`:customer`, minted by this
-    # aggregate's own `reference_to Customer`); `remote_field` names
-    # the scalar on the target aggregate to copy.
+    # A field copied from a `reference_to` target, kept fresh by a rebuild sweep (S12, ADR 0025).
+    # `reference` is the local reference attribute to walk; `remote_field` the target's scalar.
     ProjectedField = Struct.new(:name, :reference, :remote_field, keyword_init: true)
 
-    # A construct like every other: the aggregate carries its own identity
-    # and sits in the owner chain between its chapter (a Bluebook) and
-    # everything declared on it. The chain is model objects end to end —
-    # reference resolution and hecks_fqn both walk it.
-    #
-    # The holding half, and nothing else. Every line below restates what
-    # `language/bluebook/aggregate.bluebook` already declares — the field
-    # list, said again as readers, again as constructor keywords, and
-    # again as an emission. That triplication is what a generator removes;
-    # `Behaviour::Aggregate` carries everything that is not derivable from
-    # the declaration, so regenerating this file can never be lossy.
-    #
-    # Prototype: hand-written in the shape a generator would emit, to
-    # prove the seam before the generator exists. `bin/project_model`
-    # would own this file; behaviour/aggregate.rb stays hand-written.
+    # An aggregate: carries its own identity and sits in the owner chain below its chapter.
+    # The holding half only; `Behaviour::Aggregate` carries what the declaration cannot derive.
     class Aggregate
       include Construct
       include Hecks::IR
@@ -42,20 +22,10 @@ module Hecks
         value_objects:    many(:value_objects),
         commands:         many(:commands),
         invariants:       -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
-        # A precondition shared across commands, declared once (S10, ADR
-        # 0025) — the aggregate's own named `given`s, the declaration a
-        # referencing command's own (already-resolved) `givens` entry
-        # came from. Both sides of "declared once, referenced many"
-        # are real IR, the same shape a value object's type and an
-        # attribute's own reference to it both are.
+        # The named `given`s a referencing command's resolved `givens` entry came from.
         preconditions:    -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
-        # S12, ADR 0025 — deliberately not folded into `attributes`:
-        # `EraGuard::ShapeDiff` only ever walks `attributes` to decide
-        # whether a new field leaves an existing record with something
-        # genuinely absent, and a projected field's own absence story
-        # is different — a record predating the `projects` declaration
-        # is expected to be missing it until the rebuild sweep runs,
-        # not a shape drift a translation needs to explain.
+        # Not folded into `attributes`: EraGuard::ShapeDiff walks those, and a record predating
+        # `projects` is expected to lack this field until the rebuild sweep runs.
         projected_fields: lambda {
           projected_fields.map do |field|
             { name: field.name.to_s, reference: field.reference.to_s, remote_field: field.remote_field.to_s }
@@ -64,11 +34,7 @@ module Hecks
         lifecycle:        one(:lifecycle),
         entities:         many(:entities),
         queries:          many(:queries),
-        # Additive — every domain that declares no port emits `ports: []`,
-        # the same "regenerate deliberately" wire-format change
-        # ir_golden_spec.rb's own header describes; no existing key
-        # moves. See docs/decisions (rust/project/ports.rb) for the
-        # first reader of this.
+        # Additive: domains that declare no port emit `ports: []`; no existing key moves.
         ports:            many(:ports),
         provenance:       :provenance
       )
@@ -77,39 +43,7 @@ module Hecks
                   :projected_fields, :identified_by, :identity_paths, :identity_heads, :lifecycle,
                   :entities, :queries, :policies, :ports, :reference_targets, :provenance
 
-      # Assigns what the language declares, then hands off to the
-      # behaviour's own `settle` — derived identity, name indexes and
-      # owner stamping, none of which the declaration states.
-      #
-      # @param name [String, Symbol] the aggregate's declared name
-      # @param description [String, nil] the aggregate's declared prose description
-      # @param attributes [Array<Bluebook::Attribute>] the aggregate's declared fields
-      # @param value_objects [Array<Class>] the value object classes (`Bluebook::ValueObject`
-      #   subclasses) declared on this aggregate
-      # @param commands [Array<Class>] the command classes (`Bluebook::Command` subclasses)
-      #   declared on this aggregate
-      # @param invariants [Array<Bluebook::Invariant>] the aggregate-level rules that must
-      #   always hold
-      # @param preconditions [Array<Bluebook::Given>] the aggregate's own named `given`s, a
-      #   referencing command's own resolved `givens` entry can point back at
-      # @param projected_fields [Array<Bluebook::ProjectedField>] the declared `projects`
-      #   fields, copied from another aggregate's own state by the rebuild sweep
-      # @param identified_by [String, Symbol, Array<String, Symbol>] the identity path(s)
-      #   this aggregate is addressed by
-      # @param lifecycle [Bluebook::Lifecycle, nil] the aggregate's declared state machine,
-      #   or `nil` if it declares none
-      # @param entities [Array<Class>] the entity classes (`Bluebook::Entity` subclasses)
-      #   nested directly under this aggregate
-      # @param queries [Array<Bluebook::Query>] the queries declared directly on this
-      #   aggregate
-      # @param policies [Array<Bluebook::Policy>] the reactions hoisted onto this aggregate
-      #   from the chapter that assembled it
-      # @param ports [Array<Bluebook::DomainPort>] the aggregate-scoped ports attached after
-      #   this aggregate was built
-      # @param reference_targets [Array<String>] the name of every aggregate this one points
-      #   at with an aggregate-level `reference_to`
-      # @param provenance [Object, nil] the aggregate's declared canonical source, captured
-      #   exactly as written, or `nil` if it declares none
+      # Assigns the declared fields, then `settle` derives identity, name indexes and owner stamps.
       def initialize(name:, description: nil, attributes: [], value_objects: [],
                      commands: [], invariants: [], preconditions: [], projected_fields: [], identified_by: [], lifecycle: nil,
                      entities: [], queries: [], policies: [], ports: [], reference_targets: [],

data/lib/hecks/bluebook/assembly/aggregate_assembly.rb

@@ -1,14 +1,7 @@
 module Hecks
   module Bluebook
     class Assembly
-      # One head, built from its declaration.
-      #
-      # The fields come from the contract like every other construct's. What is here
-      # is the part no field table can say: which construct holds which, and how a
-      # head's references become able to resolve.
-      #
-      # It decides nothing. Whether a declaration is admissible was settled on the
-      # way in, by the language.
+      # Builds one aggregate from its declaration: containment and reference resolution.
       class AggregateAssembly
         # @param row [Hash{Symbol => Object}] one declared aggregate's raw contract data,
         #   as `@declaration[:aggregates]` carries it
@@ -36,10 +29,7 @@ module Hecks
             entities:          entities,
             queries:           asks,
             lifecycle:         lifecycle_of(@row),
-            # A policy declared inside a head is hoisted onto the chapter by the
-            # builder, and `Aggregate#to_h` never carried it — so the language does
-            # not record which head a chapter-level policy was written in. The
-            # chapter holds them all, which is what `PolicyInterpreter` reads.
+            # Policies live on the chapter, which is what `PolicyInterpreter` reads.
             policies:          [],
             reference_targets: reference_targets(fields)
           )
@@ -50,12 +40,7 @@ module Hecks
 
         private
 
-        # What this head points at with an aggregate-level `reference_to`. Not the
-        # self-references its verbs carry — the first version read
-        # `commands.filter_map(&:references)` and gave Pizza two targets of "Pizza",
-        # its own verbs pointing at itself, where the builder recorded none. An
-        # aggregate-level `reference_to X` leaves a reference attribute behind, so
-        # the attributes are where the answer is.
+        # Read from attributes, not commands: a command's self-references are not targets.
         def reference_targets(fields)
           fields.select(&:reference?).map { |field| field.type.target_name }
         end
@@ -64,12 +49,7 @@ module Hecks
           Build.call("ValueObject", row)
         end
 
-        # S17, ADR 0026 — recurses. "That is what `entity` is for, and
-        # `entity` is declared by the language and used zero times in it"
-        # — Dispatch, inside Handler, is the first use, so `row[:entities]`
-        # is built the same way `row` itself was reached: through this
-        # same method, one level deeper each time. Nothing here assumes
-        # it stops at one level of nesting.
+        # Recurses, so entities nest to any depth (ADR 0026).
         def entity(row)
           Build.call(
             "Entity", row,
@@ -80,10 +60,8 @@ module Hecks
           )
         end
 
-        # Every reference learns which head declares it, so it can reach the chapter
-        # and resolve. Deliberately across every list that can carry one — a
-        # reference the walk misses resolves to nil, and a nil target is skipped
-        # rather than refused, so the guarantee would go quiet instead of red.
+        # Must cover every list that can carry a reference: a missed one resolves to nil,
+        # and a nil target is skipped rather than refused.
         def stamp_references(aggregate)
           lists = [aggregate.attributes, *aggregate.commands.map(&:attributes), *aggregate.queries.map(&:attributes)]
           entity_reference_lists(aggregate.entities, lists)
@@ -91,8 +69,6 @@ module Hecks
           lists.flatten.select(&:reference?).each { |field| field.type.declared_in = aggregate }
         end
 
-        # S17, ADR 0026 — walks nested entities too (Dispatch, inside
-        # Handler), not only an aggregate's own direct ones.
         def entity_reference_lists(entities, lists)
           entities.each do |piece|
             lists << piece.attributes
@@ -102,9 +78,7 @@ module Hecks
           end
         end
 
-        # Three language fields, one IR object. `state_field`, `state_start` and
-        # `transitions` are separate declarations; the IR keeps one Lifecycle. The
-        # contract names them derived, and this is what derives them.
+        # Folds `state_field`, `state_start` and `transitions` into the IR's one Lifecycle.
         def lifecycle_of(row)
           declared = row[:lifecycle]
           return nil unless declared
@@ -116,11 +90,8 @@ module Hecks
           )
         end
 
-        # A lifecycle holds [command, StateTransition] pairs and `to_h` expands one
-        # pair whose `from` is a list into several rows. Grouped back by command and
-        # target, because one declared pair has exactly one target and may have many
-        # froms — grouping by command alone would fuse two declarations that move the
-        # same verb to different states.
+        # Regroups `to_h` rows by command and target; grouping by command alone would fuse
+        # declarations that move one verb to different states.
         def transitions(rows)
           rows.group_by { |move| [move[:command], move[:to_state]] }
               .map do |(command, target), moves|

data/lib/hecks/bluebook/assembly/build.rb

@@ -1,18 +1,9 @@
 module Hecks
   module Bluebook
     class Assembly
-      # One way to build a construct, for every construct.
+      # Builds any construct from its declared row by reading its `Assembly.contract`.
       #
-      # Not a method per category — `value_object(row)`, `command(row)`,
-      # `policy(row)`, each gathering the same keywords the contract already
-      # names. This reads the contract instead, so adding a field to the
-      # language and forgetting to assemble it is caught by the coverage gate
-      # rather than by nobody.
-      #
-      # `make` is the only branch, and it is a real one: a construct that became a
-      # class is `.declare`d, an instance is `.new`ed. That is the boundary
-      # `Query` sits on, and it is a fact about Ruby rather than about the
-      # domain.
+      # A construct that is a class is `.declare`d; an instance is `.new`ed.
       module Build
         module_function
 
@@ -42,8 +33,7 @@ module Hecks
           contract.holder or raise ArgumentError, "#{contract} holds nothing that can be built"
         end
 
-        # A reader is a Marks method, a list of them, or one of three spellings that
-        # need no decoding at all.
+        # Reads one value through a contract reader.
         #
         # @param reader [Symbol, Array, nil] the contract field's reader: `:plain`,
         #   `:identity`, `:flag`, `[:each, marks_method]`, `[:option, name]`, or a bare
@@ -56,8 +46,7 @@ module Hecks
           when :identity then value&.to_sym
           when :flag     then value ? true : false
           when Array
-            # [:each, reader] maps a list ; [:option, name] reads one named option,
-            # which needs its name as well as its value.
+            # `[:option, name]` needs its name as well as its value.
             if reader.first == :each
               Array(value).map { |held| Marks.public_send(reader.last, held) }
             else