Skip to content

Quod 0.7.0

Choose a tag to compare

@github-actions github-actions released this 14 Nov 13:39
· 2 commits to main since this release

Quod 0.7.0: files, as a capability, and maps that hold strings in C#. Nothing changes for a program that imports neither files nor uses a map of strings in C#.

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 files
import option

fn copy(f: files.Files, from: string, to: string) -> files.Files
  requires from != to
  ensures from in files.contents(f) ==> files.contents(result) == put(files.contents(f), to, files.contents(f)[from])
  ensures !(from in files.contents(f)) ==> files.contents(result) == files.contents(f)
{
  let r = files.read_file(f, from);
  let g = r.0;
  match r.1 {
    None => g,
    Some(text) => files.write_file(g, to, text),
  }
}

quod run copy.quod --function copy needs a main; examples/files/backup.quod is one that reads notes.txt and writes notes.bak, with a console to say what it did: quod run examples/files/backup.quod --files DIR.

Added

  • The files module of the standard library. files.Files is a capability, like the console of 0.6: a function reads and writes files only through a Files it receives, used once, which a program cannot build and whose model it cannot read in code. files.read_file(f, path) returns the next Files and an option.Option<string> (None if there is no such file), files.write_file(f, path, text) and files.delete_file(f, path) return the next Files. In a contract, files.contents(f) is a map<string, string> from path to text, and the operations are specified by it: contents(result) == put(contents(f), path, text) for a write, remove(contents(f), path) for a delete. What the files hold when the program starts is any map. As for the console, a contract has to say what becomes of the files, or the completeness check says that two results are possible.
  • Rooted in a directory. The real Files is rooted in a directory chosen by whoever runs the program: files.Files(root) in Python, new FilesModule.Files(root) in C#, --files DIR in quod run. A path that is empty, absolute or that leaves the root (..) is refused (ValueError, ArgumentException). Text is UTF-8, read and written with no change of its line ends.
  • quod run file.quod --files DIR loads the files under DIR (at most 1000 files of 1 MB, all UTF-8) into the model, runs main (any capabilities in, the same ones out, as a tuple when there are several), then writes back to DIR what the program changed or deleted, when it ends. quod_run (MCP) takes a Files as an object from path to text ({} for none) and returns the files that result.
  • C#: strings, and lists of numbers or booleans, as values of a map. map<string, string> and map<string, seq<int>> are generated: until now only integers, booleans, tuples, structs, enums, maps and sets could be values. A string is a C# string inside the map, as a key is, and a list is held as it is; a map compares its values by content. Not yet: a char, a list of strings or of lists, as a value.

Fixed

  • A private fn that only contracts call is no longer generated. It had no use in the generated code, and it could stop it: a helper over a map<string, string> used by a contract only made the C# refuse the program (found by an agent trial). A private function that code calls, however indirectly, is kept, and nothing is left out when --runtime-checks makes the contracts that were not proved run with the code.

Known

  • The same restrictions as the console. A contract on a function that has a Files must say what becomes of the files. The model has no directories, no permissions, no other program changing the files meanwhile; a write that fails for the disk (full, a path that is a directory, a file that is not UTF-8) raises an error, which is outside what is proved.
  • quod run --files loads the whole directory, and writes back at the end, not as the program goes. The generated Python and C# act on the disk as they go.
  • In C#, a char and a list of strings are still refused as map values, and sorted of structs is not generated. A caller must not change a map, a set or a list it passed, or one it received.
  • A lone surrogate in a C# string that a caller puts in a map is not rejected where it enters, but when the program first reads it as text (an ArgumentException), as for a key.
  • The MCP server of a build that is not native sometimes fails to start under an agent runner (5 runs of 12 lost in the file trial): use the native binary.

Measured

  • Tests: see the commit; 3 on files and 1 on private helpers were added to those of 0.6, and 2 on the C# values of maps.
  • An agent trial on files (claude-haiku-5-5, copy_file and append_line, 0.147 USD for 12 runs, 5 lost to the MCP server): copy_file 3 of 3 verified and passing, append_line 2 of 2 verified and passing once the wording was right (the first wording was ambiguous, and the agents followed the sentence: reported in the report); every contract says what becomes of the files.