Invariants, non-goals and givens

7. Global invariants

I1. headwater never changes a repository, and never acts on a release (5, 36).
I2. The pin alone decides what is new (9).
I3. Upstream’s words reach the asker as upstream wrote them, with no model between (11, 19).
I4. A release has one identity for ever, everywhere (10).
I5. Asking what headwater holds reaches no source and writes nothing (17).
I6. Nothing headwater keeps but acknowledgements is needed to answer again (29).

Moving a pin, building, testing or landing a change. A fixer does that, and the repository’s own gate decides whether it lands.
What a dependency depends on in turn. headwater reports what the repository’s authors chose; scanning the whole graph for advisories belongs to a vulnerability scanner.
Judging what a release means for the repository, or summarising its notes.
Recording releases as anyone’s own records. A recorder does that through its own plugin, from what headwater reports.
Telling anyone by itself. A surface tells, when its asker asks.
Licences and software bills of materials.

Constraints already fixed:

Repositories are git repositories.
An identity is a Package URL (ECMA-427).
The askers include coding agents working in many checkouts of one repository at once.
Sources are reached over the network, with the asker’s own credentials where a source needs any.
headwater is free and open source.

The rest of the stack, which a model builds on unless it says why not:

One static binary, written in Rust, as sluice is.
Every answer as JSON on request, the form of (35).
Four surfaces answering from one core, each a plugin kept outside the core as sluice keeps its plugins: a command line; a Claude Code plugin that notes new releases at a session’s start and hands a release to a background agent in a worktree of its own; a herdr plugin with a sidebar row, a popup and a key that hands a release to a new agent in a worktree; and a Flywheel plugin whose one part is an adapter that turns each release into a capture.
The profiles of Part C: the watch list, npm, Python, GitHub releases, deps.dev, OSV and the git directory first.