hecks 3.0.3 → 3.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46f6f36759cf946f2fd26b0b11b0ec64b02b7b84e1213fcf239a08aa314d0168
-  data.tar.gz: 295310e1f10f391cfdc53900f7eda2ee6b96db34ced1e93fbd73e50978b6fa07
+  metadata.gz: 90a718a197fae0287e4fe16033540bf625166bc31bfb3482e0752d1039a2a949
+  data.tar.gz: 15fe27abd9a488dfe4f579118f8e8ffbea1302b956ee36fbd2b9475eb3b88429
 SHA512:
-  metadata.gz: 9d7a89486e004a7e786177ee9debfb4fcdc1e331611da9293a29cc2e16e0b4f2b388d718d3062e7b236e27b2655f16282e6e1b1065bb151fcdd8bb67c839a34f
-  data.tar.gz: 9713d8af8eb4eebdf7885e0ec9821e304f0d6be393e22968c32b971e83d920e6f4ecfa52ce3ee46a19336de8a4e50d5c70d20c443784042aeac5607046ceb9ce
+  metadata.gz: d74d07807e22e8899c041adfa96d799b5eb47713a0dec6c05bbb9e61a579a32a35da890b67aaf876b1ba5182e0961a112f370e0e04adcf2719f8ae57a50cfd45
+  data.tar.gz: 11e85c77dc6a4f5d34ec3acd54e41873be8d03b980e4ef97a8d0d7c9da4b63ecfc2b04e2a1322f8c1536ad1d58f8f85f50df2ca58f3d6fea44126cb871c05b0d

data/exe/hecks

@@ -24,7 +24,8 @@ end
 require "hecks"
 
 # Usage is answered from the projected chapter alone: no adapter is bound and no
-# database is opened. Only a line that runs a verb boots the domain.
+# database is opened. Only a line that runs a verb boots the domain,
+# and it boots from what the usage check already loaded.
 domain = File.expand_path("../lib/hecks/hecks", __dir__)
 program = "hecks"
 described = begin
@@ -38,10 +39,13 @@ text, status, reason = Hecks::Doors::CliRunner.usage(
 )
 unless text
   runtime = begin
-    Hecks.boot(domain, install_doors: false)
+    Hecks.boot_described(described, install_doors: false)
   rescue StandardError => e
     abort "cannot open Hecks: #{e.message.lines.first.strip}"
   end
+  # A question the world lists under `streams`, given `--stream`, tails until interrupted.
+  streamed = Hecks::Doors::CliRunner.stream(runtime: runtime, argv: ARGV, program: program)
+  exit streamed unless streamed.nil?
   text, status, reason = Hecks::Doors::CliRunner.call(
     runtime: runtime, argv: ARGV, program: program
   )

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

@@ -62,6 +62,7 @@ module Hecks
             attributes: [:attributes, [:each, :shape_field]],
             givens:     [:givens,     [:each, :given]],
             ensures:    [:ensures,    [:each, :given]],
+            needs:      [:needs,      [:each, :need]],
             mutations:  [:mutations,  [:each, :mutation]],
             emits:      [:emits,      :plain],
             # Lifecycle state as a command guard: one state, an array, or nil (ADR 0025).
@@ -70,7 +71,8 @@ module Hecks
           },
           rows: { mutations: :mutation_rows },
           reads: { attributes: [:each, :shape_field], givens: [:each, :rule], ensures: [:each, :rule],
-                  mutations: [:call, :mutations], emits: :names, provenance: :provenance, from: :from },
+                  needs: [:each, :need], mutations: [:call, :mutations], emits: :names, provenance: :provenance,
+                  from: :from },
           derived: { position: :walk }
         ),
 

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

@@ -74,6 +74,9 @@ module Hecks
           Given.new(description: rule[:description], canonical: rule[:canonical])
         end
 
+        # One outside fact a command needs, as the Symbol `Command#needs` holds.
+        def need(row) = row[:fact].to_sym
+
         # All three fields are identifiers, unlike Invariant/Given's free text, so they
         # come back as Symbols.
         def projected_field(row)

data/lib/hecks/bluebook/command.rb

@@ -54,6 +54,7 @@ module Hecks
         attributes: many(:attributes),
         givens:     -> { givens.map { |rule| Expression::AstJson.rule_row(rule) } },
         ensures:    -> { ensures.map { |rule| Expression::AstJson.rule_row(rule) } },
