@letthembuild/run-receipts 0.0.0-stage → 0.2.0

package/SPEC.md

@@ -0,0 +1,230 @@
+# Run receipt, version 0.1 (draft)
+
+Status: draft. Field names and rules may change before 1.0.
+
+## What a receipt is
+
+Several models agreeing on an answer is not evidence that the answer is right. A run receipt is the short, machine-readable account of what a multi-model run actually did to check its own work: who took part, which commands were run and how they exited, where each reviewer ended up, and what nobody verified.
+
+A receipt holds figures, names and commands. It never holds a prompt, a model's reply, a file's contents or a command's full output.
+
+A receipt is the producer's account of the run. A verifier can prove that the account is well-formed, consistent with itself and unchanged since its digest was taken, and, when it is signed, which keys put their name to it. It cannot prove the run happened as described. See "What a verifier cannot tell you".
+
+## Vocabulary
+
+- **Run**: one request worked on by one lead and zero or more reviewers until it ends.
+- **Seat**: one participant in the run, with a display name and the model behind it.
+- **Lead**: the seat that does the work. **Reviewer**: a seat that examines it.
+- **Check**: a command a seat ran to test the work.
+- **Stance**: where a reviewer ended the run. `agreed`, `objected`, `silent` (answered without saying either way) or `unavailable` (could not answer at all).
+- **Gap**: something that was not verified, stated in words.
+
+## The document
+
+A receipt is one JSON object, UTF-8. `receipt.schema.json` is the normative shape; unknown fields are not allowed.
+
+### Top level
+
+| Field | Required | Meaning |
+|---|---|---|
+| `receiptVersion` | yes | `"0.1"`. |
+| `id` | no | Opaque id chosen by the producer. |
+| `producer` | yes | `name` and optional `version` of the tool that wrote the receipt. |
+| `endedAt` | yes | When the run ended, UTC, `YYYY-MM-DDTHH:MM:SSZ`. |
+| `revision` | no | The commit the work ended on, or null outside a repository. May say that uncommitted changes were present. |
+| `durationMs` | yes | Wall-clock length of the run. |
+| `firstReplyMs` | no | Time until the first seat began answering. |
+| `tokens` | yes | Tokens used by all seats, in and out. |
+| `costUsd` | yes | Metered cost of the run in US dollars. Seats on a flat subscription add nothing. |
+| `seats` | yes | One entry per seat, 1 to 32. |
+| `verdict` | yes | How the reviewers ended, or null when nobody reviewed. |
+| `checks` | yes | The commands run to test the work. May be empty. |
+| `totals` | yes | The counts the grade is worked out from. |
+| `grade` | yes | One word for how well the result was checked. |
+| `gaps` | yes | What was not verified. May be empty, and is listed even when everyone agreed. |
+| `digest` | no | `sha256:` and 64 hex characters over the canonical form. |
+| `signatures` | no | One to eight signatures over the digest. See "Signatures". |
+
+### Seat
+
+| Field | Required | Meaning |
+|---|---|---|
+| `name` | yes | Display name, unique within the run. Checks and holdouts refer to it. |
+| `role` | yes | `lead` or `reviewer`. |
+| `model` | yes | The model identifier the seat ran. |
+| `family` | no | The model's vendor family, lower case. |
+| `turns` | yes | Answers the seat completed. |
+| `errors` | yes | Attempts that failed. |
+| `timeouts` | yes | How many of those errors were the seat going quiet. |
+| `durationMs` | yes | Time the seat spent answering. Seats may run in parallel, so these do not add up to the run's length. |
+| `costUsd` | yes | Metered cost of this seat. |
+| `costBasis` | no | `metered`, `subscription` (a flat plan bought elsewhere) or `unpriced` (no published price). |
+| `stance` | reviewers only | Where the reviewer ended. |
+| `commandsVisible` | no | False when the seat worked inside a tool whose commands the producer could not observe. Such a seat is not counted as having run nothing; it is counted as not visible. |
+
+### Verdict
+
+| Field | Meaning |
+|---|---|
+| `outcome` | `agreed`, `majority` (more than half agree) or `none` (half or fewer; a tie is not a majority). |
+| `agreed` | How many reviewers agreed. |
+| `reviewers` | How many reviewers the outcome is counted over. |
+| `holdouts` | Every reviewer that did not agree, by name, with its stance. |
+
+A reviewer that could not answer is not a reviewer that disagreed. When every reviewer that answered agreed and no check is still failing, the outcome is `agreed`, counted over those that answered, and the missing seats stay named in `holdouts`.
+
+### Check
+
+| Field | Required | Meaning |
+|---|---|---|
+| `by` | yes | The seat that ran it, or null when unknown. |
+| `alsoBy` | no | Up to four other seats that re-ran it with the same result. |
+| `purpose` | no | What the seat said the command was for. |
+| `command` | yes | The command as run, at most 300 characters. |
+| `exitCode` | yes | Its exit code, or null when none was seen. |
+| `result` | no | One line of its output, at most 200 characters. |
+| `revision` | no | The commit it ran against. |
+| `where` | yes | `local`, `ci`, `cloud` or `other`. A category, never a machine name. |
+| `deployed` | yes | True when the command reached the place the work actually runs. |
+| `missingSetup` | yes | What the command needed and did not have, in words, or null. |
+| `state` | yes | `checked` (ran and answered), `reproduced` (a failure was shown), `blocked` (could not run for want of setup), `unknown` (ran, result not seen) or `untested` (named but never run). |
+| `durationMs` | no | How long it took. |
+
+`checks` is a readable list, not a ledger: identical re-runs are merged into one entry with `alsoBy`, and a producer may cap the list. `totals` holds the full counts.
+
+### Totals
+
+| Field | Required | Meaning |
+|---|---|---|
+| `reviewers` | yes | Reviewers that answered. |
+| `verifiers` | yes | Reviewers that ran at least one command. |
+| `notVisible` | no | Reviewers whose commands could not be observed. |
+| `contradicted` | yes | Reviewers that said they agreed while their own checks failed. Their agreement does not count. |
+| `ran` | yes | Commands run to test the work. |
+| `passed` | yes | Of those, how many passed. |
+| `failed` | yes | How many failed at any point in the run. |
+| `failingNow` | yes | How many were still failing when the run ended. |
+| `expected` | no | Failed as intended: a probe answering "not installed", or the failure the person asked to see. Neither passed nor failing. |
+| `resolved` | no | Failed earlier and passing at the end: caught and fixed. |
+| `filesChanged` | no | Files the lead changed. Absent means not measured; 0 means measured and none. |
+
+### Grade
+
+One of six words, decided by the first rule that applies:
+
+1. `failed`: a check is still failing, or a reviewer contradicted its own checks.
+2. `verified`: commands were run, and every reviewer ran some.
+3. `partial`: commands were run, by some reviewers only.
+4. `reviewed`: nothing was run and no file was changed. A question was answered and read.
+5. `not-visible`: nothing was run where it could be seen, and every reviewer worked out of view.
+6. `unverified`: none of the above.
+
+The grade is a word and not a score on purpose. A failed check is a different answer from an unrun one, not fewer points.
+
+## What a verifier must check
+
+A receipt is valid when it satisfies the schema and every rule below. Rule ids are stable, so tools can report them.
+
+**Seats**
+- S1. Seat names are unique.
+- S2. At least one seat is the lead.
+- S3. `timeouts` does not exceed `errors`.
+- S4. Every reviewer has a `stance`; the lead has none.
+- S5. A seat whose `costBasis` is `subscription` or `unpriced` has `costUsd` 0.
+
+**Verdict**
+- V1. `verdict` is null exactly when the run has no reviewers.
+- V2. `verdict.agreed` equals the number of reviewers whose stance is `agreed`.
+- V3. `holdouts` is exactly the reviewers whose stance is not `agreed`, each with that stance.
+- V4. `outcome` is `agreed` only if at least one reviewer answered and every reviewer that answered agreed; and, if any reviewer was `unavailable`, only if `totals.failingNow` is 0. Otherwise `outcome` is `majority` when more than half of all reviewers agreed, else `none`.
+- V5. `verdict.reviewers` is the number of reviewers that answered when the outcome is `agreed`, and the number of all reviewers otherwise.
+
+A producer may record `majority` or `none` where V4 would allow `agreed`: a run can withhold agreement for reasons of its own. It may never record `agreed` where V4 forbids it.
+
+**Totals**
+- T1. `reviewers` equals the number of reviewers whose stance is not `unavailable`.
+- T2. `verifiers`, `notVisible` and `contradicted` do not exceed `reviewers`; `notVisible` does not exceed the reviewers marked `commandsVisible: false`.
+- T3. `passed + failed + expected` does not exceed `ran`.
+- T4. `failingNow` does not exceed `failed`; `resolved` does not exceed `failed - failingNow`.
+- T5. `ran` is above 0 exactly when `verifiers` is above 0.
+
+**Grade**
+- G1. `grade` is the word the totals earn under the six rules above.
+
+**Checks**
+- C1. `by` and every name in `alsoBy` is a seat in the run.
+- C2. A check that exited 0 has state `checked`.
+- C3. State `blocked` and a non-null `missingSetup` go together.
+- C4. States `unknown` and `untested` have a null `exitCode`.
+- C5 (warning). More checks are listed as run than `totals.ran` counts.
+
+**Money and time**
+- M1 (warning). Seat costs differ from `costUsd` by more than one cent.
+- M2. `firstReplyMs` does not exceed `durationMs`.
+- M3. `endedAt` is a real date.
+
+**Digest**
+- D1. If `digest` is present it equals the digest of the receipt.
+- D2 (warning). No digest is present.
+
+**Signatures**
+- K1. Every signature is its key's signature over this receipt.
+- K2. No key signs twice.
+- K3. Only when the reader requires a signature: at least one signature is from a key the reader trusts.
+
+Warnings do not make a receipt invalid.
+
+## Digest
+
+The digest is SHA-256 over the receipt's canonical form, written `sha256:` followed by lower-case hex. The canonical form is the receipt without its top-level `digest` and `signatures` fields, serialised as JSON with object keys sorted by code unit at every level, no whitespace, and numbers and strings as `JSON.stringify` writes them, encoded as UTF-8.
+
+A digest lets a copy of a receipt, such as one quoted in a pull-request comment, be matched against the file it came from. It is not a signature: anyone who edits a receipt can retake its digest.
+
+## Signatures
+
+A signature lets a reader tell who put their name to a receipt. Signing is optional. Signatures were added to this draft after its first release; a verifier older than 0.2.0 rejects a signed receipt as carrying an unknown field.
+
+Each entry in `signatures` has two fields and no others:
+
+| Field | Meaning |
+|---|---|
+| `key` | The signer's Ed25519 public key: `ed25519:` followed by its 32 bytes in unpadded base64url. |
+| `sig` | The signature's 64 bytes in unpadded base64url. |
+
+What is signed is the UTF-8 bytes of the line `run-receipt-signature-v1`, a line feed, and the receipt's digest as written (`sha256:` and the hex). The digest signed is the one worked out from the receipt, not the one it states, so a signature holds only over the receipt as it stands. The leading line keeps a signature made for a receipt from being valid for anything else the same key signs.
+
+Because `signatures` is left out of the canonical form, signing does not change a receipt's digest, and a second party can add its own signature without disturbing the first.
+
+### What a signature means
+
+A signature that holds says that the holder of that key signed exactly this receipt. That is all it says. Three things follow.
+
+- **A key is not a name.** A receipt carries keys and never says whose they are: a signature entry has no room for a name, so a receipt cannot introduce its own signer. The reader decides which keys to trust and what to call them, in a list the reader keeps. A signature from a key the reader has not listed proves that somebody signed, and nothing about who.
+- **A signature is worth what the key's keeping is worth.** A key held by a build server and never shown to anyone supports a strong claim. A key shipped inside an application that runs on its users' machines can be taken out by any of them, and proves only that the receipt came from a copy of that application. Say which kind your key is when you publish it.
+- **A signature does not make a receipt true.** It moves the question from "was this file edited?" to "do I believe this signer's account?". The signer can still be wrong, or lie.
+
+A reader that requires a signature (rule K3) must name the keys it trusts. Requiring a signature from any key at all is meaningless, since anyone can make a key.
+
+## What a verifier cannot tell you
+
+- That the commands were really run, or exited as stated.
+- That the seats were the models named.
+- That the receipt belongs to the change it is attached to, beyond the `revision` it names.
+
+A signature from a key you trust narrows the first two to how far you trust the signer. Nothing in a receipt closes them outright.
+
+## What a receipt must not carry
+
+A tool that runs models holds far more about a run than a receipt should. A producer must keep all of the following out of a receipt, and the schema rejects unknown fields so that none of it can be added by accident.
+
+| Left out | Why |
+|---|---|
+| Prompts, replies, conversation titles, file contents | A receipt is figures, not the work. |
+| Full command output | Output carries paths, tokens and data. One line (`result`) is the limit, and the producer must mask secrets in it and in `command`. |
+| Account email, user id, team or organisation id | Personal and customer data. |
+| The id of the conversation or job the run belonged to, or anything derived from it | Links a public file to a private record. `id` must be opaque. |
+| Machine names and host names for where a check ran | `where` is a four-word category for this reason. |
+| How a seat was paid for beyond `costBasis` | Billing detail. |
+| Network destinations blocked or allowed, browser permissions, sandbox decisions | Describe the person's machine and browsing, not the result. |
+| Team policy and configuration | Belongs to the team, not to the run. |
+| Free-text narrative: why a seat was silent, what failed, notes for later | Free text can quote the work. `gaps` and `purpose` are the only prose, and both are short. |

