@crvouga/atlas 0.16.0 → 1.0.0

package/dist/server/src/user-state.js

@@ -0,0 +1,74 @@
+/**
+ * @module User state in S3
+ *
+ * Reads and writes the user state document (`UserStateSchema`: the garbage collection policy and the saved settings) as
+ * one JSON object at `server/state.json` in the object store, which in a running server is the S3 bucket. This is the
+ * only place user state is kept: not a file, not a database, not the browser. A missing object is an empty state
+ * ("nothing chosen yet"); an object that cannot be read or does not match the schema is an error that stops the
+ * server from starting and is never overwritten, so a transient or corrupt read can never silently reset anyone's choices.
+ * Saving refuses a stale revision (the SHA-256 of the stored text), serialised within this process. An object store has
+ * no conditional writes, so two servers saving at the same instant could still race; run one server per bucket.
+ *
+ * @see docs/server.md#user-state-and-garbage-collection
+ */
+import { createHash } from 'node:crypto';
+import { readUtf8, writeUtf8 } from '../../reports/src/object-io.js';
+import { UserStateSchema } from '../../schema/src/user-state.js';
+/** Where the user state lives, relative to the store (the bucket plus `ATLAS_S3_PREFIX`). */
+export const USER_STATE_KEY = 'server/state.json';
+/** Raised when the stored user state cannot be trusted. The message says where it is and what to do. */
+export class UserStateError extends Error {
+}
+const digest = (text) => createHash('sha256').update(text).digest('hex');
+/**
+ * The user state kept in `store` at {@link USER_STATE_KEY}.
+ *
+ * @example
+ * const userState = userStateStore(s3Backend.store);
+ * const { state } = await userState.read();
+ */
+export function userStateStore(store) {
+    let pending = Promise.resolve();
+    const read = async () => {
+        let text;
+        try {
+            text = await readUtf8(store, USER_STATE_KEY);
+        }
+        catch (error) {
+            throw new UserStateError(`The user state ${USER_STATE_KEY} could not be read from S3: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (text === null)
+            return { state: { schemaVersion: 1 }, revision: digest(''), exists: false };
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new UserStateError(`The user state ${USER_STATE_KEY} in S3 is not valid JSON. Atlas will not overwrite it: fix or delete that object, then restart.`);
+        }
+        const parsed = UserStateSchema.safeParse(json);
+        if (!parsed.success)
+            throw new UserStateError(`The user state ${USER_STATE_KEY} in S3 is invalid (${parsed.error.issues.map(issue => `${issue.path.join('.') || '(document)'}: ${issue.message}`).join('; ')}). Atlas will not overwrite it: fix or delete that object, then restart.`);
+        // The document as written, once it is known to be valid: defaults are not filled in, so a setting nobody chose stays unchosen.
+        return { state: json, revision: digest(text), exists: true };
+    };
+    return {
+        read,
+        update(revision, change) {
+            const run = pending.then(async () => {
+                const held = await read();
+                if (held.revision !== revision)
+                    throw new UserStateError('Settings changed. Reload them before saving.');
+                const next = { ...change(held.state), schemaVersion: 1 };
+                const checked = UserStateSchema.safeParse(next);
+                if (!checked.success)
+                    throw new UserStateError(checked.error.issues.map(issue => `${issue.path.join('.') || '(document)'}: ${issue.message}`).join('; '));
+                const text = `${JSON.stringify(next, null, 2)}\n`;
+                await writeUtf8(store, USER_STATE_KEY, text, 'application/json');
+                return { state: next, revision: digest(text), exists: true };
+            });
+            pending = run.catch(() => undefined);
+            return run;
+        }
+    };
+}

package/docs/agents.md

@@ -144,7 +144,7 @@ workspace selection and test scripts. An existing `atlas.yml` not generated by A
 workflows may still need manual integration. Non-JavaScript suites need their language/tool setup in CI.
 
 Without a server, start with [local verification](quickstart.md). To run a server later, `atlas serve`
-starts one (`http://127.0.0.1:8080`, data in `./atlas-data`); [the server guide](server.md) covers configuration
+starts one (`http://127.0.0.1:8080`; it needs S3-compatible storage configured with the `ATLAS_S3_*` variables, see `.env.example`); [the server guide](server.md) covers configuration
 and authentication. Keep synthetic failure checks in a scratch store rather than a shared production report.
 
 ## What an agent can rely on

package/docs/deploying.md

@@ -2,14 +2,14 @@
 
 This is the production setup. A project runs **one Atlas server**. Developers' machines and every CI job send
 their results to it, as they finish or when they are done, and it shows everyone, developers and the business
-alike, the whole project at once, live. It keeps results on its own disk by default, or in an object-store bucket
-if you prefer; either way nothing is partitioned by run, branch or person: results are layered. The server's API,
+alike, the whole project at once, live. It keeps results (and all its user state) in an S3-compatible bucket and
+nowhere else; nothing is partitioned by run, branch or person: results are layered. The server's API,
 configuration and protocol are in **[the Atlas server](server.md)**; this page is the path to production.
 
 ```
   a developer's worktree ─┐                                       ┌─▶ developers   (browser, live)
-  a CI job, any branch ───┼─ atlas report publish|stream ─▶ SERVER ◀┤   atlas serve: keeps layers in ./atlas-data
-  a device lab, nightly ──┘   (immutable layers, over HTTP)  or S3  ├─▶ business      or in a bucket (--write)
+  a CI job, any branch ───┼─ atlas report publish|stream ─▶ SERVER ◀┤   atlas serve: keeps layers in S3
+  a device lab, nightly ──┘   (immutable layers, over HTTP)  ──▶ S3  ├─▶ business      (required, nothing else)
                                                                     └─▶ CI gate     atlas report status
 ```
 
@@ -18,7 +18,7 @@ Why this holds together:
 - **Publishing never conflicts.** A layer is one immutable file named by its content. Two machines that
   publish at once write different files; a retry writes the same one. There is no lock, no index to
   corrupt, nothing to merge.
-- **The server is replaceable.** What it knows is its write backend (a folder, or a bucket). Replace it, restore it
+- **The server is replaceable.** What it knows is in its bucket. Replace it, restore it
   from a backup, or run a copy on a laptop: they show the same report, because a report is a function of the
   layers ([the contract](report-contract.md)).
 - **One view.** The newest completed result of every check, in every environment, from anyone. A
@@ -36,13 +36,15 @@ Why this holds together:
 
 ## 1. Where results are kept
 
-**By default, on the server's own disk** (`./atlas-data`, or the volume you mount at `ATLAS_DATA`). Nothing else
-needs to exist: skip to [section 3](#3-send-results-from-ci-and-from-laptops). Back that folder up like any data
-directory; starting a new server on a restored copy shows the same report.
+**The server keeps everything in one S3-compatible bucket** (reports and user state, such as the garbage collection
+policy), set by the required `ATLAS_S3_ENDPOINT`, `ATLAS_S3_BUCKET`, `ATLAS_S3_REGION`, `ATLAS_S3_ACCESS_KEY_ID` and
+`ATLAS_S3_SECRET_ACCESS_KEY` variables ([details](server.md#required-s3-storage), template in
+[`.env.example`](https://github.com/crvouga/atlas/blob/main/.env.example)). Without them it refuses to start, listing
+every variable and what is wrong. There is no disk or database to fall back to, so the server is replaceable:
+a new one started on the same bucket shows the same report.
 
-**To keep results in a bucket instead** (so a replaced server loses nothing, or CI already has bucket access),
-name it and make it the place uploads go: `ATLAS_STORE=project=s3://my-bucket/atlas/my-project ATLAS_WRITE=project`.
-The rest of this section is that setup. A store is named by a URL. Keys never go in it.
+**Clients and CI** name stores by URL, and a client may publish straight to a bucket or folder as well as to the
+server. A store is named by a URL. Keys never go in it.
 
 | Store | URL |
 | --- | --- |
@@ -190,18 +192,16 @@ A run is uploaded only when its privacy scan passed: the same rule the static cl
 ## 4. The server
 
 ```sh
-atlas serve                    # ATLAS_STORE says where; listens on :8080
+atlas serve                    # ATLAS_S3_* says where; listens on :8080
 ```
 
-It serves the client, the report and the project's specs and runs from all configured backends. It also
-accepts uploads and announces new results on its event stream. Uploads go to `--data` by default;
-use a named `--store project=s3://… --write project` to put uploads in a shared bucket, with publisher permissions.
+It serves the client, the report and the project's specs and runs from its bucket. It also
+accepts uploads and announces new results on its event stream. The bucket's credentials need list, read, write and delete
+permissions (`atlas report policy` prints a least-privilege policy; delete is for the garbage collection you define in the UI).
 
 | Flag | Environment | Meaning |
 | --- | --- | --- |
-| `--store <url>` (repeatable) | `ATLAS_STORE` | Where layers are. Several stores are one report: repeat the flag, or separate them in the variable with commas or new lines. |
-| `--data <dir>` | `ATLAS_DATA` | Local upload backend. Default `./atlas-data`. |
-| `--write <id>` | `ATLAS_WRITE` | Backend that accepts uploads. Default `data`. |
+| | `ATLAS_S3_ENDPOINT`, `ATLAS_S3_BUCKET`, `ATLAS_S3_REGION`, `ATLAS_S3_ACCESS_KEY_ID`, `ATLAS_S3_SECRET_ACCESS_KEY` | **Required.** The S3-compatible bucket that holds all reports and user state. Optional: `ATLAS_S3_PREFIX`, `ATLAS_S3_PATH_STYLE`, `ATLAS_S3_SESSION_TOKEN`. |
 | `--port <n>` | `ATLAS_PORT` or `PORT` | Default 8080. `0` picks a free one. |
 | `--host <h>` | `ATLAS_HOST` or `HOST` | Default `127.0.0.1`. Listening beyond this machine requires tokens or `--insecure`. |
 | `--site <dir>` | `ATLAS_SITE` | The built client. Default: `./atlas-site`, else built once into `~/.cache/atlas/site`. |
@@ -228,9 +228,10 @@ updated `latest`. Pull request builds and failed publications are labelled accor
    Leave the start command unset: the image includes the server and the prebuilt viewer.
 2. Add `ATLAS_TOKEN` with a long random value (generate one with `openssl rand -hex 24`). It grants admin
    access; optionally add separate `ATLAS_PUBLISH_TOKEN` and `ATLAS_READ_TOKEN` for publishers and readers.
-3. Attach a volume at `/data` and set `RAILWAY_RUN_UID=0`: Railway mounts volumes as root, while the image
-   normally runs as `bun` ([Railway volume permissions](https://docs.railway.com/volumes#permissions)).
-   Keep one replica. The volume retains reports and server settings when the image is replaced.
+3. Add the five required storage variables (`ATLAS_S3_ENDPOINT`, `ATLAS_S3_BUCKET`, `ATLAS_S3_REGION`,
+   `ATLAS_S3_ACCESS_KEY_ID`, `ATLAS_S3_SECRET_ACCESS_KEY`) for a bucket you own. The service keeps nothing on its own
+   disk, so no volume is needed and a replaced image loses nothing; without the variables it exits and lists each one.
+   Keep one replica.
 4. Set the healthcheck path to `/readyz` and generate a public domain. The image listens on `0.0.0.0` and
    honors Railway's `PORT`; leave `ATLAS_PORT` unset. Open the domain and sign in with your token as the
    password (any username), or use the viewer's token sign-in.
@@ -244,8 +245,7 @@ Projects publish to that domain with `ATLAS_STORE=https://YOUR-DOMAIN` and their
 [sending results](#3-send-results-from-ci-and-from-laptops). Hosting Atlas needs no project checkout; publishing
 your project's test results still needs the integration described there.
 
-For bucket storage instead, set `ATLAS_STORE=project=s3://my-bucket/atlas/my-project`, `ATLAS_WRITE=project`,
-and the bucket credentials. Keep the `/data` volume for server settings and local state.
+Then open `/admin` to define the garbage collection policy; until you save one, nothing is deleted.
 
 ### Deploy without authentication
 
@@ -261,12 +261,11 @@ In Railway, create a **Docker image** service with:
 ghcr.io/crvouga/atlas-insecure:latest
 ```
 
-Leave the start command unset. Attach a persistent volume at `/data`, set `RAILWAY_RUN_UID=0`, keep one
+Leave the start command unset. Add the required `ATLAS_S3_*` storage variables, keep one
 replica, set the healthcheck to `/readyz` and generate a public domain. Leave `ATLAS_PORT` unset so Railway's
 `PORT` is used. Enable **Settings → Source → Configure Auto Updates → Anytime** to follow `latest`.
 Do not set `ATLAS_TOKEN`, `ATLAS_PUBLISH_TOKEN` or `ATLAS_READ_TOKEN`, or add `auth.tokens` to
-`/data/atlas.server.json`: configured tokens still enable authentication. When reusing a volume from an
-authenticated deployment, remove its saved auth tokens first. Open the domain directly, including `/admin`
+a configuration file: configured tokens still enable authentication. Open the domain directly, including `/admin`
 for settings (leave the token field blank and choose **Load settings**).
 
 Verify anonymous reads and uploads without an Authorization header:
@@ -287,7 +286,7 @@ leave its `ATLAS_TOKEN` unset. Use the same publishing commands described in
 For local Docker:
 
 ```sh
-docker run --pull always -p 8080:8080 -v atlas-data:/data ghcr.io/crvouga/atlas-insecure:latest
+docker run --pull always -p 8080:8080 --env-file .env ghcr.io/crvouga/atlas-insecure:latest
 ```
 
 Both images publish full commit tags for pinning or rollback. A new GHCR package must be made Public
@@ -297,10 +296,11 @@ once before Railway can pull without registry credentials; see
 ### Docker
 
 The same published image works anywhere Docker runs. It already contains the client (the same
-for every project: the server tells the page where its data is), and keeps results on the volume at `/data`:
+for every project: the server tells the page where its data is), and keeps nothing on its own disk: it needs the
+`ATLAS_S3_*` variables (copy `.env.example` to `.env` and fill it in):
 
 ```sh
-docker run --pull always -p 8080:8080 -v atlas-data:/data \
+docker run --pull always -p 8080:8080 --env-file .env \
   -e ATLAS_TOKEN=$(openssl rand -hex 24) ghcr.io/crvouga/atlas:latest
 ```
 
@@ -309,17 +309,15 @@ back, replace `latest` with the full commit SHA. To build from this repository,
 [`examples/deploy/Dockerfile`](https://github.com/crvouga/atlas/blob/main/examples/deploy/Dockerfile) is the
 alternative for building from an npm version or a local package tarball.
 
-For a bucket as the system of record add `-e ATLAS_STORE=project=s3://my-bucket/atlas/my-project -e ATLAS_WRITE=project -e AWS_REGION=us-east-1`.
-On ECS, EKS or EC2, attach the combined **both** policy (including `server/live/*` for producer leases) to the task, service account or
-instance and set no keys.
+The bucket's account needs the combined **both** policy (including `server/live/*` for producer leases and `server/state.json`
+for user state) plus `s3:DeleteObject` for garbage collection. The server does not use ambient AWS roles: pass the keys.
 
 **Try it on one machine.** [`examples/deploy/compose.yaml`](https://github.com/crvouga/atlas/blob/main/examples/deploy/compose.yaml)
-starts the published image on a volume; `compose.s3.yaml` starts it with an S3 server and a bucket as its storage.
+starts the published image with an S3 server (SeaweedFS) and a bucket as its storage; `compose.s3.yaml` is the same stack without tokens.
 Publish to `http://localhost:8080` from your project and open it.
 
 **Kubernetes.** [`examples/deploy/kubernetes.yaml`](https://github.com/crvouga/atlas/blob/main/examples/deploy/kubernetes.yaml):
-one copy (the server is a singleton for the project), results in the bucket, readiness on `/readyz`, an IRSA
-service account.
+one copy (the server is a singleton for the project), results in the bucket (keys from a Secret), readiness on `/readyz`.
 
 **Without a container.** `bun add -d @crvouga/atlas`, then `bunx atlas client build --no-data --out
 atlas-site` and `bunx atlas serve`. Everything it can be told is in
@@ -392,12 +390,13 @@ Narrow it by choice, per consumer, never by moving data:
   listing (one request per thousand layers) runs at the start and every 30 refreshes (five minutes by
   default), which is also how a layer recorded with an old timestamp is found. One small `GET` per new
   layer, once.
-- **Retention.** Atlas deletes nothing. `atlas report doctor` shows what the bucket holds.
-- **Disaster recovery.** The write backend (the data folder, or the bucket) is the only state. Back it up, replicate or version it as you
+- **Retention.** Atlas deletes nothing until you define a garbage collection policy in the UI (`/admin`); it is kept in the bucket as JSON and
+  then removes only superseded layers older than you allow ([details](server.md#user-state-and-garbage-collection)). `atlas report doctor` shows what the bucket holds.
+- **Disaster recovery.** The bucket is the only state (reports and user state). Back it up, replicate or version it as you
   do any data; a server is rebuilt from nothing in the time it takes to read the layers (below). It listens at once
   and answers `/readyz` 503 until it has, so a liveness probe never kills one that is still reading.
-- **A second bucket.** Another team's layers, a device lab, an archive: pass several `--store`s. They are one
-  report, attributed to the store they came from.
+- **A second bucket.** The server reads one bucket. To combine another team's layers or an archive into the
+  report, copy them in with `atlas report merge --into <store>`; clients and `atlas report status` may read several stores.
 
 ## 7. Performance
 

package/docs/reference/cli.md

@@ -16,7 +16,7 @@ atlas — executable statecharts
                [--no-retry] [--output <dir>]
   atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...
   atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]
-  atlas server [--data <dir>] [--port 8080] [--store <url>]...   one Atlas node: API, projects and client
+  atlas server [--port 8080]                                     one Atlas node: API, projects and client; needs ATLAS_S3_* (atlas serve --help)
   atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client
   atlas dev    [--port 5180]                                     develop the Atlas server and client on one host
   atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)
@@ -53,14 +53,18 @@ atlas init — integrate a project with an Atlas server
 ```text
 atlas serve: the Atlas server
 
-  atlas serve [--config atlas.server.json] [--data <dir>] [--port 8080] [--host 127.0.0.1]
-              [--store <url|id=url>]... [--write <id>] [--site <dir>]
+  atlas serve [--config atlas.server.json] [--port 8080] [--host 127.0.0.1] [--site <dir>]
               [--outline-branch <b>] [--branch <name>]... [--ignore-modified] [--refresh <seconds>]
               [--anonymous-read] [--insecure] [--no-log]
 
   One process serves the client and the API. Test results are uploaded to it from anywhere (laptops, CI) and it
-  shows everyone the combined report, live. It keeps its data in --data (default ./atlas-data) and can read more
-  backends (--store): S3, other servers, folders. Uploads go to the data folder unless --write names another.
+  shows everyone the combined report, live.
+
+  Storage is required. ALL reports and ALL user state (the garbage collection policy, saved settings) are kept in
+  S3-compatible object storage and nowhere else; there is no local-disk, in-memory or database fallback. Without
+  these environment variables the server prints every one of them with what is wrong, and exits with status 2:
+    ATLAS_S3_ENDPOINT  ATLAS_S3_BUCKET  ATLAS_S3_REGION  ATLAS_S3_ACCESS_KEY_ID  ATLAS_S3_SECRET_ACCESS_KEY
+  Optional: ATLAS_S3_PREFIX, ATLAS_S3_PATH_STYLE, ATLAS_S3_SESSION_TOKEN. See .env.example.
 
   Tokens (ATLAS_TOKEN admin, ATLAS_PUBLISH_TOKEN, ATLAS_READ_TOKEN, or "auth.tokens" in the config) are required
   to listen beyond this machine unless --insecure. Every option has an environment variable (docs/deploying.md).
@@ -71,11 +75,12 @@ atlas serve: the Atlas server
 ```text
 atlas dev: the Atlas server and the client, for working on either
 
-  atlas dev [--port 5180] [--host 127.0.0.1] [--data <dir>] [--store <url|id=url>]... [--config atlas.server.json]
+  atlas dev [--port 5180] [--host 127.0.0.1] [--config atlas.server.json]
 
   Starts the server (API only, on a port of its own) and the client's dev server, which proxies /api to it, so the
   browser talks to one host and a change to the client shows at once. In production `atlas serve` does both from
-  one process.
+  one process. Storage is the same as for `atlas serve`: the required ATLAS_S3_* environment variables name the S3
+  bucket that holds all reports and user state; without them it exits with status 2 and lists every variable.
 ```
 
 ## atlas report
@@ -91,6 +96,7 @@ atlas report — layered evidence for any kind of spec
                        [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]
                        [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...
                        [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]
+                       [--require-recordings]
   atlas report stream  [--store <dir|s3://…|https://atlas.example.com>] --producer <name> [--environment <name>]
                        [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...
                        [--run-id <id>] [--run-title <t>]
@@ -127,6 +133,10 @@ atlas report — layered evidence for any kind of spec
             Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own
             folder and each --attach-root, and never from a hidden file or a link out: a report is data from a
             test run, not instructions. One that is missing or not allowed is skipped with a warning.
+            --require-recordings   exit 1 when a check that declared recordingExpectation "required" has no
+                              uploaded video (absent, left out as too large or not allowed, or refused). The layer is
+                              still written and the checks keep their results; only this command fails. The receipt of
+                              what was uploaded (counts, sizes, checksums) is in the JSON result under layer.recordings.
             From a checkout with uncommitted changes the layer is marked "modified".
   stream    Send checks as they finish: one JSON object per line on standard input (the fields of one
             check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server

package/docs/reference/http-api.md

@@ -116,7 +116,7 @@ Responses: `200` Settings editor.; `401` No token, or an unknown one. Send `Auth
 
 `GET /api/settings` · role: admin
 
-Returns editable persisted storage/report settings, active settings, a revision, and configuration precedence. Authentication settings are excluded. Requires an admin Bearer token. Embedded applications may manage settings outside this API.
+Returns the editable report and live-run settings saved in the user state in S3, active settings, a revision, and configuration precedence. Storage and authentication settings are excluded. Requires an admin Bearer token. Embedded applications may manage settings outside this API.
 
 Responses: `200` Settings and revision.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `503` Configuration is managed by the embedding application.
 
@@ -124,12 +124,40 @@ Responses: `200` Settings and revision.; `401` No token, or an unknown one. Send
 
 `PUT /api/settings` · role: admin
 
-Replaces editable storage/report settings, preserving authentication and other file fields. Atomically persists a validated configuration; no report data is moved. Environment variables and flags override these values after restart. Requires an admin Bearer token, same-origin requests in browsers, and a current revision.
+Replaces the editable report and live-run settings in the user state in S3 (`server/state.json`), preserving the garbage collection policy and other fields. Persists a validated configuration; no report data is moved. Environment variables and flags override these values after restart. Requires an admin Bearer token, same-origin requests in browsers, and a current revision.
 
 - `If-Match` (header, required): The quoted revision returned by GET /api/settings.
 
 Responses: `200` Saved settings and new revision. Restart required.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` Settings changed; reload before saving.; `413` Settings exceed the body limit.; `422` Invalid configuration.; `428` A quoted settings revision is required.; `503` Configuration is managed by the embedding application.
 
+### Read the garbage collection policy
+
+`GET /api/settings/gc` · role: admin
+
+Returns the policy kept in the user state in S3 (`server/state.json`), or `policy: null, saved: false` when none has been saved yet, in which case garbage collection is off and nothing is deleted. Also returns the revision to send back when saving and the last pass over each project. Requires an admin Bearer token. If the stored user state is unreadable the answer is 503 and the stored object is left untouched.
+
+Responses: `200` The policy, its revision and the last passes.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `503` The user state in S3 cannot be read, or settings are managed by the embedding application.
+
+### Save the garbage collection policy
+
+`PUT /api/settings/gc` · role: admin
+
+Replaces the policy in the user state in S3 and leaves the rest of that document alone. The server reads the policy from S3 each time it collects, so the new policy applies at the next pass, without a restart. Requires an admin Bearer token, same-origin requests in browsers, and the current revision.
+
+- `If-Match` (header, required): The quoted revision returned by GET /api/settings/gc.
+
+Responses: `200` The saved policy and the new revision.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` The state changed; reload before saving.; `413` The body exceeds the limit.; `422` Invalid policy.; `428` A quoted revision is required.; `503` The user state in S3 cannot be read, or settings are managed by the embedding application.
+
+### Collect garbage now, or preview it
+
+`POST /api/settings/gc/run` · role: admin
+
+Applies the policy saved in S3 to every project now, instead of waiting for the schedule. Only report layers that were read and no longer decide any result, older than the policy allows and beyond its `keepLatest`, are deleted, with the captured files only they used. With `dryRun=1` nothing is deleted and each run reports what it would delete (a disabled policy is previewed as if enabled). Answers 409 when no policy has been saved, and, without `dryRun`, when the saved policy is disabled. Requires an admin Bearer token and a same-origin request in browsers.
+
+- `dryRun` (query): `1` or `true` to only count what would be deleted.
+
+Responses: `200` One run per project.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` No policy has been saved, or it is disabled.
+
 ### Is the process up
 
 `GET /healthz` · role: none

package/docs/reference/reports.md

@@ -276,7 +276,9 @@ recursively), and hands their bytes over as `data` with a `contentType` guessed
 attachment gave none.
 
 A file that is missing, not allowed or too large is left out with a warning: evidence that could not be
-found never stops the results from being published. Attachments without a `path` are kept untouched.
+found never stops the results from being published. The exception in kind is a video of a check that declared
+`recordingExpectation: "required"`: it stays as an attachment without bytes whose `omitted` says why (`not-found`,
+`not-allowed`, `too-large`, `over-budget`), so the recording receipt can name the gap. Attachments without a `path` are kept untouched.
 
 - `holder`: A check, step, attempt or any object that may have `attachments`, `steps` and `attempts`.
 
@@ -1747,11 +1749,34 @@ export type LayerHeader = {
   readonly execution: string;
   /** What the run as a whole carries: its logs, links and labels. */
   readonly evidence?: EvidenceSummary;
+  /** Counts from the layer's recording receipt: how many expected recordings were published. Absent when the layer declared no expectations: its completeness is unknown, not complete. Never changes a status. */
+  readonly recordings?: RecordingCounts;
 };
 ```
 
 A report layer's origin and totals. Its checks are read separately, once.
 
+#### `RecordingCounts`
+
+```ts
+export type RecordingCounts = {
+  /** Checks that required a recording: `uploaded + referenced + skipped + unresolved`. */
+  readonly expected: number;
+  /** Stored in the layer, with a checksum. */
+  readonly uploaded: number;
+  /** Given only by `uri`: Atlas cannot vouch for it. */
+  readonly referenced: number;
+  /** Captured but left out, with a reason (too large, not allowed…). */
+  readonly skipped: number;
+  /** No video was attached at all. */
+  readonly unresolved: number;
+  /** Intentionally unrecorded checks: neither expected nor missing. */
+  readonly notApplicable: number;
+};
+```
+
+How many recordings a layer expected and what became of them (see `RecordingReceipt`).
+
 #### `LayerRow`
 
 ```ts
@@ -1775,6 +1800,8 @@ export type LayerRow = {
   readonly durationMs: number | null;
   /** What this result carries beyond its outcome. Absent when nothing. */
   readonly evidence?: EvidenceSummary;
+  /** What became of this check's expected recording: `uploaded`, `referenced`, `skipped`, `unresolved` or `not-applicable`, with a reason when it is not uploaded. Absent when the check declared no expectation. Independent of `status`. */
+  readonly recording?: { readonly state: string; readonly reason?: string };
 };
 ```
 
@@ -2775,6 +2802,76 @@ export function neighborStepFrame(
 
 First frame of the next / previous step (skipping same-step frames).
 
+### Layer garbage collection
+
+Source: `packages/reports/src/garbage.ts`. Import: `@crvouga/atlas/reports/garbage`
+
+Applies a garbage collection policy (`GcPolicy`, chosen by a person in the Atlas UI and kept in the user state) to the
+layers in a store. Atlas is otherwise deletion-free, so this is deliberately conservative: a layer is deleted only when
+(1) the caller says the report has read it and every result it carries has been replaced by a newer layer (`eligible`),
+(2) it was recorded longer ago than the policy allows, and (3) it is not among the newest `keepLatest` layers. Deleting
+it therefore cannot change the combined report. Its catalog entry goes first, so nothing visible ever points at a
+missing manifest; its manifest next; then the captured-file blobs that no remaining layer refers to. If any remaining
+layer cannot be read, no blob is deleted: what cannot be read is unknown, never unused. Specs, runs and commit
+inventories are not touched.
+
+See docs/server.md#user-state-and-garbage-collection
+
+#### `GcCandidate`
+
+```ts
+export type GcCandidate = { readonly id: string; readonly catalogKey: string; readonly recordedAtMs: number };
+```
+
+One layer the policy would delete.
+
+#### `GcPlan`
+
+```ts
+export type GcPlan = {
+  /** Layers to delete, oldest first. */
+  readonly candidates: readonly GcCandidate[];
+  /** Layers in the catalog that stay. */
+  readonly kept: number;
+};
+```
+
+What a policy would delete from a store right now.
+
+#### `GcOutcome`
+
+```ts
+export type GcOutcome = { readonly deletedLayers: number; readonly deletedBlobs: number };
+```
+
+The outcome of applying a plan.
+
+#### `planGarbage`
+
+```ts
+export async function planGarbage(store: ObjectStore, input: { readonly policy: GcPolicy; readonly nowMs: number; readonly eligible: ReadonlySet<string> }): Promise<GcPlan>
+```
+
+Decides which layers a policy deletes, without deleting anything. `eligible` is the set of layer ids the caller has
+read and knows no longer decide any result (`ReportIndex.superseded()`); a layer not in it is never a candidate.
+Lists the catalog only. With `policy.enabled === false` the plan is empty.
+
+**Example**
+
+```ts
+const plan = await planGarbage(store, { policy, nowMs: Date.now(), eligible: index.superseded() });
+```
+
+#### `collectGarbage`
+
+```ts
+export async function collectGarbage(store: ObjectStore, plan: GcPlan): Promise<GcOutcome>
+```
+
+Deletes the layers of a plan, then the blobs only they used. Store errors throw after whatever was already deleted;
+running the same plan again finishes the job, because every delete is idempotent and the catalog entry (what
+makes a layer visible) always goes before the content.
+
 ### URL hash routes of the reports viewer
 
 Source: `packages/reports/src/hash.ts`. Import: `@crvouga/atlas/reports/hash`
@@ -3983,7 +4080,7 @@ String choices (such as `{ device: 'iphone-15' }`) that make a result its own sl
 #### `LayerExtras`
 
 ```ts
-export type LayerExtras = Partial<Pick<import('../../schema/src/layer').LayerDocument, 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions'>>;
+export type LayerExtras = Partial<Pick<import('../../schema/src/layer').LayerDocument, 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions' | 'recordings'>>;
 ```
 
 What a layer may carry as a whole. All optional and open: see docs/extending.md.
@@ -5381,6 +5478,69 @@ export function contentTypeForMedia(media: string): string
 
 The media type for a snapshot media kind (`html`, `png`, `json`, `text`, `bytes`, `video`); an unknown kind is `application/octet-stream`.
 
+### Recording receipts
+
+Source: `packages/reports/src/recording-receipt.ts`. Import: `@crvouga/atlas/reports/recording-receipt`
+
+Answers "did the recordings we expected get published?" apart from "did the tests pass?". `recordingReceipt` reads the
+checks a producer is about to publish (after their files were stored) and describes, per check that declared a
+`recordingExpectation`, whether its video was uploaded, only referenced, left out (with a reason) or never attached.
+`recordingCompleteness` reduces the winning results of a report to the figures `atlas report status` prints. Neither
+reads a clock or the environment, and neither changes a status, a slot or a winner: a receipt describes publication, it
+does not decide a result. A layer with no receipt is Unknown, never Complete.
+
+See docs/rich-evidence.md#recording-completeness
+
+#### `isVideoAttachment`
+
+```ts
+export function isVideoAttachment(attachment: Loose): boolean
+```
+
+Is this attachment a screen recording: a role of `video`, or a `video/*` media type?
+
+#### `recordingReceipt`
+
+```ts
+export function recordingReceipt(checks: readonly Loose[]): RecordingReceipt | undefined
+```
+
+The receipt for the checks of one layer, or `undefined` when no check declares a `recordingExpectation` (the layer then
+claims nothing). Call it with checks whose attachment bytes are already stored (`bundleKey`, `bytes` and `sha256` set).
+
+A `required` check is `uploaded` when any video of it has stored bytes, `referenced` when one has only a `uri`,
+`skipped` when its videos were left out (the attachment's `omitted` is the reason) and `unresolved` when it has no
+video at all. A `not-applicable` check is listed but is neither expected nor missing. Items are sorted by check id so the
+same input is always the same receipt.
+
+#### `RecordingResult`
+
+```ts
+export type RecordingResult = {
+  readonly spec: string | null;
+  readonly check: string;
+  readonly environment: string | null;
+  readonly layer: string;
+  /** Whether the layer the result came from carried a receipt. */
+  readonly hasReceipt: boolean;
+  /** The result's item in that receipt, when its check declared an expectation. */
+  readonly recording?: { readonly state: string; readonly reason?: string };
+};
+```
+
+One result as {@link recordingCompleteness} reads it.
+
+#### `recordingCompleteness`
+
+```ts
+export function recordingCompleteness(results: readonly RecordingResult[]): RecordingCompleteness
+```
+
+Reduces the winning results of a report to its recording completeness. `incomplete` when any expected recording is
+skipped or unresolved; otherwise `unknown` when a contributing layer has no receipt (nothing is claimed for it, and a
+report with no results at all is unknown too); otherwise `complete` when something was expected and `none-expected` when
+nothing was. Gaps are sorted so the output never depends on read order.
+
 ### Remote commit report
 
 Source: `packages/reports/src/remote-report.ts`. Import: `@crvouga/atlas/reports/remote-report`
@@ -5603,6 +5763,7 @@ It reads only immutable layers (`layers/index/…`), which is what makes "read o
 - `json(): { readonly version: string; readonly text: string }` — The report as JSON text: exactly what `JSON.stringify({ ...snapshot(), active: [] })` writes, put together from the text of each layer, which is written once. `active` is what a store without live runs always sends: none.
 - `delta(since: string): { readonly text: string; readonly version: string } | null` — What differs between the report a viewer holds (named by its version) and the current one: the layers that changed in full, and the ids of those that no longer hold a winner. Null when that version is not remembered, and the viewer should ask for the whole report. See `applyEffectiveDelta`.
 - `get history(): TestHistory { return this.#history; }` — Every recorded result of every test and every run, as layers were folded in: what the test catalog, a test's history and the run list are built from. Read-only for callers; `history.rev` changes whenever a layer is taken in.
+- `superseded(): ReadonlySet<string>` — The ids of layers this index has read and that no longer decide any result. Removing one from its store cannot change the report (every slot it filled is held by a newer layer), which is what makes it safe for garbage collection to delete. A layer that failed to load, is hidden by `include`, or still holds a result is not here.
 - `stats()` — For `/readyz` and logs.
 
 ### Test loading state
@@ -5756,6 +5917,8 @@ checks (or none completed), failed checks, running checks, specs without results
 each required environment with no checks (the name is normalised, so `iOS` means `ios`), then every notice of the
 report (an unreadable layer or backend). `failing` lists each failed or running winner, in a fixed order that does
 not depend on read order; diagnostic `performance` checks are left out unless nothing else was recorded.
+`recordings` reports recording completeness of the same results apart from `ok`: an incomplete or unknown
+completeness never changes the gate (use `atlas report publish --require-recordings` to fail on a missing video).
 
 **Example**