@letthembuild/run-receipts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "{}"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright 2026 GPULogy AI LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+Run receipts
+Copyright 2026 GPULogy AI LLC
+
+This product includes software developed at GPULogy AI LLC.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# Run receipts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A run receipt is a short, machine-readable account of how well an AI run checked its own work.
+
+Several models agreeing on an answer is not evidence that the answer is right. What matters is what was actually run: which commands, by whom, how they exited, and what nobody verified. A receipt records exactly that, in one JSON file that a person can read and a tool can check.
+
+This repository holds:
+
+- **[SPEC.md](SPEC.md)**: the format, version 0.1 (draft), and the rules a valid receipt obeys.
+- **[receipt.schema.json](receipt.schema.json)**: the JSON Schema.
+- **[verify.mjs](verify.mjs)**: a verifier with no dependencies.
+- **[examples/](examples)**: two receipts to read and test against.
+
+The format is not tied to any one product. Any tool that runs one model to do work and others to review it can write a receipt.
+
+## What a receipt looks like
+
+```json
+{
+  "receiptVersion": "0.1",
+  "producer": { "name": "example-producer" },
+  "endedAt": "2026-11-10T16:42:07Z",
+  "seats": [
+    { "name": "Claude", "role": "lead", "model": "claude-sonnet-5-5", "...": "..." },
+    { "name": "Gemini", "role": "reviewer", "model": "gemini-3-pro", "stance": "agreed", "...": "..." }
+  ],
+  "verdict": { "outcome": "agreed", "agreed": 2, "reviewers": 2, "holdouts": [] },
+  "checks": [
+    { "by": "Gemini", "command": "npm test", "exitCode": 0, "where": "local", "deployed": false, "state": "checked", "...": "..." }
+  ],
+  "totals": { "reviewers": 2, "verifiers": 2, "ran": 5, "passed": 4, "failed": 1, "failingNow": 0, "...": "..." },
+  "grade": "verified",
+  "gaps": ["Behaviour under production load"]
+}
+```
+
+The full versions are in [examples/](examples). A receipt holds figures, names and commands. It never holds a prompt, a model's reply or a file's contents.
+
+## Verify a receipt
+
+You need Node 18 or later. Nothing else.
+
+With npm, no clone is needed:
+
+```bash
+npx @letthembuild/run-receipts receipt.json
+```
+
+Or from a clone of this repository:
+
+```bash
+git clone <this repository> run-receipts
+```
+
+```bash
+node run-receipts/verify.mjs run-receipts/examples/agreed-verified.json
+```
+
+```
+VALID    run-receipts/examples/agreed-verified.json
+```
+
+A receipt that does not hold together is rejected, with the rule it broke:
+
+```
+INVALID  edited.json
+  error    G1: grade is failed; the totals earn verified
+  error    D1: digest does not match the receipt's contents
+```
+
+| Command | What it does |
+|---|---|
+| `verify.mjs <file>` | Check a receipt. Exits 0 when valid, 1 when invalid, 2 when the file cannot be read. |
+| `verify.mjs --json <file>` | The same, with the result as JSON. |
+| `verify.mjs --digest <file>` | Print the digest the receipt should carry. |
+
+The verifier is also a module:
+
+```js
+import { verifyReceipt } from "./verify.mjs";
+
+const { valid, errors, warnings } = verifyReceipt(receipt);
+```
+
+## What verifying proves, and what it does not
+
+A valid receipt is well-formed, consistent with itself, and unchanged since its digest was taken. Its grade follows from its totals, its verdict follows from where each reviewer ended, and each check's state matches its exit code.
+
+Verifying does **not** prove that the commands were really run or that they exited as stated. A receipt is the producer's own account. Trusting a receipt you did not produce needs a signature, which version 0.1 leaves out.
+
+## Roadmap
+
+Not in 0.1:
+
+- **Signing**, so a reader can tell who produced a receipt.
+- **A GitHub Action** that verifies a receipt on a pull request and posts its grade, checks and gaps as a comment.
+- **A guide for producers**: how to write a receipt from your own tool.
+
+## Run the tests
+
+```bash
+npm test
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports go to the address in [SECURITY.md](SECURITY.md), not to public issues.
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). The licence covers the code and the specification; it does not grant use of any names or logos, as [TRADEMARKS.md](TRADEMARKS.md) explains.

package/SPEC.md

@@ -0,0 +1,199 @@
+# 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. 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. |
+
+### 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.
+
+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` field, 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.
+
+## 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.
+
+Closing those gaps needs a signature from the producer and a way to check the key, which this version leaves out. See the roadmap in README.md.
+
+## 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/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@letthembuild/run-receipts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+    "./schema": "./receipt.schema.json"
+  },
+  "bin": {
+    "run-receipt-verify": "./verify.mjs"
+  },
+  "files": [
+    "verify.mjs",
+    "receipt.schema.json",
+    "SPEC.md",
+    "examples",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test verify.test.mjs"
+  },
+  "keywords": [
+    "receipt",
+    "verification",
+    "ai",
+    "agents",
+    "code-review",
+    "json-schema"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/receipt.schema.json

@@ -0,0 +1,114 @@
+{
+  "$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}$" }
+  },
+  "$defs": {
+    "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 }
+      }
+    }
+  }
+}