package/examples/agreed-verified.json

@@ -0,0 +1,26 @@
+{
+  "receiptVersion": "0.1",
+  "id": "example-agreed-verified",
+  "producer": { "name": "example-producer", "version": "0.0.1" },
+  "endedAt": "2026-11-10T16:42:07Z",
+  "revision": "4f1c2ab90d3e",
+  "durationMs": 184300,
+  "firstReplyMs": 2100,
+  "tokens": 61240,
+  "costUsd": 0.4312,
+  "seats": [
+    { "name": "Claude", "role": "lead", "model": "claude-sonnet-5-5", "family": "claude", "turns": 3, "errors": 0, "timeouts": 0, "durationMs": 96200, "costUsd": 0.2871, "costBasis": "metered" },
+    { "name": "Gemini", "role": "reviewer", "model": "gemini-3-pro", "family": "gemini", "turns": 2, "errors": 0, "timeouts": 0, "durationMs": 41800, "costUsd": 0.0935, "costBasis": "metered", "stance": "agreed" },
+    { "name": "ChatGPT", "role": "reviewer", "model": "gpt-5.2", "family": "openai", "turns": 2, "errors": 1, "timeouts": 1, "durationMs": 46300, "costUsd": 0.0506, "costBasis": "metered", "stance": "agreed" }
+  ],
+  "verdict": { "outcome": "agreed", "agreed": 2, "reviewers": 2, "holdouts": [] },
+  "checks": [
+    { "by": "Gemini", "alsoBy": ["ChatGPT"], "purpose": "Run the unit tests", "command": "npm test", "exitCode": 0, "result": "42 passing", "revision": "4f1c2ab90d3e", "where": "local", "deployed": false, "missingSetup": null, "state": "checked", "durationMs": 8400 },
+    { "by": "ChatGPT", "purpose": "Check types", "command": "npm run typecheck", "exitCode": 0, "result": "", "revision": "4f1c2ab90d3e", "where": "local", "deployed": false, "missingSetup": null, "state": "checked", "durationMs": 5100 },
+    { "by": "Gemini", "purpose": "Ask the staging health endpoint", "command": "curl -fsS https://staging.example.com/healthz", "exitCode": 0, "result": "ok", "revision": null, "where": "local", "deployed": true, "missingSetup": null, "state": "checked" }
+  ],
+  "totals": { "reviewers": 2, "verifiers": 2, "notVisible": 0, "contradicted": 0, "ran": 5, "passed": 4, "failed": 1, "failingNow": 0, "resolved": 1, "filesChanged": 3 },
+  "grade": "verified",
+  "gaps": ["Behaviour under production load"],
+  "digest": "sha256:12b44c77459b21d7d99682b9a75a620d7ee5aae1ef0f581ce5e0e5df677334ab"
+}

