@crvouga/atlas 0.16.0 → 1.0.0

package/dist/schema/src/layer.js

@@ -109,12 +109,53 @@ export const AttachmentSchema = z.looseObject({
     height: z.number().nonnegative().optional(),
     durationMs: z.number().nonnegative().optional().describe('For video and audio'),
     description: z.string().optional(),
+    omitted: z.string().optional().describe('Why the producer did not include its bytes, in an open vocabulary: too-large, not-found, not-allowed, over-budget, policy… Present on a metadata-only attachment, so a reader can tell "left out" from "never recorded"'),
     tags: z.array(z.string()).optional().describe('Free labels of this one attachment, such as `demo`: shown as `#demo`, searchable, and normalized by `normalizeTag` (a leading `#` and letter case never matter). Unlike the tags of a check they say nothing about its result'),
     at: MomentSchema.optional(),
     poster: z.string().optional().describe('The `id` of an attachment that stands for this one before it is opened'),
     captions: z.array(z.string()).optional().describe('The `id`s of attachments (WebVTT, SRT) that caption this one'),
     extensions: ExtensionsSchema.optional()
 });
+/**
+ * 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.
+ */
+export const RECORDING_EXPECTATIONS = ['required', 'not-applicable'];
+/**
+ * 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.
+ */
+export const RecordingItemSchema = z.looseObject({
+    check: z.string().min(1).describe('The id of the check'),
+    state: z.string().min(1),
+    reason: z.string().optional().describe('Why the recording is not uploaded. Never contains a path, a token or payload data'),
+    files: z.array(z.looseObject({
+        name: z.string(),
+        state: z.string().optional(),
+        bytes: z.number().int().nonnegative().optional(),
+        sha256: z.string().optional().describe('The checksum of the stored bytes: proof the layer holds this exact file'),
+        reason: z.string().optional()
+    })).optional().describe('Every video attachment of the check, at any level')
+});
+/**
+ * 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.
+ */
+export const RecordingReceiptSchema = z.looseObject({
+    expected: z.number().int().nonnegative().describe('Checks that required a recording: uploaded + referenced + skipped + unresolved'),
+    uploaded: z.number().int().nonnegative(),
+    referenced: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+    unresolved: z.number().int().nonnegative(),
+    notApplicable: z.number().int().nonnegative().describe('Checks intentionally unrecorded. They are not expected and not missing'),
+    items: z.array(RecordingItemSchema)
+});
 /** A note about a result: a warning, a deprecation, a coverage figure, an accessibility finding, anything. */
 export const AnnotationSchema = z.looseObject({
     type: z.string().min(1).describe('An open vocabulary: note, warning, deprecation, issue, accessibility, coverage…'),
@@ -178,6 +219,7 @@ export const CheckSchema = z.looseObject({
     specPath: z.string().optional().describe('The spec this check belongs to, relative to the repository, such as specs/join.feature'),
     measurements: z.array(MeasurementSchema).default([]),
     durationMs: z.number().nonnegative().optional().describe('How long the check took, when the producer measured it'),
+    recordingExpectation: z.string().optional().describe('`required`: expect a video of this check, and report whether it was published. `not-applicable`: intentionally unrecorded. Absent: no expectation. Never changes the check\'s status'),
     ...evidenceShape,
     steps: z.array(StepSchema).optional().describe("The check's timeline"),
     attempts: z.array(AttemptSchema).optional().describe('Every try, when the check was retried')
@@ -269,6 +311,7 @@ export const LayerDocumentSchema = z.looseObject({
     source: LayerSourceSchema.nullable().default(null),
     recording: RecordingAddressSchema.nullable().default(null),
     bundle: BundleIndexSchema.default({}),
+    recordings: RecordingReceiptSchema.optional().describe('Which expected recordings were published. Absent: the producer expected none, or predates this field; a reader reports Unknown'),
     ...evidenceShape
 });
 /**
@@ -321,6 +364,14 @@ function lenientEvidence(holder, nested = []) {
 }
 function lenientLayer(raw) {
     const layer = lenientEvidence(raw);
+    // A receipt a reader cannot read is no receipt: recording completeness is then Unknown, and the layer is kept.
+    if ('recordings' in layer) {
+        const receipt = RecordingReceiptSchema.safeParse(layer.recordings);
+        if (receipt.success)
+            layer.recordings = receipt.data;
+        else
+            delete layer.recordings;
+    }
     // The execution only groups and labels: one that cannot be read leaves the layer to the documented grouping, never refuses it.
     if ('run' in layer && !LayerRunSchema.safeParse(layer.run).success)
         delete layer.run;
@@ -426,6 +477,25 @@ const CountsSchema = z.object({
     'not-run': z.number().int().nonnegative(),
     total: z.number().int().nonnegative()
 });
+/**
+ * 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.
+ */
+export const RecordingCompletenessSchema = z.looseObject({
+    state: z.enum(['complete', 'incomplete', 'none-expected', 'unknown']),
+    expected: z.number().int().nonnegative(),
+    uploaded: z.number().int().nonnegative(),
+    referenced: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+    unresolved: z.number().int().nonnegative(),
+    notApplicable: z.number().int().nonnegative(),
+    layersWithoutReceipt: z.number().int().nonnegative().describe('Layers that contribute results but declared no recording expectations: their completeness is unknown'),
+    gaps: z.array(z.looseObject({
+        spec: z.string().nullable(), check: z.string(), layer: z.string(), environment: z.string().nullable(),
+        state: z.string(), reason: z.string().optional()
+    })).describe('Each expected recording that is skipped or unresolved')
+});
 /** The `schemaVersion` of the `ReportStatus` JSON, currently 1. */
 export const REPORT_STATUS_SCHEMA_VERSION = 1;
 /**
@@ -463,7 +533,8 @@ export const ReportStatusSchema = z.looseObject({
         backend: z.string(),
         runUrl: z.string().nullable(),
         detail: z.string()
-    })).describe('Each slot whose newest completed result failed, or that is still running')
+    })).describe('Each slot whose newest completed result failed, or that is still running'),
+    recordings: RecordingCompletenessSchema.optional().describe('Whether the recordings the producers expected were published, separately from `ok`. It never changes `ok`')
 });
 /**
  * The specs of one version of a project, as published: what the report is laid over. Layers of

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>;

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

@@ -0,0 +1,54 @@
+/**
+ * @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';
+import { ServerEditableSettingsSchema } from './server-config.js';
+/**
+ * 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 const GcPolicySchema = z.strictObject({
+    enabled: z.boolean().describe('Delete eligible layers on a schedule. `false` keeps the policy but deletes nothing'),
+    maxAgeDays: z.number().int().min(1).max(3650).describe('A superseded layer is eligible once it was recorded more than this many days ago'),
+    keepLatest: z.number().int().min(0).max(1_000_000).default(20).describe('Always keep this many of the newest layers, however old, so recent history stays'),
+    intervalHours: z.number().min(1).max(720).default(24).describe('How often the server applies the policy')
+});
+/** What one pass of garbage collection found and did, for one project. */
+export const GcRunSchema = z.looseObject({
+    project: z.string(),
+    dryRun: z.boolean(),
+    at: z.string().describe('When the pass finished, ISO 8601'),
+    candidates: z.number().int().min(0).describe('Layers the policy would delete'),
+    deletedLayers: z.number().int().min(0),
+    deletedBlobs: z.number().int().min(0),
+    keptLayers: z.number().int().min(0),
+    error: z.string().optional().describe('Why the pass stopped early, when it did')
+});
+/** The user state document stored in S3. Both parts are optional: absent means "never chosen". */
+export const UserStateSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    gc: GcPolicySchema.optional().describe('The garbage collection policy. Absent until someone saves one: then nothing is deleted'),
+    settings: ServerEditableSettingsSchema.optional().describe('Report and live-run settings saved from the settings page, applied at the next start')
+});
+/**
+ * `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 const GcSnapshotSchema = z.looseObject({
+    revision: z.string().regex(/^[a-f0-9]{64}$/),
+    policy: GcPolicySchema.nullable(),
+    saved: z.boolean().describe('Whether a policy exists in S3. `false` means garbage collection is off: nothing is deleted'),
+    lastRuns: z.array(GcRunSchema).describe('The most recent pass over each project, newest first; empty before the first pass'),
+    stateKey: z.string().describe('Where the user state lives in the bucket, relative to the configured prefix')
+});
+/** `POST /api/settings/gc/run`: the passes that ran, one per project. */
+export const GcRunResultSchema = z.looseObject({ runs: z.array(GcRunSchema), policy: GcPolicySchema.nullable() });

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

@@ -13,7 +13,8 @@ import { type BackendInput } from '../../reports/src/compose.js';
 import type { LayerHeader } from '../../reports/src/evidence-types.js';
 import type { ObjectStore } from '../../reports/src/object-store.js';
 import { ReportIndex } from '../../reports/src/report-index.js';
-import { type ServerSettings } from './settings.js';
+import { type GcSettings, type ServerSettings } from './settings.js';
+import type { GcPolicy, GcRun } from '../../schema/src/user-state.js';
 import type { ResolvedToken } from './config.js';
 import { EventHub } from './events.js';
 /** What the server is built from: its `backends` (read together) and which one takes uploads (`write`), `tokens`, the built `site`, the report's filters (`include`, `outlineBranch`), `limits`, timings, `log`, and `now` for tests. */
@@ -44,8 +45,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>;
 };
@@ -61,6 +66,15 @@ export type AtlasServer = {
     }[];
     /** 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;
 };

package/dist/server/src/app.js

@@ -35,6 +35,7 @@ import { LiveRunStartSchema, LiveRunUpdateSchema } from '../../schema/src/live-r
 import { LiveRuns, LiveRunError } from './live-runs.js';
 import { ConfigError } from './config.js';
 import { renderSettingsPage } from './settings.js';
+import { collectGarbage, planGarbage } from '../../reports/src/garbage.js';
 import { Refusal } from './validate.js';
 import { createAuth } from './auth.js';
 import { EventHub } from './events.js';
@@ -340,6 +341,50 @@ function createProjectApplication(options) {
             throw error;
         }
     });
+    // The garbage collection policy: its own document in the user state, saved in S3 with the same revision rules.
+    app.get('/api/settings/gc', async (c) => {
+        const verdict = auth.check(c.req.raw, 'admin');
+        if (!verdict.ok)
+            return unauthorized(verdict);
+        if (!options.gc)
+            return problemResponse(503, 'Garbage collection settings are managed by the embedding application.');
+        try {
+            return c.json(await options.gc.read(), 200, { 'cache-control': 'no-store' });
+        }
+        catch (error) {
+            if (error instanceof ConfigError)
+                return problemResponse(503, error.message);
+            throw error;
+        }
+    });
+    app.put('/api/settings/gc', async (c) => {
+        const verdict = auth.check(c.req.raw, 'admin');
+        if (!verdict.ok)
+            return unauthorized(verdict);
+        if (!options.gc)
+            return problemResponse(503, 'Garbage collection settings are managed by the embedding application.');
+        const revision = /^"([a-f0-9]{64})"$/.exec(c.req.header('if-match') ?? '')?.[1];
+        if (!revision)
+            return problemResponse(428, 'Load the policy first and send its revision in If-Match.');
+        try {
+            const bytes = await readLimited(c.req.raw, Math.min(limits.json, 16 * 1024));
+            let input;
+            try {
+                input = JSON.parse(new TextDecoder().decode(bytes));
+            }
+            catch {
+                return problemResponse(422, 'The body is not JSON.');
+            }
+            return c.json(await options.gc.save(input, revision), 200, { 'cache-control': 'no-store' });
+        }
+        catch (error) {
+            if (error instanceof ConfigError)
+                return problemResponse(error.message.startsWith('Settings changed') ? 409 : 422, error.message);
+            if (error instanceof Refusal)
+                return problemResponse(error.status, error.message);
+            throw error;
+        }
+    });
     // Live updates: told when the report changes, and when specs or runs do.
     app.get('/api/events', c => events.stream(c.req.raw, () => ({ version: index.snapshot().version, ready: index.ready, time: now(), heartbeatMs: options.heartbeatMs ?? 15_000 })));
     // The report as it stands: one request, only what wins. Everything else about a layer is history.
@@ -665,11 +710,28 @@ function createProjectApplication(options) {
         options.log?.({ at: new Date(now()).toISOString(), level: 'error', path: new URL(c.req.url).pathname, error: error instanceof Error ? error.message : String(error) });
         return c.json({ error: 'Something went wrong on the server. It has been logged.' }, 500);
     });
+    async function collect(policy, run) {
+        const base = { project: run.project, dryRun: run.dryRun };
+        try {
+            // Look at the store once more first, so "superseded" is judged on everything uploaded so far.
+            await index.refreshNow();
+            const plan = await planGarbage(writeBackend.store, { policy, nowMs: now(), eligible: index.superseded() });
+            const outcome = run.dryRun ? { deletedLayers: 0, deletedBlobs: 0 } : await collectGarbage(writeBackend.store, plan);
+            if (outcome.deletedLayers)
+                options.log?.({ at: new Date(now()).toISOString(), level: 'info', gc: run.project, deletedLayers: outcome.deletedLayers, deletedBlobs: outcome.deletedBlobs });
+            return { ...base, at: new Date(now()).toISOString(), candidates: plan.candidates.length, ...outcome, keptLayers: plan.kept };
+        }
+        catch (error) {
+            options.log?.({ at: new Date(now()).toISOString(), level: 'error', gc: run.project, error: String(error) });
+            return { ...base, at: new Date(now()).toISOString(), candidates: 0, deletedLayers: 0, deletedBlobs: 0, keptLayers: 0, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
     return {
         fetch: async (request) => app.fetch(request),
         routes: app.routes.map(({ method, path }) => ({ method, path })),
         index,
         events,
+        collectGarbage: collect,
         ready: index.start(options.refreshMs ?? 10_000),
         close: () => { clearInterval(leaseTimer); stopListening(); index.stop(); events.close(); }
     };