quint_driver 0.1.0

data/examples/loans/loans.qnt

@@ -0,0 +1,57 @@
+// A lending shelf: a member borrows one book at a time, and gives it back.
+// Each command has a refused twin, so a trace checks the refusals too.
+module loans {
+  type Outcome = Done | Refused(str)
+
+  pure val BOOKS = Set("b1", "b2", "b3")
+  pure val MEMBERS = Set("m1", "m2")
+  pure val NOBODY = ""
+
+  var holder: str -> str
+  var outcome: Outcome
+
+  pure def onLoan(h: str -> str, b: str): bool = h.get(b) != NOBODY
+  pure def holds(h: str -> str, m: str): bool = BOOKS.exists(b => h.get(b) == m)
+  pure def borrowRefusal(h: str -> str, m: str, b: str): str =
+    if (onLoan(h, b)) "on_loan" else if (holds(h, m)) "limit_reached" else ""
+
+  action init = all {
+    holder' = Map("b1" -> NOBODY, "b2" -> NOBODY, "b3" -> NOBODY),
+    outcome' = Done,
+  }
+
+  action borrow(m: str, b: str): bool = all {
+    borrowRefusal(holder, m, b) == "",
+    holder' = holder.put(b, m),
+    outcome' = Done,
+  }
+  action borrow_refused(m: str, b: str): bool = all {
+    borrowRefusal(holder, m, b) != "",
+    holder' = holder,
+    outcome' = Refused(borrowRefusal(holder, m, b)),
+  }
+  action give_back(b: str): bool = all {
+    onLoan(holder, b),
+    holder' = holder.put(b, NOBODY),
+    outcome' = Done,
+  }
+  action give_back_refused(b: str): bool = all {
+    not(onLoan(holder, b)),
+    holder' = holder,
+    outcome' = Refused("not_on_loan"),
+  }
+
+  action step = any {
+    nondet m = MEMBERS.oneOf()
+    nondet b = BOOKS.oneOf()
+    any { borrow(m, b), borrow_refused(m, b) },
+    nondet b = BOOKS.oneOf()
+    any { give_back(b), give_back_refused(b) },
+  }
+
+  val one_book_each = MEMBERS.forall(m => BOOKS.filter(b => holder.get(b) == m).size() <= 1)
+  // False once a book is lent: the tests use it to see a broken invariant reported.
+  val nothing_on_loan = BOOKS.forall(b => not(onLoan(holder, b)))
+  // True once two books are lent: the tests ask quint for traces that reach it.
+  val two_on_loan = BOOKS.filter(b => onLoan(holder, b)).size() == 2
+}

data/examples/loans/loans.rb

@@ -0,0 +1,62 @@
+# The system the tests hold to loans.qnt, and a driver that runs the spec's
+# actions on it. BrokenLoans forgets the one-book limit.
+class Loans
+  class Refused < StandardError
+    attr_reader :reason
+
+    def initialize(reason)
+      @reason = reason
+      super(reason.to_s)
+    end
+  end
+
+  def initialize = @holders = {}
+
+  def borrow(member, book)
+    raise Refused.new(:on_loan) if @holders.key?(book)
+    raise Refused.new(:limit_reached) if limited? && @holders.value?(member)
+
+    @holders[book] = member
+  end
+
+  def give_back(book)
+    @holders.delete(book) || raise(Refused.new(:not_on_loan))
+  end
+
+  def holder(book) = @holders[book]
+
+  private
+    def limited? = true
+end
+
+class BrokenLoans < Loans
+  private
+    def limited? = false
+end
+
+class LoansDriver
+  SPEC = File.expand_path("loans.qnt", __dir__)
+  BOOKS = %w[b1 b2 b3].freeze
+
+  def self.spec = @spec ||= QuintDriver::Spec.new(SPEC, main: "loans")
+
+  def initialize(system = Loans)
+    @system = system
+  end
+
+  def step(action, picks)
+    @outcome = "Done"
+    case action.delete_suffix("_refused")
+    when "init" then @loans = @system.new
+    when "borrow" then @loans.borrow(picks.fetch("m"), picks.fetch("b"))
+    when "give_back" then @loans.give_back(picks.fetch("b"))
+    else raise ArgumentError, "no command for the action #{action}"
+    end
+  rescue Loans::Refused => refusal
+    @outcome = [ "Refused", refusal.reason.to_s ]
+  end
+
+  def state
+    { "holder" => BOOKS.to_h { [ _1, @loans.holder(_1) || "" ] }, "outcome" => @outcome }
+  end
+end

