Skip to content

Quod 0.6.0

Choose a tag to compare

@github-actions github-actions released this 13 Nov 17:16
· 6 commits to main since this release

Quod 0.6.0: the console, as a capability. A program can now write and read lines, and a contract says what it writes and what it leaves to read. Nothing changes for a program that does not import console.

Install

As for 0.1.0: download the package for
your system, unpack it, and run quod from that folder (z3 4.12.1 is inside). On macOS, run
xattr -d com.apple.quarantine quod z3 in the folder first. The MCP server:
claude mcp add quod -- /path/to/quod mcp, or see
docs/mcp.md. Quod.Build, attached, is a NuGet package:
see its README.

A program

import console

fn main(c: console.Console) -> console.Console
  ensures console.written(result) == console.written(c) + ["Hello from Quod", "this line was proved"]
  ensures console.pending(result) == console.pending(c)
{
  let a = console.say(c, "Hello from Quod");
  console.say(a, "this line was proved")
}

quod run hello.quod checks the file, then runs main and prints the two lines. examples/console/echo.quod reads a line and says what it read, or that there was none, with a contract that is proved and determines its result.

Added

  • The console module of the standard library. console.Console is a capability: a function writes only through a Console it receives, so a function that has none among its parameters cannot write, and its signature says so. console.say(c, line) writes the line and returns the next Console. In a contract, console.written(c) is the sequence of the lines written so far and console.pending(c) the lines still to be read, and the operations are specified by them: say gives written(result) == written(c) + [line], and read_line returns None when pending(c) is empty and Some(pending(c)[0]) otherwise, with the rest of pending left. The proofs rest on that model; the real console is not verified, and what the one who runs the program gives to read is any sequence of lines.
  • A Console is used once. let d = console.say(c, "a") consumes c, and naming c again is an error: otherwise written(c) would speak of a console that no longer exists, and the proof would be false. Each branch of an if or a match may use it; a loop that uses one must end each turn by assigning the one it went on with (d = console.say(d, ...)). A program cannot build a Console, read its lines in code, or keep one in a sequence, a map, a set, a field or a type argument; it passes it on or returns it, alone or in a tuple.
  • console.read_line(c) returns a pair: the next Console and an option.Option<string>, None when there is nothing left to read. Both parts of the pair are used once, like any Console.
  • The completeness check covers what is written, and what is left to read. A contract that says only how many lines a function writes is refused, as one that says only the length of a result is: ensures len(console.written(result)) == len(console.written(c)) + 1 accepts any line. A contract that does not say what the function does to pending leaves two results possible: a program that only writes says console.pending(result) == console.pending(c).
  • quod run file.quod [--function NAME] checks the program, then runs main(c: console.Console) -> console.Console with the evaluator and prints the lines written, at the end of the run. What it reads is the standard input, taken whole before the run (nothing when it is a terminal). It needs neither Python nor .NET.
  • quod_run (MCP) takes a console as the array of lines already written ([] for a new one), or as {"written": [...], "input": [...]} to give lines to read, and returns the lines written.
  • Python: console.Console() uses the standard output and input, console.Console(stream, source) any text streams (a test gives io.StringIO objects); console.say and console.read_line return the same object. C#: new ConsoleModule.Console() or new ConsoleModule.Console(textWriter, textReader); ConsoleModule.Say and ConsoleModule.ReadLine return the same object. The Option module is generated next to them, since read_line returns one. The module is written by Quod next to the generated files, not generated from console.quod.

Fixed

  • A proof with a string literal of 12 characters or more could take 25 seconds or give up. A literal was a chain of concatenations, one per character, and the solver unfolded them all when two lines were compared (written(result) == written(c) + [a, b]). A long literal is now a constant of the proof, with its length and its characters: the same proof takes a second. This applies to every program with long strings, not only to the console. Short literals are unchanged.

Known

  • The console only. No files, no network yet: files come next (the model of a file system will be a map<string, string>). A line is read whole; there is no way to read a character, or to know whether more input is coming without trying.
  • quod run runs the program with the evaluator, which is slow on big loops, and prints the lines when the run ends, not as they are written: a program that asks a question and waits for the answer cannot be run interactively with it (the generated Python and C# do). The generated Python and C# write as they go.
  • The model of the console is two lists of lines. It says nothing of a console that fails (a closed pipe), of two processes writing together, or of the encoding of the input and the output. Every contract of a function that has a console has to say what happens to pending, which is one more line to write; a loop that writes lines proves in about twenty seconds, mostly because of the quantified invariants on sequences of strings (the order of the invariants mattered).
  • Without the sugar of a mut parameter, a program that writes much repeats let c2 = ...; whether to add it will be decided on programs written with this form.
  • No agent has written a program with a console yet: whether the rule of use-once costs agents anything is not measured.
  • The Console of the C# module is a class over a TextWriter, not an interface; a test substitutes a StringWriter.
  • Sealed contracts and general refinement types, announced for 0.6, move to 0.7.

Measured

  • 286 tests pass, among them 15 on the console and 2 on long literals.
  • An agent trial on the console (claude-haiku-5-5, two easy tasks, 3 trials each, 0.08 USD in all; report): 6 of 6 verified, 6 of 6 pass the hidden tests, 6 of 6 generate C# that compiles, and all 6 contracts say what they do to pending. The reference tells them to, so this measures that they follow it. One run was started again because the MCP server did not connect.
  • Mutants, on a Release build (15 per file, a larger sample than in 0.5, so the counts are not comparable): the reference programs, 81 refuted of 88 (2 rejected without a hint, 5 survived); the quantified requires, 13 of 15; the dictionaries, 11 of 11. The two rejected without a hint (merge_intervals, 13 and 17 s) give the same verdict on 0.5.0: they are not new. Slowest check to reject a mutant: 107 s (a program of the bench, on a build that is not AOT).