package/examples/not-unanimous-failing.json

@@ -0,0 +1,38 @@
+{
+  "receiptVersion": "0.1",
+  "id": "example-not-unanimous-failing",
+  "producer": { "name": "example-producer", "version": "0.0.1" },
+  "endedAt": "2026-11-10T18:05:51Z",
+  "revision": "9a07de41c6b2 + uncommitted changes",
+  "durationMs": 402900,
+  "tokens": 138700,
+  "costUsd": 0.2204,
+  "seats": [
+    { "name": "Codex", "role": "lead", "model": "gpt-5.2-codex", "family": "openai", "turns": 4, "errors": 0, "timeouts": 0, "durationMs": 211000, "costUsd": 0, "costBasis": "subscription" },
+    { "name": "Claude", "role": "reviewer", "model": "claude-sonnet-5-5", "family": "claude", "turns": 3, "errors": 0, "timeouts": 0, "durationMs": 98400, "costUsd": 0.2204, "costBasis": "metered", "stance": "objected" },
+    { "name": "Gemini", "role": "reviewer", "model": "gemini-3-pro", "family": "gemini", "turns": 3, "errors": 0, "timeouts": 0, "durationMs": 77100, "costUsd": 0, "costBasis": "subscription", "stance": "agreed", "commandsVisible": false },
+    { "name": "Grok", "role": "reviewer", "model": "grok-5", "family": "xai", "turns": 0, "errors": 2, "timeouts": 2, "durationMs": 0, "costUsd": 0, "costBasis": "unpriced", "stance": "unavailable" }
+  ],
+  "verdict": {
+    "outcome": "none",
+    "agreed": 1,
+    "reviewers": 3,
+    "holdouts": [
+      { "name": "Claude", "stance": "objected" },
+      { "name": "Grok", "stance": "unavailable" }
+    ]
+  },
+  "checks": [
+    { "by": "Claude", "purpose": "Run the migration tests", "command": "pytest tests/test_migrate.py -q", "exitCode": 1, "result": "1 failed, 11 passed", "revision": "9a07de41c6b2 + uncommitted changes", "where": "local", "deployed": false, "missingSetup": null, "state": "reproduced", "durationMs": 12900 },
+    { "by": "Claude", "purpose": "Run the tests against Postgres", "command": "pytest tests/test_migrate.py -q --db postgres", "exitCode": 1, "result": "connection refused", "revision": "9a07de41c6b2 + uncommitted changes", "where": "local", "deployed": false, "missingSetup": "a service it needs was not reachable", "state": "blocked" },
+    { "by": null, "command": "make lint", "exitCode": null, "result": "", "revision": null, "where": "ci", "deployed": false, "missingSetup": null, "state": "unknown" }
+  ],
+  "totals": { "reviewers": 2, "verifiers": 1, "notVisible": 1, "contradicted": 0, "ran": 3, "passed": 0, "failed": 2, "failingNow": 2, "filesChanged": 6 },
+  "grade": "failed",
+  "gaps": [
+    "Checked locally only; deployed behaviour not verified",
+    "Behaviour on the hosted database",
+    "Gemini's commands could not be seen"
+  ],
+  "digest": "sha256:1e471ce1e3b03fb7fef58f3d56bd08cee3684c499f002e3ffdd5b64334f5170f"
+}