data/lib/quint_driver/hegel.rb

@@ -0,0 +1,141 @@
+# The Hegel adapter. It is the one file that loads hegeltest, which needs
+# Ruby 3.4, so trace replay and the model run without it.
+require "hegel"
+require_relative "../quint_driver"
+
+module QuintDriver
+  Agreement.hide(File.dirname(Hegel::Stateful.method(:run).source_location.first))
+
+  # A Hegel::StateMachine for +spec+'s +step+ action. Hegel picks each move,
+  # the model takes it, the driver runs the same command on the system, and
+  # the two states have to be equal afterwards. Hegel owns every choice, so a
+  # failure shrinks to a short sequence of commands.
+  #
+  # +choose+ is how a move is drawn:
+  # - :rule, Hegel picks a rule and a disabled one is rejected (tc.assume).
+  #   Shrinks to the shortest sequence; deep states take more test cases.
+  # - :rotate, a disabled rule passes the turn to the next enabled one.
+  #   Nothing is rejected, so deep states come sooner; shrinking leaves extra
+  #   moves, because a draw means a different rule once the state differs.
+  #
+  # +observe+ names definitions of the spec, as Trace.replay takes them: the
+  # driver reports each one in its state, held to the model's value.
+  # +ignore+ names variables the driver does not report, as Trace.replay
+  # takes them.
+  def self.machine(spec, driver:, step: "step", invariants: [], choose: :rule, observe: [], ignore: [])
+    rules = spec.rules(step)
+    observe, ignore = observe.map(&:to_s), ignore.map(&:to_s)
+    spec.observable!(observe)
+    Agreement.ignorable!(ignore, spec.declarations.select { _1["kind"] == "var" }.map { _1["name"] }, "the spec's variables")
+    # Many draws map to one sequence of moves, so the shrinker asks for the
+    # same sequence thousands of times: on one failure, 8818 test cases held
+    # 1342 distinct sequences. A sequence the system already agreed on is not
+    # run again. That assumes the system answers a sequence the same way each
+    # time, which the shrinker assumes too. A disagreement is never kept: it
+    # runs on the system every time, so the failure reported is one it
+    # reproduced.
+    agreed = Set.new
+    # A fixed domain (Spec::Rule#fixed) is the same list in every test case,
+    # so it is evaluated and sorted once per machine, not once per draw.
+    fixed = {}.compare_by_identity
+
+    init = [ "init", {} ].freeze
+    # A replay names a step by its index in the trace, init being step 0; the
+    # machine names a move by the number Hegel's report gives it.
+    at = ->(number, (action, picks)) { "step #{number} `#{action}` #{Agreement.show(picks)}" }
+
+    Class.new(Hegel::StateMachine) do
+      # The driver starts with the machine, before Hegel's first step, so a
+      # failure at init is reported with no step Hegel took. Once init agreed,
+      # the empty sequence is kept like any other, and a later machine starts
+      # its driver only on a move that is not.
+      define_method(:initialize) do
+        @model = spec.model(step)
+        @model.step(*init)
+        @start = @model.state.merge(@model.observe(observe))
+        @moves = []
+        @numbers = [] # the Hegel step of each move
+        @step = 0 # every rule Hegel ran, a rejected one too, as its report counts
+        @ran = 0 # how many of @moves the driver has run
+        next if agreed.include?(@moves)
+
+        start_driver
+        agreed << []
+      end
+
+      # Every driver is held to the model at init, also one started after an
+      # earlier machine agreed on init: a test database keeps the rows of an
+      # earlier test case unless the driver's init deletes them, and without
+      # this check the first move would take the blame for them.
+      define_method(:start_driver) do
+        actual = Agreement.drive(at.(0, init), steps: [ init ]) do
+          @driver = driver.call
+          @driver.step(*init)
+          @driver.state
+        end
+        Agreement.check!(at.(0, init), @start, actual, by: "model", steps: [ init ], observe:, spec:, ignore:)
+      end
+
+      define_method(:move!) do |action, picks, after|
+        @model.enter(after)
+        @moves << [ action, Model.plain(picks) ]
+        @numbers << @step
+        return if agreed.include?(@moves)
+
+        start_driver unless @driver
+        # Every move the driver has not run yet, which is more than the last
+        # one when the driver skipped a sequence it agreed on.
+        while @ran < @moves.size
+          move = @moves[@ran]
+          Agreement.drive(at.(@numbers[@ran], move), steps: [ init, *@moves[..@ran] ]) { @driver.step(*move) }
+          @ran += 1
+        end
+        last = at.(@numbers.last, @moves.last)
+        actual = Agreement.drive(last, steps: [ init, *@moves ]) { @driver.state }
+        Agreement.check!(last, @model.state.merge(@model.observe(observe)), actual, by: "model", steps: [ init, *@moves ], observe:, spec:, ignore:)
+        agreed << @moves.dup
+      end
+
+      case choose
+      when :rule
+        rules.each do |rule|
+          rule(rule.action) do |tc|
+            @step += 1
+            picks = rule.domains.each_with_object({}) do |(name, domain), chosen|
+              choices = fixed.fetch(domain) do
+                sorted = @model.value(domain, chosen).to_a.sort_by(&:to_s).freeze
+                rule.fixed.include?(name) ? fixed[domain] = sorted : sorted
+              end
+              # any? would reject a domain whose one element is false.
+              tc.assume(!choices.empty?)
+              chosen[name] = tc.draw(sampled_from(choices), label: name)
+            end
+            after = @model.try(rule.action, rule.args.map { @model.value(_1, picks) })
+            tc.assume(after)
+            tc.note { "#{rule.action} #{Model.plain(picks)}" }
+            move!(rule.action, picks, after)
+          end
+        end
+      when :rotate
+        rule(step) do |tc|
+          @step += 1
+          start = tc.draw(integers(min_value: 0, max_value: rules.size - 1), label: "rule")
+          moves = rules.rotate(start).lazy.map { @model.moves(_1) }.find(&:any?)
+          tc.assume(moves)
+          action, picks, after = tc.draw(sampled_from(moves), label: "move")
+          tc.note { "#{action} #{Model.plain(picks)}" }
+          move!(action, picks, after)
+        end
+      else Agreement.refuse "quint: choose is :rule or :rotate"
+      end
+
+      # Hegel samples an invariant between moves unless always_run is set;
+      # an invariant here holds after every move.
+      invariants.each do |name|
+        invariant(name, always_run: true) do
+          raise Mismatch, "quint: the model broke `#{name}`", Agreement.outside(caller_locations) unless @model.value(name.to_s) == true
+        end
+      end
+    end
+  end
+end

