Caveat Lang

CAVEAT Language

A decision ledger for agents: Caveat keeps an AI's reasons in a record you can check.

Caveat is a rules language and a runtime for decisions that may need taking back. It tracks evidence through computations, preserves the grounds of recorded decisions, and reopens them under rules you write when evidence changes. Limits says up front what it does not do (check that evidence is true, authenticate saves, know who sent an event) and what it costs.

For teams that govern their agents, Caveat is also an audit trail for agent decisions. caveat explain shows what each decision rested on: its evidence and caveats, the permission it needed and why it was later reopened. Withdrawing evidence adds to that record and never rewrites a decision's original grounds. Your application stores the events; Caveat does not sign them or authenticate the evidence, so it complements your platform's identity, permission and logging controls rather than replacing them.

The published release is 1.4.1, a patch release of 1.4.0. See the 1.4.1 release record for what it fixes, the 1.4.0 release record for what 1.4 adds and the 1.0.0 release record for what 1.x promises.

npm publication verified 2026-10-26T23:13:05.492Z: exact caveat-lang@1.4.1,

tested Linux artifact SHA256 ecb535b181f5f33836f4730ed8c1c0c8ac9a1622eb55e3d43e3e3c3492f281f5.

Published by publish-npm.yml from tag v1.4.1 with an npm provenance attestation. Both latest and next were verified at 1.4.1 on 2026-10-26.

Publication record.

When a tool result is corrected or a memory turns out to be stale, an application needs to reconsider its decision without losing the reasons for the original. Caveat is a programming language that keeps evidence and caveats with computed values, freezes a decision's grounds, and records why it was reopened.

Try the published release, 1.4.1, in an empty directory with Node 20 or later. No Rust installation is needed. Install it:

npm init -y

npm install caveat-lang@1.4.1

Then paste this "hello, world": one piece of evidence, one decision resting on it, and one event that withdraws the evidence and reopens the decision.

cat > hello.cav <<'CAV'

claim safe_to_ship; evidence ci from "the CI run"; evidence rerun from "a rerun of CI"; readings tests from ci limit 2; decisions ship limit 2;

event ci_passed; event ci_was_wrong;

on ci_passed sample tests = 1 supports safe_to_ship; on ci_passed commit ship because enough using latest(tests); on ci_was_wrong reveal rerun opposes safe_to_ship; on ci_was_wrong withdraw latest(tests) because rerun; on ci_was_wrong reopen ship because rerun; CAV printf '%s\n' '{"event":"ci_passed"}' '{"event":"ci_was_wrong"}' > events.jsonl npx --no-install caveat-lang explain hello.cav events.jsonl

Part of what it prints:

    ship@1 = 1  reopened

based on tests@1 tests@1: observed at #1 ci_passed tests@1 has since been withdrawn at #2 because rerun #1 ci_passed: committed because tests@1 #2 ci_was_wrong: reopened because rerun

The decision was reopened when the CI result it rested on was withdrawn, and it still says what it was first based on. For a fuller program with a caveat, scenarios and a displayed value, init writes the getting-started starter:

npx --no-install caveat-lang init

npx --no-install caveat-lang test umbrella.scenarios.json npx --no-install caveat-lang explain umbrella.cav events.jsonl

The two scenarios pass. The explanation shows umbrella@1 = 70 reopened by sky, still based on rain_chance@1 with its forecast_is_old caveat. New knowledge changed the decision's status; its original grounds remain visible. Getting started walks through those files, and the language in brief covers the syntax.

Start here

To see what Caveat does, give a coding agent this task in an empty directory:

Install the caveat-lang npm package (Node 20 or later) in this empty directory

and run npx --no-install caveat-lang init. Read node_modules/caveat-lang/docs/REFERENCE.md before writing any Caveat source. In umbrella.cav, raise the rain chance needed to commit the umbrella decision from 50 to 60. Add a scenario to umbrella.scenarios.json showing that a 55% forecast leaves the advice at "No decision yet". Run npx --no-install caveat-lang check umbrella.cav and npx --no-install caveat-lang test umbrella.scenarios.json, then run npx --no-install caveat-lang explain umbrella.cav events.jsonl and tell me what umbrella@1 rests on and why it was reopened. Change no other files.

The three scenarios pass, and the explanation still shows umbrella@1 resting on rain_chance@1 and its forecast_is_old caveat after sky reopened it.

