Standard library tools¶

clauz3 ships a small set of real (non-mock) tools under src/clauz3/stdlib. Unlike the layers under examples/, their effect bodies do real work: the prover skips them, but clauz3 run executes them after a program is proved and approved.

Install¶

After pip install clauz3, install one into the current repo with the stdlib: scheme:

clauz3 install stdlib:filesystem
clauz3 install stdlib:google_workspace --skills
clauz3 install stdlib:web_fetch

install stdlib:<name> locates the bundled tool with importlib.resources (so it works identically from a source checkout or an installed wheel) and copies its service domains from tools/ into the current project, exactly like installing from a local path. A bare clauz3 install <name> works as a shorthand.

Layout¶

A stdlib tool is deliberately leaner than an example. There is no top-level cases/ or Justfile; the proof cases live under tests/:

<name>/
  clauz3.yaml                   # optional shared package prerequisites
  README.md                     # user-facing prose; also rendered on the per-tool doc page
  tools/<domain>/clauz3.yaml       # domain description and setup
  tools/<domain>/trusted/          # trusted code within the installed domain directory
  tests/
    cases/                      # *_pass.py must prove, *_fail.py must not
    Justfile                    # proves the cases — the tool's own guarantees

The repo's just stdlib target runs every stdlib tool's tests/Justfile, and clauz3 test stdlib:<name> does the same for a single tool.

Available tools¶

Tool	One-line	Doc
`filesystem`	Read, search, list, write, copy, move, delete and chmod files, with policies over the events each tool performs.	filesystem
`google_workspace`	Save Gmail drafts, preview and send through gog, with recipient, content and count limits.	Google Workspace
`db`	Read typed rows from DuckDB, CSV, Parquet, or folders via DuckDB.	db
`web_fetch`	HTTP GET/POST via `urllib`, with URL-prefix, no-POST, and exfil-style URL-content guards.	web_fetch
`web_search`	Search via a configurable JSON backend, with query-content guards.	web_search
`env`	Read environment variables with name allowlist / blocklist / prefix vetoes.	env
`git`	Run local `git` subcommands and pushes with subcommand / location / push-target policies.	git
`gh`	Run the GitHub CLI with verb / object / repository policies.	gh
`rsync`	Sync files with destination / source / no-delete policies.	rsync

Each per-tool doc page renders the tool's README.md and inlines the trusted layer's source, so the doc tracks the code without a hand-maintained API table. Adding a new stdlib tool requires one README in the tool directory plus two thin stub pages (docs/stdlib/<tool>.md and docs/stdlib/<tool>-all-cases.md) and three nav lines.

Bundles and service selection¶

stdlib:google_workspace is one installable bundle, currently providing the google_workspace/gmail domain. Its card is titled Google Workspace, with service documentation and Gmail-specific authorization in the domain manifest. Future services can join the bundle without a new registry entry. Shared setup lives in the package manifest; each service keeps its own trusted root, contracts, and generated skill. The Libraries UI selects services independently for conversations. Installing or updating a bundle does not enable additional services in existing selections. See Google Workspace for migration from the old email domain and the new import paths.

Composition¶

filesystem states its contracts over events, not functions. Each effect declares with @performs what it does to the filesystem, and a contract over an event covers every effect that performs it:

@performs(lambda path: Read(path))
def grep(pattern: str, path: str) -> list[str]: ...


@contract
def never_read_under(prefix: str) -> ContractSpec:
    return Read.all(lambda e: not e.path.startswith(prefix) and ...)

So fs.never_read_under("/repo/.env") refuses read_file, grep, and a copy or move from that path, and a new tool that performs Read is covered without changing the contract. The other stdlib libraries still state policies over their own effects; git, rsync and db also touch files, and a filesystem policy does not yet cover them.