@crvouga/atlas 0.16.0 → 1.0.0

package/dist/server/src/openapi.js

@@ -15,7 +15,7 @@
 import { z } from 'zod/v4';
 import { ProjectsSchema } from '../../schema/src/project.js';
 import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, RunListSchema, RunDetailSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema } from '../../schema/src/api.js';
-import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
+import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, GcPolicySchema, GcSnapshotSchema, GcRunResultSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
 export const API_VERSION = '1.5.0';
 /** The JSON Schema of a Zod schema, as OpenAPI 3.1 embeds it. `output` for what the server sends, `input` for what it accepts. */
@@ -30,6 +30,7 @@ function schemaOf(schema, io = 'output') {
 const COMPONENTS = {
     LiveRun: [LiveRunSchema, 'output'], LiveRunStart: [LiveRunStartSchema, 'input'], LiveRunUpdate: [LiveRunUpdateSchema, 'input'],
     ServerEditableSettings: [ServerEditableSettingsSchema, 'input'], ServerSettingsSnapshot: [ServerSettingsSnapshotSchema, 'output'],
+    GcPolicy: [GcPolicySchema, 'input'], GcSnapshot: [GcSnapshotSchema, 'output'], GcRunResult: [GcRunResultSchema, 'output'],
     Problem: [ProblemSchema, 'output'], Health: [HealthSchema, 'output'], Ready: [ReadySchema, 'output'], ServerInfo: [ServerInfoSchema, 'output'],
     EffectiveEvidence: [EffectiveEvidenceSchema, 'output'], EffectiveDelta: [EffectiveDeltaSchema, 'output'], ReportStatus: [ReportStatusSchema, 'output'],
     PublishChecks: [PublishChecksSchema.partial({ recordedAtMs: true }), 'input'], ChecksResult: [ChecksResultSchema, 'output'],
@@ -92,16 +93,34 @@ const BASE_OPERATIONS = [
     },
     {
         route: 'GET /api/settings', path: '/api/settings', operationId: 'getSettings', tag: 'Operations', role: 'admin',
-        summary: 'Read server settings', description: '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.',
+        summary: 'Read server settings', description: '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': json('Settings and revision.', 'ServerSettingsSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '503': problem('Configuration is managed by the embedding application.') }
     },
     {
         route: 'PUT /api/settings', path: '/api/settings', operationId: 'saveSettings', tag: 'Operations', role: 'admin',
-        summary: 'Save settings for the next restart', description: '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.',
+        summary: 'Save settings for the next restart', description: '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.',
         parameters: [{ name: 'If-Match', in: 'header', required: true, description: 'The quoted revision returned by GET /api/settings.', schema: str }],
-        body: { description: 'Editable fields from ServerConfig, excluding authentication, host, port and site. Maximum 64 KiB.', contentType: 'application/json', required: true, schema: ref('ServerEditableSettings') },
+        body: { description: 'Editable fields from ServerConfig, excluding storage, authentication, host, port and site. Maximum 64 KiB.', contentType: 'application/json', required: true, schema: ref('ServerEditableSettings') },
         responses: { '200': json('Saved settings and new revision. Restart required.', 'ServerSettingsSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('Settings changed; reload before saving.'), '413': problem('Settings exceed the body limit.'), '422': problem('Invalid configuration.'), '428': problem('A quoted settings revision is required.'), '503': problem('Configuration is managed by the embedding application.') }
     },
+    {
+        route: 'GET /api/settings/gc', path: '/api/settings/gc', operationId: 'getGarbageCollectionPolicy', tag: 'Operations', role: 'admin',
+        summary: 'Read the garbage collection policy', description: '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': json('The policy, its revision and the last passes.', 'GcSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '503': problem('The user state in S3 cannot be read, or settings are managed by the embedding application.') }
+    },
+    {
+        route: 'PUT /api/settings/gc', path: '/api/settings/gc', operationId: 'saveGarbageCollectionPolicy', tag: 'Operations', role: 'admin',
+        summary: 'Save the garbage collection policy', description: '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.',
+        parameters: [{ name: 'If-Match', in: 'header', required: true, description: 'The quoted revision returned by GET /api/settings/gc.', schema: str }],
+        body: { description: 'The policy. Maximum 16 KiB.', contentType: 'application/json', required: true, schema: ref('GcPolicy') },
+        responses: { '200': json('The saved policy and the new revision.', 'GcSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('The state changed; reload before saving.'), '413': problem('The body exceeds the limit.'), '422': problem('Invalid policy.'), '428': problem('A quoted revision is required.'), '503': problem('The user state in S3 cannot be read, or settings are managed by the embedding application.') }
+    },
+    {
+        route: 'POST /api/settings/gc/run', path: '/api/settings/gc/run', operationId: 'runGarbageCollection', tag: 'Operations', role: 'admin',
+        summary: 'Collect garbage now, or preview it', description: '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.',
+        parameters: [{ name: 'dryRun', in: 'query', required: false, description: '`1` or `true` to only count what would be deleted.', schema: str }],
+        responses: { '200': json('One run per project.', 'GcRunResult'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('No policy has been saved, or it is disabled.') }
+    },
     {
         route: 'GET /healthz', path: '/healthz', operationId: 'getHealth', tag: 'Operations', role: 'none',
         summary: 'Is the process up',
@@ -437,7 +456,7 @@ const BASE_OPERATIONS = [
         responses: { '200': { description: 'The file.', contentType: 'application/octet-stream', schema: { type: 'string', format: 'binary' } }, '401': UNAUTHORIZED, '404': problem('No such run or file.') }
     }
 ];
-const NODE_OPERATIONS = new Set(['/api/projects', '/api/settings', '/api/server', '/api/openapi.json']);
+const NODE_OPERATIONS = new Set(['/api/projects', '/api/settings', '/api/settings/gc', '/api/settings/gc/run', '/api/server', '/api/openapi.json']);
 const PROJECT_PARAMETER = { name: 'project', in: 'query', description: 'Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.', schema: { type: 'string', pattern: '^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$', maxLength: 64 }, example: 'todo-app' };
 /** Every node operation and the same stable report protocol inside each project namespace. */
 export const OPERATIONS = BASE_OPERATIONS.flatMap(operation => {

package/dist/server/src/projects.js

@@ -9,7 +9,7 @@ import { createAuth } from './auth.js';
 import { problemResponse } from './problem.js';
 const REGISTRY = 'server/projects/';
 const SCOPED = /^\/api\/projects\/([^/]+)(\/.*)$/;
-const GLOBAL = new Set(['/api/settings', '/api/projects', '/api/openapi.json', '/api/server']);
+const GLOBAL = new Set(['/api/settings', '/api/settings/gc', '/api/settings/gc/run', '/api/projects', '/api/openapi.json', '/api/server']);
 const scopeStore = (store, slug) => typeof store.forProject === 'function'
     ? store.forProject(slug) : new ObjectStoreWithPrefix(store, `projects/${slug}`);
 /** Wrap the single-project protocol in project selection. Auth, upload validation and composition stay identical. */
@@ -61,7 +61,71 @@ export function projectServer(options, create) {
     };
     const timer = setInterval(expire, 60_000);
     timer.unref?.();
-    const routes = [...base.routes, { method: 'GET', path: '/api/projects' }];
+    /** The application of one named project, created on first use over a store scoped to it. `null` when too many are active. */
+    const ensureChild = (slug) => {
+        let child = children.get(slug);
+        if (child)
+            return child;
+        expire();
+        if (children.size >= 64)
+            return null;
+        child = { touched: Date.now(), pending: 0, server: create({ ...options,
+                ...(options.log ? { log: line => options.log({ ...line, project: slug }) } : {}),
+                backends: options.backends.map(backend => ({ ...backend, store: scopeStore(backend.store, slug) })),
+                ...(options.liveStore ? { liveStore: scopeStore(options.liveStore, slug) } : {}), site: undefined, settings: undefined, gc: undefined }) };
+        children.set(slug, child);
+        return child;
+    };
+    // Garbage collection. The policy is read from S3 every time, never cached, so a policy saved in the UI is the one applied.
+    const clock = options.now ?? Date.now;
+    let collecting;
+    let lastCollectedAt = 0;
+    const collectAll = (policy, dryRun) => {
+        collecting ??= (async () => {
+            const runs = [];
+            await discover().catch(() => { });
+            for (const slug of ['default', ...[...known].filter(item => item !== 'default').sort()]) {
+                if (closed)
+                    break;
+                if (slug === 'default') {
+                    runs.push(await base.collectGarbage(policy, { dryRun, project: slug }));
+                    continue;
+                }
+                const child = ensureChild(slug);
+                if (!child) {
+                    runs.push({ project: slug, dryRun, at: new Date(clock()).toISOString(), candidates: 0, deletedLayers: 0, deletedBlobs: 0, keptLayers: 0, error: 'Too many active projects; this one was skipped.' });
+                    continue;
+                }
+                child.pending++;
+                try {
+                    await child.server.ready;
+                    runs.push(await child.server.collectGarbage(policy, { dryRun, project: slug }));
+                }
+                finally {
+                    child.pending--;
+                    child.touched = Date.now();
+                }
+            }
+            if (!dryRun)
+                options.gc?.record(runs);
+            return runs;
+        })().finally(() => { collecting = undefined; });
+        return collecting;
+    };
+    const gcTimer = options.gc ? setInterval(() => {
+        void (async () => {
+            if (closed || collecting)
+                return;
+            const policy = await options.gc.policy();
+            if (!policy?.enabled || clock() - lastCollectedAt < policy.intervalHours * 3_600_000)
+                return;
+            await base.ready;
+            lastCollectedAt = clock();
+            await collectAll(policy, false);
+        })().catch(error => options.log?.({ level: 'error', gc: 'schedule', error: String(error) }));
+    }, options.gcCheckMs ?? 60_000) : undefined;
+    gcTimer?.unref?.();
+    const routes = [...base.routes, { method: 'GET', path: '/api/projects' }, { method: 'POST', path: '/api/settings/gc/run' }];
     for (const route of base.routes)
         if (route.path.startsWith('/api/') && route.path !== '/api/*' && !GLOBAL.has(route.path))
             routes.push({ method: route.method, path: route.path.replace('/api/', '/api/projects/:project/') });
@@ -71,6 +135,24 @@ export function projectServer(options, create) {
                 if (closed)
                     return problemResponse(503, 'Atlas is stopping.');
                 const url = new URL(request.url);
+                if (url.pathname === '/api/settings/gc/run' && request.method === 'POST') {
+                    const verdict = auth.check(request, 'admin');
+                    if (!verdict.ok)
+                        return problemResponse(verdict.status, verdict.message, verdict.status === 401 ? { 'www-authenticate': 'Basic realm="Atlas"' } : {});
+                    const origin = request.headers.get('origin');
+                    const site = request.headers.get('sec-fetch-site');
+                    if (site === 'cross-site' || (origin && origin !== url.origin && site !== 'same-origin'))
+                        return problemResponse(403, 'Changes must come from this server origin.');
+                    if (!options.gc)
+                        return problemResponse(503, 'Garbage collection settings are managed by the embedding application.');
+                    const policy = await options.gc.policy();
+                    if (!policy)
+                        return problemResponse(409, 'No garbage collection policy has been saved yet, so nothing is deleted. Save one first.');
+                    const dryRun = ['1', 'true'].includes(url.searchParams.get('dryRun') ?? '');
+                    if (!dryRun && !policy.enabled)
+                        return problemResponse(409, 'The saved garbage collection policy is disabled. Enable it, or use dryRun to preview.');
+                    return Response.json({ runs: await collectAll(dryRun ? { ...policy, enabled: true } : policy, dryRun), policy }, { headers: { 'cache-control': 'no-store' } });
+                }
                 if (url.pathname === '/api/projects' && request.method === 'GET') {
                     const verdict = auth.check(request, 'read');
                     if (!verdict.ok)
@@ -116,17 +198,9 @@ export function projectServer(options, create) {
                             return problemResponse(404, 'Unknown project. Publish reports with this project slug first.');
                     }
                 }
-                let child = children.get(slug);
-                if (!child) {
-                    expire();
-                    if (children.size >= 64)
-                        return problemResponse(429, 'Too many active projects. Retry when another project is idle.');
-                    child = { touched: Date.now(), pending: 0, server: create({ ...options,
-                            ...(options.log ? { log: line => options.log({ ...line, project: slug }) } : {}),
-                            backends: options.backends.map(backend => ({ ...backend, store: scopeStore(backend.store, slug) })),
-                            ...(options.liveStore ? { liveStore: scopeStore(options.liveStore, slug) } : {}), site: undefined, settings: undefined }) };
-                    children.set(slug, child);
-                }
+                const child = ensureChild(slug);
+                if (!child)
+                    return problemResponse(429, 'Too many active projects. Retry when another project is idle.');
                 child.touched = Date.now();
                 child.pending++;
                 try {
@@ -149,6 +223,7 @@ export function projectServer(options, create) {
                 return problemResponse(503, 'The project backend is unavailable. Retry later.');
             }
         },
-        close() { closed = true; clearInterval(timer); base.close(); for (const child of children.values())
+        close() { closed = true; clearInterval(timer); if (gcTimer)
+            clearInterval(gcTimer); base.close(); for (const child of children.values())
             child.server.close(); children.clear(); } };
 }

package/dist/server/src/settings.d.ts

@@ -1,5 +1,7 @@
+import { type GcPolicy, type GcRun, type GcSnapshot } from '../../schema/src/user-state.js';
 import { type ResolvedServerConfig } from './config.js';
-/** The persisted editable settings, active settings and a revision for optimistic concurrency. Authentication token settings are excluded. */
+import { type UserStateStore } from './user-state.js';
+/** The saved editable settings, the active settings and a revision for optimistic concurrency. Authentication token settings are excluded. */
 export type SettingsSnapshot = {
     readonly revision: string;
     readonly settings: Record<string, unknown>;
@@ -7,17 +9,31 @@ export type SettingsSnapshot = {
     readonly restartRequired: boolean;
     readonly precedence: string;
 };
-/** 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. */
 export type ServerSettings = {
     read(): Promise<SettingsSnapshot>;
     save(settings: unknown, revision: string): Promise<SettingsSnapshot>;
 };
+/** The garbage collection policy as the admin API and the collector see it. */
+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;
+};
 /**
- * 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
- * const settings = fileServerSettings(config, argv, process.env, process.cwd());
+ * const { settings, gc } = storedSettings(config, argv, process.env, process.cwd(), userStateStore(store));
  */
-export declare function fileServerSettings(config: ResolvedServerConfig, argv: readonly string[], env: Readonly<Record<string, string | undefined>>, cwd: string): ServerSettings;
+export declare function storedSettings(config: ResolvedServerConfig, argv: readonly string[], env: Readonly<Record<string, string | undefined>>, cwd: string, userState: UserStateStore): {
+    settings: ServerSettings;
+    gc: GcSettings;
+};
 export { SETTINGS_PAGE, renderSettingsPage } from './settings-page.js';

package/dist/server/src/settings.js

@@ -1,72 +1,62 @@
 /** @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.
  */
-import { createHash, randomUUID } from 'node:crypto';
-import { readFile, rename, rm, writeFile } from 'node:fs/promises';
-import path from 'node:path';
 import { ServerEditableSettingsSchema } from '../../schema/src/server-config.js';
-import { parseStoreLocation } from '../../reports/src/store-url.js';
+import { GcPolicySchema } from '../../schema/src/user-state.js';
 import { ConfigError, loadServerConfig } from './config.js';
+import { USER_STATE_KEY, UserStateError } from './user-state.js';
 const editable = ServerEditableSettingsSchema;
-const keys = new Set(Object.keys(editable.shape));
-const select = (value) => Object.fromEntries(Object.entries(value).filter(([key]) => keys.has(key)));
-const digest = (text) => createHash('sha256').update(text).digest('hex');
+const conflict = (error) => {
+    if (error instanceof UserStateError)
+        throw new ConfigError(error.message);
+    throw error;
+};
 /**
- * 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
- * const settings = fileServerSettings(config, argv, process.env, process.cwd());
+ * const { settings, gc } = storedSettings(config, argv, process.env, process.cwd(), userStateStore(store));
  */
-export function fileServerSettings(config, argv, env, cwd) {
-    const file = config.configFile ?? path.join(cwd, 'atlas.server.json');
-    const active = { data: config.data, backends: config.backends.slice(1), write: config.writeId, outlineBranch: config.outlineBranch, include: config.include, refreshSeconds: config.refreshSeconds, limits: config.limits, heartbeatSeconds: config.heartbeatSeconds, runTimeoutSeconds: config.runTimeoutSeconds, runStallSeconds: config.runStallSeconds, log: config.log };
+export function storedSettings(config, argv, env, cwd, userState) {
+    const active = { outlineBranch: config.outlineBranch, include: config.include, refreshSeconds: config.refreshSeconds, limits: config.limits, heartbeatSeconds: config.heartbeatSeconds, runTimeoutSeconds: config.runTimeoutSeconds, runStallSeconds: config.runStallSeconds, log: config.log };
     let saved = false;
-    let pending = Promise.resolve();
-    const readText = () => readFile(file, 'utf8').catch(error => { if (error.code === 'ENOENT')
-        return '{}'; throw error; });
-    const read = async () => {
-        const text = await readText();
-        return { revision: digest(text), settings: select(JSON.parse(text)), active,
-            restartRequired: saved, precedence: 'File settings apply after restart. Environment variables and command-line flags override the file.' };
+    let lastRuns = [];
+    const snapshot = (stored) => ({
+        revision: stored.revision, settings: (stored.state.settings ?? {}), active, restartRequired: saved,
+        precedence: `Saved in S3 (${USER_STATE_KEY}) and applied after restart. The configuration file, environment variables and command-line flags override them.`
+    });
+    const gcSnapshot = (stored) => ({
+        revision: stored.revision, policy: stored.state.gc ? GcPolicySchema.parse(stored.state.gc) : null, saved: stored.state.gc !== undefined, lastRuns, stateKey: USER_STATE_KEY
+    });
+    const settings = {
+        read: async () => snapshot(await userState.read().catch(conflict)),
+        async save(input, revision) {
+            const parsed = editable.safeParse(input);
+            if (!parsed.success)
+                throw new ConfigError(parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; '));
+            // Prove the exact deployment (file, environment, flags and these settings) can start before keeping them.
+            loadServerConfig(argv, env, cwd, undefined, parsed.data);
+            // What the person chose, as sent: validated, but without the defaults filled in, so unchosen settings keep following the defaults.
+            const stored = await userState.update(revision, state => ({ ...state, settings: input })).catch(conflict);
+            saved = true;
+            return snapshot(stored);
+        }
     };
-    return { read, save(settings, revision) {
-            const update = pending.then(async () => {
-                const parsed = editable.safeParse(settings);
-                if (!parsed.success)
-                    throw new ConfigError(parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; '));
-                const before = await readText();
-                if (digest(before) !== revision)
-                    throw new ConfigError('Settings changed. Reload them before saving.');
-                const original = JSON.parse(before);
-                const merged = { ...Object.fromEntries(Object.entries(original).filter(([key]) => !keys.has(key))), ...parsed.data };
-                const text = `${JSON.stringify(merged, null, 2)}\n`;
-                // Prove it is independently usable, then prove the exact deployment (including overrides) can start.
-                const base = loadServerConfig(['--config', file], env, cwd, () => text);
-                const effective = loadServerConfig([...argv, '--config', file], env, cwd, () => text);
-                try {
-                    for (const backend of [...base.backends, ...effective.backends])
-                        parseStoreLocation(backend.url, path.dirname(file), env);
-                }
-                catch (error) {
-                    throw new ConfigError(error instanceof Error ? error.message : String(error));
-                }
-                const temporary = `${file}.${randomUUID()}.tmp`;
-                try {
-                    await writeFile(temporary, text, { mode: 0o600, flag: 'wx' });
-                    if (await readText() !== before)
-                        throw new ConfigError('Settings changed. Reload them before saving.');
-                    await rename(temporary, file);
-                }
-                finally {
-                    await rm(temporary, { force: true });
-                }
-                saved = true;
-                return read();
-            });
-            pending = update.catch(() => undefined);
-            return update;
-        } };
+    const gc = {
+        read: async () => gcSnapshot(await userState.read().catch(conflict)),
+        async save(input, revision) {
+            const parsed = GcPolicySchema.safeParse(input);
+            if (!parsed.success)
+                throw new ConfigError(parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; '));
+            return gcSnapshot(await userState.update(revision, state => ({ ...state, gc: parsed.data })).catch(conflict));
+        },
+        policy: async () => { const { state } = await userState.read(); return state.gc ? GcPolicySchema.parse(state.gc) : null; },
+        record(runs) { lastRuns = [...runs, ...lastRuns.filter(old => !runs.some(run => run.project === old.project))].slice(0, 50); }
+    };
+    return { settings, gc };
 }
 export { SETTINGS_PAGE, renderSettingsPage } from './settings-page.js';

package/dist/server/src/storage.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module Required S3 storage configuration
+ *
+ * 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
+ */
+type Env = Readonly<Record<string, string | undefined>>;
+/** One environment variable of the storage configuration. */
+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;
+};
+/** Every variable that configures storage, required ones first. */
+export declare const S3_VARIABLES: readonly S3Variable[];
+/** The storage settings once checked: everything needed to open the bucket, with credentials spelled out. */
+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 state of one variable after checking, for the banner. */
+export type S3Finding = {
+    readonly variable: S3Variable;
+    readonly status: 'ok' | 'missing' | 'invalid' | 'unset';
+    readonly problem?: string;
+};
+/** The storage configuration could not be used. `findings` has every variable, not only the first problem. */
+export declare class S3ConfigError extends Error {
+    readonly findings: readonly S3Finding[];
+    readonly reason: string;
+    constructor(findings: readonly S3Finding[], reason?: string);
+}
+/** Looks at every storage variable and returns what each is. Nothing here throws. */
+export declare function inspectS3Env(env: Env): readonly S3Finding[];
+/**
+ * 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
+ * const s3 = resolveS3Config(process.env);
+ */
+export declare function resolveS3Config(env: Env): S3Config;
+/** Where the storage is, without a secret: what the log may say. */
+export declare const describeS3: (config: S3Config) => 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.
+ */
+export declare function startupFailure(findings: readonly S3Finding[], reason: string, detail?: string): string;
+export {};

package/dist/server/src/storage.js

@@ -0,0 +1,125 @@
+/**
+ * @module Required S3 storage configuration
+ *
+ * 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
+ */
+const hostOf = (value) => {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return 'must start with https:// (or http:// for a local S3 server)';
+        if (url.username || url.password)
+            return 'must not contain a user name or password; credentials have their own variables';
+        if (url.search || url.hash)
+            return 'must be just the address, with no query or fragment';
+        return null;
+    }
+    catch {
+        return 'is not a URL; write it like https://s3.eu-west-1.amazonaws.com';
+    }
+};
+/** Every variable that configures storage, required ones first. */
+export const S3_VARIABLES = [
+    { name: 'ATLAS_S3_ENDPOINT', required: true, meaning: 'S3 API endpoint of the object storage service', example: 'https://s3.eu-west-1.amazonaws.com', check: hostOf },
+    { name: 'ATLAS_S3_BUCKET', required: true, meaning: 'Bucket that holds reports and user state; it must already exist', example: 'my-atlas-reports',
+        check: value => (/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(value) ? null : 'must be 3-63 lowercase letters, digits, dots or hyphens, starting and ending with a letter or digit') },
+    { name: 'ATLAS_S3_REGION', required: true, meaning: 'Region of the bucket (`auto` for Cloudflare R2, `us-east-1` for most self-hosted servers)', example: 'eu-west-1',
+        check: value => (/^[a-z0-9][a-z0-9-]*$/.test(value) ? null : 'must be lowercase letters, digits and hyphens, like eu-west-1') },
+    { name: 'ATLAS_S3_ACCESS_KEY_ID', required: true, meaning: 'Access key id of an account that may list, read, write and delete in the bucket', example: 'AKIAEXAMPLE', secret: true,
+        check: value => (/^\S+$/.test(value) ? null : 'must not contain spaces or line breaks') },
+    { name: 'ATLAS_S3_SECRET_ACCESS_KEY', required: true, meaning: 'Secret key that goes with the access key id', example: 'change-me', secret: true,
+        check: value => (/^\S+$/.test(value) ? null : 'must not contain spaces or line breaks') },
+    { name: 'ATLAS_S3_PREFIX', required: false, meaning: 'Folder inside the bucket for everything Atlas writes (default: the bucket root)', example: 'atlas',
+        check: value => (/^[\w./-]+$/.test(value) && !value.split('/').includes('..') ? null : 'may contain only letters, digits, `.`, `_`, `-` and `/`, and no `..`') },
+    { name: 'ATLAS_S3_PATH_STYLE', required: false, meaning: 'Address the bucket as endpoint/bucket/key (default: yes; set 0 for virtual-hosted style)', example: '1',
+        check: value => (['1', '0', 'true', 'false'].includes(value) ? null : 'must be 1, 0, true or false') },
+    { name: 'ATLAS_S3_SESSION_TOKEN', required: false, meaning: 'Session token, only for temporary credentials', example: '', secret: true,
+        check: value => (/^\S+$/.test(value) ? null : 'must not contain spaces or line breaks') }
+];
+/** The storage configuration could not be used. `findings` has every variable, not only the first problem. */
+export class S3ConfigError extends Error {
+    findings;
+    reason;
+    constructor(findings, reason = 'the S3 configuration is missing or invalid') {
+        super(startupFailure(findings, reason));
+        this.findings = findings;
+        this.reason = reason;
+        this.name = 'S3ConfigError';
+    }
+}
+/** Looks at every storage variable and returns what each is. Nothing here throws. */
+export function inspectS3Env(env) {
+    return S3_VARIABLES.map(variable => {
+        const raw = env[variable.name];
+        if (raw === undefined || raw.trim() === '')
+            return { variable, status: variable.required ? 'missing' : 'unset' };
+        const problem = variable.check(raw.trim());
+        return problem ? { variable, status: 'invalid', problem } : { variable, status: 'ok' };
+    });
+}
+/**
+ * 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
+ * const s3 = resolveS3Config(process.env);
+ */
+export function resolveS3Config(env) {
+    const findings = inspectS3Env(env);
+    if (findings.some(finding => finding.status === 'missing' || finding.status === 'invalid'))
+        throw new S3ConfigError(findings);
+    const value = (name) => env[name]?.trim() ?? '';
+    const style = value('ATLAS_S3_PATH_STYLE');
+    return {
+        endpoint: value('ATLAS_S3_ENDPOINT').replace(/\/+$/, ''), bucket: value('ATLAS_S3_BUCKET'), region: value('ATLAS_S3_REGION'),
+        prefix: value('ATLAS_S3_PREFIX').replace(/^\/+|\/+$/g, ''), pathStyle: style === '' ? true : style === '1' || style === 'true',
+        accessKeyId: value('ATLAS_S3_ACCESS_KEY_ID'), secretAccessKey: value('ATLAS_S3_SECRET_ACCESS_KEY'),
+        ...(value('ATLAS_S3_SESSION_TOKEN') ? { sessionToken: value('ATLAS_S3_SESSION_TOKEN') } : {})
+    };
+}
+/** Where the storage is, without a secret: what the log may say. */
+export const describeS3 = (config) => `s3://${config.bucket}/${config.prefix ? `${config.prefix}/` : ''} on ${new URL(config.endpoint).host} (${config.region})`;
+const RULE = '='.repeat(78);
+/**
+ * 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.
+ */
+export function startupFailure(findings, reason, detail) {
+    const width = Math.max(...findings.map(finding => finding.variable.name.length));
+    const mark = (finding) => finding.status === 'missing' ? '[MISSING]' : finding.status === 'invalid' ? '[INVALID]' : finding.status === 'ok' ? '[ok]     ' : '[not set]';
+    const line = (finding) => {
+        const { variable } = finding;
+        const note = finding.status === 'invalid' ? `${finding.problem}` : variable.meaning;
+        return `  ${mark(finding)} ${variable.name.padEnd(width)}  ${note}`;
+    };
+    const required = findings.filter(finding => finding.variable.required);
+    const optional = findings.filter(finding => !finding.variable.required);
+    const bad = findings.filter(finding => finding.status === 'missing' || finding.status === 'invalid').map(finding => finding.variable.name);
+    return [
+        '', RULE,
+        '  ATLAS CANNOT START: S3 STORAGE IS NOT USABLE',
+        RULE,
+        `  Why:    ${reason}.`,
+        '  Reason: Atlas stores ALL reports and ALL user state (the garbage collection policy and saved',
+        '          settings) in S3-compatible object storage, and nowhere else. There is no local-disk,',
+        '          in-memory or database fallback, so the server refuses to start without working S3.',
+        ...(detail ? ['', `  S3 said: ${detail}`] : []),
+        '',
+        '  Required environment variables:',
+        ...required.map(line),
+        '',
+        '  Optional environment variables:',
+        ...optional.map(line),
+        '',
+        bad.length ? `  Fix these ${bad.length}: ${bad.join(', ')}` : '  Every variable is well-formed, so the values themselves are wrong; check them against the storage service.',
+        '  See .env.example for a complete example and docs/server.md#required-s3-storage.',
+        '  Exiting with status 2.', RULE, ''
+    ].join('\n');
+}

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

@@ -0,0 +1,31 @@
+import type { ObjectStore } from '../../reports/src/object-store.js';
+import { type UserState } from '../../schema/src/user-state.js';
+/** Where the user state lives, relative to the store (the bucket plus `ATLAS_S3_PREFIX`). */
+export declare const USER_STATE_KEY = "server/state.json";
+/** The user state as stored: the document, its `revision` and whether the object `exists` yet. */
+export type StoredUserState = {
+    readonly state: UserState;
+    readonly revision: string;
+    readonly exists: boolean;
+};
+/** Raised when the stored user state cannot be trusted. The message says where it is and what to do. */
+export declare class UserStateError extends Error {
+}
+/** The user state of one server: read it, or change it against the revision that was read. */
+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 kept in `store` at {@link USER_STATE_KEY}.
+ *
+ * @example
+ * const userState = userStateStore(s3Backend.store);
+ * const { state } = await userState.read();
+ */
+export declare function userStateStore(store: ObjectStore): UserStateStore;