@letthembuild/run-receipts 0.1.0 → 0.2.0

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

@@ -9,10 +9,15 @@ 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
@@ -73,6 +78,8 @@ INVALID  edited.json
 | `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:
 
@@ -82,19 +89,118 @@ 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.
+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. Trusting a receipt you did not produce needs a signature, which version 0.1 leaves out.
+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 in 0.1:
+Not yet:
 
-- **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.
+- **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
 

package/SPEC.md

@@ -8,7 +8,7 @@ Several models agreeing on an answer is not evidence that the answer is right. A
 
 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".
+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
 
@@ -43,6 +43,7 @@ A receipt is one JSON object, UTF-8. `receipt.schema.json` is the normative shap
 | `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
 
@@ -166,21 +167,51 @@ A producer may record `majority` or `none` where V4 would allow `agreed`: a run
 - 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` 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.
+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.
 
-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.
+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
 

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,6 @@
 {
   "name": "@letthembuild/run-receipts",
-  "version": "0.1.0",
+  "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",
@@ -16,15 +16,20 @@
   "main": "./verify.mjs",
   "exports": {
     ".": "./verify.mjs",
+    "./sign": "./sign.mjs",
     "./schema": "./receipt.schema.json"
   },
   "bin": {
-    "run-receipt-verify": "./verify.mjs"
+    "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"
   ],
@@ -32,7 +37,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test verify.test.mjs"
+    "test": "node --test verify.test.mjs sign.test.mjs action.test.mjs produce.test.mjs"
   },
   "keywords": [
     "receipt",

package/receipt.schema.json

@@ -30,9 +30,19 @@
     "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}$" }
+    "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",

package/sign.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// Copyright 2026 GPULogy AI LLC
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Sign a run receipt, and make the key to sign with.
+ *
+ * A signature says one thing: whoever holds this key put their name to this
+ * receipt, and it has not changed since. It does not say the commands were
+ * run. What a signature is worth is what the key is worth: who holds it, and
+ * how hard it is for anyone else to.
+ *
+ * No dependencies: Node 18 or later, and verify.mjs beside this file.
+ */
+import { readFileSync, writeFileSync, realpathSync, existsSync } from "node:fs";
+import { generateKeyPairSync, createPrivateKey, sign as signBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { digestOf, signedBytes, verifyReceipt, publicKeyOf } from "./verify.mjs";
+
+/** A new key pair: `key` is public and goes in receipts and trust lists; `secret` signs and goes nowhere. */
+export function generateKey() {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const jwk = privateKey.export({ format: "jwk" });
+  return { key: `ed25519:${jwk.x}`, secret: jwk.d };
+}
+
+/** The signing key Node needs, from a { key, secret } pair. Throws when they are not a pair. */
+function privateKeyOf(pair) {
+  const x = /^ed25519:([A-Za-z0-9_-]{43})$/.exec(String(pair?.key ?? ""))?.[1];
+  if (!x || !/^[A-Za-z0-9_-]{43}$/.test(String(pair?.secret ?? ""))) throw new Error("not a signing key");
+  if (!publicKeyOf(pair.key)) throw new Error("not a signing key");
+  try { return createPrivateKey({ key: { kty: "OKP", crv: "Ed25519", x, d: pair.secret }, format: "jwk" }); }
+  catch { throw new Error("not a signing key"); }
+}
+
+/**
+ * The receipt, signed: its digest retaken, and this key's signature added in
+ * place of any earlier one from the same key. Other keys' signatures are kept
+ * only while they still hold. Refuses a receipt that does not verify: a
+ * signature on a broken receipt would put a name to nothing.
+ */
+export function signReceipt(receipt, pair) {
+  const key = privateKeyOf(pair);
+  const { signatures: before = [], ...rest } = receipt;
+  const unsigned = { ...rest, digest: digestOf(rest) };
+  const check = verifyReceipt(unsigned);
+  if (!check.valid) throw new Error(`the receipt does not verify, so it is not signed:\n${check.errors.join("\n")}`);
+  const sig = signBytes(null, signedBytes(unsigned.digest), key).toString("base64url");
+  const kept = before.filter((s) => s.key !== pair.key && verifyReceipt({ ...unsigned, signatures: [s] }).valid);
+  const signed = { ...unsigned, signatures: [...kept, { key: pair.key, sig }] };
+  const after = verifyReceipt(signed);
+  if (!after.valid) throw new Error("the key's two halves do not belong together");
+  return signed;
+}
+
+/* ── Command line ────────────────────────────────────────────────────── */
+
+const USAGE = `Usage:
+  sign.mjs keygen <key-file>                  make a signing key; prints the public half
+  sign.mjs sign --key <key-file> <receipt>    print the receipt, signed
+  sign.mjs sign --key <key-file> --write <receipt>   sign it where it is
+
+The key can also come from the environment, for a build server:
+  RUN_RECEIPT_SIGNING_KEY   the contents of a key file`;
+
+function readPair(file, env) {
+  const text = file ? readFileSync(file, "utf8") : env.RUN_RECEIPT_SIGNING_KEY;
+  if (!text) throw new Error("no signing key: pass --key <key-file> or set RUN_RECEIPT_SIGNING_KEY");
+  return JSON.parse(text);
+}
+
+export function main(argv, env = process.env) {
+  const [command, ...rest] = argv;
+  if (command === "keygen") {
+    if (rest.length !== 1 || rest[0].startsWith("--")) { console.error(USAGE); return 2; }
+    if (existsSync(rest[0])) { console.error(`${rest[0]} exists. A key is not overwritten: receipts signed with it would have nobody to answer for them.`); return 2; }
+    const pair = generateKey();
+    writeFileSync(rest[0], JSON.stringify(pair, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+    console.log(pair.key);
+    console.error(`The signing key is in ${rest[0]}. Keep it out of your repository. Give readers the line above.`);
+    return 0;
+  }
+  if (command === "sign") {
+    const args = [...rest];
+    let keyFile = null;
+    const at = args.indexOf("--key");
+    if (at !== -1) { keyFile = args[at + 1] ?? null; args.splice(at, 2); if (!keyFile) { console.error(USAGE); return 2; } }
+    const write = args.includes("--write");
+    const files = args.filter((a) => !a.startsWith("--"));
+    if (files.length !== 1 || args.some((a) => a.startsWith("--") && a !== "--write")) { console.error(USAGE); return 2; }
+    let receipt, pair;
+    try { receipt = JSON.parse(readFileSync(files[0], "utf8")); }
+    catch (e) { console.error(`Cannot read ${files[0]}: ${e.message}`); return 2; }
+    try { pair = readPair(keyFile, env); }
+    catch (e) { console.error(`Cannot read the signing key: ${e.message}`); return 2; }
+    let signed;
+    try { signed = signReceipt(receipt, pair); }
+    catch (e) { console.error(e.message); return 1; }
+    const text = JSON.stringify(signed, null, 2) + "\n";
+    if (write) { writeFileSync(files[0], text); console.error(`Signed ${files[0]} as ${pair.key}`); }
+    else process.stdout.write(text);
+    return 0;
+  }
+  console.error(USAGE);
+  return 2;
+}
+
+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)));

package/verify.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Run-receipt verifier, v0.1.
+ * Run-receipt verifier, for format 0.1.
  *
  * Answers one question about a receipt file: does it hold together? First
  * against the schema (shape, bounds), then against itself (the rules in
@@ -9,12 +9,13 @@
  *
  * 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.
+ * carries a digest, unaltered since the digest was taken. When it is signed,
+ * it also says which keys signed it, and whether you listed them as trusted.
  *
  * 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 { createHash, createPublicKey, verify as verifyBytes } from "node:crypto";
 import { fileURLToPath } from "node:url";
 
 const SCHEMA_URL = new URL("./receipt.schema.json", import.meta.url);
@@ -73,7 +74,7 @@ export function validateSchema(value, schema, root = schema, path = "$") {
 
 /* ── Digest ──────────────────────────────────────────────────────────── */
 
-/** The receipt as bytes to hash: keys sorted, no whitespace, `digest` left out. */
+/** The receipt as bytes to hash: keys sorted, no whitespace, `digest` and `signatures` 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(",")}]`;
@@ -81,10 +82,71 @@ export function canonical(value) {
 }
 
 export function digestOf(receipt) {
-  const { digest: _left_out, ...rest } = receipt;
+  const { digest: _left_out, signatures: _nor_these, ...rest } = receipt;
   return `sha256:${createHash("sha256").update(canonical(rest), "utf8").digest("hex")}`;
 }
 
