Preamble, purpose, actors and vocabulary
A statement of what headwater must always do and never do, written to admit any model that satisfies it.
The statement is in three parts. Part A is what must hold of headwater on its own: what a repository depends on, which releases of those dependencies are new to it, when each is looked for, what headwater keeps, and what it gives the people and programs that ask. Part B is its contracts: the operations it needs across its five seams, a dependency description, a release source, a notes source, an advisory source and a store, and the guarantee each must give. Part C is the profiles: the ways each contract is satisfied.
Parts A and B name no mechanism: no command, file, format, field, registry, service or tool. One thing of the world they do name freely, because section 9 fixes it: git. Every other real tool is named only in section 9 and in Part C. A reader who has never seen a dependency updater should be able to design from Parts A and B and git alone.
1. Purpose
headwater tells a repository which releases of what it depends on are newer than what it runs. It reads what the repository declares, asks where each dependency is published, and reports every newer release with the words upstream wrote for it. It looks often for the dependencies a repository’s authors care most about, and less often for the rest. It answers the same way to a person, a coding agent, a pane beside the agents, and a program that records what it hears, and none of them needs another to use it. headwater never changes a repository, never judges what a release means, and never acts on one: a person or an agent decides, and the change is theirs.
2. Actors
| actor | may decide | may not |
|---|---|---|
| the repository’s authors | what the repository depends on, which dependencies belong to which tier, and each tier’s cadence | they never decide what a source publishes, or that a release is older than it is |
| an asker (a person, a coding agent, a surface, a recorder, a scheduler) | which repository and which tiers to ask about, and when | it never changes an answer by who it is, and never supplies a release or a version order |
| upstream (whoever publishes a dependency) | what is released, when, under which version, and what its notes say | it never learns anything of the repository beyond the identities and versions headwater asks about |
| headwater | which releases are newer than each pin, as this statement fixes them, and what it keeps to answer again | it never changes a repository, never rewords or judges what upstream wrote, never acts on a release, and never keeps a credential |
| a fixer (a coding agent or a person who makes changes) | whether and how to move a pin, given a brief | it never changes what headwater reports about upstream |
| a recorder (a program that keeps what it hears as its own records) | how it records each release, and what its own judgment of one is | it never writes headwater’s state |
| the operator | everything the repository’s authors and an asker do not settle |
3. Vocabulary
Terms are defined by meaning. A model may add terms; it may not redefine these.
- repository state: the content of a repository at one commit, together with any uncommitted change the asker names as part of it.
- dependency: something published apart from the repository that the repository’s authors chose to use: a package, a tool, an image, or another repository’s releases.
- declaration: one place in a repository state that names a dependency, and what it says of the version.
- identity: the one name of a dependency that every declaration, source and asker uses for it.
- pin: of a dependency at a repository state, the version the repository runs, or unknown when the repository state names no single version.
- source: where upstream publishes a dependency’s releases, or an index of those places.
- release: one version of a dependency that its source publishes, with its date and a link to it.
- version order: how a dependency’s source orders its versions.
- newer: of a release against a pin, later in the dependency’s version order.
- notes: what upstream wrote of a release, as upstream wrote it.
- advisory: a published warning that names versions of a dependency as unsafe.
- tier: a named set of a repository’s dependencies, with a cadence. The default tier holds every dependency no other tier names.
- cadence: the longest time a tier may go without a complete scan while scans are asked for.
- due: of a tier, that its cadence has passed since its last complete scan, or that it has never had one.
- scan: one reading of a repository state’s dependencies and of the sources of those in the tiers it covers.
- complete: of a tier’s scan, that every dependency of the tier was read and every source reached.
- unread: of a dependency in a scan, that headwater could not read its declarations or reach its source, with the reason.
- report: what a scan found: for each dependency of the tiers it covers, its pin, the releases newer than it, the advisories that name it, or that it is unread.
- acknowledgement: a person’s word, or an acting session’s, on one release of one dependency: dismissed, or skipped until a newer release.
- brief: everything a fixer needs to move one dependency to one release: the release, its notes, its advisories, and every declaration of the dependency.
- held state: everything headwater keeps of its own for one repository.
- surface: one way an asker reaches headwater.
- profile: one way a contract of Part B is satisfied, as Part C describes.