diff --git a/README.md b/README.md index 9059b96..bd5ff1c 100644 --- a/README.md +++ b/README.md @@ -325,9 +325,13 @@ pnpm validate ``` `pnpm validate` typechecks, builds the deterministic release, runs the source and -adversarial release tests, verifies the result byte-for-byte against the exact -published website artifact recorded in `release-reference.json`, and exercises a -clean global install. +adversarial release tests, verifies the rebuilt artifact byte-for-byte against the +packed archive, and exercises a clean global install. Note that this checks the +build against itself: it proves the release is reproducible from this source, not +that it matches a digest pinned elsewhere. `release-reference.json` records the +published digests but nothing reads it, so it is documentation rather than a +control. To check a release against an independent record, use the attestation +below. Verify a downloaded release yourself: diff --git a/docs/RELEASE.md b/docs/RELEASE.md index 33ae114..aef4ace 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -7,9 +7,11 @@ account, npm token, package access, or npm environment approval. ## GitHub release 1. Confirm CI is green on `main` and the package version and changelog are final. - Update `release-reference.json` from the immutable website candidate. The - verifier rejects any archive, SBOM, or executable digest that differs from - that checked-in reference. + Update `release-reference.json` from the immutable website candidate. This + is a checked-in record of the released digests, not an enforced control: no + script or workflow reads it today, so it can drift without anything failing + (it sat a full release stale before this was noticed). Treat it as + documentation until the verifier is changed to require it. 2. Create and push the matching annotated tag, for example `v0.2.30` for package version `0.2.30`. 3. `.github/workflows/release.yml` installs the locked dependency graph, runs