Part C
Part C. Profiles
Parts A and B do not change to admit a profile.
C.1 Identity: Package URL
An identity is a Package URL (ECMA-427) without its version:
pkg:npm/react, pkg:pypi/fastapi, pkg:github/jdx/mise. A release’s
identity is the same Package URL with its version (10):
pkg:github/jdx/mise@2026.10.10.
C.2 Dependency descriptions
| profile | declarations read | the pin |
|---|---|---|
| npm | package.json dependencies | the version the lockfile resolves; unknown without a lockfile |
| Python | pyproject.toml and requirements*.txt | the version uv.lock or poetry.lock resolves, or a == requirement; unknown otherwise |
| Cargo | Cargo.toml dependencies | the version Cargo.lock resolves |
| Go | go.mod requirements | the version go.mod names |
| mise | mise.toml and .tool-versions tools | the version each names; unknown for latest or a prefix |
| GitHub Actions | uses: in .github/workflows | the tag or version named; unknown for a branch |
| container images | FROM in a Dockerfile | the tag named; unknown for latest |
| watch list | a file naming each dependency’s upstream repository, its tag pattern, its pin and its tier | as the file gives it; swancloud’s, generated from lib/release-sources.nix |
Tiers are read from .config/headwater.toml: each tier’s name, its
cadence, and the identities it names. A repository with no such file has
the default tier alone, with a cadence of seven days.
C.3 Release sources
| profile | identities | list-releases / order |
|---|---|---|
| deps.dev | npm, PyPI, Cargo, Go, Maven, NuGet, RubyGems | the versions and dates of a batched Package URL lookup, with no key; order by the ecosystem’s own rules |
| a registry’s own API | the registry’s packages | the registry’s version list, for a release deps.dev has not seen yet; order as above |
| GitHub releases | pkg:github/*, and any dependency whose source repository is on GitHub | the repository’s releases through GraphQL, fifty repositories a query, with the asker’s own gh sign-in (38); order by Semantic Versioning where the tags parse, by the watch list’s tag pattern otherwise |
| ecosyste.ms | GitHub Actions, container images, Homebrew, nixpkgs and the other registries it indexes | its packages API by Package URL |
Order by ecosystem: Semantic Versioning 2.0.0 for npm, Cargo and GitHub tags that parse; PEP 440 for PyPI; Go’s module rules; and a calendar version compared field by field where a watch list says so.
C.4 Notes sources
| profile | read-notes |
|---|---|
| GitHub release | the body of the GitHub release at the version’s tag in the dependency’s source repository, which deps.dev links or the watch list names |
| changelog | the section for the version in the source repository’s CHANGELOG.md at that tag, where no release body exists |
C.5 Advisory source: OSV
| operation | how OSV satisfies it |
|---|---|
| read-advisories | OSV’s batched query by Package URL and version; severity as the advisory gives it |
C.6 Store: the git directory
| operation | how the git directory satisfies it |
|---|---|
| read | the files under <git common dir>/headwater/, which every worktree of the repository shares (28) |
| write | a new file written beside the old and renamed over it, under a lock held for the write (30, 49) |
Notes are kept whole under the same directory, never in the repository’s content.