Concepts

Five nouns carry the whole tool: store, artifact, coordinate, manifest, channel. Learn these and the commands read themselves.

Store

A directory on disk. Its layout is fixed and documented so you can read it with ls and trust what you see:

<root>/<name>/<version>/
    payload          the bytes you pushed, unmodified
    manifest.json    canonical metadata (sorted keys, LF, no trailing space)
    manifest.sig     Ed25519 detached signature over manifest.json

The store records store format 4 at its root. The format number changes only when the on-disk shape changes; it last moved at 2.0.0.

Artifact & coordinate

An artifact is one payload plus its manifest. Its coordinate is name@version - for example io.byteanvil.gateway@2.4.1. Names are reverse-DNS by convention, not by rule; the only hard rule is that a coordinate is written exactly once. Pushing over an existing coordinate fails with exit 2. If you need a rebuild, bump the version.

Manifest & digest

The manifest is small JSON: the payload digest, size, creation time, builder string, source commit, the channel it entered on, and the signing key id. The payload digest is a lowercase-hex SHA-256 written as sha256:…. Nothing in the manifest is free text the tool trusts - verify re-hashes the payload and re-checks the signature; it does not take the manifest's word for the digest.

Channels

Exactly three, in a fixed order of maturity: dev, staging, release. An artifact enters on one channel and is promoted upward. Promotion is a metadata move - the payload and its digest never change - so a build that reaches release is provably the same bytes that were tested on staging. There is no fourth channel and no way to add one; that limit is the point.