The watch list
Some dependencies have no file in the repository that names their version in a form a program reads: a tool a fleet builds from a pinned release, whose pin only an evaluation computes. The watch list declares them.
What it is
The watch list is a dependency description (C.2): a file naming each
dependency’s upstream repository, its tag pattern, its pin and its
tier. headwater reads it as it reads any other declaration, and the pin
is what the file gives. Each entry also carries a name and the files a
bump moves (design/capture/design.md).
| an entry holds | for example |
|---|---|
| its name | mise |
| its upstream repository | jdx/mise |
| its tag pattern | the shape of the tool’s release tags |
| its pin | 2026.9.18 |
| its tier | the tier it belongs to |
| the files a bump moves | packages/mise/default.nix |
A watch-list entry’s identity is the Package URL of its upstream
repository, pkg:github/jdx/mise (C.1). GitHub releases lists its
releases, and orders them by Semantic Versioning where the tags parse
and by the watch list’s tag pattern otherwise. Where the list says the
version is a calendar version, they compare field by field (C.3).
When a watch list names fourteen tools by their upstream repositories and tag patterns, headwater reports each release under the same identity a declaration of that tool would give it (S11). A tool named both in a watch list and in another declaration is one dependency (2), and each of its releases is one release.
The key it gives
A watch-list entry’s release keys as release/<name>/<version>, under
the name the list gives it, when the Flywheel plugin turns it into a
capture (Releases as captures).
The first fleet
swancloud, the first fleet that runs headwater, generates its watch
list from lib/release-sources.nix, the list of tools it pins (C.2). The
fleet hands headwater the pins that only Nix evaluates. It commits the
generated file, and a flake check refuses the file when it drifts from
the evaluation, as swancloud already checks its generated task list
(design/capture/design.md).
Once headwater reports swancloud’s releases, the fleet’s own release adapter retires. Its captures’ keys carry on unchanged, because a watch-list entry keys as that adapter always has.
Still to rule: question 10, with 7, 8 and 14 from other chapters; the files a bump moves and the key enter the statement in plan step H1. See Open questions.