Release hygiene: one version, one Node line, every env var written down

[Apolloccrypt]

Points 1, 2, 8 and 9 from the toekomstbestendigheid report of 2026-09-02. Only
the parts that need no product decision. No tag, no deploy: those belong
together, and docs/RELEASE.md says so.

9. Versions: four places, three answers

Measured before: root package.json 3.1.0, relay/package.json 3.0.0,
admin/package.json 0.9.0-beta, relay image label 3.0.0, admin image label
1.0.0, a VERSION literal in relay.js reading 3.1.0, and
scripts/post-deploy-verify.sh asserting that /health returns 3.0.0 while
the relay already answered 3.1.0. The one check that could have caught the
drift was part of it.

Now the root package.json is the version and nothing else states it:

• relay.js does require('./package.json').version, and the runtime stage of
  relay/Dockerfile copies package.json in for exactly that read.
• Both Dockerfiles label from ARG IMAGE_VERSION, defaulted to the same
  string. docker-publish.yml passes the tag on a tagged build and the
  package.json version on main, so the label is never a short sha.
• post-deploy-verify.sh reads relay/package.json into EXPECT_VER.
• Admin moves from 0.9.0-beta to the project version.

tests/version-consistency.test.mjs (8 checks) fails the build the next time
any copy drifts, so the list does not have to be remembered.

Verified end to end, not just on paper: the production Dockerfile builds, the
image carries org.opencontainers.image.version=3.1.0, and a relay booted from
it answers {"ok":true,"version":"3.1.0","sector":"relay",...} on /health.

2. Node: two of the three versions were end of life

	before	after
relay and admin image	node:25-alpine3.21 (EOL)	node:24-alpine3.24
CI, all 7 job steps	20 (EOL)	24
devcontainer	20	24
engines	absent	>=22 <25
.nvmrc	absent	24

Node 24 is the newest LTS line. >=22 <25 is exactly the two lines still
getting security fixes: it keeps a Node 22 dev machine (the NUC) working while
blocking 20, 23 and 25, all end of life, and it makes adopting Node 26 a
deliberate bump rather than an accident.

Alpine 3.24 is a second, unplanned win: the crypto binding is compiled in the
rust:1.98-alpine stage, which is Alpine 3.24. It was being loaded on a 3.21
runtime. Those now match.

Proof, run locally rather than asserted: all three suites under
node:24-alpine (Node 24.20.0) and a full build of relay/Dockerfile
including the liboqs/musl chain.

8. Environment variables: 40 of 57 documented nowhere

deploy/.env.example documented three names. relay.js, relay/lib and the
admin panel read 57, and 40 of them appeared in neither .env.example.

It now documents 77: all 72 that the relay or admin reads, plus 5 that
docker-compose.yml or install.sh consumes. Each entry says what the
variable does, whether it is required or optional, its default, and the file
that reads it. Grouped by area, generated from the code and then written by
hand.

tests/env-documented.test.mjs holds the line in both directions:

• E1 a process.env name with no entry fails the build (verified by adding
  one and watching it go red),
• E2 an entry that nothing reads fails too, unless it is in
  NOT_READ_BY_NODE with a stated reason,
• E3 that allowlist cannot outlive its reason,
• E4 every entry carries a read in: line,
• E5 the header count matches reality.

The extractor also catches env.X in the modules that take an injectable env
object (developer-gate, webauthn, entitlements), which a plain
process.env grep misses. DEVELOPER_ALLOWLIST and NODE_ENV are documented
because of it.

Two honest findings that fell out of the sweep, written into the file rather
than fixed here: LOG_LEVEL and ADMIN_TOTP_SECRET are passed to the relays
by docker-compose.yml and read by nothing. Removing them from the compose
file is a change to the running stack, not a documentation fix.

1. Release process

docs/RELEASE.md: what a version number means, cutting a release in nine
steps, rolling back, and a section on what is still not automated. It names the
gap between docker-publish.yml (which pushes images) and
docs/RUNBOOK-DEPLOY-3.0.0.md (which says there is no registry) instead of
pretending it is closed, and defers that to a deploy-time decision.

