A tiny, privacy-first wire format for what your coding agents cost: tokens, dollars, provenance, and the work they attach to — as plain JSON a team can merge across machines without a server, an account, or a network.
This folder is the protocol's home. It is self-contained: nothing here needs Node, Python, or any particular tool — just JSON and this repository's files.
| Path | What it is |
|---|---|
| SPEC.md | The normative protocol: event model, provenance R1–R3, merge semantics, privacy P1–P4, version negotiation. |
| schema-1.0.json | JSON Schema (draft 2020-12 subset) for a ULP bundle. |
| conformance/ | Pure-JSON test vectors — the kit any implementation runs against, in any language. |
| reference/ulp-reader.py | Reference implementation #2: a stdlib-only Python reader, validator, merger, and kit runner. |
| rfc/ | The open change process and published decisions. |
| CHANGELOG.md | Version history of the protocol itself. |
- burn — the cross-agent cost ledger
CLI that grew the protocol.
node src/cli.js conformancereferees the kit;export --ulpemits,ingestaccepts. - ulp-reader.py — proof that conformance needs no hidden Node-ness: one file, standard library only, same vectors green.
Both MUST pass every vector; disagreement is resolved by amending SPEC.md, not by patching one implementation (see the kit README).
Core fields never change under 1.x (additive-only). Anything implementation-
specific goes under x-<impl>-*, where <impl> follows the
{repo-or-user}-{tool} convention —
registry-free, self-declared, no domain squatting. Behavior changes, new core
fields with changed meaning, or new merge rules require an
RFC.
1.0 — ratified. The two-implementation gate is met and the spec now lives
in its own repository (this one), which is the condition CHANGELOG.md
sets for dropping the draft marker. burn keeps a vendored copy under
ulp/ so its CI can referee
both homes from one checkout; this repository is the normative source. Version
1.1+ requires an RFC.