@letthembuild/run-receipts 0.0.0-stage → 0.2.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/PRODUCERS.md

@@ -0,0 +1,192 @@
+# Writing receipts from your own tool
+
+This guide is for anyone whose tool runs a model to do work and other models to review it, and who wants that tool to write a run receipt when a run ends. [SPEC.md](SPEC.md) is the definition; this is the practical route through it.
+
+You do not need any code from this repository to write a receipt. A receipt is one JSON file. You do need the verifier to check what you wrote, and you should never write a receipt that does not verify.
+
+## The smallest valid receipt
+
+One seat did some work, nobody reviewed it and nothing was run:
+
+```json
+{
+  "receiptVersion": "0.1",
+  "producer": { "name": "your-tool" },
+  "endedAt": "2026-11-12T09:30:00Z",
+  "durationMs": 4200,
+  "tokens": 1800,
+  "costUsd": 0.01,
+  "seats": [
+    { "name": "Builder", "role": "lead", "model": "model-a", "turns": 1, "errors": 0, "timeouts": 0, "durationMs": 4200, "costUsd": 0.01 }
+  ],
+  "verdict": null,
+  "checks": [],
+  "totals": { "reviewers": 0, "verifiers": 0, "ran": 0, "passed": 0, "failed": 0, "failingNow": 0, "contradicted": 0 },
+  "grade": "unverified",
+  "gaps": ["Nobody reviewed this run"]
+}
+```
+
+It is valid, and its grade is the honest one: `unverified`. Everything below is about earning a better grade truthfully.
+
+## What to record while the run is going
+
+A receipt is written at the end, from things you can only know during the run. Collect these as they happen:
+
+| Record | When | Becomes |
+|---|---|---|
+| Each seat's name, role and model | When the run starts | `seats` |
+| For each seat: answers completed, attempts that failed, how many of those were timeouts, time spent, metered cost | As each attempt ends | `turns`, `errors`, `timeouts`, `durationMs`, `costUsd` |
+| For each reviewer: where it ended | When the run ends | `stance` |
+| Every command a reviewer ran to test the work: who ran it, the command, its exit code, one line of output | As each command exits | `checks` and `totals` |
+| Whether you could see a reviewer's commands at all | When the run starts | `commandsVisible` |
+| How many files the lead changed, if you can measure it | When the run ends | `totals.filesChanged` |
+| What nobody verified | When the run ends | `gaps` |
+
+If you cannot observe something, say so in the receipt and do not guess. A reviewer working inside a tool whose commands you cannot see gets `commandsVisible: false`, not a made-up list of checks. An exit code you did not see is `null` with state `unknown`, not `0`.
+
+## A worked example
+
+[examples/produce.mjs](examples/produce.mjs) is a complete producer, short enough to read in one sitting. It takes a run as a tool might hold it (seats, the commands reviewers ran in order, and the gaps) and returns a receipt. Run it:
+
+```bash
+node examples/produce.mjs
+```
+
+Read it alongside the sections below. It is written to be adapted, in any language; nothing in it is specific to JavaScript except the two helpers it borrows from the verifier, `gradeOf` and `digestOf`, both of which are a few lines you can re-implement from SPEC.md.
+
+## Counting: the rules that catch people out
+
+Most invalid receipts come from totals that do not match the seats. These are the ones to get right.
+
+**Totals count reviewers' commands, not the lead's.** `ran`, `passed` and `failed` are the commands run *to test the work*, by reviewers that answered. The lead running its own tests while building is not a check of the work by somebody else. Rule T5 holds you to this: `ran` is above 0 exactly when at least one reviewer is counted in `verifiers`.
+
+**Each run of a command counts.** A command run twice is two in `ran`. If it failed and then passed, that is one in `failed`, one in `passed`, zero in `failingNow` and one in `resolved`. In `checks` it appears once, as it stood at the end.
+
+**`totals.reviewers` is the reviewers that answered.** A reviewer whose stance is `unavailable` is a seat, appears in `seats` and in the verdict's holdouts, and is not counted in `totals.reviewers`.
+
+**The verdict counts differently depending on its outcome.** When the outcome is `agreed`, `verdict.reviewers` is the reviewers that answered. Otherwise it is all reviewers, including unavailable ones. An absent reviewer cannot block agreement among those who answered, but it also cannot be left out of a count that fell short.
+
+**`agreed` has a condition when somebody was missing.** If any reviewer was unavailable, the outcome may be `agreed` only when nothing is failing at the end. You may always record less agreement than the rules allow; you may never record more.
+
+**A reviewer that agreed while its own check was failing is `contradicted`.** Its stance stays `agreed`, it is counted in `totals.contradicted`, and that alone makes the grade `failed`.
+
+**Do not choose the grade. Work it out.** The grade is the first of these that applies to your totals:
+
+| Grade | When |
+|---|---|
+| `failed` | `failingNow` or `contradicted` is above 0 |
+| `verified` | `ran` is above 0 and every reviewer that answered ran something |
+| `partial` | `ran` is above 0 and some reviewer that answered ran nothing |
+| `reviewed` | nothing was run and `filesChanged` is 0 |
+| `not-visible` | nothing was run and every reviewer that answered worked out of view |
+| `unverified` | anything else |
+
+Leave `filesChanged` out when you did not measure it. Writing `0` claims you measured and found none, and turns an unverified change into `reviewed`.
+
+## Each check
+
+| Situation | `exitCode` | `state` | `missingSetup` |
+|---|---|---|---|
+| Ran and exited 0 | `0` | `checked` | `null` |
+| Ran and exited non-zero | the code | `reproduced` | `null` |
+| Could not run for want of something (a service, a credential, a tool) | the code, or `null` | `blocked` | what was missing, in a few words |
+| Ran, and you never saw how it ended | `null` | `unknown` | `null` |
+| Named by a seat and never run | `null` | `untested` | `null` |
+
+`where` is one of `local`, `ci`, `cloud` or `other`. It is a category on purpose: never write a machine name there. `deployed` is true only when the command reached the place the work actually runs, such as a request to the live service; a test suite on a laptop is `false`.
+
+## What must stay out
+
+A tool that runs models holds prompts, replies, file contents, account details and full command output. None of it belongs in a receipt, and the schema rejects unknown fields so that none can be added by accident. Three places still take free text from the run, and they are yours to make safe:
+
+- **`command`**: mask credentials (`API_TOKEN=***`), and replace home folders with `~`. At most 300 characters, one line.
+- **`result`**: one line of output, at most 200 characters, masked the same way. Never the whole output.
+- **`gaps` and `purpose`**: short statements you compose. Do not paste a model's reply into them.
+
+Also: make `id` opaque. A random identifier is right; your internal conversation or job id, or anything derived from it, links a public file to a private record.
+
+The masking in the example is a starting point. You know what your users' secrets look like better than a generic pattern does.
+
+## Digest, verify, sign if you can, then write
+
+1. Build the whole receipt without `digest`.
+2. Take the digest: SHA-256 over the receipt serialised as JSON with object keys sorted at every level and no whitespace, written as `sha256:` and lower-case hex. Add it as `digest`.
+3. Verify the result. If it does not verify, do not write it: fix the producer.
+4. Sign it, if your tool has a key worth signing with. See "Signing" below.
+
+In JavaScript, with the package:
+
+```js
+import { verifyReceipt, digestOf } from "@letthembuild/run-receipts";
+
+receipt.digest = digestOf(receipt);
+const { valid, errors } = verifyReceipt(receipt);
+if (!valid) throw new Error(errors.join("\n"));
+```
+
+In any other language, write the file and check it in your own tests with the command line:
+
+```bash
+npx @letthembuild/run-receipts receipt.json
+```
+
+Number formatting is where digests written in other languages go wrong: the canonical form writes numbers as JavaScript's `JSON.stringify` does, so `0.10` is `0.1` and `2.0` is `2`. Test your digest against the two receipts in [examples/](examples), which carry theirs.
+
+## Signing
+
+Signing is optional, and an unsigned receipt is a complete receipt. Sign when a reader needs to know that a receipt came from you and was not rewritten on the way.
+
+```js
+import { signReceipt } from "@letthembuild/run-receipts/sign";
+
+const signed = signReceipt(receipt, signingKey); // { key, secret }, as `sign.mjs keygen` writes it
+```
+
+In another language: sign the UTF-8 bytes of `run-receipt-signature-v1`, a line feed, and the digest string, with Ed25519, and add `{ "key": "ed25519:<public key, base64url>", "sig": "<signature, base64url>" }` to `signatures`. Both are unpadded.
+
+Before you add signing, decide where the key lives, because that decides what your signature is worth:
+
+| Where the key is | What a signature from it shows |
+|---|---|
+| On a build server or service you run, never given out | The receipt came from your service. The strongest claim you can make. |
+| Made on each user's machine, one key per installation | The receipt came from that installation and was not edited since. The user publishes their own key to whoever needs to trust it. |
+| One key built into the application you ship | Only that the receipt came from some copy of your application. Anyone with the application can extract the key, so do not present this as your signature. |
+
+Publish your public key somewhere readers already trust, such as your documentation over HTTPS, and say which of the three it is. Never put a name in a receipt to say who signed: the format has no field for it, on purpose.
+
+## Where the file goes
+
+The format does not say. Two conventions work well:
+
+- **Beside the work.** Write it into the project, in a folder of its own such as `receipts/`, named so that files sort by time: `run-receipt-20261112-093000-verified.json`. Whether it is committed is the person's choice; do not commit it for them.
+- **On the pull request.** A receipt committed with a change can be verified and shown to reviewers by the GitHub Action in this repository. See [README.md](README.md#verify-receipts-on-pull-requests).
+
+Write a receipt for every run, including the ones that went badly. A tool that only writes receipts for good runs has made the grade meaningless.
+
+## When the verifier says no
+
+| Rule | Usual cause |
+|---|---|
+| `schema: ... is not part of the format` | You added a field. Unknown fields are not allowed, by design. |
+| S4 | A reviewer has no `stance`, or the lead has one. |
+| S5 | A seat on a flat subscription carries a cost. Its `costUsd` is 0. |
+| V3 | `holdouts` is missing a reviewer that did not agree, or lists one with the wrong stance. |
+| V4, V5 | The verdict was chosen instead of worked out from the stances. |
+| T1 | `totals.reviewers` counts an unavailable reviewer. |
+| T5 | The lead's commands were counted, or commands were counted from a reviewer that is not counted as answering. |
+| G1 | The grade was chosen instead of worked out from the totals. |
+| C2 | A check exited 0 with a state other than `checked`. |
+| C3 | `blocked` without `missingSetup`, or `missingSetup` on a check that is not blocked. |
+| D1 | The receipt was changed after its digest was taken, or the canonical form is not quite right. |
+| K1 | The receipt was changed after it was signed, or the signature was made over something other than the context line and the digest. |
+
+## Before you ship
+
+- [ ] Every receipt your tool writes is verified first, and an invalid one is never written.
+- [ ] Your tests build a receipt for a run that agreed, one that did not, one with a failing check, one where nothing was run, and one with a reviewer that never answered.
+- [ ] No prompt, reply, file content or account detail can reach a receipt. Test it with a run that contains a recognisable secret and search the receipt for it.
+- [ ] `producer.name` is your tool's own name, and `producer.version` its version.
+- [ ] Receipts are written for bad runs as well as good ones.
+
+If something in the format stops you from describing a run truthfully, that is a problem with the format. Please open an issue.

package/README.md

@@ -1,3 +1,217 @@
-# 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.
+- **[sign.mjs](sign.mjs)**: makes a signing key and signs a receipt with it.
+- **[PRODUCERS.md](PRODUCERS.md)**: how to write receipts from your own tool, with a worked example.
+- **[action.yml](action.yml)**: a GitHub Action that verifies the receipts a pull request carries and reports them.
+- **[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.
+
+Maintained by GPULogy AI LLC, the makers of [LetThemBuild](https://letthembuild.com), an app where several AI models do the work and review each other. Run receipts began as its record of what a run actually checked.
+
+## 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. |
+| `verify.mjs --keys <list> <file>` | Also say whether each signature is from a key on your list. |
+| `verify.mjs --keys <list> --require-signature <file>` | Not valid unless a key on your list signed it. |
+
+The verifier is also a module:
+
+```js
+import { verifyReceipt } from "./verify.mjs";
+
+const { valid, errors, warnings } = verifyReceipt(receipt);
+```
+
+## Sign a receipt, and check who signed
+
+A digest shows that a receipt was not edited by accident. Anyone who edits one on purpose can retake the digest. A signature closes that: it shows that the holder of a particular key signed exactly this receipt.
+
+Make a key once. The file it writes is the signing key; keep it out of your repository. The line it prints is the public key, which is what you give to readers:
+
+```bash
+node sign.mjs keygen signing-key.json
+```
+
+```
+ed25519:Qm3v...
+```
+
+Sign a receipt where it is:
+
+```bash
+node sign.mjs sign --key signing-key.json --write receipt.json
+```
+
+A reader keeps a list of the keys they trust, one to a line, each with their own name for it:
+
+```
+ed25519:Qm3v... Release builds
+```
+
+```bash
+node verify.mjs --keys trusted-keys.txt --require-signature receipt.json
+```
+
+```
+VALID    receipt.json
+  signed   Release builds (ed25519:Qm3v...)
+```
+
+On a build server, put the contents of the key file in a secret and pass it as `RUN_RECEIPT_SIGNING_KEY` instead of `--key`.
+
+A receipt carries keys, never names: the name shown is always the reader's own. A signature from a key that is not on your list tells you somebody signed, and nothing about who. And a key is only as good as its keeping. One that lives on a build server supports a strong claim; one shipped inside an app on its users' machines can be extracted by any of them. [SPEC.md](SPEC.md#signatures) says exactly what a signature does and does not mean.
+
+## Verify receipts on pull requests
+
+The GitHub Action checks every receipt a pull request carries, and puts the grade, the checks that were run and what nobody verified where a reviewer will see them: in a comment on the pull request and in the job summary.
+
+```yaml
+name: run receipts
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  receipts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gpulogyai/run-receipts@v0
+        with:
+          path: receipts
+```
+
+The job fails when a receipt does not verify. A receipt that verifies and is graded `failed` is an honest report of a bad result, so by default it is shown and the job passes; name the grades you will not accept to change that.
+
+| Input | Default | What it does |
+|---|---|---|
+| `path` | required | Files or folders, one per line. A folder stands for every `.json` file inside it. |
+| `comment` | `true` | Post the report on the pull request. One comment, updated on each run. |
+| `fail-on-grade` | none | Grades that fail the job, separated by commas: `failed`, `unverified`, `not-visible`, `reviewed`, `partial`, `verified`. |
+| `if-no-receipt` | `warn` | What to do when the path holds no receipt: `error`, `warn` or `ignore`. |
+| `trusted-keys` | none | The keys this workflow trusts to sign receipts, one to a line, each followed by your name for it. |
+| `require-signature` | `false` | Fail the job unless every receipt is signed by a trusted key. |
+| `token` | the job's token | The token the comment is posted with. |
+
+| Output | What it holds |
+|---|---|
+| `count` | How many receipts were checked. |
+| `valid` | `true` when at least one was checked and every one verified. |
+| `grade` | The grade, when exactly one receipt was checked and it verified. |
+| `grades` | The grades of the receipts that verified, separated by commas. |
+| `signed` | `true` when every receipt verified and was signed by a trusted key. |
+
+To accept only receipts signed by keys you trust, list the keys in the workflow or in a repository variable. Do not read them from a file in the pull request: the pull request could change it.
+
+```yaml
+      - uses: gpulogyai/run-receipts@v0
+        with:
+          path: receipts
+          require-signature: true
+          trusted-keys: |
+            ed25519:Qm3v... Release builds
+```
+
+Three things to know:
+
+- **Pull requests from forks.** Their token cannot write, so the comment is skipped with a warning and the report is in the job summary. Keep the trigger as `pull_request`. Do not switch to `pull_request_target` to get the comment: that runs with your repository's permissions on a stranger's files.
+- **A receipt's text is treated as untrusted.** Names, commands and results are shown as plain text: they cannot add formatting, links or mentions to the comment, and they cannot issue commands to the runner.
+- **Requirements.** Node 18 or later on the runner, which GitHub's hosted runners have. The action installs nothing and makes no network call other than posting its comment.
+
+## 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. When it is signed, verifying also says which keys signed it and whether they are keys you listed.
+
+Verifying does **not** prove that the commands were really run or that they exited as stated. A receipt is the producer's own account. A signature from a key you trust tells you whose account it is, not that the account is true.
+
+## Roadmap
+
+Not yet:
+
+- **A published list of well-known producers' keys**, so a reader does not have to collect them by hand.
+- **Signing by identity instead of a kept key**, for build servers that can prove who they are.
+
+## 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.