The 1.0.0 verified publication record identifies the exact tested npm artifact. 1.0.0 makes the compatibility commitment the promise for every 1.x release: the language, the 19 refusal codes, the CLI, library exports, serve, the MCP tools, named schemas and saves are stable, and 1.x minors only add. It adds no language, schema, operation, field, CLI flag, export or MCP tool over rc.20, and its Rust runtime is unchanged from rc.20.

Restoring a save still does not authenticate its history. A refused operation is not completed; hosts must inspect its outcome. The package has no npm runtime dependencies.

With 1.4.1 installed, use npx --no-install caveat-lang doctor to check it and npx --no-install caveat-lang demo agent to see observation, assessment, correction and revision in one run. Introduced in rc.7, the unambiguous caveat-lang command remains preferred; caveat is supported shorthand. See CLI names.

Integrating an agent? Follow the agent quickstart and the official Python client. Caveat records supplied evidence and authored policy; it does not authenticate evidence or authorize external actions. Repository agent guidance includes how to report a capability missing from a real integration.

What stands behind it? What is checked, and how separates the Lean model theorems (proofs/lean), sampled native and WebAssembly conformance with mutation controls, runtime tests, and the boundaries nothing proves. It also states the limits: windows do not bound saves, nothing is authenticated, and hosts set their own resource budgets.

Principles and capabilities

For the thinking behind Caveat, read The Caveatist way.

Say what you know, and what it rests on.

Carry the caveats honestly.

Give uncertainty the attention its consequences deserve.

Act when there is enough to proceed.

Remember why you chose, and remain willing to choose again.

These are the project's principles. They are not additional license conditions: Caveat is under the MIT License, and using it does not require adopting them.

• Values carry their evidence. Every number computed from an observation carries that evidence and its caveats through every sum, comparison and label.
• Explanations are checked against recorded dependencies. Anything a program shows can say *why*, and the runtime rejects an explanation that cites something outside the value's recorded dependencies. That does not prove the evidence true or the explanation complete.
• Decisions remember. A decision records what it was made on, reopens when the world disagrees, and keeps a journal.
• Late knowledge is one line. A late qualification reaches current values built on the evidence and future values that read it. Archived readings and decisions already made keep what they knew.

[What Caveat is for](https://wsattazahn.github.io/caveat-lang/about.html), on one page: the problem, one example to run, and the limitations.

[Try to break this](https://wsattazahn.github.io/caveat-lang/break.html). One claim about withdrawal, as five rules a checker tests after every event of a program you write. If Caveat reopens too much or too little, the page fills in an issue for you.

[Play the glowcap explainer](https://wsattazahn.github.io/caveat-lang/glowcap.html). Four look-alike mushrooms, a belief, a trust decision that is made, doubted and remade, and a "why?" under everything on the page. The rules and explanations all live in game/glowcap.cav; the page only renders them.

Start with Change what you know at the top of that page. Make a decision in one click, learn something new in a second, and see what changed, why the decision reopened, and the original reasons it kept.

Trail Rescue is a new, complete mechanic: spend three scout tokens, weigh fallible reports, choose a tunnel and reconsider when its evidence changes or ages. Its requirements and 24 scenarios were committed before implementation. The Caveat program owns the rules; the browser page displays its decisions and frozen explanations. Build and run it with npm run build, npm run serve, then open http://127.0.0.1:4173/trail-rescue.html.

The mechanic added state caveat queries: has_caveat(plan_basis, stale) checks the actual grounds of a saved basis, and reopen route because caveated(plan_basis, stale) cites the precise observations that have gone stale. The journal now preserves elapsed time and the chosen numeric value, and restore checks its consistency with commitments and evidence. See the implementation record.

Fresh-agent authoring: six fresh contexts authored three specified policies using a frozen documentation packet, without private-test feedback. Two first submissions and all six final submissions passed the registered corpus: 20,512 final-source events and 4,788 restores. All four initial failures exposed an unclear numeric-bound restriction, now documented. Two final programs still have known clock-horizon contract violations outside the corpus. The study report preserves those limits, every revision and the independent verification.

Reactive source can now read the runtime clock directly with elapsed(): bind hud.elapsed = elapsed();. It uses the same time as scheduled caveats and decision journals, survives save/restore, and removes the need for a separate bounded state timer.

A four-context follow-up repeated the two clock tasks with this read and the updated guide. Three first submissions and all four f