+/* ── Signatures ──────────────────────────────────────────────────────── */
+
+/** What a signature is made over: these words, then the receipt's digest. The words keep a signature made for a receipt from being one for anything else. */
+export const SIGNATURE_CONTEXT = "run-receipt-signature-v1\n";
+export const signedBytes = (digest) => Buffer.from(SIGNATURE_CONTEXT + digest, "utf8");
+
+const KEY_FORM = /^ed25519:([A-Za-z0-9_-]{43})$/;
+
+/** A public key as Node holds it, from its written form, or null when it is not one. */
+export function publicKeyOf(key) {
+  const m = KEY_FORM.exec(String(key ?? ""));
+  if (!m) return null;
+  try { return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: m[1] }, format: "jwk" }); }
+  catch { return null; }
+}
+
+/** True when `signature` is its key's signature over this receipt as it stands. */
+export function signatureHolds(receipt, signature) {
+  const key = publicKeyOf(signature?.key);
+  if (!key || typeof signature.sig !== "string") return false;
+  try { return verifyBytes(null, signedBytes(digestOf(receipt)), key, Buffer.from(signature.sig, "base64url")); }
+  catch { return false; }
+}
+
+/**
+ * A list of keys somebody trusts, from text: either JSON,
+ * { "keys": [{ "key": "ed25519:…", "name": "…" }] }, or one key to a line with
+ * an optional name after it. Lines starting with # are comments. The names are
+ * the reader's own words for each key; a receipt never supplies them.
+ */
+export function parseKeys(text) {
+  const src = String(text ?? "").trim();
+  const keys = [], problems = [];
+  const add = (key, name, where) => {
+    if (!publicKeyOf(key)) problems.push(`${where}: not a key`);
+    else if (!keys.some((k) => k.key === key)) keys.push({ key, name: String(name ?? "").trim().slice(0, 80) });
+  };
+  if (src.startsWith("{")) {
+    let doc;
+    try { doc = JSON.parse(src); } catch { return { keys, problems: ["the key list is not readable as JSON"] }; }
+    if (!Array.isArray(doc?.keys)) return { keys, problems: ["the key list has no keys"] };
+    doc.keys.forEach((k, i) => add(k?.key, k?.name, `keys[${i}]`));
+  } else {
+    src.split(/\r?\n/).forEach((raw, i) => {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) return;
+      const [key, ...name] = line.split(/\s+/);
+      add(key, name.join(" "), `line ${i + 1}`);
+    });
+  }
+  return { keys, problems };
+}
+
+/** Who signed a receipt: each key whose signature holds, with the reader's name for it when they listed it. */
+export function signersOf(receipt, trustedKeys = []) {
+  return (receipt.signatures ?? []).filter((s) => signatureHolds(receipt, s)).map((s) => {
+    const known = trustedKeys.find((k) => k.key === s.key);
+    return { key: s.key, trusted: Boolean(known), name: known?.name ?? "" };
+  });
+}
+
 /* ── Consistency: the rules of SPEC.md, by number ────────────────────── */
 
 /** The grade the totals earn (SPEC rule G). */