package/examples/produce.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// Copyright 2026 GPULogy AI LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+// An example producer: the least a tool needs to turn what it saw during a
+// run into a valid receipt. PRODUCERS.md walks through it. It is an example
+// to read and adapt, not a library; the rules it follows are SPEC.md's.
+//
+//   node examples/produce.mjs            print a receipt for the sample run below
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { gradeOf, digestOf, verifyReceipt } from "../verify.mjs";
+
+/** One line, cut to length: `command` and `result` never carry more. */
+const line = (s, max) => Array.from(String(s ?? "").replace(/\s+/g, " ").trim()).slice(0, max).join("");
+
+/**
+ * A starting point for masking, and no more than that. A real producer knows
+ * what its own secrets look like and must mask those too.
+ */
+export const mask = (s) => String(s ?? "")
+  .replace(/\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)[A-Z0-9_]*)=\S+/g, "$1=***")
+  .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/g, "$1 ***")
+  .replace(/(?:\/Users|\/home)\/[^/\s]+/g, "~");
+
+/**
+ * Build a receipt from a run.
+ *
+ *   run.seats     every seat, the lead and the reviewers, with its figures and,
+ *                 for a reviewer, where it ended (stance)
+ *   run.commands  every command a reviewer ran to test the work, in the order
+ *                 they were run: { by, command, exitCode, purpose?, result?,
+ *                 where?, deployed?, missingSetup? }
+ *   run.gaps      what nobody verified, in words
+ */
+export function buildReceipt(run) {
+  const reviewers = run.seats.filter((s) => s.role === "reviewer");
+  const answered = reviewers.filter((s) => s.stance !== "unavailable");
+  const agreed = reviewers.filter((s) => s.stance === "agreed");
+  const counted = new Set(answered.map((s) => s.name));
+
+  // Totals count what reviewers that answered ran. Each run of a command is
+  // counted; a command run twice is two.
+  const runs = run.commands.filter((c) => counted.has(c.by));
+  const failedRun = (c) => typeof c.exitCode === "number" && c.exitCode !== 0;
+  const last = new Map();        // command -> its last run
+  const everFailed = new Set();  // commands that failed at any point
+  const lastBySeat = new Map();  // "seat command" -> that seat's last run of it
+  for (const c of runs) {
+    last.set(c.command, c);
+    lastBySeat.set(`${c.by}\n${c.command}`, c);
+    if (failedRun(c)) everFailed.add(c.command);
+  }
+  const failingNow = [...last.values()].filter(failedRun).length;
+  const verifiers = answered.filter((s) => runs.some((c) => c.by === s.name));
+
+  const totals = {
+    reviewers: answered.length,
+    verifiers: verifiers.length,
+    notVisible: answered.filter((s) => s.commandsVisible === false && !verifiers.includes(s)).length,
+    // Agreed while a command of its own was still failing: that agreement does not count.
+    contradicted: agreed.filter((s) => [...lastBySeat.entries()].some(([k, c]) => k.startsWith(`${s.name}\n`) && failedRun(c))).length,
+    ran: runs.length,
+    passed: runs.filter((c) => c.exitCode === 0).length,
+    failed: runs.filter(failedRun).length,
+    failingNow,
+    resolved: [...everFailed].filter((cmd) => last.get(cmd).exitCode === 0).length,
+    ...(Number.isInteger(run.filesChanged) ? { filesChanged: run.filesChanged } : {}),
+  };
+
+  // The verdict follows from the stances (rules V1 to V5).
+  let verdict = null;
+  if (reviewers.length) {
+    const everyAnswerAgreed = answered.length > 0 && answered.every((s) => s.stance === "agreed");
+    const isAgreed = everyAnswerAgreed && (answered.length === reviewers.length || failingNow === 0);
+    verdict = {
+      outcome: isAgreed ? "agreed" : agreed.length * 2 > reviewers.length ? "majority" : "none",
+      agreed: agreed.length,
+      reviewers: isAgreed ? answered.length : reviewers.length,
+      holdouts: reviewers.filter((s) => s.stance !== "agreed").map((s) => ({ name: s.name, stance: s.stance })),
+    };
+  }
+
+  // One check per command, as it stood at the end.
+  const checks = [...last.values()].map((c) => {
+    const others = [...new Set(runs.filter((o) => o.command === c.command && o.by !== c.by && o.exitCode === c.exitCode).map((o) => o.by))].slice(0, 4);
+    const blocked = Boolean(c.missingSetup);
+    return {
+      by: c.by,
+      ...(others.length ? { alsoBy: others } : {}),
+      ...(c.purpose ? { purpose: line(c.purpose, 100) } : {}),
+      command: line(mask(c.command), 300),
+      exitCode: typeof c.exitCode === "number" ? c.exitCode : null,
+      result: line(mask(c.result), 200),
+      where: c.where ?? "local",
+      deployed: c.deployed === true,
+      missingSetup: blocked ? line(c.missingSetup, 120) : null,
+      state: blocked ? "blocked" : typeof c.exitCode !== "number" ? "unknown" : c.exitCode === 0 ? "checked" : "reproduced",
+    };
+  });
+
+  const receipt = {
+    receiptVersion: "0.1",
+    producer: run.producer,
+    endedAt: new Date(run.endedAt).toISOString().replace(/\.\d{3}Z$/, "Z"),
+    ...(run.revision ? { revision: run.revision } : {}),
+    durationMs: run.durationMs,
+    tokens: run.tokens,
+    costUsd: Number(run.seats.reduce((n, s) => n + s.costUsd, 0).toFixed(4)),
+    seats: run.seats,
+    verdict,
+    checks,
+    totals,
+    grade: gradeOf(totals),
+    gaps: run.gaps.map((g) => line(g, 200)),
+  };
+  // The digest is taken last, over everything else.
+  receipt.digest = digestOf(receipt);
+  return receipt;
+}
+
+/** A run as a tool might hold it when the run ends. */
+export const sampleRun = {
+  producer: { name: "example-producer", version: "0.0.1" },
+  endedAt: "2026-11-12T09:30:00Z",
+  revision: "4f1c2ab90d3e",
+  durationMs: 95000,
+  tokens: 41800,
+  filesChanged: 2,
+  seats: [
+    { name: "Builder", role: "lead", model: "model-a", turns: 2, errors: 0, timeouts: 0, durationMs: 52000, costUsd: 0.21, costBasis: "metered" },
+    { name: "First reviewer", role: "reviewer", model: "model-b", turns: 2, errors: 0, timeouts: 0, durationMs: 30000, costUsd: 0.08, costBasis: "metered", stance: "agreed" },
+    { name: "Second reviewer", role: "reviewer", model: "model-c", turns: 1, errors: 0, timeouts: 0, durationMs: 21000, costUsd: 0, costBasis: "subscription", stance: "agreed" },
+  ],
+  commands: [
+    { by: "First reviewer", command: "npm test", exitCode: 1, purpose: "Run the unit tests", result: "1 failing" },
+    { by: "First reviewer", command: "npm test", exitCode: 0, purpose: "Run the unit tests", result: "18 passing" },
+    { by: "Second reviewer", command: "npm test", exitCode: 0, result: "18 passing" },
+    { by: "Second reviewer", command: "API_TOKEN=abc123 npm run smoke", exitCode: 0, purpose: "Smoke test", result: "ok" },
+  ],
+  gaps: ["Checked locally only; deployed behaviour not verified"],
+};
+
+function isMain() {
+  if (!process.argv[1]) return false;
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+}
+
+if (isMain()) {
+  const receipt = buildReceipt(sampleRun);
+  // Never write a receipt that does not verify.
+  const { valid, errors } = verifyReceipt(receipt);
+  if (!valid) { console.error(errors.join("\n")); process.exit(1); }
+  console.log(JSON.stringify(receipt, null, 2));
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@letthembuild/run-receipts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A format for recording how well an AI run checked its own work, and a verifier for it.",
+  "license": "Apache-2.0",
+  "author": "GPULogy AI LLC",
+  "homepage": "https://github.com/gpulogyai/run-receipts#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gpulogyai/run-receipts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gpulogyai/run-receipts/issues"
+  },
+  "type": "module",
+  "main": "./verify.mjs",
+  "exports": {
+    ".": "./verify.mjs",
+    "./sign": "./sign.mjs",
+    "./schema": "./receipt.schema.json"
+  },
+  "bin": {
+    "run-receipts": "verify.mjs",
+    "run-receipt-verify": "verify.mjs",
+    "run-receipt-sign": "sign.mjs"
+  },
+  "files": [
+    "verify.mjs",
+    "sign.mjs",
+    "receipt.schema.json",
+    "SPEC.md",
+    "PRODUCERS.md",
+    "examples",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test verify.test.mjs sign.test.mjs action.test.mjs produce.test.mjs"
+  },
+  "keywords": [
+    "receipt",
+    "verification",
+    "ai",
+    "agents",
+    "code-review",
+    "json-schema"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/receipt.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://letthembuild.com/schemas/run-receipt/0.1/receipt.schema.json",
+  "title": "Run receipt",
+  "description": "What one multi-model run did and how well its result was checked: who took part, what was run, what passed, and what nobody verified. Figures and commands only; never a prompt, a reply or a file's contents.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["receiptVersion", "producer", "endedAt", "durationMs", "tokens", "costUsd", "seats", "verdict", "checks", "totals", "grade", "gaps"],
+  "properties": {
+    "receiptVersion": { "const": "0.1" },
+    "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "An opaque id chosen by the producer. Carries no meaning to a verifier." },
+    "producer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 60 },
+        "version": { "type": "string", "minLength": 1, "maxLength": 40 }
+      }
+    },
+    "endedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,3})?Z$", "description": "When the run ended, UTC, RFC 3339." },
+    "revision": { "type": ["string", "null"], "maxLength": 60, "description": "The commit the work ended on, if it was in a repository." },
+    "durationMs": { "type": "integer", "minimum": 0, "maximum": 86400000 },
+    "firstReplyMs": { "type": "integer", "minimum": 0, "maximum": 86400000 },
+    "tokens": { "type": "integer", "minimum": 0, "maximum": 2000000000 },
+    "costUsd": { "type": "number", "minimum": 0, "maximum": 1000000 },
+    "seats": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "$ref": "#/$defs/seat" } },
+    "verdict": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/verdict" }] },
+    "checks": { "type": "array", "maxItems": 200, "items": { "$ref": "#/$defs/check" } },
+    "totals": { "$ref": "#/$defs/totals" },
+    "grade": { "enum": ["failed", "verified", "partial", "not-visible", "reviewed", "unverified"] },
+    "gaps": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 200 } },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "signatures": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/$defs/signature" }, "description": "Signatures over the digest. Left out of the digest themselves." }
+  },
+  "$defs": {
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "sig"],
+      "properties": {
+        "key": { "type": "string", "pattern": "^ed25519:[A-Za-z0-9_-]{43}$", "description": "The signer's Ed25519 public key: its 32 bytes in base64url." },
+        "sig": { "type": "string", "pattern": "^[A-Za-z0-9_-]{86}$", "description": "The signature's 64 bytes in base64url." }
+      }
+    },
+    "stance": { "enum": ["agreed", "objected", "silent", "unavailable"] },
+    "seat": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "role", "model", "turns", "errors", "timeouts", "durationMs", "costUsd"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 60 },
+        "role": { "enum": ["lead", "reviewer"] },
+        "model": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "family": { "type": "string", "minLength": 1, "maxLength": 40 },
+        "turns": { "type": "integer", "minimum": 0, "maximum": 1000 },
+        "errors": { "type": "integer", "minimum": 0, "maximum": 1000 },
+        "timeouts": { "type": "integer", "minimum": 0, "maximum": 1000 },
+        "durationMs": { "type": "integer", "minimum": 0, "maximum": 86400000 },
+        "costUsd": { "type": "number", "minimum": 0, "maximum": 1000000 },
+        "costBasis": { "enum": ["metered", "subscription", "unpriced"] },
+        "stance": { "$ref": "#/$defs/stance" },
+        "commandsVisible": { "type": "boolean", "description": "False when the seat worked inside a tool whose commands the producer could not see." }
+      }
+    },
+    "holdout": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "stance"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 60 },
+        "stance": { "enum": ["objected", "silent", "unavailable"] }
+      }
+    },
+    "verdict": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["outcome", "agreed", "reviewers", "holdouts"],
+      "properties": {
+        "outcome": { "enum": ["agreed", "majority", "none"] },
+        "agreed": { "type": "integer", "minimum": 0, "maximum": 32 },
+        "reviewers": { "type": "integer", "minimum": 0, "maximum": 32 },
+        "holdouts": { "type": "array", "maxItems": 32, "items": { "$ref": "#/$defs/holdout" } }
+      }
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["by", "command", "exitCode", "where", "deployed", "missingSetup", "state"],
+      "properties": {
+        "by": { "type": ["string", "null"], "maxLength": 60 },
+        "alsoBy": { "type": "array", "maxItems": 4, "items": { "type": "string", "minLength": 1, "maxLength": 60 } },
+        "purpose": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "command": { "type": "string", "minLength": 1, "maxLength": 300 },
+        "exitCode": { "type": ["integer", "null"] },
+        "result": { "type": "string", "maxLength": 200, "description": "One line of the command's output. Never the whole output." },
+        "revision": { "type": ["string", "null"], "maxLength": 60 },
+        "where": { "enum": ["local", "ci", "cloud", "other"] },
+        "deployed": { "type": "boolean", "description": "True when the command reached the place the work actually runs." },
+        "missingSetup": { "type": ["string", "null"], "maxLength": 120 },
+        "state": { "enum": ["checked", "reproduced", "blocked", "unknown", "untested"] },
+        "durationMs": { "type": "integer", "minimum": 0, "maximum": 86400000 }
+      }
+    },
+    "totals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reviewers", "verifiers", "ran", "passed", "failed", "failingNow", "contradicted"],
+      "properties": {
+        "reviewers": { "type": "integer", "minimum": 0, "maximum": 32 },
+        "verifiers": { "type": "integer", "minimum": 0, "maximum": 32 },
+        "notVisible": { "type": "integer", "minimum": 0, "maximum": 32 },
+        "contradicted": { "type": "integer", "minimum": 0, "maximum": 32 },
+        "ran": { "type": "integer", "minimum": 0, "maximum": 100000 },
+        "passed": { "type": "integer", "minimum": 0, "maximum": 100000 },
+        "failed": { "type": "integer", "minimum": 0, "maximum": 100000 },
+        "failingNow": { "type": "integer", "minimum": 0, "maximum": 100000 },
+        "expected": { "type": "integer", "minimum": 0, "maximum": 100000 },
+        "resolved": { "type": "integer", "minimum": 0, "maximum": 100000 },
+        "filesChanged": { "type": "integer", "minimum": 0, "maximum": 100000 }
+      }
+    }
+  }
+}