What it gives you that plain code doesn't
An agent or a program decides to act: ship a release, pin a dependency, send a crew. Later one of the readings it used turns out to be wrong. Three questions follow: what did the decision rest on when it was made, what else rests on that reading, and does the decision still stand?
In TypeScript, or any ordinary language, a decision is a variable. You can store its reasons beside it, but the language does not know what the value was computed from, so keeping those reasons accurate is code you write, test and maintain yourself. In Caveat it is the runtime's job:
- Withdraw evidence without losing the past. Withdrawing a reading records that it is no longer stood behind; nothing is erased, and the opposite claim is not established. A rule you wrote can then reopen the decisions that rested on it, and each one keeps the grounds it was made on, readable afterwards.
- Ask what rests on a reading. Every value carries the
evidence it was computed from, and its caveats, through every sum,
comparison and label.
caveat dependentsanswers "what rests on this?" andcaveat explainprints each decision's grounds, permission and history. - Reasons the runtime checks. A
becausethat cites evidence the value never read is refused, asevaluation/ungrounded_citation. A type checker tells you a value has the right shape; it cannot tell you a stated reason is one the value actually depended on. - Permission kept apart from grounds. A
permitted byclause names which evidence counts as the go-ahead. The decision is refused, aspolicy/not_permitted, unless that grant has been observed and not withdrawn, and it records the grant separately from what the decision was computed from. - A refusal changes nothing. An event the program refuses leaves no partial trace; your host checks each outcome before acting. A journal lists every decision and every reopening, with its reasons.
Caveat is not an agent framework: it does not call models or tools. Your
code, or your agent's harness, sends a Caveat program events through the Node
or browser library, as JSON lines with caveat serve from any
language, or through the MCP server, and acts on what the program decides.
When it pays off
For decisions that get revisited: release and deploy gates, dependency and runtime choices, accepted-risk exceptions, agent memory that gets corrected. Those are the cases where "what did this rest on?" and "what changes if that reading was wrong?" come up, and where Caveat answers them without extra bookkeeping.
It is not worth it for a one-off call nobody will look at again, for hot inner loops, or for a program where no one will ever ask why. Plain code is simpler there.
Integrating Caveat with an agent? Start with the
Python
caveat serve example. If a real integration exposes a missing
capability, please
open
an agent feature request for the project owner to evaluate. Check existing
issues and include the exact version, a small reproduction, and expected versus
actual behavior.
One example: covering seedlings
The worked
example is one program of about 60 lines. Two instruments read the soil
temperature: a probe, and a survey drone whose readings carry the caveat
uncalibrated. When the probe reads 2 °C or colder and the
grower has given a go-ahead, the program decides to cover the seedlings. A
probe or drone reading above 2 °C reopens that decision, and so does
finding out that the reading it rested on was taken wrongly.
The decision, from the program (line breaks added):
on decide when latest(soil) <= 2
commit cover because enough
using latest(soil)
permitted by latest(approvals);
After a cold probe reading, a go-ahead from "sam", the decision, a cold
drone reading and then a warm probe reading, caveat explain
prints this for the decision (an excerpt, with its indentation trimmed):
cover@1 = 1 reopened
based on soil@1
permitted by approvals@1
could also have been influenced by approvals@1
#3 decide: committed because soil@1
#5 probe_read: reopened because soil@2
"Based on" is the grounds. The cold drone reading came after the decision,
and it would not be among the grounds anyway, because the decision's value was
computed from the probe alone. "Could also have been influenced by" lists the
rest of the decision's lineage: other evidence that could have affected it,
here the grant, kept conservatively. The example's scenario file also checks that
without a go-ahead the decision is refused, as
policy/not_permitted; that withdrawing the reading it rested on
lets a rule reopen it, with the original grounds kept; and that refused events
change nothing.
Run it
You need Node 20 or later. In an empty directory:
npm init -y
npm install caveat-lang@1.0.0
Save the three files shown in the worked
example as frost.cav, frost.scenarios.json and
events.jsonl. Then:
npx --no-install caveat test frost.scenarios.json
npx --no-install caveat explain frost.cav events.jsonl
The test prints 4 passed, 0 failed (frost.scenarios.json), and
the explanation is the one in the worked example. The package's own tests
follow the worked example the same way.
Limitations
- 1.0.0 is stable under the
compatibility
promise, which says what every 1.x release keeps and what is not covered,
such as the games, message wording and timing. After the owner's channel
update on 2026-10-17, npm's
latestandnextwere both verified at 1.0.0. The bundled guides identify their exact package version; this page and the dated release record track publication. - Caveat records what a decision rests on. It does not authenticate evidence, inspect a model's internal reasoning, or authorize actions outside the program. A source label says where evidence came from; it does not prove it.
- The program decides what counts as approval. Caveat requires the
designated grant to be observed and not withdrawn, and checks its value
against
for Xwhen one is given. It does not authenticate the grant's source, infer approval from its wording or from whether it supports or opposes a claim, or enforce expiry by itself. - An explanation says what a decision read and what could have influenced it. It does not show that each item was a cause, that the evidence was accurate, or that the rule was sensible.
- Caveat stores nothing by itself: your code keeps the events or the session's save. A save is not signed; restoring it checks that it is consistent, not that it is genuine. The journal is not a tamper-evident audit log.
- Reading and decision histories have declared limits. An event that would exceed a limit is refused, unless the history declares a supported window, in which case its oldest record retires. Since rc.16 a session can remove eligible retired records from the live save and transfer history to a host-drained archive. Required reasons remain: their dependency chains can grow, so windows do not bound the complete save. Archive storage is additional. State is numbers, and a program does no input or output of its own.
- The evidence that it helps is still small: the project's own games, authoring trials by AI agents and a benchmark game. Whether Caveat helps real decision systems is still a hypothesis.
- It costs speed and size: an event takes tens to hundreds of microseconds, and the runtime is hundreds of kilobytes gzipped. That is fine at event boundaries and not suited to per-frame work.
- The registered agent examples have host-policy checks; these do not establish conformance for arbitrary integrations or a security sandbox.
What is checked, and how separates the Lean model theorems, sampled native and WebAssembly conformance with mutation controls, runtime tests and the boundaries nothing proves.
Recent releases
1.0.0 makes the compatibility commitment the promise for every 1.x
release: 1.x minors only add, and only 2.0 removes or changes what is stable.
It adds no language, schema, operation, field, CLI flag, export or MCP tool
over rc.20, and its Rust runtime is unchanged. rc.20 clarified when to use
each MCP tool, its inputs and its results, and fixed human-readable
explanations of caveats. rc.19 began the 1.0
feature freeze: it added no language, schema, operation, field, CLI flag or
export. rc.18 added unqualify, which takes back a caveat that
qualify added; the take-back is recorded, not erased, and
decisions keep their basis. Earlier changes are in each
release
record, and the
history
integration guide covers windows, departure and archives.
Existing Lean proofs cover their documented model, not the entire Rust runtime. No npm runtime dependency is added. The 1.0.0 verified release record identifies the exact tested Linux tarball. Publication used the repository's workflow with npm provenance; registry bytes, provenance, signatures and a fresh exact-version installation were verified.
Links
- caveat-lang on npm, version 1.0.0.
- Verified publication record: exact package identity, checksums and provenance.
- Caveat
on one page: the language in brief. Its links to the specifications work
in the installed package, under
node_modules/caveat-lang/docs/; on GitHub, use the specifications link below. - Release notes for 1.0.0.
- The specifications, including drafts, earlier versions and profiles used only by the games.
- Source code and issues, under the MIT License.
Culture
Caveatism is the philosophy that grew up around Mr. Caveat, a mechanical fortune teller who always has a caveat; it lives in the repository's caveatism directory and is culture, not a contract of the language. The Archive and Atlas are its texts, and the canon keeps the Archive as a Caveat program with scenarios.
Games on this site
The rest of this site is games written in Caveat and run in the browser. The glowcap explainer, Trail Rescue and Light the Way use the same form of Caveat as the package. Moon Garden, Mr. Caveat and others use an earlier form that the package does not load. They are demonstrations, not part of the package.