@crvouga/atlas 0.17.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog: @crvouga/atlas
 
+## 1.0.0 (2026-10-28)
+
+### ⚠️ Breaking changes
+
+- store all reports and user state in S3 only, with a GC policy set in the UI (#51) ([157ea67](https://github.com/crvouga/atlas/commit/157ea6734439f9d890b3de992aad72f4bca2d597))
+
 ## 0.17.0 (2026-10-28)
 
 ### Features

package/README.md

@@ -18,7 +18,7 @@ backends, and tells you in one command whether the product still does what it wa
   versioned layer format with a golden fixture, and an `ObjectStore` interface any bucket fits.
 - **One node, many projects.** `atlas server` runs a Bun API and serves the Atlas client from the same host. Reports, specs, recordings and live progress are partitioned by project slug.
   Every laptop and CI job sends results to it as they finish (`atlas report publish`, or `atlas report stream` while
-  a suite runs), it keeps them on its own disk (or in S3, R2, MinIO), and every client sees the combined report
+  a suite runs), it keeps them in an S3-compatible bucket (AWS S3, R2, MinIO; required, nothing else is used), and every client sees the combined report
   update live, receiving only what changed ([the server](docs/server.md), [deploying](docs/deploying.md)).
 - **Fast and fail-closed.** Publishing is two small writes. A thousand layers of a hundred checks
   combine in about a second. An unreadable layer, a downed backend or a check still running is never
