Task/vessel channel api

[tarkah]

Channel API

This PR adds a new channel API which enables us to record a "history" of package index "versions" and human readable links to those "versions" in the way of "tags" and "streams". The following will describe these concepts and touch on some implementation details from this PR.

Channel

A channel defines a single git recipe repo and its respective moss-format repo. vessel handles the moss-format side of the channel and is what this PR implements.

vessel can work with many channels, which will eventually be included on requests to vessel from summit. But for now we hard-code a single channel called "main" for all operations to keep vessel backwards compatible w/ summit.

Each channel has its own isolated pool/ directory (containing package .stone files) and "version" directories (containing package index files).

Channel version

A channel "version" describes a single package index file which moss can use as a repository. There are currently 3 different types of versions - history, tags & streams.

• history versions are "recorded" for every new change made. For now, each change occurs when we build a task and upload its packages to vessel. Each upload of packages records a new history version
• stream versions are links to history that intend to move along w/ history. We currently define volatile and unstable:
  • volatile is automatically updated to link to the latest history version
  • unstable is manually updated to link to some history version after it is deemed worthy of "promotion"
• tag versions are links to history that are intended to be immutable / never change

Note how stream and tag versions are simply links to a history version. This means that package index files only ever live within a history version and these other types simply symlink to a history version.

An example of how this looks on disk:

history/
  1/
    x86_64/
      stone.index
  2/
    x86_64/
      stone.index
  3/
    x86_64/
      stone.index
stream/
  volatile -> ../history/3
  unstable -> ../history/2
tag/
  2025.10-iso -> ../history/1
  2025-11-25-unstable-stream -> ../history/2

Pruning

Disk space can be reclaimed by ensuring that old packages can be pruned. The only packages that can be pruned are those no longer referenced by any version, meaning not in any history version. We therefore need a way to prune stale history versions. Once "stale" history versions are removed, the orphaned packages from those can then be cleaned up as well.

A history version is considered "stale" when it is not linked to by any tag or stream versions and it is older than X time. Currently we hardcode the retention policy time to 14 days, but we intend to make this configurable either based on a retention time "rolling window" policy or some available disk space policy.

Backwards compatibility

Backwards compatibility is important at this stage and we wanted to ensure 0 code changes were needed anywhere except vessel.

• Vessel's public API for taking package uploads hasn't changed. This is why the main channel is currently hardcoded, since summit isn't ready to deal w/ the new channel concept yet. It is fine to simply work with our single main channel for now.
• history is simply recorded on each task being completed and published. In the future we will have a different mechanism of recording history, but for now this will work just fine.
• The previous volatile/x86_64/stone.index now lives at stream/volatile/x86_64/stone.index which is technically a breaking change, but we can use Caddy to resolve volatile/x86_64/stone.index as stream/volatile/x86_64/stone.index.
• Within moss, users with a volatile/x86_64/stone.index URI defined will receive the redirected index file which technically has an incompatible relative path depth of ../../../ instead of ../../ but this saturates at the root / path and we can setup similar path rewrites in Caddy to resolve /pool and /volatile to the correct locations

With the above, we can deploy this change transparently and immediately benefit from recording history / creating long lived streams & tags.

Admin CLI

New commands are added to admin CLI to update-stream, add-tag and remove-tag

• update-stream allows one to update the link of a stream to any other version which will link it to that underlying history version. Even though volatile automatically updates, it might be useful to roll back volatile to older history in case a bad package is delivered & needs to be dropped, and then subsequently fixed in a newer build. Re. unstable, we can "promote" older history or tag versions to the unstable stream w/ this mechanism.
• add-tag allows us to manually create a new tag from some history
• remove-tag allows us to manually delete old tags. This likely shouldn't ever happen but might be reasonable after some period of time to ensure very old packages can be pruned

[ermo]

Converting this to draft until the design outline has been added to the PR description.

[ermo]

@tarkah reports that this is running very well locally, so merging now.

[ermo]

🚀