chore: pin the corpus to a revision, and make a pin record its measurement

[ShocOne]

Two defects behind #92, both of which would have caused it again.

1. The github pin followed a branch

Its upstreamUrl named github/rest-api-description /main/ — a branch
tip, not a revision. So it re-pinned itself every time the vendor published: the
hash stopped matching, every test reading the document failed, and the only
remedy was to restate the pin. It was already broken when I found it:

pinned:  80850db290cde4eb487e0efb587cf27f305e77b6bef96933ed8a09b5169d5b1d
served:  81c0ff2bbff9099b569058ef387e0ef83c33ef00ca0346e8a092777a71c192e3

CI was green only because no test reads that document — specmodel and
intermediate_representation both fetch thousandeyes alone. It was a trap
rather than a break.

It now names commit 67c14c7e, at the same 808 paths and 1220 operations the
old pin recorded, so the corpus surface is unchanged.

Why not a tag

I proposed one and was wrong; the measurement corrected it. That repository's
tags are not maintained — v2.0.0 dates from 2022:

ref	sha	paths / operations
old pin (main, 7 Aug)	80850db2	808 / 1220
commit 67c14c7e	81c0ff2b	808 / 1220
tag v2.1.0	b138e9cd	561 / 860 — 30% smaller
tag v1.1.4	369b85bc	— (not the pinned bytes either)

Pinning a tag would have quietly shrunk the corpus by a third.

2. A pin recorded that nothing had measured the document

corpus.Describer was a package variable whose doc said "the CLI installs the
real parser". Nothing installed it, in internal/ or cmd/. So RewriteLock
wrote this for every pin it restated:

"operationCount": 0,
"pathCount": 0,
"version": "unparsed",

which is what my first attempt at #92 produced. Those counts exist to catch a
truncated download that happens to parse, so zeroing them disables the check
that the lock is for.

It is now an argument — RewriteLock(ids, describe), CheckUpstream(id, describe)
— so a caller cannot forget it and there is no default to be wrong. The
degraded describer survives as unexported unparsed, used only by
verifyAgainstPin, where the failure is already named by digest and the caller
genuinely has no parser. It is never written to the lock.

specmodel.Describe is the implementation to pass. It lives on the specmodel
side because the cycle the original comment describes is real: specmodel's
in-package tests import corpus.

Guards so neither can return

TestUnit_Corpus_LockPinsTheDocumentsTheTestsRead now also refuses a pin whose
URL names a moving ref, and one whose version is empty or unparsed.
TestUnit_Corpus_AMovingRefIsRejected proves that guard catches
main/master/latest and passes a commit SHA, a tag, and the ThousandEyes
URL — so it cannot pass by accident on a lock that happens to hold no branch URL.
TestUnit_Refresh_RewriteLockRestatesOnlyThePinsThatMoved now asserts the pin
carries the describer's own measurements rather than unparsed.

Measured effect

No generated output changes; this is test infrastructure. go test ./... is
green, including both TestIntegration_*_APinnedVendorDocument.

Still not fixed

RewriteLock has no caller — re-pinning needs a throwaway harness. Adding a
verb to drive it needs an owner-approved name, so it is not in this PR.
ThousandEyes serves from a URL with no ref at all and will drift again; the
mirrorUrl field is the designed mitigation and is empty.

Gates

• gofmt -l internal cmd — empty
• scripts/repo_hygiene_gate.sh — pass
• golangci-lint run — 0 issues
• go build ./... && go vet ./... — pass
• go test ./... — pass, coverage 91.4% total

🤖 Generated with Claude Code