caveat-lang

# CAVEAT Language

The published preview is **0.1.0-rc.14**. See the
[rc.14 release record](docs/releases/v0.1.0-rc.14.md) for what it changes.

> npm publication verified 2026-10-05T02:17:29.240Z: exact **caveat-lang@0.1.0-rc.14**,
> tested Linux artifact SHA256 `9aab7b811666e5b43b6f7c96ad5116235241b08fbed395698476cc035bfd57bf`.
> `latest` and `next` name rc.14. Published by `publish-npm.yml` from tag `v0.1.0-rc.14` with an npm provenance attestation.
> [Publication record](docs/releases/v0.1.0-rc.14-npm-publication.json).


**Programs that remember why.**

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 preview, **0.1.0-rc.14**, in an empty directory with Node 20 or
later. No Rust installation is needed:

```sh
npm init -y
npm install caveat-lang@0.1.0-rc.14
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](kit/docs/GETTING_STARTED.md) walks through those files, and
[the language in brief](kit/docs/REFERENCE.md) covers the syntax.

The [rc.14 verified publication record](docs/releases/v0.1.0-rc.14.md) identifies the
published npm candidate. The [rc.14 GitHub prerelease](https://github.com/WSattazahn/caveat-lang/releases/tag/v0.1.0-rc.14)
retains the exact tested Linux tarball and its checksum. rc.14 changes only the
package's MCP server name, so the MCP Registry lists it as
`io.github.WSattazahn/caveat-lang`; the language is rc.13's. rc.13 reports a
program's interface as JSON and writes TypeScript declarations from it
(`caveat-lang types`), makes restore refuse a caveat the source cannot attach
and a membership without its record, and turns `id_text` of a non-handle into a
refused event instead of a fatal failure. Restoring a save still does not
authenticate its history. A refused operation is not completed; hosts must
inspect its outcome. It adds no npm runtime dependency.

With rc.14 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](kit/docs/NAMES.md).

**Integrating an agent?** Follow the [agent quickstart](kit/docs/AGENT_START.md)
and the [official Python client](kit/examples/agent-evidence/README.md). Caveat
records supplied evidence and authored policy; it does not authenticate evidence
or authorize external actions. [Repository agent guidance](AGENTS.md) includes
how to report a capability missing from a real integration.

## Principles and capabilities

For the thinking behind Caveat, read
[The Caveatist way](docs/WHY_CAVEAT.md#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](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.

**[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`](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](experiments/trail-rescue/PROTOCOL.md)
were committed before implementation. The [Caveat program](game/trail_rescue.cav)
owns the rules; the [browser page](web/trail-rescue.html) 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](spec/caveat-state-caveats-0.1.md):
`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](experiments/trail-rescue/RESULTS.md).

**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](experiments/agent-authoring/v1/RESULTS.md) preserves those limits,
every revision and the independent verification.

Reactive source can now read the runtime clock directly with
[`elapsed()`](spec/caveat-elapsed-0.1.md): `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](experiments/agent-authoring/v2/RESULTS.md) repeated
the two clock tasks with this read and the updated guide. Three first submissions
and all four final submissions passed: 13,704 event dispatches and 3,158 restores.
All four used `elapsed()` directly, without a separate state clock. The remaining
first-source failure was unsupported comment syntax, repaired by its author.
This is evidence on two repeated tasks, not a general reliability claim.

The reactive runtime also offers [structured dispatch outcomes](spec/caveat-dispatch-0.1.md).
`dispatch_outcome` distinguishes an authored policy rejection from invalid input,
state-bound failure and execution-budget exhaustion. Unclassified errors remain
fatal. Existing dispatch methods retain their behavior; new integrations can use
the explicit outcome contract when testing why an event was refused. A host that
redraws from the view uses `dispatch_view_outcome` (`session.dispatchView` in the
developer kit): the same outcome, with the view in place of the snapshot.

## What Caveat makes part of the language

These mechanisms can also be implemented and checked in a general-purpose
language, through application code or libraries. Caveat supplies them together
as language and runtime facilities; the comparison is about what an author
has to provide, not what another language can express.

| | Caveat | In a general-purpose language |
| --- | --- | --- |
| **Explanations** | `bind label = "Could be a duskcap" when … because contradiction;` The runtime checks cited evidence and caveats against recorded dependencies. | Implement dependency tracking and citation checks, or use a library that supplies them. |
| **Caveats through computation** | `qualified(1, taste, tasted_in_dark)` carries evidence and caveats through computations that use it. | Use provenance-aware values and operations to propagate the same information. |
| **Late caveats** | `qualify taste with taste_faded;` qualifies current values built on the taste while earlier decision records retain their frozen caveats. | Track dependencies or resolve qualifications when read, and freeze decision records. |
| **Decisions that remember** | `commit`, `reopen`, and decision-series revisions retain each revision's grounds and publish its changes in `decision_journal`. | Implement decision records, frozen bases and an ordered change journal. |
| **Grounds and lineage** | The runtime distinguishes a value's content grounds from its wider control lineage and enforces grounds ⊆ lineage. | Represent both kinds of dependency and enforce their relationship in code or a library. |
| **Atomic events** | `reject "already absorbed";` rolls back the event's changes to the Caveat session. | Use transactions, immutable state or explicit rollback to publish changes atomically. |

Citation checking establishes that cited dependencies were recorded; it does
not establish that supplied evidence or authored explanation prose is tru