quint_driver 0.1.0

data/lib/quint_driver/quint.rb

@@ -0,0 +1,376 @@
+require "etc"
+require "json"
+require "open3"
+require "shellwords"
+require "tmpdir"
+
+module QuintDriver
+  # The `quint` command line: the one place this library runs another process.
+  module Quint
+    # Read on every call, so a caller can set QUINT after requiring the gem.
+    def self.command = ENV.fetch("QUINT", "npx --yes @informalsystems/quint@0.33.0")
+
+    # The spec's JSON IR, frozen. +main+ names the module quint checks;
+    # without it, quint checks the module named after the file, and fails when
+    # none is. A file compiles once per process and quint command, until its
+    # text or the text of a file it imports changes: one compile costs a
+    # second or two of node, and every Spec.new asks for one. Its other
+    # modules reuse that compile: quint typechecks every module of the file
+    # whichever is main, and --main only sets "main" and adds q::init and
+    # q::step, which nothing here reads. They are `true` here: quint names
+    # init and step there by default, and fails a module that lacks either,
+    # though a caller can pass step: another action. Threads that ask for one
+    # file at once wait for one compile; other files compile beside it.
+    #
+    # With +flat+, the IR holds only +main+, with each definition it imports
+    # among its own declarations, as quint flattens a module before it runs
+    # it. That is one compile per module, so only a module that imports asks
+    # for it. quint drops each imported definition that neither q::init, nor
+    # q::step, nor a declaration of +main+ reaches, so q::step there names
+    # every one it can (imported_names): a module needs no action named step
+    # to compile, and a definition only the caller reads stays.
+    def self.compile(path, main: nil, flat: false)
+      key = [ command, File.expand_path(path), (main if flat) ]
+      wanted = main || File.basename(path, ".qnt")
+      @locking.synchronize { @locks[key] ||= Mutex.new }.synchronize do
+        sources = sources(path) if File.file?(path)
+        cached_sources, ir = @compiled[key]
+        if sources && sources == cached_sources && ir["modules"].any? { _1["name"] == wanted }
+          return ir["main"] == wanted ? ir : ir.merge("main" => wanted).freeze
+        end
+
+        ir = compile_now(path, main, flat)
+        @compiled[key] = [ sources, ir ] if sources
+        ir
+      end
+    end
+    @compiled = {}
+    @locks = {}
+    @locking = Mutex.new
+
+    # The text of +path+ and of each file it imports, directly or through
+    # another, by path. Quint resolves `from "name"` against the directory of
+    # the file that writes it, and adds .qnt to the name, also to one that
+    # ends in .qnt, so `from "start.qnt"` reads start.qnt.qnt. A name in
+    # a comment reads as an import too, which costs only a file read.
+    def self.sources(path, read = {})
+      path = File.expand_path(path)
+      return read if read.key?(path) || !File.file?(path)
+
+      read[path] = File.read(path)
+      read[path].scan(/\bfrom\s+"([^"]+)"/) do |(name)|
+        sources(File.join(File.dirname(path), "#{name}.qnt"), read)
+      end
+      read
+    end
+
+    def self.compile_now(path, main, flat)
+      Dir.mktmpdir("quint") do |dir|
+        # Into a file: through a pipe, quint exits before its 64 KB of JSON is
+        # out. With --out, quint writes the modules as the file has them; on
+        # stdout it prints the main module flattened. The shell makes that file
+        # before quint runs, so a flat compile that fails leaves it empty.
+        out = File.join(dir, "ir.json")
+        words = [ "compile", "--target", "json", path, *([ "--main", main ] if main), "--init", "true" ]
+        output, status = if flat
+                           capture(*words, "--step", "and(true, #{imported_names(compile(path, main:), main).join(', ')})", stdout: out)
+                         else
+                           capture(*words, "--step", "true", "--out", out)
+                         end
+        ir = begin
+          File.size?(out) ? JSON.parse(File.read(out), freeze: true) : {}
+        rescue JSON::ParserError
+          # A flat compile that fails to flatten prints the module text
+          # instead, and its error with the stack of quint's own code.
+          output = "#{output.gsub(/^ +at .*\n?/, '').rstrip}\nquint flattens every module of the file, so the module that lacks the name may be another one"
+          { "stage" => "flattening" }
+        end
+        return ir if status.success? && ir.key?("modules")
+
+        # With --out, quint writes its errors into the file and prints nothing;
+        # a missing spec leaves no error at all, only the stage it stopped at,
+        # and a missing module only the modules the file has. quint lists them
+        # in an order an edit to one module can change; it numbers a module
+        # after the text it parses, so its id gives the order of the file.
+        modules = ir.fetch("modules", []).sort_by { _1["id"] }.map { _1["name"] }
+        wanted = main || File.basename(path, ".qnt")
+        missing = "no module is named #{wanted}; #{path} has #{modules.join(', ')}" if modules.any? && !modules.include?(wanted)
+        reasons = [ output.strip, *ir.fetch("errors", []).map { _1["explanation"] }, missing.to_s ].reject(&:empty?)
+        failed "quint compile failed for #{path} at the #{ir.fetch('stage', 'start')} stage\n#{reasons.join("\n")}"
+      end
+    end
+
+    # Each name +main+ imports, so a flat compile whose --step is `and` of
+    # them keeps every definition +main+ imports, not only the ones its own
+    # declarations reach. quint 0.33.0 resolves the names of --step there
+    # and checks no type, so a value, a run, or a def with parameters stands
+    # in it as an action does. An instance adds no name: its definitions
+    # would bring its variables, which a trace of `quint run` lacks when
+    # nothing of +main+ reaches them, and init would leave them unassigned.
+    # An export can name a module by what an import of it calls it, such as
+    # A in `import base as A` and `export A.*`.
+    def self.imported_names(ir, main)
+      modules = ir.fetch("modules").to_h { [ _1["name"], _1["declarations"] ] }
+      named = ->(declarations, by) { declarations.select { [ nil, "*", _1["name"] ].include?(by["defName"]) }.map { renamed(_1, by) } }
+      shown = lambda do |name|
+        declarations = modules.fetch(name, [])
+        aliases = declarations.select { _1["kind"] == "import" }.to_h { [ _1["qualifiedName"], _1["protoName"] ] }
+        declarations.flat_map do |declaration|
+          case declaration["kind"]
+          when "def" then [ declaration ]
+          when "export" then named.(shown.(aliases.fetch(declaration["protoName"], declaration["protoName"])), declaration)
+          else []
+          end
+        end
+      end
+      modules.fetch(main).select { _1["kind"] == "import" }.flat_map { named.(shown.(_1["protoName"]), _1) }.map { _1["name"] }
+    end
+
+    def self.renamed(declaration, import)
+      import["qualifiedName"] ? declaration.merge("name" => "#{import['qualifiedName']}::#{declaration['name']}") : declaration
+    end
+
+    # Writes +traces+ traces of the spec's +step+ action and yields each file.
+    # +main+ names the module to run; without it, quint runs the module named
+    # after the file. +reach+ names a definition of the module that holds at
+    # the state a test is after: each trace then ends at the first state where
+    # it holds, and only the traces that get there are yielded.
+    def self.simulate(path, traces:, max_steps:, seed:, main: nil, step: "step", backend: "rust", reach: nil)
+      Dir.mktmpdir("quint") do |dir|
+        refuse_unfound = runnable!(path, main:, step:, reach:)
+        evaluator = self.evaluator if backend == "rust"
+        input = evaluator_input(path, traces:, max_steps:, seed:, main:, step:, reach:) if evaluator
+        if input
+          write_traces(evaluator, input, dir)
+        else
+          arguments = [ "run", path, "--mbt", "--backend", backend, "--max-steps", max_steps, "--max-samples", traces,
+                        "--n-traces", traces, "--seed", seed, "--step", step, "--out-itf", "#{dir}/trace_{seq}.itf.json", "--verbosity", 0 ]
+          arguments += [ "--main", main ] if main
+          # quint ends a trace where its invariant breaks, and exits 1 then.
+          arguments += [ "--invariant", "not(#{reach})" ] if reach
+          output, status = capture(*arguments)
+          refuse_unfound.(output)
+          failed "quint run failed:\n#{output}" unless status.success? || reach && output.match?(/^error: invariant violated$/i)
+        end
+
+        # A trace that broke the invariant is one that reached +reach+.
+        traces_written = Dir["#{dir}/trace_*.itf.json"].sort_by { _1[/(\d+)\.itf/, 1].to_i }
+        traces_written.select! { JSON.parse(File.read(_1)).dig("#meta", "status") == "violation" } if reach
+        if reach && traces_written.empty?
+          failed "quint: no trace of #{traces} reached #{reach} within #{max_steps} steps; raise max_steps or traces"
+        end
+
+        written_by = call("simulate", path, traces:, max_steps:, seed:, main:, step:, backend:, reach:)
+        yield_traces(traces_written, seed:, written_by:) { yield _1 }
+      end
+    end
+
+    # Raises ArgumentError when +step+ names no action without parameters, or
+    # +reach+ no predicate. quint finds that out only while it runs, and its
+    # two evaluators each say "Expected boolean" in words of their own. A
+    # name the module does not declare may be one it imports, which this IR
+    # does not hold, so the check it returns reads quint's output for a name
+    # quint did not find either.
+    def self.runnable!(path, main:, step:, reach:)
+      ir = compile(path, main:)
+      declarations = ir.fetch("modules").find { _1["name"] == ir["main"] }.fetch("declarations")
+      kinds = declarations.select { _1["name"] }.to_h { [ _1["name"], kind_of(_1, ir.fetch("types")) ] }
+      wanted = { "step" => [ step, "an action", "an action without parameters" ],
+                 "reach" => [ reach, "a predicate", "a predicate, a boolean val or def without parameters" ] }
+      refuse = lambda do |argument, what|
+        name, kind, takes = wanted.fetch(argument)
+        such_as = kinds.select { |of_name, of| of == kind && of_name != "init" && !of_name.start_with?("q::") }.keys.sort.join(", ")
+        Agreement.refuse "quint: #{argument} names #{name}, #{what}; #{argument} takes #{takes}, such as #{such_as}"
+      end
+      wanted.each do |argument, (name, kind)|
+        refuse.(argument, "#{kinds[name]} of #{ir['main']}") if kinds.key?(name) && kinds[name] != kind
+      end
+      lambda do |output|
+        unfound = output[/\[QNT404\] Name '(.+)' not found/, 1]
+        Agreement.refuse(without_init(ir["main"])) if unfound == "init"
+        argument, = wanted.find { |_, (name)| name == unfound } if unfound
+        refuse.(argument, "which #{ir['main']} neither declares nor imports") if argument
+      end
+    end
+
+    # Quint's own --init could name another action, but a trace names its
+    # first step after that action, the model and the machine step through
+    # init, and a driver reads init: one name keeps the four alike.
+    def self.without_init(main)
+      "quint: #{main} neither declares nor imports an action named init; quint_driver starts every trace " \
+        "and every model at init, so declare `action init = ...` with what starts #{main}"
+    end
+
+    # What a declaration is, as a step or a reach has to tell: a variant
+    # quint declares as a val, or as a def when it carries a value. A val and
+    # a def without parameters both read as a value: the keyword changes
+    # nothing a step or a reach needs.
+    def self.kind_of(declaration, types)
+      expr = declaration["expr"] || {}
+      lambda = expr["kind"] == "lambda"
+      type = types.dig(declaration["id"].to_s, "type", "kind")
+      case
+      when declaration["kind"] == "var" then "a variable"
+      when declaration["kind"] == "const" then "a constant"
+      when declaration["kind"] != "def" then "a type"
+      when (lambda ? expr["expr"] : expr)["opcode"] == "variant" then "a case of a sum type"
+      when declaration["qualifier"] == "action" then lambda ? "an action with parameters" : "an action"
+      when declaration["qualifier"] == "run" then "a run"
+      when declaration["qualifier"] == "temporal" then "a temporal formula"
+      when lambda then "a def with parameters"
+      when type == "bool" then "a predicate"
+      else "#{type.match?(/\A[aeiou]/) ? 'an' : 'a'} #{type} value"
+      end
+    end
+
+    # Writes the trace of the run named +name+, such as
+    # `run lendTest = init.then(...)`, and yields its file. +main+ names the
+    # module that holds the run. quint test writes no mbt::actionTaken, so
+    # replay it with Trace.replay's +action+: the spec has to record the
+    # action each step took, as a Choreo spec does.
+    def self.test(path, name, seed:, main: nil)
+      Dir.mktmpdir("quint") do |dir|
+        arguments = [ "test", path, "--match", "^#{name}$", "--seed", seed, "--max-samples", 1, "--out-itf", "#{dir}/test_{seq}.itf.json", "--verbosity", 1 ]
+        arguments += [ "--main", main ] if main
+        output, status = capture(*arguments)
+        failed "quint test failed:\n#{output}" unless status.success?
+
+        written = Dir["#{dir}/test_*.itf.json"]
+        if written.empty?
+          ir = compile(path, main:)
+          runs = ir["modules"].find { _1["name"] == ir["main"] }["declarations"].select { _1["qualifier"] == "run" }.map { _1["name"] }
+          failed "quint: no run is named #{name} in #{ir['main']}; it has #{runs.sort.join(', ')}"
+        end
+        yield_traces(written, seed:, written_by: call("test", path, name, seed:, main:)) { yield _1 }
+      end
+    end
+
+    # The call that writes the same traces again, with the spec named as
+    # raised in names a frame.
+    def self.call(method, path, *names, **options)
+      arguments = [ Agreement.relative(File.expand_path(path)), *names ].map(&:inspect)
+      "Quint.#{method}(#{[ *arguments, *options.compact.map { "#{_1}: #{_2.inspect}" } ].join(', ')})"
+    end
+
+    # The trace files go with their directory, so a replay's failure names
+    # its trace by +seed+ and +written_by+, the call that writes it again,
+    # instead of by its path.
+    def self.yield_traces(traces, seed:, written_by:)
+      traces.each do |trace|
+        @written[trace] = { seed:, written_by: }
+        yield trace
+      rescue Mismatch, StepRaised => failure
+        name_trace(failure, trace)
+        raise
+      ensure
+        @written.delete(trace)
+      end
+    end
+    @written = {}
+
+    # Names +trace+ on a +failure+ that names none and, while a simulate or
+    # test block is yielding it, the seed and the call that write it again.
+    # It keeps its class and cause, and leaves quint_driver's frames out of its
+    # backtrace, as Agreement.outside says. Trace.replay calls it too, so
+    # a block that rescues a replay's failure reads what the caller of
+    # simulate reads.
+    def self.name_trace(failure, trace)
+      failure.send(:name_trace, trace, **@written[trace].to_h) unless failure.trace
+      Agreement.lead_outside(failure)
+    end
+
+    # The Rust evaluator quint 0.33.0 runs under `quint run --backend rust`.
+    # Its stdin format is not a documented interface, so the gem reads only
+    # this version's.
+    EVALUATOR_VERSION = "v0.7.0"
+
+    # The Rust evaluator simulate runs, without node: QUINT_EVALUATOR names
+    # it, and an empty QUINT_EVALUATOR means `quint run`. Unset, it is the copy
+    # quint downloaded into QUINT_HOME (~/.quint by default), or `quint run`
+    # when there is none.
+    def self.evaluator
+      return ENV["QUINT_EVALUATOR"].then { _1.empty? ? nil : _1 } if ENV.key?("QUINT_EVALUATOR")
+
+      home = ENV.fetch("QUINT_HOME") { File.join(Dir.home, ".quint") }
+      found = File.join(home, "rust-evaluator-#{EVALUATOR_VERSION}", Gem.win_platform? ? "quint_evaluator.exe" : "quint_evaluator")
+      found if File.executable?(found)
+    end
+
+    # What `quint run --mbt` sends the evaluator for this call, or nil when
+    # +step+ is no action of the module or +reach+ no definition of it, so
+    # `quint run` reports it.
+    def self.evaluator_input(path, traces:, max_steps:, seed:, main:, step:, reach:)
+      ir = compile(path, main:)
+      declarations = ir.fetch("modules").find { _1["name"] == ir["main"] }&.fetch("declarations") || []
+      table = ir.fetch("table").dup
+      id = table.keys.map(&:to_i).max.to_i
+      # quint parses --init and --step into name nodes with fresh ids, and
+      # the table resolves each id to the action.
+      named = %w[init].push(step).map do |action|
+        definition = declarations.find { _1["kind"] == "def" && _1["qualifier"] == "action" && _1["name"] == action } or return
+        table[(id += 1).to_s] = definition
+        { "id" => id, "kind" => "name", "name" => action }
+      end
+      invariant = if reach
+                    table[(id += 1).to_s] = declarations.find { _1["kind"] == "def" && _1["name"] == reach } || return
+                    { id: id + 1, kind: "app", opcode: "not", args: [ { id:, kind: "name", name: reach } ] }
+                  else
+                    { id: id + 1, kind: "bool", value: true }
+                  end
+      number = Integer(seed.to_s, exception: false) or failed "quint: the seed #{seed.inspect} is not an integer"
+      { parsed: { modules: ir["modules"], table:, main: ir["main"], init: named[0], step: named[1],
+                  invariants: [ invariant ], witnesses: [] },
+        source: path, nruns: traces, nsteps: max_steps, ntraces: traces, nthreads: [ traces, Etc.nprocessors ].min,
+        seed: number, mbt: true, verbosity: 0 }
+    end
+
+    # Writes each trace the evaluator returns as quint would: trace_0.itf.json
+    # onwards, in the order it returns them.
+    def self.write_traces(evaluator, input, dir)
+      output, errors, status = begin
+        Open3.capture3(evaluator, "simulate-from-stdin", stdin_data: JSON.generate(input))
+      rescue SystemCallError => error
+        failed "quint: cannot run the Rust evaluator #{evaluator}; set QUINT_EVALUATOR to it, or to an empty string to simulate through `quint run` (#{error.message})"
+      end
+      failed "quint: the Rust evaluator #{evaluator} failed:\n#{errors}" unless status.success?
+
+      result = begin
+        JSON.parse(output.lines.reverse.find { _1.start_with?("{") }.to_s)
+      rescue JSON::ParserError
+      end
+      unless result.is_a?(Hash) && result["bestTraces"].is_a?(Array) && result["bestTraces"].all? { _1["states"].is_a?(Hash) }
+        failed "quint: the Rust evaluator #{evaluator} answered in a format quint_driver does not read; " \
+                           "it reads the #{EVALUATOR_VERSION} evaluator quint 0.33.0 runs. Set QUINT_EVALUATOR to that " \
+                           "evaluator, or to an empty string to simulate through `quint run`"
+      end
+      # A violation is only possible when simulate asks to reach a definition.
+      unless %w[ok violation].include?(result["status"])
+        failed "quint run failed:\n#{result.fetch('errors', []).map { "Error [#{_1['code']}]: #{_1['message']}" }.join("\n")}"
+      end
+
+      result["bestTraces"].each_with_index { |trace, index| File.write(File.join(dir, "trace_#{index}.itf.json"), JSON.generate(trace["states"])) }
+    end
+
+    # QUINT is a shell command, such as `npx --yes ...`, so the line runs
+    # through a shell, and each word after it is quoted: an app's folder can
+    # have a space in its name. +stdout+ is a file quint's output goes into.
+    def self.capture(*words, stdout: nil)
+      line = "#{command} #{Shellwords.join(words)}#{" > #{Shellwords.escape(stdout)}" if stdout}"
+      output, status = Open3.capture2e(line)
+      # Only npm prefixes its lines with "npm error", so these mean npx did
+      # not get as far as running quint.
+      fetch = output[/^npm (?:error|ERR!) code .*/] if !status.success? && !ENV.key?("QUINT")
+      failed "quint: QUINT is unset, and `#{command}` could not fetch quint (#{fetch}); install quint and set QUINT to its command" if fetch
+
+      [ output, status ]
+    rescue SystemCallError => error
+      failed "quint: cannot run `#{command}`; set QUINT to the quint command (#{error.message})"
+    end
+
+    # A failure of quint's, raised from the caller's line: the spec is the
+    # caller's, so its frame leads, as a refused argument's does.
+    def self.failed(message) = Agreement.refuse(message, QuintFailed)
+
+    private_class_method :call, :capture, :compile_now, :evaluator_input, :failed, :imported_names, :kind_of, :name_trace, :renamed, :runnable!, :sources, :without_init, :write_traces, :yield_traces
+  end
+end

data/lib/quint_driver/spec.rb

@@ -0,0 +1,110 @@
+module QuintDriver
+  # One module of a compiled Quint spec, and the rules a step action offers.
+  class Spec
+    # A move the step action can take: +action+ called with +args+ (IR nodes),
+    # whose free names are the nondet picks drawn from +domains+ (name => IR
+    # node of a set), in order, since a later set may read an earlier pick.
+    # +fixed+ names the domains that are the same set in every state and
+    # after every earlier pick, so a caller can evaluate each of them once.
+    Rule = Struct.new(:action, :args, :domains, :fixed)
+
+    attr_reader :declarations
+
+    # The q:: definitions are what quint adds for --main, so only the module
+    # a file compiled for first would have them. A module that imports reads
+    # quint's flattened copy, where what it imports is its own.
+    def initialize(path, main:)
+      ir = Quint.compile(path, main:)
+      declarations = ir.fetch("modules").find { _1["name"] == main }.fetch("declarations")
+      ir = Quint.compile(path, main:, flat: true) if declarations.any? { %w[import instance export].include?(_1["kind"]) }
+      @declarations = ir.fetch("modules").find { _1["name"] == main }.fetch("declarations")
+                        .reject { _1["name"].to_s.start_with?("q::") }
+      @effects = ir.fetch("effects")
+      @main = main
+    end
+
+    # With +step+ nil, the model holds no rules: it evaluates definitions on
+    # a state it is given, and takes no step.
+    def model(step = "step") = Model.send(:new, declarations, step ? rules(step) : [], owners)
+
+    # Raises ArgumentError unless each of +names+ is a definition the model
+    # can read in a state: a val or a def without parameters, not an action,
+    # and not a sum type's case, which quint declares as a val too.
+    def observable!(names)
+      name = names.find { !observable.include?(_1) } or return
+      Agreement.refuse "quint: observe names #{name}, which is no definition without parameters of #{@main}; it has #{observable.sort.join(', ')}"
+    end
+
+    # The definition that writes each IR node, by node id, so the model names
+    # where a node is written when it cannot evaluate it.
+    def owners
+      @owners ||= declarations.each_with_object({}) do |declaration, owners|
+        ids_in(declaration["expr"]).each { owners[_1] = declaration["name"] } if declaration["kind"] == "def"
+      end.freeze
+    end
+
+    # Walks +step+: `any` splits into rules, `nondet x = S.oneOf()` adds a
+    # domain, and a call of a declared action ends a rule. A parameterless
+    # action made of `any` (such as `step` inside a wider step) opens in place.
+    # An `all` of one action is that action, as in `all { nondet x = ...
+    # any { ... } }`; an `all` of more holds a condition no rule can carry.
+    def rules(step)
+      actions = declarations.select { _1["qualifier"] == "action" }.to_h { [ _1["name"], _1 ] }
+      Agreement.refuse(Quint.send(:without_init, @main)) unless actions.key?("init")
+      choice = ->(node) { node["kind"] == "app" && node["opcode"] == "actionAny" }
+      walk = lambda do |node, domains, within|
+        if choice.(node)
+          node["args"].flat_map { walk.(_1, domains, within) }
+        elsif node["kind"] == "app" && node["opcode"] == "actionAll" && node["args"].size == 1
+          walk.(node["args"].first, domains, within)
+        elsif node["kind"] == "let" && node["opdef"]["qualifier"] == "nondet" && node["opdef"]["expr"]["opcode"] == "oneOf"
+          walk.(node["expr"], domains.merge(node["opdef"]["name"] => node["opdef"]["expr"]["args"].first), within)
+        elsif actions.key?(node["name"])
+          body = actions[node["name"]]["expr"]
+          choice.(body) ? walk.(body, domains, node["name"]) : [ Rule.new(node["name"], [], domains, fixed(domains)) ]
+        elsif node["kind"] == "app" && actions.key?(node["opcode"])
+          [ Rule.new(node["opcode"], node["args"], domains, fixed(domains)) ]
+        else
+          arm = node["opcode"] == "assign" ? "assigns #{node['args'][0]['name']}'" : "holds #{node['opcode'] || node['kind']}"
+          raise Unsupported, "quint: #{within} #{arm} in an arm that names no action; name every action in #{step}"
+        end
+      end
+      top = actions.fetch(step) { Agreement.refuse "quint: no action is named #{step}; the module has #{actions.keys.sort.join(', ')}" }
+      walk.(top["expr"], {}, step)
+    end
+
+    private
+      def observable
+        @observable ||= declarations.select do
+          %w[val def pureval puredef].include?(_1["qualifier"]) && _1["expr"]["kind"] != "lambda" && _1["expr"]["opcode"] != "variant"
+        end.map { _1["name"] }
+      end
+
+      # Quint's effect of a set says which variables it reads, and a pick is
+      # not a variable, so a set also has to name no earlier pick. A lambda
+      # parameter that shadows a pick counts as the pick: one evaluation too
+      # many is only slower.
+      def fixed(domains)
+        domains.each_with_index.filter_map do |(name, domain), index|
+          reads_none = @effects.dig(domain["id"].to_s, "effect") == { "kind" => "concrete", "components" => [] }
+          name if reads_none && !names_in(domain).intersect?(domains.keys.take(index))
+        end.to_set
+      end
+
+      def ids_in(node)
+        case node
+        when Hash then [ node["id"], *node.each_value.flat_map { ids_in(_1) } ].compact
+        when Array then node.flat_map { ids_in(_1) }
+        else []
+        end
+      end
+
+def names_in(node)
+        case node
+        when Hash then [ node["kind"] == "name" ? node["name"] : node["opcode"], *node.each_value.flat_map { names_in(_1) } ].compact
+        when Array then node.flat_map { names_in(_1) }
+        else []
+        end
+      end
+  end
+end

data/lib/quint_driver/trace.rb

@@ -0,0 +1,129 @@
+module QuintDriver
+  # A trace `quint run --mbt` wrote. Each state names the action the
+  # simulator took and the values it picked, so a driver can run the same
+  # command and be held to the next state.
+  module Trace
+    Step = Struct.new(:action, :picks, :expected, :index)
+
+    # +state+ is the path to the record or map a driver is held to, such as
+    # %w[choreo::s system] in a Choreo spec, which keeps the whole state in
+    # one variable. +action+ is the path to a variable the spec records the
+    # action in, as a sum type whose tag names the action and whose record
+    # holds its picks; without it, the action is quint's mbt::actionTaken,
+    # which `quint run --mbt` writes and quint test does not.
+    def self.steps(path, state: [], action: nil)
+      JSON.parse(File.read(path)).fetch("states").each_with_index.map do |itf, index|
+        values = decode(itf)
+        taken, picks = if action
+                         at(values, action, index).then { _1.is_a?(String) ? [ _1, {} ] : _1 }
+                       else
+                         [ values.fetch("mbt::actionTaken") { raise Unsupported, "quint: state #{index} of the trace names no action taken; quint test writes no mbt::actionTaken, so pass action: the path to a variable that records it" },
+                           made(itf.fetch("mbt::nondetPicks")) ]
+                       end
+        expected = at(values.reject { _1.start_with?("mbt::") }, state, index)
+        unless expected.is_a?(Hash)
+          raise Unsupported, "quint: state #{index} of the trace has #{state.join('.')} = #{Agreement.show(expected)}, " \
+                             "which is no record or map; pass state: the path to the record or map the driver reports"
+        end
+        Step.new(taken, picks, expected, index)
+      end
+    end
+
+    # quint wraps each pick in an Option of its own: Some when the move made
+    # it, None when it did not. Only that wrapper is taken off, so a pick the
+    # move made of the spec's own None is nil and still present.
+    def self.made(picks)
+      picks.filter_map { |name, pick| [ name, decode(pick["value"]) ] if pick["tag"] == "Some" }.to_h
+    end
+    private_class_method :made
+
+    def self.at(values, path, index)
+      path.each_with_index.reduce(values) do |value, (key, depth)|
+        next value[key] if value.is_a?(Hash) && value.key?(key)
+
+        within = path.take(depth).join(".")
+        raise Unsupported, "quint: state #{index} of the trace has no #{path.take(depth + 1).join('.')}" \
+                           "#{"; #{within} has #{value.keys.sort.join(', ')}" if value.is_a?(Hash)}"
+      end
+    end
+    private_class_method :at
+
+    # +log+, an IO such as $stdout, gets each step before the driver runs it.
+    # +state+ and +action+ are paths into each state, as Trace.steps reads them.
+    # +observe+ names definitions of +spec+, a Spec, that derive a value from
+    # the variables, such as a total no variable holds: the driver reports
+    # each one in its state by name, and is held to the value the spec's
+    # definition has in the trace's state. +ignore+ names variables the
+    # driver does not report, such as what a remote service answers, which
+    # the spec models and the driver only reads to set the system up; the
+    # driver reports every other variable. Returns the steps it ran, so a
+    # caller can count the actions and states its traces reached.
+    def self.replay(path, driver, log: nil, state: [], action: nil, spec: nil, observe: [], ignore: [])
+      observe, ignore = observe.map(&:to_s), ignore.map(&:to_s)
+      observed = observed(path, spec, observe)
+      ran = []
+      steps = steps(path, state:, action:)
+      Agreement.ignorable!(ignore, steps.first.expected.keys, "the trace's state") if steps.any?
+      steps.each do |step|
+        # An unnamed action names no command for the driver to run.
+        raise Unsupported, "quint: step #{step.index} of #{path} took an anonymous action; name every action in step" if step.action.empty?
+
+        log&.puts "step #{step.index} #{step.action} #{Agreement.show(step.picks)}"
+        ran << [ step.action, step.picks ]
+        at = "step #{step.index} `#{step.action}` #{Agreement.show(step.picks)}"
+        actual = Agreement.drive(at, steps: ran) do
+          driver.step(step.action, step.picks)
+          driver.state
+        end
+        Agreement.check!(at, step.expected.merge(observed[step.index]), actual, by: "trace", steps: ran, observe:, spec:, ignore:)
+      end
+    rescue Mismatch, StepRaised => failure
+      Quint.send(:name_trace, failure, path)
+      raise
+    end
+
+    # The value of each definition +observe+ names, in each state of the
+    # trace. The model reads the state as quint wrote it, so the driver's
+    # steps never pass through the model; it reads only the spec's variables,
+    # so the mbt:: entries stay.
+    def self.observed(path, spec, observe)
+      return Hash.new({}) if observe.empty?
+      Agreement.refuse "quint: observe needs spec:, the Spec that evaluates #{observe.join(', ')}" unless spec
+
+      spec.observable!(observe)
+      model = spec.model(nil)
+      JSON.parse(File.read(path)).fetch("states").map do |values|
+        model.enter(decode(values) { |tag, inner| Model::Variant.new(tag, inner) })
+        model.observe(observe)
+      end
+    end
+    private_class_method :observed
+
+    # ITF (https://apalache-mc.org/docs/adr/015adr-trace.html) to plain values.
+    # An Option is nil for None and its value for Some, as Model.plain gives one.
+    # With a block, a sum type's value is what the block makes of its tag and
+    # its decoded value, as the model holds one.
+    def self.decode(value, &variant)
+      case value
+      when Array then value.map { decode(_1, &variant) }
+      when Hash
+        if value.key?("#set") then value["#set"].to_set { decode(_1, &variant) }
+        elsif value.key?("#map") then value["#map"].to_h { |k, v| [ decode(k, &variant), decode(v, &variant) ] }
+        elsif value.key?("#tup") then value["#tup"].map { decode(_1, &variant) }
+        elsif value.key?("#bigint") then value["#bigint"].to_i
+        elsif value.key?("tag") && value.key?("value")
+          inner = decode(value["value"], &variant)
+          return variant.(value["tag"], inner) if variant
+
+          case value["tag"]
+          when "None" then nil
+          when "Some" then inner
+          else inner == [] ? value["tag"] : [ value["tag"], inner ]
+          end
+        else value.except("#meta").transform_values { decode(_1, &variant) }
+        end
+      else value
+      end
+    end
+  end
+end

data/lib/quint_driver/version.rb

@@ -0,0 +1,3 @@
+module QuintDriver
+  VERSION = "0.1.0"
+end