data/lib/quint_driver/model.rb

@@ -0,0 +1,289 @@
+module QuintDriver
+  # Evaluates a spec's JSON IR inside the Ruby process, so a Hegel step costs
+  # no call to another process. It covers the operators a command-per-action
+  # spec uses and raises Unsupported on any other, so a spec that outgrows it
+  # fails loudly instead of being judged wrongly. It answers the driver
+  # protocol too, which is how it is held to Quint: replay Quint's own traces
+  # through it.
+  class Model
+    Variant = Struct.new(:tag, :value)
+    BOOL = Set[false, true].freeze
+
+    # +within+ names the definition that holds the lambda, so an operator its
+    # body cannot evaluate is reported where the spec writes it.
+    Closure = Struct.new(:params, :body, :env, :within)
+
+    # Spec#model is the one way to build a model: the evaluator trusts the
+    # shape of quint's compiled IR and checks none of it.
+    private_class_method :new
+
+    # +owners+ names the definition that writes each IR node, by its id.
+    def initialize(declarations, rules, owners)
+      @owners = owners
+      @defs = declarations.select { _1["kind"] == "def" }.to_h { [ _1["name"], _1 ] }
+      @vars = declarations.select { _1["kind"] == "var" }.map { _1["name"] }
+      @rules = rules.to_h { [ _1.action, _1 ] }
+      @state = {}
+      @constant = {}
+      @within = nil
+    end
+
+    # The driver protocol. Picks from a trace are plain values; each one
+    # becomes the element of its domain that reads as the same plain value,
+    # so a variant pick is a variant again.
+    def step(action, picks)
+      args = if action == "init" then []
+             else
+               # Quint names a move after step itself when step is one action,
+               # or a nondet pick, that no `any` wraps.
+               rule = @rules.fetch(action) do
+                 raise Unsupported, "quint: no action of step is named #{action}; write step as any { ... } so each move names its action"
+               end
+               typed = rule.domains.each_with_object({}) do |(name, domain), chosen|
+                 pick = picks.fetch(name) { raise Unsupported, "quint: #{action} needs a pick for #{name}, and the move gives none" }
+                 # A pick can be false, so the lookup asks whether it found
+                 # an element, never whether the element is truthy.
+                 elements = value(domain, chosen).to_a
+                 at = elements.index { Model.plain(_1) == pick }
+                 raise Mismatch, "quint: the model cannot pick #{name} = #{pick.inspect} for #{action}" unless at
+
+                 chosen[name] = elements[at]
+               end
+               rule.args.map { value(_1, typed) }
+             end
+      enter(try(action, args) || raise(Mismatch, "quint: the model refused #{action} #{Agreement.show(picks)}"))
+    end
+
+    def state = Model.plain(@state)
+
+    # The state the action would reach, or nil when it is disabled. The model
+    # stays where it is, so a caller can ask which actions are enabled.
+    def try(name, args = [])
+      expr = @defs.fetch(name)["expr"]
+      env = {}
+      if expr["kind"] == "lambda"
+        env = expr["params"].map { _1["name"] }.zip(args).to_h
+        expr = expr["expr"]
+      end
+      @next = {}
+      return nil unless inside(name) { eval(expr, env) }
+
+      missing = @vars - @next.keys
+      raise Unsupported, "quint: #{name} leaves #{missing.join(', ')} unassigned" if missing.any?
+
+      @next
+    end
+
+    def enter(state) = @state = state
+
+    # Every [action, picks, next state] that +rule+, a Spec::Rule, allows
+    # now, in a fixed order, so the same draw means the same move from the
+    # same state.
+    def moves(rule)
+      picks_of(rule, rule.domains.to_a, {}).filter_map do |picks|
+        after = try(rule.action, rule.args.map { value(_1, picks) })
+        [ rule.action, picks, after ] if after
+      end
+    end
+
+    # A refusal names the definition that writes +node_or_name+, such as the
+    # action a domain or an argument of a rule is written in, or says the node
+    # is outside any definition when no definition of the spec holds it.
+    def value(node_or_name, env = {})
+      node = node_or_name.is_a?(String) ? { "kind" => "name", "name" => node_or_name } : node_or_name
+      inside(@owners[node["id"]]) { eval(node, env) }
+    end
+
+    # Each definition +names+ names, by name, as a plain value.
+    def observe(names) = names.to_h { [ _1, Model.plain(value(_1)) ] }
+
+    # A value as Trace.decode gives it, so a driver reads an Option the same
+    # on a replay and under the machine: nil for None, the value for Some.
+    def self.plain(value)
+      case value
+      when Variant
+        case value.tag
+        when "None" then nil
+        when "Some" then plain(value.value)
+        else value.value == [] ? value.tag : [ value.tag, plain(value.value) ]
+        end
+      when Set then value.to_set { plain(_1) }
+      when Hash then value.to_h { |k, v| [ plain(k), plain(v) ] }
+      when Array then value.map { plain(_1) }
+      else value
+      end
+    end
+
+    private
+      def picks_of(rule, domains, picks)
+        return [ picks ] if domains.empty?
+
+        (name, domain), *rest = domains
+        value(domain, picks).to_a.sort_by(&:to_s).flat_map { picks_of(rule, rest, picks.merge(name => _1)) }
+      end
+
+      def eval(node, env)
+        case node["kind"]
+        when "str", "int", "bool" then node["value"]
+        when "name" then lookup(node["name"], env)
+        when "lambda" then Closure.new(node["params"].map { _1["name"] }, node["expr"], env, @within)
+        when "let"
+          definition = node["opdef"]
+          eval(node["expr"], env.merge(definition["name"] => eval(definition["expr"], env)))
+        when "app" then apply(node["opcode"], node["args"], env)
+        else refuse("IR kind #{node['kind']}")
+        end
+      end
+
+      # Quint reserves Bool, Int and Nat, so no definition shadows them.
+      def lookup(name, env)
+        return env[name] if env.key?(name)
+        return @state.fetch(name) if @vars.include?(name)
+        return BOOL if name == "Bool"
+
+        defined(name) do
+          if %w[Int Nat].include?(name)
+            refuse("the name #{name}", "#{name} is infinite, so no move can list its picks; draw from a finite set such as 0.to(9)")
+          end
+          refuse("the name #{name}", "no definition, variable or parameter has it")
+        end
+      end
+
+      # A pure val or pure def reads no variable, and a lambda reads none
+      # until it is called, so their value is the same in every state and is
+      # evaluated once. Every other definition is evaluated on each read.
+      def defined(name, &missing)
+        @constant.fetch(name) do
+          definition = @defs.fetch(name, &missing)
+          value = inside(name) { eval(definition["expr"], {}) }
+          constant = %w[pureval puredef].include?(definition["qualifier"]) || definition["expr"]["kind"] == "lambda"
+          constant ? @constant[name] = value.freeze : value
+        end
+      end
+
+      def call(closure, args)
+        inside(closure.within) { eval(closure.body, closure.env.merge(closure.params.zip(args).to_h)) }
+      end
+
+      def inside(name)
+        outer, @within = @within, name
+        yield
+      ensure
+        @within = outer
+      end
+
+      def refuse(what, why = nil)
+        raise Unsupported, "quint: no evaluation for #{what} #{@within ? "in #{@within}" : 'outside any definition'}#{"; #{why}" if why}"
+      end
+
+      # Quint's builtin docs leave these undefined, and its two evaluators do
+      # not always agree on them (range(3, 1) is [] in one and [3, 2] in the
+      # other), so the model refuses them rather than pick an answer.
+      def undefined(what) = refuse(what, "Quint leaves it undefined")
+
+      def index!(list, i, op)
+        return i if i.between?(0, list.size - 1)
+
+        undefined("#{op}(_, #{i}) on a list of length #{list.size}")
+      end
+
+      def nonempty!(list, op) = list.empty? ? undefined("#{op} of an empty list") : list
+
+      def keyed!(map, key, op) = map.key?(key) || refuse("#{op}(_, #{key.inspect})", "the map has no such key")
+
+      # Quint documents no rounding: its evaluators truncate / and % toward
+      # zero, and Ruby's Integer#/ and #% floor, so only operands where the
+      # two agree are evaluated.
+      def divide(a, b, op)
+        refuse("#{a} #{op} #{b}", "Quint documents no rounding for a negative operand") if a.negative? || b.negative?
+        b.zero? ? undefined("#{a} #{op} 0") : a.public_send(op, b)
+      end
+
+      def apply(op, args, env)
+        case op
+        when "actionAll", "and" then args.all? { eval(_1, env) }
+        when "or" then args.any? { eval(_1, env) }
+        when "implies" then !eval(args[0], env) || eval(args[1], env)
+        when "ite" then eval(args[eval(args[0], env) ? 1 : 2], env)
+        when "assign" then @next[args[0]["name"]] = eval(args[1], env); true
+        else operate(op, args.map { eval(_1, env) })
+        end
+      end
+
+      # Every other operator reads all of its arguments, so they are evaluated
+      # once, before it runs.
+      def operate(op, values)
+        a, b, c = values
+        case op
+        when "not" then !a
+        when "eq", "iff" then a == b
+        when "neq" then a != b
+        when "igt" then a > b
+        when "igte" then a >= b
+        when "ilt" then a < b
+        when "ilte" then a <= b
+        when "iadd" then a + b
+        when "isub" then a - b
+        when "imul" then a * b
+        when "idiv" then divide(a, b, "/")
+        when "imod" then divide(a, b, "%")
+        when "iuminus" then -a
+        when "to" then a <= b ? (a..b).to_set : undefined("#{a}.to(#{b})")
+        # A set's fold order is unspecified, so Quint leaves a fold whose
+        # operator is not associative and commutative undefined.
+        when "fold", "foldl" then a.reduce(b) { |acc, x| call(c, [ acc, x ]) }
+        # The builtin docs leave foldr out, but both evaluators fold from the
+        # right and pass the element first.
+        when "foldr" then a.reverse.reduce(b) { |acc, x| call(c, [ x, acc ]) }
+        when "List", "Tup" then values
+        when "append" then a + [ b ]
+        when "concat" then a + b
+        when "head" then nonempty!(a, "head").first
+        when "tail" then nonempty!(a, "tail").drop(1)
+        when "length" then a.size
+        when "nth" then a[index!(a, b, "nth")]
+        when "indices" then (0...a.size).to_set
+        when "replaceAt" then a.dup.tap { _1[index!(a, b, "replaceAt")] = c }
+        when "slice"
+          # The docs also leave i == l.length() undefined, but both evaluators
+          # answer slice(l, l.length(), l.length()) with [], which the docs'
+          # own reading (from i inclusive to j exclusive) gives, and a spec
+          # that drops a list's last element needs it.
+          0 <= b && b <= c && c <= a.size ? a[b...c] : undefined("slice(_, #{b}, #{c}) on a list of length #{a.size}")
+        when "range" then a <= b ? (a...b).to_a : undefined("range(#{a}, #{b})")
+        when "select" then a.select { call(b, [ _1 ]) }
+        when "Set" then values.to_set
+        when "contains" then a.include?(b)
+        when "in" then b.include?(a)
+        when "union" then a | b
+        when "intersect" then a & b
+        when "exclude" then a - b
+        when "subseteq" then a.subset?(b)
+        when "size" then a.size
+        when "exists" then a.any? { call(b, [ _1 ]) }
+        when "forall" then a.all? { call(b, [ _1 ]) }
+        when "filter" then a.select { call(b, [ _1 ]) }.to_set
+        when "map" then a.to_set { call(b, [ _1 ]) }
+        when "Map" then values.to_h
+        when "put", "with" then a.merge(b => c)
+        when "mapBy" then a.to_h { [ _1, call(b, [ _1 ]) ] }
+        when "set" then a.merge(b => c) if keyed!(a, b, "set")
+        when "setBy" then a.merge(b => call(c, [ a[b] ])) if keyed!(a, b, "setBy")
+        # Which of two pairs with one key wins depends on the set's order.
+        when "setToMap" then a.to_h.tap { undefined("setToMap of pairs that share a key") if _1.size < a.size }
+        when "get" then a.fetch(b) { refuse("get(_, #{b.inspect})", "the map has no such key") }
+        when "keys" then a.keys.to_set
+        when "item" then a.fetch(b - 1)
+        when "Rec" then values.each_slice(2).to_h
+        when "field" then a.fetch(b)
+        when "variant" then Variant.new(a, b)
+        when "matchVariant"
+          arm = values.drop(1).each_slice(2).find { |label, _| [ a.tag, "_" ].include?(label) }
+          call(arm[1], [ a.value ])
+        else
+          # A definition is a lambda, or another operator's name (`def doubleOf = twice`).
+          call(defined(op) { refuse("operator #{op}") }, values)
+        end
+      end
+  end
+end