sdkref

Overview ¶

Package main implements sdkref, the guard over how this repository cites the Anthropic SDK and the other sources it reads at a tag (#722, plan 51).

A citation into an external source does two jobs at once, and they have opposite requirements under a pin bump. It makes a *temporal claim* — this has been true since vX, this was verified at vX, this is gone as of vX — and it gives a *locator* inside that source. Written as one clause — "at the pinned" tag, then a file and a line number — a bump appears to invalidate every one of them, so the bump is either done wholesale (which turns true `since` sentences false and produces a green diff proving nothing was re-checked) or not at all. docs/plan/51_sdk-reference-binding.md separates the axes; this tool holds the separation.

Three rungs, and only two of them can fail the gate:

• Shape is syntax, plus which files git tracks and which modules go.mod requires, and always decidable, so it runs on every citation.
• Resolution runs only for a citation stamped at the version go.mod pins, because that is the one tag the gate is guaranteed to have: `make verify` begins with `build`, so the module is already materialised and `go list -m` finds it with GOPROXY=off. The registry cites tags no cold runner holds, and reaching for them would make the gate need the network.
• The report resolves every anchor it can against the pin whatever the citation's stamp, and never fails the gate. At gate time a symbol that has vanished is not yet a defect — the entry may describe a version where it existed — so this rung is judgment, not obligation. A gate that reddened until fifty claims were re-verified would recreate the thing the plan removes. It is also the only rung that may read a tag other than the pin, and only ever one a module cache already holds: available, never required.

Both halves of the corpus go through the same scanner: the registry named by File, and the citations written in Go comments, which GoComments reads.

The two failing rungs fail `make verify` through this package's own test, which runs -fail over both halves. The report's one obligation is on the pull request that brings a transition — moving a pin, or editing a citation — where .github/workflows/sdk-bump.yml runs -report and fails while one awaits the disposition docs/REFERENCE_PROJECTS.md describes.