Snapshot store

Version 1, draft. The server side of the release train (release train is the client side): how a mirror becomes a store of immutable snapshots with channel pointers, and how pacvamp-repo snapshot moves them.

Layout

<store>/
  snapshots/<id>/                 immutable; id is lexically sortable UTC
    core/os/x86_64/core.db, *.pkg.tar.zst, *.sig
    extra/os/x86_64/...
    multilib/os/x86_64/...
    release.json, release.json.minisig
  channels/
    edge -> ../snapshots/<id>     symlinks: the pointers
    rc -> ../snapshots/<id>
    stable -> ../snapshots/<id>

A machine on channel stable has Server = <base>/channels/stable/$repo/os/$arch in its mirrorlist and reads <base>/channels/stable/release.json. Pinning writes <base>/snapshots/<id>/$repo/os/$arch.

The CLI defaults IDs to YYYY-MM-DDTHH. Automated publishers may add finer UTC precision, such as YYYY-MM-DDTHHMMSSZ, when more than one deployment can occur within an hour.

Package files are hard-linked from the previous snapshot when unchanged, so a snapshot costs the churn since the last one, not a full copy.

Commands

• snapshot cut --store S --from <mirror> --key K [--id <id>] [--repo-index <pacvamp-index.json>]... copies the repositories from a synced Arch mirror into a new snapshot, records the database digests and each supplied repository index sequence, writes and signs release.json with no test result, and points edge at it.
• snapshot test --store S --id <id> [--suite <command>] runs the suite with PACVAMP_SNAPSHOT_ID and PACVAMP_SNAPSHOT_DIR set. Exit 0 is a pass. Lines the suite prints as tested: <pkgbase> become tested_pkgbases. The result is recorded and signed; a pass points rc at the snapshot when it is newer than the current rc. Without --suite the built-in consistency check runs (below).
• snapshot promote --store S --channel stable [--id <id>] [--soak 3d] [--expedited] moves a pointer. Without --id, the current rc is promoted when it passed, is not held, and has soaked for --soak since reaching rc. With --id a maintainer promotes deliberately; --expedited marks a security snapshot that ran the short suite.
• snapshot hold --store S --id <id> --reason <text> marks a snapshot held and moves any channel pointing at it back to the newest earlier snapshot that was promoted to that channel and is not held. snapshot unhold clears the flag; pointers do not move forward on their own.
• snapshot status --store S [--json] lists snapshots and pointers.
• snapshot prune --store S [--retain 90d] [--stable-retain 365d] deletes snapshots older than the retention, keeping any that were ever stable for the longer period and never a channel target.

PACVAMP_REPO_NOW fixes the clock for tests.

Built-in consistency check

For every repository in the snapshot: the database parses, its digest matches release.json, and every package file present beside it has the size and sha256 the database records. Missing files fail the check unless --allow-missing (a partial mirror). The verified package names become the release's tested_pkgbases; the standalone snapshot check command also prints them as tested: <name>. Client tested labels therefore need the suite context: this check establishes file consistency, not that the package booted or ran successfully.

The Omarchy suite

A distro suite can exercise installation, a desktop session, upgrades, and rollback using the same environment/exit-code/tested: contract. That full Omarchy matrix is adoption work. This repository has a separate Arch VM lifecycle fixture; neither its existence nor the built-in consistency check establishes Omarchy hardware coverage. See the harness contract and development tests.

Use the snapshot CLI for required flags, including the signing key for commands that update a release manifest.