@crvouga/atlas 0.16.0 → 1.0.0

package/docs/reference/schema.md

@@ -764,6 +764,47 @@ export type Attachment = z.output<typeof AttachmentSchema>;
 
 An attachment as stored in a layer, parsed from `AttachmentSchema`.
 
+#### `RECORDING_EXPECTATIONS`
+
+```ts
+export const RECORDING_EXPECTATIONS = …
+```
+
+Whether a check is expected to have a screen recording (a video). `required`: the producer expects one, and the layer's
+recording receipt says whether it arrived. `not-applicable`: the check is intentionally unrecorded (an API-only check),
+so it counts as neither a recorded pass nor a missing video. An open string: a reader treats any other value, and its
+absence, as no expectation.
+
+#### `RecordingItemSchema`
+
+```ts
+export const RecordingItemSchema = …
+```
+
+The state of one check's recording in a receipt, in an open vocabulary. Conventions: `uploaded` (the video's bytes are in
+the layer, with a checksum), `referenced` (only a `uri` was given: Atlas cannot vouch for it), `skipped` (the video was
+captured but its bytes were left out, with a reason), `unresolved` (no video was attached at all), `not-applicable`
+(intentionally unrecorded). A reader shows a state it does not know as it is and never counts it as uploaded.
+
+#### `RecordingReceiptSchema`
+
+```ts
+export const RecordingReceiptSchema = …
+```
+
+What a layer's producer published about the recordings it expected: counts and one item per check that expected a
+recording (or declared itself not applicable). Written by `publishChecks` when any check declares a
+`recordingExpectation`; a layer without it says nothing, which a reader reports as Unknown, never Complete. It only
+describes publication: it never changes a check's status, its slot or which result wins.
+
+#### `RecordingReceipt`
+
+```ts
+export type RecordingReceipt = z.output<typeof RecordingReceiptSchema>;
+```
+
+A recording receipt as stored in a layer, parsed from `RecordingReceiptSchema`.
+
 #### `AnnotationSchema`
 
 ```ts
@@ -962,6 +1003,24 @@ export type PublishChecksInput = z.input<typeof PublishChecksSchema>;
 
 What a caller passes to `publishChecks`: the input type of `PublishChecksSchema`, before defaults.
 
+#### `RecordingCompletenessSchema`
+
+```ts
+export const RecordingCompletenessSchema = …
+```
+
+Recording completeness across the winning results of a report: `complete` (every expected recording was published),
+`incomplete` (at least one is skipped or unresolved), `none-expected` (every layer declared its expectations, and none
+required a recording) or `unknown` (a layer has no receipt, so nothing is claimed). Independent of the checks' outcomes.
+
+#### `RecordingCompleteness`
+
+```ts
+export type RecordingCompleteness = z.output<typeof RecordingCompletenessSchema>;
+```
+
+A parsed `RecordingCompletenessSchema` value.
+
 #### `REPORT_STATUS_SCHEMA_VERSION`
 
 ```ts
@@ -1571,9 +1630,10 @@ export const RunsIndexSchema = …
 Source: `packages/schema/src/server-config.ts`
 
 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
@@ -1594,15 +1654,6 @@ export type ServerRole = z.infer<typeof ServerRoleSchema>;
 
 One of the roles of `ServerRoleSchema`.
 
-#### `ServerBackendSchema`
-
-```ts
-export const ServerBackendSchema = …
-```
-
-A further store the server reads together with its data folder, and optionally writes to: an id, a label and a
-location URL.
-
 #### `ServerTokenSchema`
 
 ```ts
@@ -1618,8 +1669,7 @@ A bearer token: a name for logs, a role, and the token itself or the name of the
 export const ServerConfigSchema = …
 ```
 
-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.
 
 #### `ServerConfig`
 
@@ -1643,7 +1693,7 @@ A server configuration as written, before defaults are applied.
 export const ServerEditableSettingsSchema = …
 ```
 
-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.
 
 #### `ServerSettingsSnapshotSchema`
 
@@ -1651,7 +1701,7 @@ Storage and report settings editable by an admin. Authentication, listeners and
 export const ServerSettingsSnapshotSchema = …
 ```
 
