# Artifact Reference

Every `cs build` writes a runtime plus metadata files. The runtime
is the final stamped binary artifact. Downstream signing and attestation
workflows run after conda-ship writes these files.

## Layouts

| Layout | Runtime | Bundle file | Network during bootstrap |
| --- | --- | --- | --- |
| `online` | `RUNTIME` | none | yes |
| `external` | `RUNTIME` | `RUNTIME.bundle.tar.zst` | optional |
| `embedded` | `RUNTIMEz` | embedded in binary | no |

On Windows, binary filenames also include `.exe`.

## Bundle Contents

Bundles are a transport for the conda package archives already named in the
runtime lock. They are not channel mirrors and do not use a `linux-64/` or
`noarch/` directory layout.

`external` and `embedded` bundles contain top-level `.conda` and `.tar.bz2`
package archive files. The runtime matches those filenames against the stamped
lockfile and verifies package SHA256 values before installing from them.

External bundle directories may contain unrelated files, but conda-ship only
indexes top-level conda package archives and skips symbolic links. Embedded
bundles are stricter because they are extracted from a tar archive: every entry
must be a top-level regular `.conda` or `.tar.bz2` file. Directory entries,
nested paths, symbolic links, hard links, and other file types are rejected.

## Metadata Files

For an `online` build with runtime `demo`, conda-ship stages:

- `demo` or `demo.exe`
- `demo.runtime.lock`
- `demo.packages.txt`
- `demo.info.json`
- `demo.sha256`

When `--target-label` is used, the label is inserted into the stem, for example
`demo-linux-64.info.json`.

For an `embedded` build, the stem uses the `z` suffix, for example
`demoz.info.json` or `demoz-linux-64.info.json`.

For an `external` build, conda-ship also stages `demo.bundle.tar.zst` or a
target-qualified equivalent.

## Stamped Runtime Data

conda-ship appends a runtime data block to every staged runtime. The block
contains the runtime lock, runtime name, delegate executable, install scheme,
install name, docs URL, bundle environment variable names, and the embedded
bundle bytes for `embedded` builds.

The data block ends with:

- format version
- header length
- bundle length
- header SHA256
- bundle SHA256, or the SHA256 of empty bytes when no embedded bundle is present
- conda-ship runtime-data magic bytes

The generated runtime validates the stamped header at startup. For
embedded artifacts, it also verifies the bundle checksum before extracting package
archives during `bootstrap`.

The binary checksum in `.sha256` covers the final stamped artifact. The
conda-ship release workflow also publishes GitHub Artifact Attestations for
the `cs` CLI, runtime templates, and `SHA256SUMS` manifest.

Verify a downloaded release asset with:

```bash
gh attestation verify ./cs-x86_64-unknown-linux-gnu \
  -R jezdez/conda-ship \
  --signer-workflow jezdez/conda-ship/.github/workflows/release.yml
```

Downstream distributions can add their own attestations or platform signing
after conda-ship finishes staging their runtime artifacts.

## Info JSON

The info JSON contains:

- schema version
- artifact name
- layout
- conda platform
- runtime filename
- optional external bundle filename
- lock filename
- package list filename
- package count
- SHA256 checksums

## Package List

The package list is tab-separated and contains:

- package name
- version
- build string
- package URL
- SHA256, when available from the lockfile