@@ -67,7 +67,7 @@ bun atlas          # starts the project-agnostic Atlas node at http://localhost:
 bun example:run    # runs tests and streams results, current steps and progress as they execute
 ```
 
-The server starts independently with data in `./atlas-data`; it never loads example specs or reports. `bun example:run` publishes the Todo example under `todo-app`. Select a project using the top-right picker, then use the spec dropdown breadcrumbs to navigate. Other projects set `ATLAS_SERVER_URL`, `ATLAS_PROJECT` (for example `checkout-service`) and their publish token. Every uploader talks to the node; storage credentials stay on the server.
+The server starts independently; it never loads example specs or reports. **It needs S3-compatible storage** (see [Required S3 storage](#required-s3-storage)): copy `.env.example` to `.env` and fill in the `ATLAS_S3_*` variables first, or it exits at once and lists every one that is missing. `bun example:run` publishes the Todo example under `todo-app`. Select a project using the top-right picker, then use the spec dropdown breadcrumbs to navigate. Other projects set `ATLAS_SERVER_URL`, `ATLAS_PROJECT` (for example `checkout-service`) and their publish token. Every uploader talks to the node; storage credentials stay on the server.
 
 Every Gherkin scenario runs, including sharing and renaming. Test reports show running spinners,
 live step logs and a Running status filter. Producers send heartbeats every
@@ -88,8 +88,11 @@ or package installation. [`latest` on GHCR](https://github.com/users/crvouga/pac
 the newest checked `main` image, independently of npm releases.
 
 1. Leave the start command unset. Add a long random secret as `ATLAS_TOKEN` (at least 12 characters;
-   use 48 or more) and set `RAILWAY_RUN_UID=0` for [Railway volume permissions](https://docs.railway.com/volumes#permissions).
-2. Attach a persistent volume at `/data` and keep one replica so reports and server settings survive updates.
+   use 48 or more).
+2. 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`; see [Required S3 storage](#required-s3-storage)) for a
+   bucket you own, and keep one replica. All reports and settings live in that bucket, so no volume is needed and
+   the service refuses to start, listing what is missing, without them.
 3. Set the healthcheck path to `/readyz` and generate a public domain. Railway supplies `PORT`;
    leave `ATLAS_PORT` unset. Open the domain and sign in with the token as the password (any username).
 4. Enable **Settings → Source → Configure Auto Updates → Anytime** to follow `latest`.
@@ -100,7 +103,7 @@ For the exact image from a run, open **[CI](https://github.com/crvouga/atlas/act
 run → Summary → Atlas CI**. The summary includes a copyable full commit tag, the immutable registry digest,
 whether that run updated `latest`, all job results, npm release details and artifact links. Use the commit
 tag to pin or roll back a deployment. The [deployment guide](docs/deploying.md#run-it) covers optional reader
-and publisher tokens, bucket storage and sending results from your projects.
+and publisher tokens, the S3 bucket and sending results from your projects.
 
 ### Deploy without authentication
 
@@ -231,8 +234,8 @@ flag).
 
 **The server** is `atlas serve`: one process that serves the client, takes in results and streams the report to
 every client. Point `ATLAS_STORE` at it and every developer's laptop and every CI job sends results with the same
-commands that write to a folder; everyone then looks at one report, live. Results are kept in its data folder
-unless you choose a bucket. `atlas dev` runs the same server with the client's dev server in front, so
+commands that write to a folder; everyone then looks at one report, live. Results are kept in an S3-compatible bucket
+and nowhere else ([required storage](#required-s3-storage)). `atlas dev` runs the same server with the client's dev server in front, so
 development is one host too. See [the server](docs/server.md) and
 [running Atlas for a project](docs/deploying.md).
 
@@ -240,7 +243,7 @@ Deploy the server using the [Railway setup above](#deploy-to-railway-without-cod
 [deployment guide](docs/deploying.md#run-it) for other hosts.
 
 ```sh
-atlas serve                                          # the project's server, at :8080 (ATLAS_TOKEN says who may upload)
+atlas serve                                          # the project's server, at :8080 (needs ATLAS_S3_*; ATLAS_TOKEN says who may upload)
 
 export ATLAS_STORE=https://atlas.example.com ATLAS_TOKEN=…   # on every laptop and CI job
 atlas report publish --producer unit --junit out.xml --specs ./specs     # when a suite is done
@@ -248,6 +251,47 @@ my-suite --json | atlas report stream --producer e2e --environment ios  # or as
 atlas report status --branch main --ignore-modified  # the gate, answered by the server
 ```
 
+### Required S3 storage
+
+The Atlas server keeps **all reports and all user state in S3-compatible object storage, and nowhere else**: no local
+disk, no memory, no database, no browser storage. *User state* is one JSON document in the bucket,
+`server/state.json`, that holds the **garbage collection policy** (defined in the Atlas UI at `/admin`) and the
+settings saved there. The server reads the policy from that document each time it collects. Until someone saves a
+policy, garbage collection is off and nothing is ever deleted.
+
+Because of that, the storage settings are **required environment variables with no defaults** (see
+[`.env.example`](https://github.com/crvouga/atlas/blob/main/.env.example)), and the server **refuses to start** (exit status 2) without them:
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `ATLAS_S3_ENDPOINT` | yes | S3 API endpoint, e.g. `https://s3.eu-west-1.amazonaws.com` |
+| `ATLAS_S3_BUCKET` | yes | Bucket for reports and user state; it must already exist |
+| `ATLAS_S3_REGION` | yes | Bucket region (`auto` for Cloudflare R2) |
+| `ATLAS_S3_ACCESS_KEY_ID` | yes | Access key of an account that may list, read, write and delete in the bucket |
+| `ATLAS_S3_SECRET_ACCESS_KEY` | yes | Its secret key |
+| `ATLAS_S3_PREFIX` | no | Folder inside the bucket (default: the bucket root) |
+| `ATLAS_S3_PATH_STYLE` | no | `1` (default) for `endpoint/bucket/key`, `0` for virtual-hosted style |
+| `ATLAS_S3_SESSION_TOKEN` | no | Only for temporary credentials |
+
+If a variable is missing or malformed, or S3 rejects the settings, Atlas lists **every** variable with `[MISSING]`
+or `[INVALID]` next to the ones that are wrong, says why storage is required, and exits non-zero:
+
+```text
+==============================================================================
+  ATLAS CANNOT START: S3 STORAGE IS NOT USABLE
+==============================================================================
+  Why:    the S3 configuration is missing or invalid.
+  Reason: Atlas stores ALL reports and ALL user state (the garbage collection policy and saved
+          settings) in S3-compatible object storage, and nowhere else. …
+  Required environment variables:
+  [MISSING] ATLAS_S3_ENDPOINT           S3 API endpoint of the object storage service
+  [ok]      ATLAS_S3_BUCKET             Bucket that holds reports and user state; it must already exist
+  …
+```
+
+See [the server guide](docs/server.md#required-s3-storage) for the details and
+[user state and garbage collection](docs/server.md#user-state-and-garbage-collection) for how the policy works.
+
 **The client** shows each spec (Gherkin, Quint, DMN, Alloy, OpenSLO, and the rest by file type) with
 its combined result per environment and the layer behind it. See
 [integrating Atlas](docs/integrating.md#6-browse-it).

package/dist/core/src/cli.d.ts

@@ -9,6 +9,6 @@
  * @see docs/reference/cli.md
  */
 /** The text `atlas --help` prints: every command, and the flags of the statechart commands. */
-export declare const USAGE = "atlas \u2014 executable statecharts\n\n  atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]\n  atlas plan   [--config atlas.config.ts] [--state <name>]\n  atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]\n               [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]\n               [--no-retry] [--output <dir>]\n  atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...\n  atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]\n  atlas server [--data <dir>] [--port 8080] [--store <url>]...   one Atlas node: API, projects and client\n  atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client\n  atlas dev    [--port 5180]                                     develop the Atlas server and client on one host\n  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)\n  atlas report publish|stream|status|merge|doctor|policy \u2026       layered evidence for any kind of spec (atlas report --help)\n\n  --workers       path attempts that run at once (default: one per CPU, capped by the driver)\n  --seed          only paths that start from this seed (\"start\" for paths setup starts); repeatable\n  --shard 2/4     run the second quarter of the plan; merge the shards' runs afterwards\n  --rerun-failed  keep the newest run's passed paths and run only the rest\n";
+export declare const USAGE = "atlas \u2014 executable statecharts\n\n  atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]\n  atlas plan   [--config atlas.config.ts] [--state <name>]\n  atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]\n               [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]\n               [--no-retry] [--output <dir>]\n  atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...\n  atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]\n  atlas server [--port 8080]                                     one Atlas node: API, projects and client; needs ATLAS_S3_* (atlas serve --help)\n  atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client\n  atlas dev    [--port 5180]                                     develop the Atlas server and client on one host\n  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)\n  atlas report publish|stream|status|merge|doctor|policy \u2026       layered evidence for any kind of spec (atlas report --help)\n\n  --workers       path attempts that run at once (default: one per CPU, capped by the driver)\n  --seed          only paths that start from this seed (\"start\" for paths setup starts); repeatable\n  --shard 2/4     run the second quarter of the plan; merge the shards' runs afterwards\n  --rerun-failed  keep the newest run's passed paths and run only the rest\n";
 /** Runs `atlas` with `argv` (default: the process arguments) and returns the exit code. Throws for a command that is wrong, which the `atlas` binary reports as a message and exit code 2. */
 export declare function main(argv?: string[]): Promise<number>;

package/dist/core/src/cli.js

@@ -28,7 +28,7 @@ export const USAGE = `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)

package/dist/reports/src/garbage.d.ts

@@ -0,0 +1,39 @@
+import type { ObjectStore } from './object-store.js';
+import type { GcPolicy } from '../../schema/src/user-state.js';
+/** One layer the policy would delete. */
+export type GcCandidate = {
+    readonly id: string;
+    readonly catalogKey: string;
+    readonly recordedAtMs: number;
+};
+/** What a policy would delete from a store right now. */
+export type GcPlan = {
+    /** Layers to delete, oldest first. */
+    readonly candidates: readonly GcCandidate[];
+    /** Layers in the catalog that stay. */
+    readonly kept: number;
+};
+/** The outcome of applying a plan. */
+export type GcOutcome = {
+    readonly deletedLayers: number;
+    readonly deletedBlobs: number;
+};
+/**
+ * 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
+ * const plan = await planGarbage(store, { policy, nowMs: Date.now(), eligible: index.superseded() });
+ */
+export declare function planGarbage(store: ObjectStore, input: {
+    readonly policy: GcPolicy;
+    readonly nowMs: number;
+    readonly eligible: ReadonlySet<string>;
+}): Promise<GcPlan>;
+/**
+ * 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.
+ */
+export declare function collectGarbage(store: ObjectStore, plan: GcPlan): Promise<GcOutcome>;

package/dist/reports/src/garbage.js

@@ -0,0 +1,82 @@
+/**
+ * @module Layer garbage collection
+ *
+ * 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
+ */
+import { eachLimited } from './completion-order.js';
+import { LAYER_INDEX, layerKey, readLayer } from './layer-store.js';
+const DAY_MS = 86_400_000;
+const CATALOG = /^layers\/index\/(\d{16})-([0-9a-f]{64})\.json$/;
+/**
+ * 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
+ * const plan = await planGarbage(store, { policy, nowMs: Date.now(), eligible: index.superseded() });
+ */
+export async function planGarbage(store, input) {
+    const entries = (await store.listKeys(LAYER_INDEX)).flatMap(key => {
+        const match = CATALOG.exec(key);
+        return match ? [{ id: match[2], catalogKey: key, recordedAtMs: Number.MAX_SAFE_INTEGER - Number(match[1]) }] : [];
+    });
+    // Catalog keys sort newest first (the time is inverted), so the layers to always keep are the first `keepLatest`.
+    entries.sort((a, b) => b.recordedAtMs - a.recordedAtMs || (a.id < b.id ? -1 : 1));
+    if (!input.policy.enabled)
+        return { candidates: [], kept: entries.length };
+    const cutoff = input.nowMs - input.policy.maxAgeDays * DAY_MS;
+    const candidates = entries.slice(input.policy.keepLatest).filter(entry => entry.recordedAtMs < cutoff && input.eligible.has(entry.id));
+    return { candidates: candidates.reverse(), kept: entries.length - candidates.length };
+}
+/**
+ * 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.
+ */
+export async function collectGarbage(store, plan) {
+    if (!plan.candidates.length)
+        return { deletedLayers: 0, deletedBlobs: 0 };
+    const doomed = new Set(plan.candidates.map(candidate => candidate.id));
+    // Which blobs the doomed layers used, read before anything is deleted. A layer that cannot be read stays: unknown is not garbage.
+    const used = new Map();
+    const readable = [];
+    await eachLimited(plan.candidates, 16, async (candidate) => {
+        const layer = await readLayer(store, candidate.id).catch(() => null);
+        if (!layer)
+            return;
+        used.set(candidate.id, new Set(Object.values(layer.bundle).flatMap(file => file.parts.map(part => part.blob))));
+        readable.push(candidate);
+    });
+    if (!readable.length)
+        return { deletedLayers: 0, deletedBlobs: 0 };
+    await store.deleteMany(readable.map(candidate => candidate.catalogKey));
+    await store.deleteMany(readable.map(candidate => layerKey(candidate.id)));
+    const removed = new Set(readable.map(candidate => candidate.id));
+    const orphanable = new Set([...removed].flatMap(id => [...used.get(id)]));
+    // Blobs that any remaining layer still points at must stay. If a remaining layer cannot be read, keep every blob.
+    const remaining = (await store.listKeys(LAYER_INDEX)).flatMap(key => CATALOG.exec(key)?.[2] ?? []).filter(id => !removed.has(id));
+    let unreadable = false;
+    await eachLimited(remaining, 16, async (id) => {
+        const layer = await readLayer(store, id).catch(() => null);
+        if (!layer) {
+            unreadable = true;
+            return;
+        }
+        for (const file of Object.values(layer.bundle))
+            for (const part of file.parts)
+                orphanable.delete(part.blob);
+    });
+    if (unreadable)
+        return { deletedLayers: removed.size, deletedBlobs: 0 };
+    await store.deleteMany([...orphanable]);
+    return { deletedLayers: removed.size, deletedBlobs: orphanable.size };
+}

package/dist/reports/src/report-index.d.ts

@@ -93,6 +93,12 @@ export declare class ReportIndex {
      * and the run list are built from. Read-only for callers; `history.rev` changes whenever a layer is taken in.
      */
     get history(): TestHistory;
+    /**
+     * 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.
+     */
+    superseded(): ReadonlySet<string>;
     /** For `/readyz` and logs. */
     stats(): {
         backends: number;

package/dist/reports/src/report-index.js

@@ -50,6 +50,8 @@ export class ReportIndex {
     /** Layers that stopped holding any winner, and when. Older removals are forgotten; `#forgotten` says how far. */
     #removed = [];
     #forgotten = 0;
+    /** Layers that were read, took part in the report, and no longer decide any result: all their checks were replaced by newer layers. */
+    #superseded = new Set();
     #refreshing = null;
     #timer = null;
     #refreshedAt = 0;
@@ -248,6 +250,9 @@ export class ReportIndex {
         if (wins.size) {
             this.#held.set(id, { evidence, wins, rev: ++this.#rev, entry: null, json: null, digest: null });
         }
+        else {
+            this.#superseded.add(id);
+        }
     }
     /** What this layer sends has changed. */
     #touch(held) {
@@ -264,6 +269,7 @@ export class ReportIndex {
             return;
         }
         this.#held.delete(layerId);
+        this.#superseded.add(layerId);
         this.#removed.push({ id: layerId, rev: ++this.#rev });
         if (this.#removed.length > REMEMBERED_REMOVALS)
             this.#forgotten = this.#removed.splice(0, this.#removed.length - REMEMBERED_REMOVALS).at(-1).rev;
@@ -342,6 +348,14 @@ export class ReportIndex {
     get history() {
         return this.#history;
     }
+    /**
+     * 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.
+     */
+    superseded() {
+        return this.#superseded;
+    }
     /** For `/readyz` and logs. */
     stats() {
         return { backends: this.#backends.length, layers: this.#attribution.size, slots: this.#winners.size, holding: this.#held.size, failed: this.#failed.size, refreshedAt: this.#refreshedAt };

package/dist/schema/src/index.d.ts

@@ -15,6 +15,7 @@ export * from './spec.js';
 export * from './report-sources.js';
 export * from './layer.js';
 export * from './server-config.js';
+export * from './user-state.js';
 export * from './api.js';
 export * from './cli-results.js';
 export * from './live-run.js';

package/dist/schema/src/index.js

@@ -15,6 +15,7 @@ export * from './spec.js';
 export * from './report-sources.js';
 export * from './layer.js';
 export * from './server-config.js';
+export * from './user-state.js';
 export * from './api.js';
 export * from './cli-results.js';
 export * from './live-run.js';

package/dist/schema/src/server-config.d.ts

@@ -2,9 +2,10 @@
  * @module Server configuration schema
  *
  * The schema of `atlas.server.json`, the file that configures `atlas serve` and `atlas dev`: where to listen, which
- * folder and further backends hold the data, which bearer tokens may read, publish or administer, and limits. Every
- * field has a default, so an empty file is a working server. Unlike the report format, unknown keys are an error, so
- * a typo is reported instead of ignored. Flags and environment variables override the file.
+ * bearer tokens may read, publish or administer, and limits. Where reports are kept is not here: the server stores
+ * everything in S3-compatible storage named by required `ATLAS_S3_*` environment variables, never in this file.
+ * Every field has a default. Unlike the report format, unknown keys are an error, so a typo (or a removed `data`,
+ * `backends` or `write` key) is reported instead of ignored. Flags and environment variables override the file.
  *
  * @see docs/deploying.md
  * @see docs/server.md
@@ -18,16 +19,6 @@ export declare const ServerRoleSchema: z.ZodEnum<{
 }>;
 /** One of the roles of `ServerRoleSchema`. */
 export type ServerRole = z.infer<typeof ServerRoleSchema>;
-/**
- * A further store the server reads together with its data folder, and optionally writes to: an id, a label and a
- * location URL.
- */
-export declare const ServerBackendSchema: z.ZodObject<{
-    id: z.ZodString;
-    label: z.ZodOptional<z.ZodString>;
-    url: z.ZodString;
-    write: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
 /**
  * A bearer token: a name for logs, a role, and the token itself or the name of the environment variable that holds it
  * (exactly one of the two).
@@ -43,21 +34,12 @@ export declare const ServerTokenSchema: z.ZodObject<{
     tokenEnv: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /**
- * The whole `atlas.server.json`: listening address, data folder, backends and write target, authentication, the
- * viewer to serve, which layers take part in the report, refresh and heartbeat intervals, request limits and logging.
+ * The whole `atlas.server.json`: listening address, authentication, the viewer to serve, which layers take part in the report, refresh and heartbeat intervals, request limits and logging.
  */
 export declare const ServerConfigSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     host: z.ZodDefault<z.ZodString>;
     port: z.ZodDefault<z.ZodNumber>;
-    data: z.ZodDefault<z.ZodString>;
-    backends: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        label: z.ZodOptional<z.ZodString>;
-        url: z.ZodString;
-        write: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strict>>>;
-    write: z.ZodOptional<z.ZodString>;
     auth: z.ZodDefault<z.ZodObject<{
         tokens: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -93,17 +75,9 @@ export declare const ServerConfigSchema: z.ZodObject<{
 export type ServerConfig = z.output<typeof ServerConfigSchema>;
 /** A server configuration as written, before defaults are applied. */
 export type ServerConfigInput = z.input<typeof ServerConfigSchema>;
-/** Storage and report settings editable by an admin. Authentication, listeners and the served site stay deployment-owned. Replaces the editable portion of the file; omitted fields use defaults after restart. */
+/** Report and live-run settings editable by an admin. Storage, authentication, listeners and the served site stay deployment-owned. Replaces the saved portion of the user state; omitted fields use defaults after restart. */
 export declare const ServerEditableSettingsSchema: z.ZodObject<{
-    data: z.ZodOptional<z.ZodDefault<z.ZodString>>;
-    backends: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        label: z.ZodOptional<z.ZodString>;
-        url: z.ZodString;
-        write: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strict>>>>;
     log: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-    write: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     outlineBranch: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     include: z.ZodOptional<z.ZodDefault<z.ZodObject<{
         branches: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -119,19 +93,11 @@ export declare const ServerEditableSettingsSchema: z.ZodObject<{
     runStallSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     heartbeatSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
 }, z.core.$strict>;
-/** The settings API response: persisted editable configuration, active values, concurrency revision and restart/precedence guidance. Authentication token settings are excluded. */
+/** The settings API response: editable configuration saved in the user state in S3, active values, concurrency revision and restart/precedence guidance. Authentication token settings are excluded. */
 export declare const ServerSettingsSnapshotSchema: z.ZodObject<{
     revision: z.ZodString;
     settings: z.ZodObject<{
-        data: z.ZodOptional<z.ZodDefault<z.ZodString>>;
-        backends: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            label: z.ZodOptional<z.ZodString>;
-            url: z.ZodString;
-            write: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strict>>>>;
         log: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        write: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         outlineBranch: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         include: z.ZodOptional<z.ZodDefault<z.ZodObject<{
             branches: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -148,15 +114,7 @@ export declare const ServerSettingsSnapshotSchema: z.ZodObject<{
         heartbeatSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     }, z.core.$strict>;
     active: z.ZodObject<{
-        data: z.ZodOptional<z.ZodDefault<z.ZodString>>;
-        backends: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            label: z.ZodOptional<z.ZodString>;
-            url: z.ZodString;
-            write: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strict>>>>;
         log: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        write: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         outlineBranch: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         include: z.ZodOptional<z.ZodDefault<z.ZodObject<{
             branches: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/schema/src/server-config.js

@@ -2,9 +2,10 @@
  * @module Server configuration schema
  *
  * The schema of `atlas.server.json`, the file that configures `atlas serve` and `atlas dev`: where to listen, which
- * folder and further backends hold the data, which bearer tokens may read, publish or administer, and limits. Every
- * field has a default, so an empty file is a working server. Unlike the report format, unknown keys are an error, so
- * a typo is reported instead of ignored. Flags and environment variables override the file.
+ * bearer tokens may read, publish or administer, and limits. Where reports are kept is not here: the server stores
+ * everything in S3-compatible storage named by required `ATLAS_S3_*` environment variables, never in this file.
+ * Every field has a default. Unlike the report format, unknown keys are an error, so a typo (or a removed `data`,
+ * `backends` or `write` key) is reported instead of ignored. Flags and environment variables override the file.
  *
  * @see docs/deploying.md
  * @see docs/server.md
@@ -12,16 +13,6 @@
 import { z } from 'zod/v4';
 /** What a bearer token may do: `read` (look), `publish` (also upload) or `admin` (also remove scratch objects). */
 export const ServerRoleSchema = z.enum(['read', 'publish', 'admin']);
-/**
- * A further store the server reads together with its data folder, and optionally writes to: an id, a label and a
- * location URL.
- */
-export const ServerBackendSchema = z.strictObject({
-    id: z.string().regex(/^[a-z0-9-]+$/).describe('Lowercase letters, digits and hyphens. Names where a result came from'),
-    label: z.string().optional(),
-    url: z.string().min(1).describe('A folder, s3://bucket/prefix, r2://, gs://, or another Atlas server (https://…)'),
-    write: z.boolean().optional().describe('Uploads go here instead of the data folder. At most one backend is the write target')
-});
 /**
  * A bearer token: a name for logs, a role, and the token itself or the name of the environment variable that holds it
  * (exactly one of the two).
@@ -35,16 +26,12 @@ export const ServerTokenSchema = z
 })
     .refine((value) => (value.token === undefined) !== (value.tokenEnv === undefined), { message: 'Give exactly one of token or tokenEnv' });
 /**
- * The whole `atlas.server.json`: listening address, data folder, backends and write target, authentication, the
- * viewer to serve, which layers take part in the report, refresh and heartbeat intervals, request limits and logging.
+ * The whole `atlas.server.json`: listening address, authentication, the viewer to serve, which layers take part in the report, refresh and heartbeat intervals, request limits and logging.
  */
 export const ServerConfigSchema = z.strictObject({
     $schema: z.string().optional(),
     host: z.string().default('127.0.0.1').describe('Where to listen. 127.0.0.1 keeps it on this machine; 0.0.0.0 is every interface and needs tokens (or `auth.insecure`)'),
     port: z.number().int().min(0).max(65535).default(8080),
-    data: z.string().default('./atlas-data').describe('The folder that is the default backend and the default write target: layers, specs and runs live here'),
-    backends: z.array(ServerBackendSchema).default([]).describe('Further backends, read together with the data folder: S3, another server, a device lab'),
-    write: z.string().optional().describe('The id of the backend uploads go to. Default: the data folder'),
     auth: z
         .strictObject({
         tokens: z.array(ServerTokenSchema).default([]),
@@ -73,9 +60,9 @@ export const ServerConfigSchema = z.strictObject({
     heartbeatSeconds: z.number().min(1).default(15).describe('How often a live connection is touched, so proxies keep it open'),
     log: z.boolean().default(true).describe('One JSON line per request')
 });
-/** Storage and report settings editable by an admin. Authentication, listeners and the served site stay deployment-owned. Replaces the editable portion of the file; omitted fields use defaults after restart. */
-export const ServerEditableSettingsSchema = ServerConfigSchema.pick({ data: true, backends: true, write: true, outlineBranch: true, include: true, refreshSeconds: true, limits: true, heartbeatSeconds: true, runTimeoutSeconds: true, runStallSeconds: true, log: true }).partial();
-/** The settings API response: persisted editable configuration, active values, concurrency revision and restart/precedence guidance. Authentication token settings are excluded. */
+/** Report and live-run settings editable by an admin. Storage, authentication, listeners and the served site stay deployment-owned. Replaces the saved portion of the user state; omitted fields use defaults after restart. */
+export const ServerEditableSettingsSchema = ServerConfigSchema.pick({ outlineBranch: true, include: true, refreshSeconds: true, limits: true, heartbeatSeconds: true, runTimeoutSeconds: true, runStallSeconds: true, log: true }).partial();
+/** The settings API response: editable configuration saved in the user state in S3, active values, concurrency revision and restart/precedence guidance. Authentication token settings are excluded. */
 export const ServerSettingsSnapshotSchema = z.looseObject({
     revision: z.string().regex(/^[a-f0-9]{64}$/),
     settings: ServerEditableSettingsSchema,

package/dist/schema/src/user-state.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @module User state schema
+ *
+ * The one JSON document that holds everything a person using Atlas has chosen, as opposed to what an operator deployed:
+ * the garbage collection policy and the saved server settings. The server keeps it in S3-compatible object storage
+ * (`server/state.json` under the configured prefix) and nowhere else: not in a file, a database or the browser. A
+ * document that does not exist yet means nothing has been chosen; a document that cannot be read is an error, never
+ * an empty state. Unknown keys are kept, so an older server does not drop what a newer one wrote.
+ *
+ * @see docs/server.md#user-state-and-garbage-collection
+ */
+import { z } from 'zod/v4';
+/**
+ * The garbage collection policy: which report layers the server may delete from S3, and when. Only layers that the
+ * report has loaded and that no longer decide any result (every check they carry has since been superseded by a newer
+ * layer) are ever candidates, and the newest `keepLatest` layers are always kept. With `enabled: false` nothing is deleted.
+ */
+export declare const GcPolicySchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    maxAgeDays: z.ZodNumber;
+    keepLatest: z.ZodDefault<z.ZodNumber>;
+    intervalHours: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/** A garbage collection policy as stored, defaults applied. */
+export type GcPolicy = z.output<typeof GcPolicySchema>;
+/** A garbage collection policy as written, before defaults are applied. */
+export type GcPolicyInput = z.input<typeof GcPolicySchema>;
+/** What one pass of garbage collection found and did, for one project. */
+export declare const GcRunSchema: z.ZodObject<{
+    project: z.ZodString;
+    dryRun: z.ZodBoolean;
+    at: z.ZodString;
+    candidates: z.ZodNumber;
+    deletedLayers: z.ZodNumber;
+    deletedBlobs: z.ZodNumber;
+    keptLayers: z.ZodNumber;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** One pass of garbage collection, see {@link GcRunSchema}. */
+export type GcRun = z.output<typeof GcRunSchema>;
+/** The user state document stored in S3. Both parts are optional: absent means "never chosen". */
+export declare const UserStateSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    gc: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        maxAgeDays: z.ZodNumber;
+        keepLatest: z.ZodDefault<z.ZodNumber>;
+        intervalHours: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    settings: z.ZodOptional<z.ZodObject<{
+        log: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        outlineBranch: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        include: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+            branches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            ignoreModified: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>>;
+        refreshSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        limits: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+            maxObjectMiB: z.ZodDefault<z.ZodNumber>;
+            maxJsonMiB: z.ZodDefault<z.ZodNumber>;
+            maxStreams: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        runTimeoutSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        runStallSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        heartbeatSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    }, z.core.$strict>>;
+}, z.core.$loose>;
+/** The user state document, see {@link UserStateSchema}. */
+export type UserState = z.output<typeof UserStateSchema>;
+/**
+ * `GET /api/settings/gc` and `PUT /api/settings/gc`: the policy as saved in S3 (`null` when none has been saved), the
+ * revision to send back in `If-Match`, and the result of the last pass this server ran.
+ */
+export declare const GcSnapshotSchema: z.ZodObject<{
+    revision: z.ZodString;
+    policy: z.ZodNullable<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        maxAgeDays: z.ZodNumber;
+        keepLatest: z.ZodDefault<z.ZodNumber>;
+        intervalHours: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    saved: z.ZodBoolean;
+    lastRuns: z.ZodArray<z.ZodObject<{
+        project: z.ZodString;
+        dryRun: z.ZodBoolean;
+        at: z.ZodString;
+        candidates: z.ZodNumber;
+        deletedLayers: z.ZodNumber;
+        deletedBlobs: z.ZodNumber;
+        keptLayers: z.ZodNumber;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    stateKey: z.ZodString;
+}, z.core.$loose>;
+/** The garbage collection settings response, see {@link GcSnapshotSchema}. */
+export type GcSnapshot = z.output<typeof GcSnapshotSchema>;
+/** `POST /api/settings/gc/run`: the passes that ran, one per project. */
+export declare const GcRunResultSchema: z.ZodObject<{
+    runs: z.ZodArray<z.ZodObject<{
+        project: z.ZodString;
+        dryRun: z.ZodBoolean;
+        at: z.ZodString;
+        candidates: z.ZodNumber;
+        deletedLayers: z.ZodNumber;
+        deletedBlobs: z.ZodNumber;
+        keptLayers: z.ZodNumber;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    policy: z.ZodNullable<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        maxAgeDays: z.ZodNumber;
+        keepLatest: z.ZodDefault<z.ZodNumber>;
+        intervalHours: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$loose>;