The core and its seams

headwater is one core that knows git and reaches everything else through five seams. Each seam is a contract of Part B, and each is bound by naming one or more profiles of Part C (51). Parts A and B do not change to admit a profile.

The five seams

The dependency description (B.1) reads a repository state. It answers every dependency the state declares, each with its identity, every declaration of it and the pin each gives, and every declaration it could not read, with the reason (40). It answers the tiers, each with its cadence and the identities it names (41). Both answers are the same for the same repository state, and reading either changes nothing (42).

The release source (B.2) lists every release it publishes for an identity, each with its version, its date, its link and whether the source has withdrawn it. Where the source cannot be reached, it says so (43). It orders two versions of one identity: one is newer, they are the same, or their order cannot be decided (44). The order is the source’s own, and the same two versions always order the same way (45).

The notes source (B.3) gives what upstream wrote of one release, whole and unchanged, or says upstream wrote nothing (46).

The advisory source (B.4) gives every advisory that names one version of an identity, each with its identity, its severity as the advisory gives it, and a link (47).

The store (B.5) reads a repository’s held state with the version it was read at (48). It writes the next held state all or nothing, and only if the held state is still at that version (49). It holds nothing in the repository’s content, and every checkout of one repository reaches the same store (50).

Binding

Any number of dependency descriptions, release sources, notes sources and advisory sources are bound at once, each answering for the identities it knows, and exactly one store is written (51). A repository that holds npm packages, Python requirements and a watch list binds all three descriptions, and deps.dev and GitHub releases each answer for the identities they know.

The capture design puts each ecosystem’s own package manager first among the release sources, run read-only in the repository’s own shell, with deps.dev, GitHub and ecosyste.ms answering where none runs. The statement takes it at plan step H1 (Where headwater asks).

What a source learns

headwater sends a source nothing of the repository but the identities and versions it asks about (37): no file, no path, no commit. It reaches a source with the asker’s own credentials or with none (38). GitHub releases are read through the asker’s own gh sign-in, fifty repositories a query (C.3). Where two sources disagree about one release, the report names both and chooses neither (39).

One suite

One conformance suite holds every profile to Parts A and B, and a profile that fails it is not one (52). Each of its scenarios cites the clauses it exercises, and the suite fails when no scenario cites a clause (section 12). A new profile implements its seam’s contract and passes the suite, and nothing else in headwater changes.

One binary

headwater is one static binary, written in Rust as sluice is, and gives every answer as JSON on request (section 9).

Still to rule: questions 4, 11, 32 and 33, and how a package manager in the repository’s shell keeps (5), in Open questions.