# Bucket layout

A version is a directory holding its `_manifest.json`. Artifacts writes each
upload's files under a directory of its own inside it, named in the manifest's
`dir`, so a retried or superseded upload never touches another's files:

```text
<bucket>/<location path>/<artifact>/<version>/<dir>/<file>    # location path: empty for created buckets
o41art-7f3k2q9d/experiments/hoonshot/1234/step-00000500/u3f9c2a7d1e04b6a8c5f2/params.safetensors
                                                   .../u3f9c2a7d1e04b6a8c5f2/state.json
                                                   .../_manifest.json   # written last
```

The crate writing to a raw `s3://`, `gs://`, `az://` or local location puts the
files beside the manifest and writes `dir: null`. Every reader, the crate's
included, takes the files from `<version>/<dir>/` when `dir` is set and from
`<version>/` otherwise.

## The manifest

```json
{
  "format": "o41-artifacts/1",
  "artifact": "experiments/hoonshot/1234",
  "version": "step-00000500",
  "files": [
    { "name": "params.safetensors", "size": 2793406464 },
    { "name": "state.json", "size": 912 }
  ],
  "meta": { "step": 500 },
  "source": null,
  "dir": "u3f9c2a7d1e04b6a8c5f2",
  "committed": "2026-10-06T11:42:10Z"
}
```

`source` is the full path a fork's first version was forked from, `null`
otherwise.

## Commit

- A version is committed when its manifest exists and the service has marked it
  so. The service completes every upload, checks every size, writes
  `_manifest.json`, then commits.
- A version without a manifest is a cut-off write: never listed, never the
  latest.
- Pending uploads expire after 24 hours: they are aborted and what was written
  is deleted. Created buckets also abort unfinished multipart uploads after 2
  days.
- Buckets are self-describing: an artifact's catalog can be rebuilt from its
  manifests.

---

Artifacts by 041 documentation. Every page: https://artifacts.041.io/llms.txt