@@ -179,15 +241,30 @@ export function checkConsistency(r) {
   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");
 
+  // K — signatures.
+  const signed = r.signatures ?? [];
+  if (new Set(signed.map((s) => s.key)).size !== signed.length) err("K2", "one key signed twice");
+  signed.forEach((s, i) => { if (!signatureHolds(r, s)) err("K1", `signatures[${i}]: is not that key's signature over this receipt`); });
+
   return { errors, warnings };
 }
 
 /** Schema first; the consistency rules only run on a receipt with the right shape. */
-export function verifyReceipt(receipt) {
+/**
+ * `signers` lists the keys whose signatures hold, and is empty for a receipt
+ * that is not valid. Pass `trustedKeys` (as parseKeys returns them) to have
+ * each marked as one you listed. With `requireSignature`, a receipt no listed
+ * key has signed is not valid.
+ */
+export function verifyReceipt(receipt, { trustedKeys = [], requireSignature = false } = {}) {
   const schemaErrors = validateSchema(receipt, loadSchema());
-  if (schemaErrors.length) return { valid: false, errors: schemaErrors.map((e) => `schema: ${e}`), warnings: [] };
+  if (schemaErrors.length) return { valid: false, errors: schemaErrors.map((e) => `schema: ${e}`), warnings: [], signers: [] };
   const { errors, warnings } = checkConsistency(receipt);
-  return { valid: errors.length === 0, errors, warnings };
+  const signers = errors.length ? [] : signersOf(receipt, trustedKeys);
+  if (requireSignature && !errors.length && !signers.some((s) => s.trusted)) {
+    errors.push(signers.length ? "K3: signed, but by no key on the trusted list" : "K3: not signed, and a signature from a trusted key is required");
+  }
+  return { valid: errors.length === 0, errors, warnings, signers: errors.length ? [] : signers };
 }
 
 /* ── Command line ────────────────────────────────────────────────────── */
@@ -195,12 +272,33 @@ export function verifyReceipt(receipt) {
 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`;
+  verify.mjs --digest <receipt.json>   print the digest the receipt should carry
+
+Signatures:
+  --keys <file>          the keys you trust: JSON, or one "ed25519:… name" to a line
+  --require-signature    not valid unless a key from --keys signed it`;
+
+/** A key as people read it: enough of it to tell two apart. */
+export const shortKey = (key) => `${String(key).slice(0, 16)}…`;
 
 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; }
+  const args = [...argv];
+  let keysFile = null;
+  const at = args.indexOf("--keys");
+  if (at !== -1) { keysFile = args[at + 1] ?? null; args.splice(at, 2); if (!keysFile || keysFile.startsWith("--")) { console.error(USAGE); return 2; } }
+  const flags = args.filter((a) => a.startsWith("--"));
+  const files = args.filter((a) => !a.startsWith("--"));
+  if (files.length !== 1 || flags.some((f) => !["--json", "--digest", "--require-signature"].includes(f))) { console.error(USAGE); return 2; }
+  const requireSignature = flags.includes("--require-signature");
+  let trustedKeys = [];
+  if (keysFile) {
+    let parsed;
+    try { parsed = parseKeys(readFileSync(keysFile, "utf8")); }
+    catch (e) { console.error(`Cannot read ${keysFile}: ${e.message}`); return 2; }
+    if (parsed.problems.length) { console.error(`${keysFile}: ${parsed.problems.join("; ")}`); return 2; }
+    trustedKeys = parsed.keys;
+  }
+  if (requireSignature && !trustedKeys.length) { console.error("--require-signature needs --keys: a signature only means something from a key you trust."); return 2; }
   let receipt;
   try { receipt = JSON.parse(readFileSync(files[0], "utf8")); }
   catch (e) { console.error(`Cannot read ${files[0]}: ${e.message}`); return 2; }
@@ -209,12 +307,13 @@ function main(argv) {
     console.log(digestOf(receipt));
     return 0;
   }
-  const result = verifyReceipt(receipt);
+  const result = verifyReceipt(receipt, { trustedKeys, requireSignature });
   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}`);
+    for (const s of result.signers) console.log(s.trusted ? `  signed   ${s.name || "a trusted key"} (${shortKey(s.key)})` : `  signed   ${shortKey(s.key)}, which ${keysFile ? "is not on your list" : "nothing here vouches for (pass --keys)"}`);
   }
   return result.valid ? 0 : 1;
 }