-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.
 
 ### Statechart spec schemas
 
@@ -1903,3 +1953,98 @@ export function isStatechartFile(path: string)
 ```
 
 Whether a spec-relative path (using `/`) matches `STATECHART_FILE_PATTERNS`.
+
+### User state schema
+
+Source: `packages/schema/src/user-state.ts`
+
+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
+
+#### `GcPolicySchema`
+
+```ts
+export const GcPolicySchema = …
+```
+
+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.
+
+#### `GcPolicy`
+
+```ts
+export type GcPolicy = z.output<typeof GcPolicySchema>;
+```
+
+A garbage collection policy as stored, defaults applied.
+
+#### `GcPolicyInput`
+
+```ts
+export type GcPolicyInput = z.input<typeof GcPolicySchema>;
+```
+
+A garbage collection policy as written, before defaults are applied.
+
+#### `GcRunSchema`
+
+```ts
+export const GcRunSchema = …
+```
+
+What one pass of garbage collection found and did, for one project.
+
+#### `GcRun`
+
+```ts
+export type GcRun = z.output<typeof GcRunSchema>;
+```
+
+One pass of garbage collection, see {@link GcRunSchema}.
+
+#### `UserStateSchema`
+
+```ts
+export const UserStateSchema = …
+```
+
+The user state document stored in S3. Both parts are optional: absent means "never chosen".
+
+#### `UserState`
+
+```ts
+export type UserState = z.output<typeof UserStateSchema>;
+```
+
+The user state document, see {@link UserStateSchema}.
+
+#### `GcSnapshotSchema`
+
+```ts
+export const GcSnapshotSchema = …
+```
+
+`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.
+
+#### `GcSnapshot`
+
+```ts
+export type GcSnapshot = z.output<typeof GcSnapshotSchema>;
+```
+
+The garbage collection settings response, see {@link GcSnapshotSchema}.
+
+#### `GcRunResultSchema`
+
+```ts
+export const GcRunResultSchema = …
+```
+
+`POST /api/settings/gc/run`: the passes that ran, one per project.

package/docs/reference/server.md

@@ -42,8 +42,12 @@ export type AtlasServerOptions = {
   readonly log?: (line: Record<string, unknown>) => void;
   readonly now?: () => number;
   readonly version?: string;
-  /** Admin configuration persistence, supplied by atlas serve. Changes apply on restart. */
+  /** Admin configuration persistence, supplied by atlas serve; kept in S3. Changes apply on restart. */
   readonly settings?: ServerSettings;
+  /** The garbage collection policy, kept in S3 and read from there each time the server collects. Supplied by atlas serve. */
+  readonly gc?: GcSettings;
+  /** How often (ms) the server checks whether a garbage collection pass is due. Default 60 000; for tests. */
+  readonly gcCheckMs?: number;
   /** Extra runtime configuration written into the page. */
   readonly page?: Record<string, unknown>;
 };
@@ -62,6 +66,12 @@ export type AtlasServer = {
   readonly routes: readonly { readonly method: string; readonly path: string }[];
   /** Resolves when the first pass over the backends is done. */
   readonly ready: Promise<void>;
+  /**
+   * Apply a garbage collection policy to this project's upload backend. Deletes only layers the report has read and
+   * that no longer decide any result, older than the policy allows and beyond its `keepLatest`. With `dryRun` it only
+   * counts. Never throws: a failure is the `error` of the returned run.
+   */
+  collectGarbage(policy: GcPolicy, options: { readonly dryRun: boolean; readonly project: string }): Promise<GcRun>;
   /** Stop refreshing and end every live connection. */
   close(): void;
 };