package/verify.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * Run-receipt verifier, v0.1.
+ *
+ * Answers one question about a receipt file: does it hold together? First
+ * against the schema (shape, bounds), then against itself (the rules in
+ * SPEC.md: a grade that follows from the totals, a verdict that follows from
+ * where each reviewer ended, checks whose state matches their exit code).
+ *
+ * It does not prove the run happened. A receipt is the producer's account;
+ * this proves the account is well-formed, internally consistent and, when it
+ * carries a digest, unaltered since the digest was taken.
+ *
+ * No dependencies: Node 18 or later and this file, with the schema beside it.
+ */
+import { readFileSync, realpathSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const SCHEMA_URL = new URL("./receipt.schema.json", import.meta.url);
+let cachedSchema = null;
+export function loadSchema() {
+  return (cachedSchema ??= JSON.parse(readFileSync(SCHEMA_URL, "utf8")));
+}
+
+/* ── Schema: the subset of JSON Schema that receipt.schema.json uses ───── */
+
+const typeOf = (v) => (v === null ? "null" : Array.isArray(v) ? "array" : Number.isInteger(v) ? "integer" : typeof v);
+const isType = (v, t) => typeOf(v) === t || (t === "number" && typeof v === "number");
+
+/** Every way `value` fails `schema`, as "path: what is wrong". Empty when it passes. */
+export function validateSchema(value, schema, root = schema, path = "$") {
+  if (schema.$ref) {
+    const target = schema.$ref.replace(/^#\//, "").split("/").reduce((o, k) => o?.[k], root);
+    if (!target) return [`${path}: schema reference ${schema.$ref} not found`];
+    return validateSchema(value, target, root, path);
+  }
+  if (schema.anyOf) {
+    return schema.anyOf.some((s) => validateSchema(value, s, root, path).length === 0) ? [] : [`${path}: matches none of the allowed forms`];
+  }
+  const out = [];
+  if ("const" in schema && value !== schema.const) return [`${path}: must be ${JSON.stringify(schema.const)}`];
+  if (schema.enum && !schema.enum.includes(value)) return [`${path}: must be one of ${schema.enum.join(", ")}`];
+  if (schema.type) {
+    const types = [].concat(schema.type);
+    if (!types.some((t) => isType(value, t))) return [`${path}: must be ${types.join(" or ")}, found ${typeOf(value)}`];
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) out.push(`${path}: must be a finite number`);
+    if (schema.minimum !== undefined && value < schema.minimum) out.push(`${path}: must be at least ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) out.push(`${path}: must be at most ${schema.maximum}`);
+  }
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength) out.push(`${path}: must be at least ${schema.minLength} characters`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) out.push(`${path}: must be at most ${schema.maxLength} characters`);
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) out.push(`${path}: does not have the required form`);
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) out.push(`${path}: needs at least ${schema.minItems} item(s)`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) out.push(`${path}: allows at most ${schema.maxItems} items`);
+    if (schema.items) value.forEach((v, i) => out.push(...validateSchema(v, schema.items, root, `${path}[${i}]`)));
+  }
+  if (typeOf(value) === "object") {
+    const props = schema.properties ?? {};
+    for (const key of schema.required ?? []) if (!(key in value)) out.push(`${path}.${key}: is required`);
+    for (const [key, v] of Object.entries(value)) {
+      if (key in props) out.push(...validateSchema(v, props[key], root, `${path}.${key}`));
+      else if (schema.additionalProperties === false) out.push(`${path}.${key}: is not part of the format`);
+    }
+  }
+  return out;
+}
+
+/* ── Digest ──────────────────────────────────────────────────────────── */
+
+/** The receipt as bytes to hash: keys sorted, no whitespace, `digest` left out. */
+export function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+}
+
+export function digestOf(receipt) {
+  const { digest: _left_out, ...rest } = receipt;
+  return `sha256:${createHash("sha256").update(canonical(rest), "utf8").digest("hex")}`;
+}
+
+/* ── Consistency: the rules of SPEC.md, by number ────────────────────── */
+
+/** The grade the totals earn (SPEC rule G). */
+export function gradeOf(t) {
+  if (t.failingNow > 0 || t.contradicted > 0) return "failed";
+  if (t.ran > 0) return t.verifiers >= t.reviewers ? "verified" : "partial";
+  if (t.filesChanged === 0) return "reviewed";
+  if (t.reviewers > 0 && (t.notVisible ?? 0) >= t.reviewers) return "not-visible";
+  return "unverified";
+}
+
+/** Errors and warnings from a receipt that already passed the schema. */
+export function checkConsistency(r) {
+  const errors = [], warnings = [];
+  const err = (rule, msg) => errors.push(`${rule}: ${msg}`);
+  const t = r.totals;
+
+  // S — seats.
+  const names = r.seats.map((s) => s.name);
+  if (new Set(names).size !== names.length) err("S1", "two seats share a name");
+  if (!r.seats.some((s) => s.role === "lead")) err("S2", "no seat is the lead");
+  const reviewers = r.seats.filter((s) => s.role === "reviewer");
+  for (const s of r.seats) {
+    if (s.timeouts > s.errors) err("S3", `${s.name}: more timeouts than errors`);
+    if (s.role === "reviewer" && !s.stance) err("S4", `${s.name}: a reviewer needs a stance`);
+    if (s.role === "lead" && s.stance) err("S4", `${s.name}: the lead has no stance`);
+    if (s.costBasis && s.costBasis !== "metered" && s.costUsd > 0) err("S5", `${s.name}: a ${s.costBasis} seat cannot carry a metered cost`);
+  }
+
+  // V — verdict.
+  const agreed = reviewers.filter((s) => s.stance === "agreed");
+  const answered = reviewers.filter((s) => s.stance !== "unavailable");
+  const out = reviewers.filter((s) => s.stance && s.stance !== "agreed");
+  if (reviewers.length === 0) {
+    if (r.verdict !== null) err("V1", "nobody reviewed, so there can be no verdict");
+  } else if (r.verdict === null) {
+    err("V1", "reviewers took part, so a verdict is required");
+  } else {
+    const v = r.verdict;
+    if (v.agreed !== agreed.length) err("V2", `verdict counts ${v.agreed} agreeing; the seats show ${agreed.length}`);
+    const key = (h) => `${h.name}\u0000${h.stance}`;
+    const want = out.map(key).sort().join("\n"), got = v.holdouts.map(key).sort().join("\n");
+    if (want !== got) err("V3", "holdouts are not exactly the reviewers that did not agree");
+    if (v.outcome === "agreed") {
+      const allWhoAnsweredAgreed = answered.length > 0 && answered.every((s) => s.stance === "agreed");
+      const someoneMissing = answered.length < reviewers.length;
+      if (!allWhoAnsweredAgreed) err("V4", "outcome is agreed while a reviewer that answered did not agree");
+      else if (someoneMissing && t.failingNow > 0) err("V4", "outcome is agreed without a reviewer while a check is still failing");
+      if (v.reviewers !== answered.length) err("V5", `an agreed verdict counts the reviewers that answered (${answered.length}), not ${v.reviewers}`);
+    } else {
+      const expected = agreed.length * 2 > reviewers.length ? "majority" : "none";
+      if (v.outcome !== expected) err("V4", `outcome should be ${expected}: ${agreed.length} of ${reviewers.length} agree`);
+      if (v.reviewers !== reviewers.length) err("V5", `verdict counts ${v.reviewers} reviewers; the seats show ${reviewers.length}`);
+    }
+  }
+
+  // T — totals.
+  if (t.reviewers !== answered.length) err("T1", `totals count ${t.reviewers} reviewers; ${answered.length} answered`);
+  if (t.verifiers > t.reviewers) err("T2", "more verifiers than reviewers");
+  if ((t.notVisible ?? 0) > t.reviewers) err("T2", "more not-visible seats than reviewers");
+  if (t.contradicted > t.reviewers) err("T2", "more contradicted seats than reviewers");
+  const hidden = reviewers.filter((s) => s.commandsVisible === false).length;
+  if ((t.notVisible ?? 0) > hidden) err("T2", `totals count ${t.notVisible} not-visible seats; ${hidden} reviewer(s) are marked so`);
+  if (t.passed + t.failed + (t.expected ?? 0) > t.ran) err("T3", "passed, failed and expected add up to more than ran");
+  if (t.failingNow > t.failed) err("T4", "more checks failing now than ever failed");
+  if ((t.resolved ?? 0) > t.failed - t.failingNow) err("T4", "more checks resolved than stopped failing");
+  if (t.ran > 0 && t.verifiers === 0) err("T5", "commands were run, but no reviewer is counted as running any");
+  if (t.ran === 0 && t.verifiers > 0) err("T5", "a reviewer is counted as running commands, but none were run");
+
+  // G — grade.
+  const grade = gradeOf(t);
+  if (r.grade !== grade) err("G1", `grade is ${r.grade}; the totals earn ${grade}`);
+
+  // C — checks.
+  r.checks.forEach((c, i) => {
+    const at = `checks[${i}]`;
+    for (const who of [c.by, ...(c.alsoBy ?? [])]) if (who !== null && !names.includes(who)) err("C1", `${at}: ${who} is not a seat in this run`);
+    if (c.exitCode === 0 && c.state !== "checked") err("C2", `${at}: exited 0, so its state is checked, not ${c.state}`);
+    if ((c.state === "blocked") !== (c.missingSetup !== null)) err("C3", `${at}: blocked and missing setup go together`);
+    if ((c.state === "unknown" || c.state === "untested") && c.exitCode !== null) err("C4", `${at}: a state of ${c.state} has no exit code`);
+  });
+  const ranHere = r.checks.filter((c) => c.state !== "untested").length;
+  if (ranHere > t.ran) warnings.push(`C5: ${ranHere} checks are listed as run, but the totals count ${t.ran}`);
+
+  // M — money and time.
+  const seatCost = r.seats.reduce((n, s) => n + s.costUsd, 0);
+  if (Math.abs(seatCost - r.costUsd) > 0.01) warnings.push(`M1: seats add up to $${seatCost.toFixed(4)}; the run says $${r.costUsd.toFixed(4)}`);
+  if (r.firstReplyMs !== undefined && r.firstReplyMs > r.durationMs) err("M2", "the first reply came after the run ended");
+  if (Number.isNaN(Date.parse(r.endedAt))) err("M3", "endedAt is not a real date");
+
+  // D — digest.
+  if (r.digest && r.digest !== digestOf(r)) err("D1", "digest does not match the receipt's contents");
+  if (!r.digest) warnings.push("D2: no digest, so a copy cannot be told from an edited one");
+
+  return { errors, warnings };
+}
+
+/** Schema first; the consistency rules only run on a receipt with the right shape. */
+export function verifyReceipt(receipt) {
+  const schemaErrors = validateSchema(receipt, loadSchema());
+  if (schemaErrors.length) return { valid: false, errors: schemaErrors.map((e) => `schema: ${e}`), warnings: [] };
+  const { errors, warnings } = checkConsistency(receipt);
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/* ── Command line ────────────────────────────────────────────────────── */
+
+const USAGE = `Usage:
+  verify.mjs <receipt.json>            check a receipt; exit 0 valid, 1 invalid
+  verify.mjs --json <receipt.json>     the same, as JSON
+  verify.mjs --digest <receipt.json>   print the digest the receipt should carry`;
+
+function main(argv) {
+  const flags = argv.filter((a) => a.startsWith("--"));
+  const files = argv.filter((a) => !a.startsWith("--"));
+  if (files.length !== 1 || flags.some((f) => !["--json", "--digest"].includes(f))) { console.error(USAGE); return 2; }
+  let receipt;
+  try { receipt = JSON.parse(readFileSync(files[0], "utf8")); }
+  catch (e) { console.error(`Cannot read ${files[0]}: ${e.message}`); return 2; }
+  if (flags.includes("--digest")) {
+    if (typeOf(receipt) !== "object") { console.error("Not a receipt."); return 2; }
+    console.log(digestOf(receipt));
+    return 0;
+  }
+  const result = verifyReceipt(receipt);
+  if (flags.includes("--json")) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(result.valid ? `VALID    ${files[0]}` : `INVALID  ${files[0]}`);
+    for (const e of result.errors) console.log(`  error    ${e}`);
+    for (const w of result.warnings) console.log(`  warning  ${w}`);
+  }
+  return result.valid ? 0 : 1;
+}
+
+/** Run as a program, and not imported: true through a symlink too, which is how an installed command arrives. */
+function isMain() {
+  if (!process.argv[1]) return false;
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+}
+
+if (isMain()) process.exit(main(process.argv.slice(2)));