in reviewhumanPR #359Transport

Cerata: add legal-check Track integration with fault and fail-closed tests

Cerata is a hosted legal check for AI agents. Before an agent calls, texts, emails, lists a home or posts a job, it tells Cerata what it is about to do; Cerata answers clear, flag, hold or block, with a signed receipt anyone can verify…

Author

Status
In review
Opened on
Nov 11
Branch
integration/cerata-preflight

Description

The pitch.

## Summary

Cerata is a hosted legal check for AI agents. Before an agent calls, texts, emails, lists a home or posts a job, it tells Cerata what it is about to do; Cerata answers clear, flag, hold or block, with a signed receipt anyone can verify and, for a clear, a single-use token for that one action.

This PR connects the hosted service to Town without moving it in. It adds `examples/integrations/cerata-preflight/`: a stateless Track seller adapter in front of Cerata's API, an agent buyer that judges each answer and verifies receipts independently, 22 situations with the answer Cerata must give, a compatibility check (40 Track runs plus an MCP check), a results/verify script, an offline fixture for CI, and `tests/test_example_cerata_preflight.py`. No Town code changes; `MANIFEST.in` ships the example's data with the tests that read it.

## Integration

- **Subject:** Cerata, hosted separately at `clearance-kohl.vercel.app` (release v1.3, deployed commit `2195f7a6`). It is treated as a black box: the check judges only what an agent sees.
- **Interface:** the Track mailbox exchange between two `cmd:` participants. The seller (`cerata_seller.py`) claims a `quote_request` carrying the action and calls `POST /v1/preflight` with a test key from the environment. The buyer (`agent_buyer.py`) is an agent that must ask before it acts; it judges the reply, verifies the receipt with Cerata's public `POST /v1/verify` (a channel that goes through neither the seller nor Town), and uses any clearance token once, then checks a second use is refused.
- **Stateless adapter:** the seller keeps no journal. Its `Idempotency-Key` is derived from the Town run and message identity, so a redelivery or a restart that forgot everything gets Cerata's stored answer back (`Idempotent-Replayed: true`) and sends a byte-identical reply. The ack reports an application only when Cerata ran a new check, or when the town holds no record of an earlier one.
- **MCP:** `mcp_check.py` uses Cerata's MCP endpoint as a host would: `initialize`, `tools/list`, `tools/call preflight` twice under one idempotency key, `tools/call verify`, and a refused key.
- **Fixture:** `fake_cerata.py` answers from `cases.json` so CI can test the wiring offline. It is a Town fixture and is not presented as compatibility evidence.

## Reproduce

- Town: `projnanda/nandatown@6f9a7c0` (`main`), nandatown 0.2.0, Track evaluator 0.5.0. This branch: `e31d732`.
- Cerata: release v1.3 as deployed at commit `2195f7a6` (v1.3 plus the two fixes for finding 1), test environment. Tested on Ubuntu on WSL2 (Linux 6.6) with Python 3.14.4 (example tests also pass on 3.11 and 3.12).

```bash
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest -q tests/test_example_cerata_preflight.py      # offline, no key

export CERATA_URL=https://clearance-kohl.vercel.app
export CERATA_API_KEY=ak_test_...                               # test key, environment only
examples/integrations/cerata-preflight/check.sh runs/cerata
python examples/integrations/cerata-preflight/results.py runs/cerata
```

One case: `CERATA_CASE=fl-call-after-8pm nandatown run quote-amnesia-restart --agent "seller=cmd:python examples/integrations/cerata-preflight/cerata_seller.py" --agent "buyer=cmd:python examples/integrations/cerata-preflight/agent_buyer.py"`

## Results and limitations

**40 of 41 checks matched against live Cerata; every Track bundle passes `nandatown verify`. The one difference is explained below.** (about 2 minutes, run 2026-11-11; full tables in `examples/integrations/cerata-preflight/RESULTS.md`).

| Section | What it tests | Expected | Observed |
|---|---|---|---|
| situations (22 runs) | state limits stricter than federal, the recipient's location and local time (daylight-saving change, UTC input), consent and do-not-call facts, a rule not yet in force, places and purposes not covered yet, email, a rental listing; receipts, a single-use token, a repeated case | the expe

…

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/359/head:pr-359
git checkout pr-359