+        needs:      -> { needs.map { |fact| { fact: fact.to_s } } },
         mutations:  many(:mutations),
         emits:      :emits,
         # The lifecycle state this command is admissible from: a guard, not a transition.
@@ -62,7 +63,7 @@ module Hecks
       )
 
       class << self
-        attr_reader :role, :goal, :attributes, :givens, :ensures, :mutations, :emits, :references,
+        attr_reader :role, :goal, :attributes, :givens, :ensures, :needs, :mutations, :emits, :references,
                     :from, :provenance
 
         # Mints one command as its own anonymous subclass of the class `declare` is called on.
@@ -71,18 +72,18 @@ module Hecks
         # @param role [String, nil] the declared role text; `goal` is the goal text
         # @param attributes [Array<Bluebook::Attribute>] the declared arguments
         # @param givens [Array<Bluebook::Given>] the declared preconditions
-        # @param ensures [Array<Bluebook::Given>] the declared postconditions
+        # @param ensures [Array<Bluebook::Given>] the postconditions; `needs` the facts it supplies
         # @param mutations [Array<Bluebook::Mutation>] the state changes it applies
         # @param emits [Array<String>] the event names it may emit
         # @param references [String, Symbol, nil] the aggregate its `reference_to` addresses
         # @param from [String, Array<String>, nil] the lifecycle states it is admissible from
         # @param provenance [Object, nil] the declared canonical source, as written
-        def declare(name:, role: nil, goal: nil, attributes: [], givens: [], ensures: [],
+        def declare(name:, role: nil, goal: nil, attributes: [], givens: [], ensures: [], needs: [],
                     mutations: [], emits: [], references: nil, from: nil, provenance: nil)
           verb = Class.new(self)
           verb.hecks_name = name.to_s
           verb.absorb(role: role, goal: goal, attributes: attributes, givens: givens,
-                      ensures: ensures, mutations: mutations, emits: emits, references: references&.to_s,
+                      ensures: ensures, needs: needs, mutations: mutations, emits: emits, references: references&.to_s,
                       from: from, provenance: provenance)
           verb
         end
@@ -93,12 +94,13 @@ module Hecks
         #
         # @return [Class] self
         def absorb(role:, goal:, attributes:, givens:, ensures:, mutations:, emits:, references:,
-                   from: nil, provenance: nil)
+                   needs: [], from: nil, provenance: nil)
           @role       = role
           @goal       = goal
           @attributes = attributes
           @givens     = givens
           @ensures    = ensures
+          @needs      = needs
           @mutations  = mutations
           @emits      = emits
           @references = references

data/lib/hecks/bluebook/dsl/bootstrap_table.rb

@@ -41,6 +41,7 @@ module Hecks
           ["Command", "then_set"] => :then_set_impl,
           ["Command", "delegates_to"] => :delegates_to_impl,
           ["Command", "attribute"] => :attribute_impl,
+          ["Command", "needs"] => :needs_impl,
           ["Command", "corrects"] => :corrects_impl,
           ["Entity", "identified_by"] => :identified_by_impl,
           ["Entity", "given"] => :given_impl,

data/lib/hecks/bluebook/dsl/command_builder.rb

@@ -22,6 +22,7 @@ module Hecks
           @owner             = owner
           @givens            = []
           @ensures           = []
+          @needs             = []
           @mutations         = []
           @emits             = []
           @named_givens      = named_givens
@@ -66,6 +67,31 @@ module Hecks
         # @return [String] the description as stored
         def goal(value) = @goal = value
 
+        # The outside facts a command may declare it needs, each the name of the attribute the
+        # runtime fills when the caller leaves it out. `now` is the clock port's answer, in epoch
+        # seconds.
+        NEEDABLE_FACTS = %i[now].freeze
+
+        # Declares an outside fact the runtime supplies before any given runs (ADR 0081):
+        # `needs :now` fills the command's own `now` attribute from the clock port when the caller
+        # names none.
+        #
+        # @param fact [Symbol] one of `NEEDABLE_FACTS`
+        # @return [Array<Symbol>] the facts declared so far
+        # @raise [Bluebook::DSL::Malformed] if the fact is not one the runtime can supply, or is
+        #   declared twice
+        def needs_impl(fact)
+          fact = fact.to_sym
+          unless NEEDABLE_FACTS.include?(fact)
+            raise Malformed,
+                  "#{@name} needs :#{fact}, which the runtime cannot supply — it supplies " \
+                  "#{NEEDABLE_FACTS.map { |known| ":#{known}" }.join(', ')}"
+          end
+          raise Malformed, "#{@name} declares needs :#{fact} twice" if @needs.include?(fact)
+
+          @needs << fact
+        end
+
         # Names where a concept adopted from a canonical source came from.
         #
         # @param from [Object] the canonical source, captured exactly as written