@@ -136,11 +146,13 @@ The authentication of one server: `identify` (who is this), `check` (may they, f
 
 Source: `packages/server/src/config.ts`
 
-Loads how the server runs: `atlas.server.json`, then environment variables, then flags, each overriding the last, checked
-against `ServerConfigSchema` and resolved (paths made absolute, backends named, tokens read). Every mistake is a
-`ConfigError` that says what to change, and a server that would listen beyond this machine with no tokens refuses to
-start. `SERVER_SETTINGS` documents every setting once; the table in docs/server.md is generated from it and a test proves
-each row.
+Loads how the server runs: the settings saved in S3 (the user state), then `atlas.server.json`, then environment
+variables, then flags, each overriding the last, checked against `ServerConfigSchema` and resolved (storage read from
+the required `ATLAS_S3_*` variables, tokens read). Storage is never optional: all reports and user state live in
+S3-compatible object storage, so missing or invalid storage variables are an `S3ConfigError` naming every variable.
+Every other mistake is a `ConfigError` that says what to change, and a server that would listen beyond this machine
+with no tokens refuses to start. `SERVER_SETTINGS` documents every setting once; the table in docs/server.md is
+generated from it and a test proves each row.
 
 See docs/server.md#configuration
 
@@ -152,23 +164,12 @@ export type ResolvedToken = { readonly name: string; readonly role: ServerRole;
 
 A token as the server holds it: the `name` it is shown under in logs, its `role`, and the secret `token`.
 
-#### `BackendSpec`
-
-```ts
-export type BackendSpec = { readonly id: string; readonly label: string; readonly url: string };
-```
-
-A backend as configured: its `id`, the `label` people see, and the `url` (a folder, `s3://…`, or another server) to open.
-
 #### `ResolvedServerConfig`
 
 ```ts
-export type ResolvedServerConfig = Omit<ServerConfig, 'backends' | 'auth' | 'write'> & {
-  /** The folder that is the default backend, absolute. */
-  readonly data: string;
-  /** Every backend, the data folder first. All are read; uploads go to `writeId`. */
-  readonly backends: readonly BackendSpec[];
-  readonly writeId: string;
+export type ResolvedServerConfig = Omit<ServerConfig, 'auth'> & {
+  /** The S3-compatible storage that holds every report and all user state. Required; there is no other. */
+  readonly s3: S3Config;
   readonly tokens: readonly ResolvedToken[];
   readonly anonymousRead: boolean;
   readonly insecure: boolean;
@@ -241,12 +242,13 @@ The text `atlas serve --help` prints. Also the source of the `atlas serve` secti
 #### `loadServerConfig`
 
 ```ts
-export function loadServerConfig(argv: readonly string[], env: Env, cwd: string, read: (file: string) => string = file => readFileSync(file, 'utf8')): ResolvedServerConfig
+export function loadServerConfig(argv: readonly string[], env: Env, cwd: string, read: (file: string) => string = file => readFileSync(file, 'utf8'), saved: Record<string, unknown> = {}): ResolvedServerConfig
 ```
 
 Read the file named by `--config`/`ATLAS_CONFIG`, or `atlas.server.json` in the folder if there is one, lay the
-environment and then the flags over it, and check the result. Every problem is a {@link ConfigError} that says
-what to change.
+environment and then the flags over it, and check the result. `saved` is the settings kept in S3 (the user state),
+the lowest layer. Every problem is a {@link ConfigError} that says what to change; missing or invalid storage
+variables are an `S3ConfigError` that names all of them, and are checked first.
 
 #### `assertSafeToListen`
 
@@ -365,6 +367,8 @@ Source: `packages/server/src/index.ts`. Import: `@crvouga/atlas/server`
 Everything needed to run the Atlas server from code: `createAtlasServer` (a `fetch` handler with the live report, uploads
 and the viewer), `listen` (serve it over HTTP on Bun or Node), `loadServerConfig` (the file, the environment and the flags
 as one checked configuration), `serveMain` (what `atlas serve` runs), `EventHub`, `createAuth`, and the upload checks.
+`atlas serve` keeps everything in S3: `resolveS3Config` reads the required `ATLAS_S3_*` variables, `userStateStore` the user
+state in the bucket, and `storedSettings` serves the settings page from it.
 
 See docs/server.md
 
@@ -442,28 +446,38 @@ The guide for one server, Markdown. Stable in structure: an agent may read it by
 
 Source: `packages/server/src/main.ts`
 
-Starts the Atlas server from its configuration: opens every backend (creating the data folder), proves the upload
-backend can be written to before listening, finds or builds the client, listens at once (so a liveness probe finds the
-process while a large backend is still being read), and stops cleanly on SIGTERM or SIGINT. `serverOptionsOf` is shared
-with `atlas dev`, so the two run the same server.
+Starts the Atlas server from its configuration. Storage comes first and is not optional: the required `ATLAS_S3_*`
+variables are checked (every problem listed together), the bucket is proven reachable and writable, and the user
+state (garbage collection policy and saved settings) is read from it, all before anything listens. Any failure prints
+a banner naming every variable and exits 2; there is no fallback to a local folder, memory or a database. Then it
+finds or builds the client, listens at once (so a liveness probe finds the process while a large bucket is still being
+read), and stops cleanly on SIGTERM or SIGINT. `serverOptionsOf` is shared with `atlas dev`, so the two run the same server.
 
 See docs/server.md#run-it
 
 #### `ServeIo`
 
 ```ts
-export type ServeIo = { readonly out: (text: string) => void; readonly env?: Env; readonly cwd?: string; readonly signal?: AbortSignal };
+export type ServeIo = { readonly out: (text: string) => void; readonly env?: Env; readonly cwd?: string; readonly signal?: AbortSignal; readonly fetch?: typeof fetch };
 ```
 
-What `serveMain` and `devMain` are given besides arguments: where output goes, and, for tests and embedding, the environment, working directory and an `AbortSignal` that stops the server (otherwise SIGTERM and SIGINT do).
+What `serveMain` and `devMain` are given besides arguments: where output goes, and, for tests and embedding, the environment, working directory, the `fetch` S3 requests are sent with, and an `AbortSignal` that stops the server (otherwise SIGTERM and SIGINT do).
+
+#### `S3_BACKEND_ID`
+
+```ts
+export const S3_BACKEND_ID = …
+```
+
+The id of the one backend: the S3 bucket.
 
 #### `openConfiguredBackends`
 
 ```ts
-export function openConfiguredBackends(config: ResolvedServerConfig, env: Env, cwd: string): (BackendInput & { readonly writable: boolean })[]
+export function openConfiguredBackends(config: ResolvedServerConfig, fetchImpl?: typeof fetch): (BackendInput & { readonly writable: boolean })[]
 ```
 
-Open every backend of a configuration. The data folder is made if it is not there.
+Open the S3 bucket named by a configuration, with exactly the credentials it gives (no ambient AWS lookup). Nothing is contacted yet.
 
 #### `serverOptionsOf`
 
@@ -473,6 +487,15 @@ export function serverOptionsOf(config: ResolvedServerConfig, backends: ReturnTy
 
 What `createAtlasServer` is given for a configuration: `atlas serve` and `atlas dev` run the same server.
 
+#### `connectStorage`
+
+```ts
+export async function connectStorage(config: ResolvedServerConfig, env: Env, io: Pick<ServeIo, 'fetch'>): Promise<{ readonly backends: ReturnType<typeof openConfiguredBackends>; readonly stored: StoredUserState } | { readonly failure: string }>
+```
+
+Check the storage and read the user state, in that order, with the failure banner for each way it can go wrong.
+Returns the opened backends and the state, or the text to print before exiting 2.
+
 #### `serveMain`
 
 ```ts
@@ -638,8 +661,10 @@ const html = await renderSettingsPage();
 Source: `packages/server/src/settings.ts`
 
 @module Persisted server settings
-The admin UI edits storage and report configuration in atlas.server.json. Changes take effect on restart;
-environment variables and flags keep their documented precedence. Authentication is managed outside this UI.
+The settings page edits two things, and both are kept in the user state document in S3 (`server/state.json`), never on
+the server's disk: the report and live-run settings (applied at the next start, below the configuration file,
+the environment and the flags in precedence) and the garbage collection policy (read by the server each time it
+collects). Storage and authentication are deployment-owned and are not editable here.
 
 #### `SettingsSnapshot`
 
@@ -647,7 +672,7 @@ environment variables and flags keep their documented precedence. Authentication
 export type SettingsSnapshot = { readonly revision: string; readonly settings: Record<string, unknown>; readonly active: Record<string, unknown>; readonly restartRequired: boolean; readonly precedence: string };
 ```
 
-The persisted editable settings, active settings and a revision for optimistic concurrency. Authentication token settings are excluded.
+The saved editable settings, the active settings and a revision for optimistic concurrency. Authentication token settings are excluded.
 
 #### `ServerSettings`
 
@@ -655,22 +680,38 @@ The persisted editable settings, active settings and a revision for optimistic c
 export type ServerSettings = { read(): Promise<SettingsSnapshot>; save(settings: unknown, revision: string): Promise<SettingsSnapshot> };
 ```
 
-Storage for the admin API; saving is serialized and refuses a stale revision.
+Storage for the admin API; saving is serialised and refuses a stale revision.
+
+#### `GcSettings`
+
+```ts
+export type GcSettings = {
+  /** The policy in S3 with its revision and the last passes. */
+  read(): Promise<GcSnapshot>;
+  /** Validates and saves a policy; a stale `revision` is refused. */
+  save(policy: unknown, revision: string): Promise<GcSnapshot>;
+  /** The policy in S3 right now, or `null` when none has been saved. Read from S3 every time. */
+  policy(): Promise<GcPolicy | null>;
+  /** Remembers the result of a pass, for `read`. */
+  record(runs: readonly GcRun[]): void;
+};
+```
+
+The garbage collection policy as the admin API and the collector see it.
 
-#### `fileServerSettings`
+#### `storedSettings`
 
 ```ts
-export function fileServerSettings(config: ResolvedServerConfig, argv: readonly string[], env: Readonly<Record<string, string | undefined>>, cwd: string): ServerSettings
+export function storedSettings(config: ResolvedServerConfig, argv: readonly string[], env: Readonly<Record<string, string | undefined>>, cwd: string, userState: UserStateStore): { settings: ServerSettings; gc: GcSettings }
 ```
 
-Manage the server's configuration file with atomic replacement, preserving authentication and unrelated fields.
-Validates both the file alone and the effective configuration before saving. Never migrates or deletes report data.
-Changes need a server restart; deployment environment variables and flags override the file.
+The settings and garbage collection policy kept in `userState` (S3). Validates a settings change against the
+whole deployment (file, environment and flags) before saving, so what is saved can start. Never moves report data.
 
 **Example**
 
 ```ts
-const settings = fileServerSettings(config, argv, process.env, process.cwd());
+const { settings, gc } = storedSettings(config, argv, process.env, process.cwd(), userStateStore(store));
 ```
 
 ### Finding the client
@@ -713,6 +754,118 @@ export async function findSite(named: string | undefined, cwd: string, log: (tex
 
 The client to serve: the one named, a build beside the project, or one built into the user's cache.
 
+### Required S3 storage configuration
+
+Source: `packages/server/src/storage.ts`
+
+The Atlas server keeps ALL reports and ALL user state (the garbage collection policy and saved settings) in
+S3-compatible object storage, and nowhere else: no local folder, no memory, no database. So the storage settings
+are required, come only from environment variables (they hold secrets), and have no defaults for where or as whom
+to connect. `resolveS3Config` checks every variable in one pass and reports all the problems together;
+`startupFailure` renders them as a banner that cannot be missed. `S3_VARIABLES` is the single description of the
+variables: the banner, `.env.example` and the documentation table are all made from it.
+
+See docs/server.md#required-s3-storage
+
+#### `S3Variable`
+
+```ts
+export type S3Variable = {
+  readonly name: string;
+  readonly required: boolean;
+  /** Shown in the banner and the documentation. Never a real secret. */
+  readonly meaning: string;
+  readonly example: string;
+  /** Secrets are never printed, not even when invalid. */
+  readonly secret?: true;
+  /** Returns what is wrong with a value that is set, or null when it is fine. */
+  readonly check: (value: string) => string | null;
+};
+```
+
+One environment variable of the storage configuration.
+
+#### `S3_VARIABLES`
+
+```ts
+export const S3_VARIABLES: readonly S3Variable[]
+```
+
+Every variable that configures storage, required ones first.
+
+#### `S3Config`
+
+```ts
+export type S3Config = {
+  readonly endpoint: string;
+  readonly bucket: string;
+  readonly region: string;
+  readonly prefix: string;
+  readonly pathStyle: boolean;
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  readonly sessionToken?: string;
+};
+```
+
+The storage settings once checked: everything needed to open the bucket, with credentials spelled out.
+
+#### `S3Finding`
+
+```ts
+export type S3Finding = { readonly variable: S3Variable; readonly status: 'ok' | 'missing' | 'invalid' | 'unset'; readonly problem?: string };
+```
+
+The state of one variable after checking, for the banner.
+
+#### `S3ConfigError`
+
+```ts
+export class S3ConfigError extends Error
+```
+
+The storage configuration could not be used. `findings` has every variable, not only the first problem.
+
+#### `inspectS3Env`
+
+```ts
+export function inspectS3Env(env: Env): readonly S3Finding[]
+```
+
+Looks at every storage variable and returns what each is. Nothing here throws.
+
+#### `resolveS3Config`
+
+```ts
+export function resolveS3Config(env: Env): S3Config
+```
+
+The storage settings from the environment. Throws {@link S3ConfigError}, whose message lists every variable and
+marks each missing or invalid one, when any required variable is absent or any set variable is malformed.
+
+**Example**
+
+```ts
+const s3 = resolveS3Config(process.env);
+```
+
+#### `describeS3`
+
+```ts
+export const describeS3 = …
+```
+
+Where the storage is, without a secret: what the log may say.
+
+#### `startupFailure`
+
+```ts
+export function startupFailure(findings: readonly S3Finding[], reason: string, detail?: string): string
+```
+
+The banner printed when the server cannot start because of storage: why storage is required, then EVERY variable by
+name with what is wrong with it. Values of secrets are never printed.
+
 ### Store protocol routes
 
 Source: `packages/server/src/store-api.ts`
@@ -754,6 +907,75 @@ export function storeApi(options: StoreApiOptions)
 
 The Hono app of the store protocol, to be mounted at `/api/store`. Reads need role `read`; writes need `publish` through a Bearer token.
 
+### User state in S3
+
+Source: `packages/server/src/user-state.ts`
+
+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
+
+#### `USER_STATE_KEY`
+
+```ts
+export const USER_STATE_KEY = …
+```
+
+Where the user state lives, relative to the store (the bucket plus `ATLAS_S3_PREFIX`).
+
+#### `StoredUserState`
+
+```ts
+export type StoredUserState = { readonly state: UserState; readonly revision: string; readonly exists: boolean };
+```
+
+The user state as stored: the document, its `revision` and whether the object `exists` yet.
+
+#### `UserStateError`
+
+```ts
+export class UserStateError extends Error {}
+```
+
+Raised when the stored user state cannot be trusted. The message says where it is and what to do.
+
+#### `UserStateStore`
+
+```ts
+export type UserStateStore = {
+  /** Reads the document. Throws {@link UserStateError} when it exists but is unreadable or invalid. */
+  read(): Promise<StoredUserState>;
+  /**
+   * Applies `change` to the stored state and writes the result, if `revision` is still the stored one. Throws a
+   * `UserStateError` starting with "Settings changed" for a stale revision.
+   */
+  update(revision: string, change: (state: UserState) => UserState): Promise<StoredUserState>;
+};
+```
+
+The user state of one server: read it, or change it against the revision that was read.
+
+#### `userStateStore`
+
+```ts
+export function userStateStore(store: ObjectStore): UserStateStore
+```
+
+The user state kept in `store` at {@link USER_STATE_KEY}.
+
+**Example**
+
+```ts
+const userState = userStateStore(s3Backend.store);
+const { state } = await userState.read();
+```
+
 ### Upload validation
 
 Source: `packages/server/src/validate.ts`