Skip to content

Quod 0.3.0

Choose a tag to compare

@github-actions github-actions released this 06 Nov 08:11
· 55 commits to main since this release

Quod 0.3: a language for business rules. Modules, strings with a library written in Quod, i32 and i64, structs, enums, match and generics.

This is a lot of new code at once, and no agent has written with it yet: treat it as a first version. A program that uses none of it gives the same diagnostics and generated code as 0.2, except where listed below.

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.

New

import strings

struct Candidate {
  value: string,
  confidence: i32,
}

enum Decision {
  Accepted(value: string),
  Rejected(reason: string),
}

fn decide(c: Candidate, keep: i32) -> Decision
  ensures match result {
    Accepted(v) => v == strings.trim(c.value) && c.confidence >= keep,
    Rejected(r) => r == "too low" && c.confidence < keep,
  }
{
  if c.confidence >= keep { Accepted(strings.trim(c.value)) } else { Rejected("too low") }
}
  • Modules. A file is a module. import name; a function of another module always has its full name; private fn. Everything imported is verified with the program, every time.
  • char and string. A string is a sequence of Unicode scalar values, the same in every backend. Nothing is normalized, and nothing depends on a locale.
  • A standard library in Quod, proved with your program: import strings and import option.
  • i32 and i64. In code, an operation that leaves the bounds is a proof not met, with a counterexample. In contracts, arithmetic is mathematical. In C#, they are int and long.
  • struct, enum, match. A match covers every case. In C#, immutable classes equal by value, with IEquatable<T>, == and a hash on what they hold, which copy the lists they are given and hand out views that cannot be cast back; an enum has a Match with one function per case, so a C# caller can be held to every case too. In Python, frozen dataclasses.
  • Generics, by copies: a generic function is checked and proved for the types it is used with. A type cannot hold itself: no recursive types yet.
  • run_by: contracts read a definition by recursion, and code runs a loop proved equal.
  • A tail call runs as a loop, in Python and in C#, in an if, a &&, a || or a match, whatever the length of the input.

The reference describes them all.

Changed

  • An expression function that ends by calling itself is generated as a loop, so its generated code changes, not its verdict. A stack overflow on a deep input no longer happens for it.
  • A C# method whose name would be that of a type gets Of, and a double underscore in a function's name keeps an underscore in its C# name.

Measured

  • All compiler tests pass.
  • Mutant bench: 57 of 64 mutants refuted, none unconfirmed or without a hint, the 7 survivors equivalent, none hung; quantified.quod 28 of 29. No verdict changed from 0.1.8, the last run of this bench before this version.
  • On the library: 39 of 40 mutants of strings.quod refuted with a counterexample, the last rejected without one, none survived.
  • On 42 programs of this repository written before these features, compared with 0.2.0: the same exit codes and generated code; 2 differ in the wording of one diagnostic, a proof given up on its time limit. This comparison came before the tail calls.
  • Python and C# on .NET Framework 4.7.2 gave the same answers on hand-written programs: accents, combining accents, emoji, lone surrogates refused, overflows at the bounds, Euclidean division, three modules, generics.
  • Three outside reviews of this version ran 4750 cases through the evaluator, Python and C# (on .NET 10) on the new types, with no difference, and tried to break the rules. The first two found false proofs and generated programs that contradicted a proof, all fixed here, with their programs as tests:
    • an assumption on lengths, reopened by a one-line lemma after a first fix, and false in Python: it is gone, and to_i32(len(xs)) now needs a requires;
    • a run_by that could require more than the function it runs for;
    • with --runtime-checks, a function proved by relying on one that was not: it is now checked too;
    • a function named like a copy of a generic, which captured its calls: two underscores in a row are now reserved;
    • in Python, a function named ord or divmod that the generated code would call, and class_ next to class;
    • a seq<nat> inside a struct, not checked when built;
    • int.MinValue % -1, which throws in .NET.
      That such faults took two sessions says how little this new code had been attacked before. What they attacked without success is listed in their reports: the axioms of sequences, the helpers of bounded division, tail calls, chars and strings.
  • The third review found no false proof in the default build. It found, all fixed here with their programs as tests:
    • in Python, a parameter or a local named like a case or a struct, which hid its class: a function proved true returned False;
    • in Python, a list read from a struct, which a caller could change under a proof: it now refuses to change;
    • with --runtime-checks, what a type promises was not checked (x * 1000 wrapped in C#, shrink(0) returned -1), and neither were the requires of a proved function called from an unproved one;
    • a generic struct did not compile in C#.
      It attacked without success: the completeness of enums and tuples, the copies of generics (requires, decreases, their use across modules), private, the state of the C# generator under MCP.

Known

  • No measure with agents. Whether an agent writes these features well, and whether i32 costs it too many proofs, is not known.
  • Copies of generics are verbose: in C#, Option.Option_int.Some, whose field is F0, and a BigInteger for Quod's int (prefer i32 and i64 in signatures); in Python, Box__int_Box for a Box<int>. In C#, two copies whose names coincide, Pair<int, seq<int>> and Pair<int_seq, int>, do not compile.
  • A C# caller is not forced to use Match: it can still test the classes itself.
  • Python: the elements of a seq<i32> parameter are checked only with --check-requires all, which its docstring says. A value's lists can still be changed with list.append(value.xs, 1), which is no longer an accident.
  • Names: in Python, a module named like a built-in one (math, sys) or a reserved word fails when imported; in C#, a struct named like its file, or a function big_integer, does not compile. Option<nat> does not work with option.value_or: the type parameter is taken as int. [] == s is refused where s == [] passes. run_by is not available in a generic.
  • A recursion that is not a tail call follows its input in depth, in the generated code: use run_by. In the library, digits_value and digits_of remain so, which their inputs make harmless.
  • A generic function is not checked at all until it is used, and a warning says so.
  • A contract that calls itself through another function, rather than directly, can still crash the compiler.
  • Completeness: when the solver answers unknown, a contract is only warned about, and it is built. A struct holding a list described by a quantifier does that: ensures result.n == k && len(result.xs) == k with forall i in 0..k: result.xs[i] >= 0 is underspecified, and gets the warning. On a plain seq<int> it is refused.
  • loose concerns its own function: ensures result == any_pos(x) determines its result, as a function of any_pos, whose freedom it inherits without saying so. No proof depends on loose.
  • MCP: path reads any file the server can read; the server is meant to run locally. Which file an import takes depends on file_name: the report now lists the modules it used.
  • Everything of 0.2 still holds: z3 is 4.12.1, and verdicts can depend on the load of the machine.
  • There may be other false proofs in this new code. They were looked for during three sessions of review: the first two found some, the third none.