CHANGELOG.md gets a ## [3.1.0] - unreleased section covering the 268
commits since v3.0.0, grouped into Security, Added, Changed, Fixed, Removed,
and Build/CI/dependencies, with PR numbers where a commit carried one. One
trap, documented in RELEASE.md so the next person does not fall in it: a
trailing (#nn) is not always a PR. #19 and #21 in this range are security
findings, and PR #21 is an unrelated dependabot bump. Checked with gh pr view
before writing them down.

The existing [Unreleased] body is folded into the 3.1.0 section unchanged,
with the reason stated: the CHANGELOG's 3.0.0 section is dated 2026-05-27 and
the v3.0.0 tag was cut on 2026-06-24, so that backlog never had a released
section to go to. Rewriting it would be guessing at what it meant.

docs/PROJECT-STATUS.md declared itself obsolete in its own second line on
2026-05-27 and kept being cited by three other documents. It is now a pointer
table to the CHANGELOG, RELEASE.md, DEPLOY-3.1.md and gh pr list. The five
findings that R010, cross-repo-coordination.md and
audit-readiness-checklist.md cite by number are kept, each with its status as
measured today: finding 1 is fixed by this PR, 2 is still open and belongs to
the tagging step, 4 and 5 are superseded. ROADMAP.md no longer claims that
PROJECT-STATUS is regenerated each run.

Tests

Everything below ran locally on this branch.

Suite	Result
relay unit, as test.yml runs it	176 pass, 0 fail
admin unit	37 pass, 0 fail
root integration, no browser	123 tests, 121 pass, 2 pre-existing skips (110/108/2 on main, so +13 new checks and no new skips)
the same three under node:24-alpine	identical
tests/static-sanity.sh	PASS, all ten checks including the style guard
bash -n on every .sh	clean
npx eslint@9 .	clean
silent-suites gate	still exactly parasign-signs-quota
docker build -f relay/Dockerfile	succeeds; label 3.1.0, Node v24.20.0, /health reports 3.1.0

Note on check 10 of static-sanity: it was red on main because commit
c45d1c6 carries an attribution trailer. This branch's commit has none, per
AGENTS.md, so the gate is green.

Not in this PR

Deliberately, because each needs a decision rather than a change:

• No tag. Tagging and deploying are one step (docs/RELEASE.md steps 5 to 8).
• install.sh still pins v3.0.0. It clones that git tag, so bumping it
  before v3.1.0 exists points the self-host installer at something nobody can
  clone. It is step 9 of the release.
• docs/RUNBOOK-DEPLOY-3.0.0.md keeps its name and its content. Renaming it is
  cheap; reconciling registry-pull versus build-on-server is the actual
  question, and it is a production decision.
• Points 3, 4, 5, 6, 7 and 10 of the report are untouched.

[Apolloccrypt]

Two things found after the description above was written.

The Node bump broke a gate, and the gate was right. The relay unit job went
red in seven seconds. Node's default node --test reporter for a non-TTY
changed from tap to spec between Node 20 and Node 24, which drops the #
prefix from the diagnostic lines that test/_requires.js prints. The
silent-suites gate greps for exactly that prefix, found nothing, read it as "no
suite asserted anything silently" and failed on the mismatch with its expected
list. Fixed by pinning --test-reporter=tap on that one step, so the gate's
input is an explicit contract rather than a Node default. Verified under
node:24-alpine: 176 pass, 0 fail, gate reports exactly parasign-signs-quota.

Checked the other places that read test output instead of an exit code: the
heartbeat's issue body already filters on both the TAP and the spec forms, so
it needed nothing.

The musl binding was the one real risk of the base change, and it loads.
The crypto binding is compiled in the rust:1.98-alpine stage (Alpine 3.24) and
was being loaded on a node:25-alpine3.21 runtime. Now both are Alpine 3.24.
Proven rather than assumed, in the built image:

$ docker run --rm --entrypoint node <image> -e "require('/app/node_modules/@paramant/core')"
binding geladen op v24.20.0 | exports: kemDecaps,kemEncaps,kemKeygen,mldsaSign,aeadEncrypt,mldsaKeygen

All 11 checks green, heartbeat - production skipped as it should be on a PR.

[Apolloccrypt]

Rebased onto main (99909a1) and pushed. Head is 9a5ecd5, four commits, all
checks green.

Worth saying why the checks went quiet for half an hour before this: GitHub does
not build a merge ref for a PR it cannot merge, so once main moved ahead no
pull_request runs were queued at all. That reads as "CI is slow", and it is
not; it is the PR being DIRTY. A workflow_dispatch run does go through, which
is how the branch was tested in the meantime, but it scans differently: the
gitleaks step does a full-history scan on that event instead of the PR's own
commits, and it reported five findings. Those are pre-existing. Measured rather
than assumed: full history on origin/main and on this branch both report 29
findings locally, so these four commits add none.

Two conflicts, both resolved toward main's newer structure.

product-heartbeat.yml. #338 moved the live job out into heartbeat.yml.
Took main's file whole and applied the Node 24 bump to both files instead, so
the bump follows the job rather than the filename. All seven node-version
entries across the five workflows now read '24'.

test.yml. #341 added a second silent-suites gate for the new route job and
set both expected sets to empty. Kept main's exclusion lists and applied
--test-reporter=tap to both steps.

That second one is more important after the rebase than before, and it inverts
the failure mode. With a non-empty expected list, Node 24's spec reporter made
the gate go red, which is how it was found in the first place. With an empty
expected list, spec makes it pass: the grep matches nothing, silent is
empty, and a gate that can no longer see anything reports green. A dead gate
reporting green is exactly what both gates exist to prevent. Both now pin the
reporter rather than inherit a Node default. CI confirms they are alive and
empty on this run:

--- suites that asserted nothing in this job:       (none)
--- route suites that asserted nothing in this job: (none)

CHANGELOG. The six PRs that landed while this was open are in the 3.1.0
section: /parasign (#325), the messaging guide (#331), the homepage rewrite
(#328), the site claims pinned to code (#327), the evidence-backed heartbeat
(#338) and the route suites (#341). The intro count goes from 268 commits and
52 PRs to 277 and 58, and now says it was rebased rather than pretending it was
written in one pass. #341 is named for what it is: point 3 of the report was
that relay.js, 6488 lines and 68 routes, was loaded by no unit test. It is now
loaded by the route suites. Not closed, but no longer zero.

docs/RELEASE.md step 3 was rewritten to match what test.yml does today:
the new exclusion lists, the npm ci the root job now needs (#338's
heartbeat-lib test imports @noble/post-quantum), and a line on why the
reporter is pinned. It said "run what CI runs" while running something else,
which is the same class of untruth as the read in: pointers in the previous
commit.

Tests after the rebase, on Node 22 and again under node:24-alpine: relay 175,
admin 40, root 145 (143 pass, the same 2 pre-existing skips). static-sanity
PASS including the style guard, bash -n and eslint clean.