@@ -292,6 +318,7 @@ module Hecks
         def build
           resolve_implicit_attributes!
           refuse_duplicate_targets!
+          refuse_undeclared_needs!
 
           delegation = @mutations.find { |mutation| mutation.op == :delegate }
           if delegation && (@mutations.size > 1 || @emits.any?)
@@ -308,6 +335,7 @@ module Hecks
             attributes: attributes,
             givens:     @givens,
             ensures:    @ensures,
+            needs:      @needs,
             mutations:  @mutations,
             emits:      @emits,
             references: @references,
@@ -316,6 +344,20 @@ module Hecks
           )
         end
 
+        # A fact is filled into the argument of the same name, so the command declares one.
+        #
+        # @raise [Bluebook::DSL::Malformed] if a needed fact has no attribute to fill
+        def refuse_undeclared_needs!
+          declared = attributes.map { |attribute| attribute.name.to_s }
+          missing  = @needs.reject { |fact| declared.include?(fact.to_s) }
+          return if missing.empty?
+
+          raise Malformed,
+                "#{@name} needs :#{missing.first} but declares no attribute :#{missing.first} " \
+                "for the runtime to fill — add `attribute :#{missing.first}, <type>`"
+        end
+        private :refuse_undeclared_needs!
+
         # Evaluates a `command` block against a fresh builder and returns what it built.
         #
         # @param name [String] the command's name

data/lib/hecks/bluebook/expression/canonical_form.rb

@@ -40,6 +40,7 @@ module Hecks
           case rule.strategy
           when "collapse_whitespace" then map_outside_strings(text) { |segment| segment.gsub(/\s+/, " ") }
           when "replace"             then replace(text, rule)
+          when "scale_call"          then scale_call(text, rule)
           else
             raise ArgumentError, "#{rule.strategy.inspect} is not a linked normalisation strategy"
           end
@@ -55,6 +56,17 @@ module Hecks
           end
         end
 
+        # Folds a duration written as a call on a whole number into seconds: `days(730)` becomes
+        # `63072000` when the rule's token is `days` and its replacement `86400`. A call on anything
+        # but a literal whole number is left as written, and a method call (`x.days(3)`) is not a
+        # duration.
+        def scale_call(text, rule)
+          call = /(?<![[:alnum:]_.])#{Regexp.escape(rule.source_token)}\(\s*(\d+)\s*\)/
+          map_outside_strings(text) do |segment|
+            segment.gsub(call) { (Regexp.last_match(1).to_i * rule.replacement.to_i).to_s }
+          end
+        end
+
         # Yields each run of `text` outside quoted literals, copying quoted runs through verbatim.
         # Quote-blind rewriting would change what a predicate compares a string against.
         # Handles `"` and `'`; an unterminated quote is passed through raw.

data/lib/hecks/bluebook/expression/projection.json

@@ -225,6 +225,27 @@
       "replacement": ".size",
       "boundary": "word",
       "position": 2
+    },
+    {
+      "strategy": "scale_call",
+      "source_token": "days",
+      "replacement": "86400",
+      "boundary": "word",
+      "position": 3
+    },
+    {
+      "strategy": "scale_call",
+      "source_token": "hours",
+      "replacement": "3600",
+      "boundary": "word",
+      "position": 4
+    },
+    {
+      "strategy": "scale_call",
+      "source_token": "minutes",
+      "replacement": "60",
+      "boundary": "word",
+      "position": 5
     }
   ]
 }

data/lib/hecks/bluebook/meta_validator/shapes.rb

@@ -83,6 +83,9 @@ module Hecks
         # A rule's plain description/canonical pair, for a `given`/`invariant`/`ensures`.
         def rule(row) = { description: text(row[:description]), canonical: text(row[:canonical]) }
 
+        # One outside fact a command needs, in the shape `Command#to_h` emits it.
+        def need(row) = { fact: text(row[:fact]) }
+
         # `projects :name, from: :"reference.remote_field"` (ADR 0025), read back as
         # its plain name/reference/remote_field triple.
         def projected_field(row)

data/lib/hecks/cli/project_cli.rb

@@ -212,7 +212,8 @@ module Hecks
       def described_entry(name, boot, shown)
         <<~RUBY.chomp
           # Usage is answered from the projected chapter alone: no adapter is bound and no
-          # database is opened. Only a line that runs a verb boots the domain.
+          # database is opened. Only a line that runs a verb boots the domain,
+          # and it boots from what the usage check already loaded.
           domain = #{boot}
           program = "#{shown}"
           described = begin
@@ -226,10 +227,13 @@ module Hecks
           )
           unless text
             runtime = begin
-              Hecks.boot(domain, install_doors: false)
+              Hecks.boot_described(described, install_doors: false)
             rescue StandardError => e
               abort "cannot open #{name}: \#{e.message.lines.first.strip}"
             end
+            # A question the world lists under `streams`, given `--stream`, tails until interrupted.
+            streamed = Hecks::Doors::CliRunner.stream(runtime: runtime, argv: ARGV, program: program)
+            exit streamed unless streamed.nil?
             text, status, reason = Hecks::Doors::CliRunner.call(
               runtime: runtime, argv: ARGV, program: program
             )

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -20,6 +20,9 @@ Hecks.bluebook "Deploy" do
     attribute :timeout,  Timeout
     attribute :database, Database
     attribute :web,      Web
+    attribute :dispatch, Dispatch,      optional: true
+    attribute :handler_module, HandlerModule, optional: true
+    attribute :secret_env, SecretEnv,   optional: true
 
     value_object "DomainName" do
       attribute :value, String
@@ -47,6 +50,27 @@ Hecks.bluebook "Deploy" do
       attribute :value, String, one_of: ["None", "Rust"]
     end
 
+    # "Rust" (default) or "None": a domain with no `.bluebook` command surface to dispatch through
+    # (a webhook that dispatches straight into Ruby) skips the rust/host dispatch Lambda, and its
+    # WebFunction becomes its only Lambda. That WebFunction's `lambda_handler.rb` defines the module
+    # `handler_module` names, so `dispatch "None"` must name one.
+    value_object "Dispatch" do
+      attribute :value, String, one_of: ["Rust", "None"]
+    end
+
+    # The module the domain's `lambda_handler.rb` defines for its WebFunction.
+    value_object "HandlerModule" do
+      attribute :value, String
+      invariant("a handler module is named") { !value.to_s.empty? }
+    end
+
+    # The env var the WebFunction's `lambda_handler.rb` finds the fetched secret's plaintext under,
+    # once it resolves `<name>_ARN`.
+    value_object "SecretEnv" do
+      attribute :value, String
+      invariant("a secret env var is named") { !value.to_s.empty? }
+    end
+
     # 128-10240 MB, AWS Lambda's own floor and ceiling.
     value_object "Memory" do
       attribute :value, Integer
@@ -73,6 +97,13 @@ Hecks.bluebook "Deploy" do
       attribute :timeout,  Timeout
       attribute :database, Database
       attribute :web,      Web
+      attribute :dispatch, Dispatch,      optional: true
+      attribute :handler_module, HandlerModule, optional: true
+      attribute :secret_env, SecretEnv,   optional: true
+
+      given('dispatch "None" names its handler_module: add handler_module "YourModuleName" for the module lambda_handler.rb defines') do
+        dispatch.unset? || dispatch.value != "None" || handler_module.set?
+      end
 
       sets :domain
       sets :region
@@ -80,6 +111,9 @@ Hecks.bluebook "Deploy" do
       sets :timeout
       sets :database
       sets :web
+      sets :dispatch
+      sets :handler_module
+      sets :secret_env
 
       emits "LambdaTargetDeclared"
     end

data/lib/hecks/doors/cli_runner.rb

@@ -34,6 +34,62 @@ module Hecks
                  bluebook: plan[:bluebook], launcher: plan[:launcher])
       end
 
+      # Tails a question: asks, prints each new entry as one JSON line, and asks again from the
+      # cursor the answer gave, until the reader interrupts. Only for a question the `launcher`
+      # setting lists under `streams`, given `--stream`; `from_now` applies to the first ask only.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+      # @param argv [Array<String>] as for `call`, with `--stream`
+      # @param program [String] how the caller was invoked
+      # @param out [IO] where each entry's line goes
+      # @param err [IO] where a refusal goes
+      # @param max_polls [Integer, nil] stop after this many asks; unbounded when nil
+      # @return [Integer, nil] 0 or 1 for a stream, nil when `call` should run the line
+      def stream(runtime:, argv:, program: "hecks run", out: $stdout, err: $stderr, max_polls: nil)
+        plan = resolve(runtime, argv, program)
+        return if plan[:answer] || !LauncherOptions.streams?(plan[:launcher], plan[:spec])
+
+        words, streaming = LauncherOptions.take_stream(plan[:rest])
+        return unless streaming
+
+        tail(runtime, plan[:spec], CliDoor.arguments(plan[:spec], words), out, max_polls)
+        0
+      rescue Interrupt, Errno::EPIPE
+        0
+      rescue Runtime::NotFound, Runtime::TypeMismatch => e
+        err.puts("#{e.message}\n\n  #{program} #{plan[:name]} --help")
+        1
+      rescue *Runtime::DOMAIN_REFUSALS => e
+        err.puts(e.message)
+        1
+      end
+
+      # One ask after another, each from the cursor the last gave.
+      def tail(runtime, spec, args, out, max_polls)
+        args   = args.merge(wait: { value: 30 }) unless args.key?(:wait)
+        polls  = 0
+        cursor = nil
+        loop do
+          ask  = cursor ? args.except(:from_now).merge(since: { value: cursor }) : args
+          rows = runtime.query(spec[:verb], **ask)
+          row  = rows.first || {}
+          Array(row[:events]).each { |event| out.puts(JSON.generate(entry_line(JsonDoor.materialize(event)))) }
+          out.flush
+          cursor = row[:cursor]
+          polls += 1
+          break if cursor.nil? || (max_polls && polls >= max_polls)
+        end
+      end
+
+      # An entry as a line: its payload, which the answer holds as JSON text, back as an object.
+      def entry_line(event)
+        line = JSON.parse(JSON.generate(event))
+        line["payload"] = JSON.parse(line["payload"]) if line["payload"].is_a?(String)
+        line
+      rescue JSON::ParserError
+        line
+      end
+
       # Answers a command line that asks only for usage, from the projection alone.
       #
       # Needs a registry and no bound adapter, so a `Runtime::Loader::Described` serves: the
@@ -110,7 +166,7 @@ module Hecks
       # @param launcher [Hash, nil] the chapter's `launcher` world setting; nil when not opted in
       def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil)
         rest, wait = LauncherOptions.take_wait(spec, rest) if launcher
-        args = stamp_time(runtime, spec, CliDoor.arguments(spec, rest))
+        args = CliDoor.arguments(spec, rest)
 
         return answer_query(runtime, spec, args, wait) if spec[:kind] == :query
 
@@ -231,17 +287,6 @@ module Hecks
         rows.first[:text]
       end
 
-      # Fills in a `now` argument the caller left out, from the clock port; an explicit one wins.
-      #
-      # Done at the door, not in the runtime: a clock read inside the interpreter would give a
-      # replayed corpus step the replay day's time. Matched by the argument's name alone.
-      def stamp_time(runtime, spec, args)
-        return args unless spec[:arguments].any? { |argument| argument[:path].start_with?("now.") }
-        return args if args.key?(:now)
-
-        args.merge(now: { value: Ports::Clock.now(runtime.registry) })
-      end
-
       # The reactions one dispatch caused that the domain refused, as `refused_reactions:`.
       #
       # A policy's trigger that a `given` refuses is not the command's own refusal: the command

data/lib/hecks/doors/launcher_options.rb

@@ -15,9 +15,11 @@ module Hecks
     # - **run_keys** mints the `run` key of a creating command that was given none.
     # - **failure_states** are the lifecycle states `--wait` reports as a failure (exit 1).
     # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
+    # - **streams** lists the questions `--stream` may tail, one JSON line per new entry.
     module LauncherOptions
       SETTING = "launcher".freeze
       WAIT    = "--wait".freeze
+      STREAM  = "--stream".freeze
       RUN_KEY = "run.value".freeze
 
       module_function
@@ -67,6 +69,27 @@ module Hecks
         [rest, wait]
       end
 
+      # Whether a question may be tailed with `--stream`: the chapter's `launcher` setting lists it
+      # under `streams`, by the question's own name.
+      #
+      # @param launcher [Hash, nil] the chapter's `launcher` setting
+      # @param spec [Hash] the question's projected spec
+      # @return [Boolean] true for a question the setting names
+      def streams?(launcher, spec)
+        return false unless launcher && spec[:kind] == :query
+
+        Array(launcher[:streams]).map(&:to_s).include?(spec[:verb].to_s.split(/[.:]+/).last)
+      end
+
+      # Takes `--stream` out of a question's words.
+      #
+      # @param words [Array<String>] the words after the question
+      # @return [Array(Array<String>, Boolean)] the remaining words, and whether `--stream` was
+      #   given
+      def take_stream(words)
+        [words.reject { |word| word == STREAM }, words.include?(STREAM)]
+      end
+
       # @api private
       def wait_word?(word) = word == WAIT || word.start_with?("#{WAIT}=")
 

data/lib/hecks/fuzzing/properties.rb

@@ -39,7 +39,7 @@ module Hecks
         query_answers_match_reference:                    %w[Query#wheres Query#order_field Query#order_way Query#limit],
         paging_offset_partitions_correctly:               %w[Query#options],
         authorize_scopes_or_refuses:                      %w[Query#options],
-        guard_refusals_are_declared:                      %w[Command#givens Command#ensures],
+        guard_refusals_are_declared:                      %w[Command#givens Command#ensures Command#needs],
         lifecycle_guard_and_given_violations_are_refused: %w[Command#from Aggregate#preconditions Entity#preconditions],
         # Dispatch#command_name/with_spec aren't claimable feature names — the
         # coverage walk only reaches one level of entity nesting and Dispatch

data/lib/hecks/fuzzing/sequence_generator/adversary.rb

@@ -212,9 +212,10 @@ module Hecks
           if mapped.empty? && !entry.key?(:entity) && command.creates?
             mapped = command.attributes.map { |attribute| attribute.name.to_s }
           end
+          needed = needed_facts_of(entry)
           command.attributes.select do |attribute|
             name = attribute.name.to_s
-            mapped.include?(name) && args.key?(name) && !heads.include?(name)
+            mapped.include?(name) && args.key?(name) && !heads.include?(name) && !needed.include?(name)
           end
         end
 
@@ -352,12 +353,19 @@ module Hecks
         end
 
         def droppable_required_attributes(args, entry)
-          heads = identity_heads_of(entry)
+          heads  = identity_heads_of(entry)
+          needed = needed_facts_of(entry)
           entry[:command].attributes.reject(&:optional?).select do |attribute|
-            args.key?(attribute.name.to_s) && !heads.include?(attribute.name.to_s)
+            name = attribute.name.to_s
+            args.key?(name) && !heads.include?(name) && !needed.include?(name)
           end
         end
 
+        # The facts the command `needs`: the runtime answers them when a step leaves them out
+        # (each engine from its own clock), so a recorded step carries them and dropping one is not
+        # an absent-argument case.
+        def needed_facts_of(entry) = entry[:command].needs.map(&:to_s)
+
         # Aims a grant at a role some command declares; random role text would make `actor_known`
         # unreachable. Does nothing without the role draw.
         def steer_grant!(args, entry, catalog)

data/lib/hecks/fuzzing/sequence_generator/step_builder.rb

@@ -39,7 +39,7 @@ module Hecks
         # The caller draw and then the dry-run coin follow the mutation. The order
         # is part of the seed contract; both draw nothing when off.
         def build_command_step(runtime, catalog, entry)
-          args = args_for(entry[:command].attributes, entry[:aggregate])
+          args = args_for(entry[:command].attributes, entry[:aggregate], needed: entry[:command].needs.map(&:to_s))
           add_identity!(args, entry)
           steer_grant!(args, entry, catalog)
           mutations = adversarial_mutations!(args, entry, catalog)
@@ -76,7 +76,9 @@ module Hecks
           Hecks.as_caller(role: caller["role"], actor_id: caller["actor_id"], &)
         end
 
-        def args_for(attributes, aggregate)
+        # `needed` names the facts the runtime answers when a step leaves them out; a malformation
+        # never drops one, since each engine would fill it from its own clock.
+        def args_for(attributes, aggregate, needed: [])
           args = attributes.each_with_object({}) do |attribute, built|
             # Omitting an optional argument is an ordinary payload, not a malformation
             # (see OPTIONAL_OMITTED_PROBABILITY).
@@ -94,7 +96,7 @@ module Hecks
             end
           end
 
-          malform(args, attributes, aggregate)
+          malform(args, attributes, aggregate, needed)
         end
 
         # An array of 0-3 independently generated elements shaped like the bare
@@ -108,21 +110,21 @@ module Hecks
 
         # At most one malformation per step, so the check that fired is identifiable.
         # The rate stays low because refused steps reach no state.
-        def malform(args, attributes, aggregate)
+        def malform(args, attributes, aggregate, needed)
           return args if args.empty? || @random.rand >= MALFORMED_ARGUMENT_PROBABILITY
 
           case @random.rand(3)
           when 0 then corrupt_one(args, attributes, aggregate)
-          when 1 then drop_one(args, aggregate)
+          when 1 then drop_one(args, aggregate, needed)
           else        args.merge([InvalidValueGenerator.undeclared_argument(random: @random)].to_h)
           end
         end
 
         # Never drops the identity: an auto-minted id is unreproducible, so the
         # step's outcome could not be replayed.
-        def drop_one(args, aggregate)
+        def drop_one(args, aggregate, needed)
           identity  = (aggregate.identified_by || :id).to_s
-          droppable = args.keys - [identity, "id"]
+          droppable = args.keys - [identity, "id"] - needed
           return args if droppable.empty?
 
           args.reject { |name, _| name == droppable.sample(random: @random) }

data/lib/hecks/gate/stages.yml

@@ -0,0 +1,51 @@
+# The checks a stage runs before its change is let through. `hecks gate <stage>` reads this file and
+# the git pre-push hook calls it, so the list of checks lives here and nowhere else.
+#
+# A check is one command run from the repository root, all of a stage's checks at once:
+#   id       the name it is reported and selected by (`only=a,b`)
+#   title    the heading its output is printed under
+#   run      the program and its arguments; `{workers}` is half the machine's cores, at least one
+#   blocked  what a red check means and what to do about it
+#
+# `env` is set only where the caller has not set it: a push check has no use for the Hecks
+# domain's database, so it runs on Memory, as a pull-request run does in CI.
+pre_push:
+  env:
+    HECKS_ENVIRONMENT: memory
+  checks:
+    - id: rspec
+      title: rspec (parallel)
+      run: [bundle, exec, parallel_rspec, spec, -n, "{workers}"]
+      blocked: the suite is red.
+    - id: fuzzing
+      title: spec/fuzzing, which the parallel run above excludes
+      run: [bundle, exec, rspec, spec/fuzzing, --tag, fuzzing]
+      blocked: spec/fuzzing is red.
+    - id: query_agreement
+      title: adapter agreement, one declared query and every engine giving the same answer
+      run: [bundle, exec, rspec, spec/adapters/query_agreement_spec.rb, --tag, io]
+      blocked: the engines disagree about a declared query; one of them is wrong, and a self-consistent adapter spec cannot tell which.
+    - id: engine_agreement
+      title: engine agreement, every declared comparator on both engines
+      run: [bundle, exec, exe/hecks, check_engine_agreement, --wait]
+      blocked: a comparator is missing a shared case or a cross-engine spec.
+    - id: model_check
+      title: model check, unreachable states, dead transitions and orphaned handlers
+      run: [bundle, exec, exe/hecks, model_check, --wait]
+      blocked: the model checker found something.
+    - id: doc_coverage
+      title: docs coverage, words with no running example
+      run: [bundle, exec, exe/hecks, measure_doc_coverage, --wait]
+      blocked: the language ships something undocumented; write the missing sections and examples.
+    - id: rubocop
+      title: rubocop, the static style and correctness gate
+      run: [bundle, exec, rubocop, -c, .rubocop.yml]
+      blocked: rubocop found an offense.
+    - id: codegen_drift
+      title: codegen drift, the committed rust/src/generated/ must match a fresh regeneration
+      run: [bundle, exec, exe/hecks, regenerate_corpus, --check, --wait]
+      blocked: regenerating hits a diff, so the committed Rust is stale; run `hecks regenerate_corpus --confirm` and commit the result.
+    - id: comment_blocks
+      title: comment blocks, no run of comment lines past ADR 0075's cap
+      run: [bundle, exec, exe/hecks, check_comments, "paths=lib,spec,examples", only=long_block, --wait]
+      blocked: a comment block ran past the cap; shorten it.