@crvouga/atlas 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog: @crvouga/atlas
 
-## 1.19.0 (2026-10-29)
+## 1.20.0 (2026-10-29)
+
+### Features
+
+- mark stored-then-unavailable recordings in the Runs tab from a server read-back ([8c9370a](https://github.com/crvouga/atlas/commit/8c9370aecf67e2b2e690ba25ed512be36a137875))
+
+## 1.19.0 (2026-10-28)
 
 ### Features
 

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

@@ -1679,6 +1679,61 @@ export declare const ArtifactTagsSchema: z.ZodObject<{
         atMs: z.ZodNumber;
     }, z.core.$loose>>;
 }, z.core.$loose>;
+/** One stored video that failed the server's read-back: which check holds it and what is wrong with it. */
+export declare const StoredRecordingGapSchema: z.ZodObject<{
+    check: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    bundleKey: z.ZodString;
+    problem: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$loose>;
+/** What reading back the stored videos of one layer found. */
+export declare const LayerRecordingCheckSchema: z.ZodObject<{
+    layer: z.ZodString;
+    run: z.ZodString;
+    verifiedAtMs: z.ZodNumber;
+    checked: z.ZodNumber;
+    ok: z.ZodNumber;
+    referenced: z.ZodNumber;
+    gaps: z.ZodArray<z.ZodObject<{
+        check: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        bundleKey: z.ZodString;
+        problem: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/**
+ * `GET` and `POST /api/reports/recordings/verification`: the newest read-back the server did of stored videos, per layer.
+ * A layer that was never read back is absent, which means "not verified", never "fine".
+ */
+export declare const RecordingVerificationSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    layers: z.ZodArray<z.ZodObject<{
+        layer: z.ZodString;
+        run: z.ZodString;
+        verifiedAtMs: z.ZodNumber;
+        checked: z.ZodNumber;
+        ok: z.ZodNumber;
+        referenced: z.ZodNumber;
+        gaps: z.ZodArray<z.ZodObject<{
+            check: z.ZodNullable<z.ZodString>;
+            name: z.ZodString;
+            bundleKey: z.ZodString;
+            problem: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    notices: z.ZodArray<z.ZodString>;
+    verified: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+/** The document of {@link RecordingVerificationSchema}, as a type. */
+export type RecordingVerification = z.infer<typeof RecordingVerificationSchema>;
+/** The body of `POST /api/reports/recordings/verification`. Both fields are optional; an empty body reads back the newest layers. */
+export declare const RecordingVerifyRequestSchema: z.ZodObject<{
+    layers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
 /** A source a review collection points at: one recorded result of one archived layer, and optionally one of its recordings. Exact and immutable: a layer never changes. */
 export declare const ReviewSourceSchema: z.ZodObject<{
     layer: z.ZodString;

package/dist/schema/src/api.js

@@ -254,6 +254,39 @@ export const ArtifactTagsSchema = z.looseObject({
     schemaVersion: z.literal(1),
     entries: z.array(ArtifactTagEntrySchema)
 });
+/** One stored video that failed the server's read-back: which check holds it and what is wrong with it. */
+export const StoredRecordingGapSchema = z.looseObject({
+    check: z.string().nullable().describe('The id of the check that holds the video, or null for a video attached to the run or a part'),
+    name: z.string().describe('The attachment\'s name'),
+    bundleKey: z.string().describe('The key the layer names the file by'),
+    problem: z.string().describe('`not-in-bundle`, `blob-missing`, `unreadable`, `size-mismatch`, `checksum-mismatch` or `undecodable`. An open vocabulary: treat an unknown value as a gap'),
+    reason: z.string().describe('A short explanation without secrets or paths')
+});
+/** What reading back the stored videos of one layer found. */
+export const LayerRecordingCheckSchema = z.looseObject({
+    layer: z.string().describe('The layer id'),
+    run: z.string().describe('The key of the run the layer belongs to (a `RunSummary.key`)'),
+    verifiedAtMs: z.number().describe('When the server read the videos back, epoch milliseconds'),
+    checked: z.number().int().describe('Videos read back: those that name a bundle key'),
+    ok: z.number().int().describe('Of those, the ones that passed every check'),
+    referenced: z.number().int().describe('Videos given only by address, which Atlas cannot read back and so does not vouch for'),
+    gaps: z.array(StoredRecordingGapSchema).describe('The videos that did not pass. Never a test result: statuses are unchanged')
+});
+/**
+ * `GET` and `POST /api/reports/recordings/verification`: the newest read-back the server did of stored videos, per layer.
+ * A layer that was never read back is absent, which means "not verified", never "fine".
+ */
+export const RecordingVerificationSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    layers: z.array(LayerRecordingCheckSchema).describe('Layers the server has read back and still holds, newest first'),
+    notices: z.array(z.string()).describe('Layers the last pass could not read at all: their recordings are unknown, not verified'),
+    verified: z.number().int().optional().describe('POST only: how many layers this pass read back')
+});
+/** The body of `POST /api/reports/recordings/verification`. Both fields are optional; an empty body reads back the newest layers. */
+export const RecordingVerifyRequestSchema = z.looseObject({
+    layers: z.array(z.string().regex(/^[0-9a-f]{7,64}$/i)).max(50).optional().describe('Only layers whose id starts with one of these (at least 7 hex digits)'),
+    limit: z.number().int().min(1).max(200).optional().describe('How many of the newest layers to read back. Default 20, at most 200')
+});
 /** A source a review collection points at: one recorded result of one archived layer, and optionally one of its recordings. Exact and immutable: a layer never changes. */
 export const ReviewSourceSchema = z.looseObject({
     layer: z.string().regex(/^[0-9a-f]{64}$/).describe('The id of the archived layer that recorded the result'),

package/dist/server/src/app.js

@@ -44,6 +44,7 @@ import { createAuth } from './auth.js';
 import { EventHub } from './events.js';
 import { projectServer } from './projects.js';
 import { mountReviewCollections } from './review-collections.js';
+import { mountRecordingVerification } from './recording-verification.js';
 import { readLimited, storeApi } from './store-api.js';
 const gzipAsync = promisify(gzip);
 const brotliAsync = promisify(brotliCompress);
@@ -260,7 +261,7 @@ function createProjectApplication(options) {
             name: 'atlas', version: options.version ?? null, role: identity?.role ?? 'read', open: auth.open,
             write: options.write, ready: index.ready, viewers: events.count, time: now(),
             backends: snapshot.backends.map(({ id, label, available }) => ({ id, label, available, write: id === options.write })),
-            ...(({ backends: _unused, ...rest }) => rest)(index.stats()), capabilities: { events: true, ingest: true, store: true, checks: true, status: true, effective: true, live: true, tests: true, artifactTags: true, artifactSearch: true, reviewCollections: true }
+            ...(({ backends: _unused, ...rest }) => rest)(index.stats()), capabilities: { events: true, ingest: true, store: true, checks: true, status: true, effective: true, live: true, tests: true, artifactTags: true, artifactSearch: true, reviewCollections: true, recordingVerification: true }
         });
     });
     app.get('/api/live', async (c) => c.json({ runs: await live.list() }, 200, { 'cache-control': 'no-store' }));
@@ -565,6 +566,7 @@ function createProjectApplication(options) {
     });
     // Review collections: immutable, curated references to recorded results, with reviewers' notes kept apart.
     mountReviewCollections(app, { store: tagStore, stores, auth, index, now, maxBytes: limits.json, unauthorized });
+    mountRecordingVerification(app, { stores, auth, index, now, unauthorized });
     app.route('/api/reports', layers);
     // Upload: the store protocol, and a simple JSON way in for anything that can make a request.
     app.route('/api/store', storeApi({

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

@@ -1,5 +1,5 @@
 /** 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 declare const API_VERSION = "1.6.0";
+export declare const API_VERSION = "1.7.0";
 /** Who may call an operation: `none` (anyone), or the least role that may (`read` < `critic` < `publish` < `admin`). */
 export type Role = 'none' | 'read' | 'critic' | 'publish' | 'admin';
 type JsonSchema = Record<string, unknown>;

package/dist/server/src/openapi.js

@@ -14,10 +14,10 @@
  */
 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, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, UiCatalogSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema, ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewCollectionListSchema, ReviewCollectionDetailSchema, ReviewNoteInputSchema, ReviewNoteSchema, ReviewManifestSchema } from '../../schema/src/api.js';
+import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, UiCatalogSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema, ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewCollectionListSchema, ReviewCollectionDetailSchema, ReviewNoteInputSchema, ReviewNoteSchema, ReviewManifestSchema, RecordingVerificationSchema, RecordingVerifyRequestSchema } from '../../schema/src/api.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.6.0';
+export const API_VERSION = '1.7.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. */
 function schemaOf(schema, io = 'output') {
     const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { target: 'draft-2020-12', unrepresentable: 'any', io });
@@ -38,6 +38,7 @@ const COMPONENTS = {
     Outline: [OutlineSchema, 'output'], EvidencePage: [EvidencePageSchema, 'output'], LayerRows: [LayerRowsSchema, 'output'], CheckDetail: [CheckDetailSchema, 'output'],
     ArtifactTagEdit: [ArtifactTagEditSchema, 'input'], ArtifactTagEntry: [ArtifactTagEntrySchema, 'output'], ArtifactTags: [ArtifactTagsSchema, 'output'],
     ReviewCollectionRequest: [ReviewCollectionRequestSchema, 'input'], ReviewCollection: [ReviewCollectionSchema, 'output'], ReviewCollectionList: [ReviewCollectionListSchema, 'output'], ReviewCollectionDetail: [ReviewCollectionDetailSchema, 'output'], ReviewNoteInput: [ReviewNoteInputSchema, 'input'], ReviewNote: [ReviewNoteSchema, 'output'], ReviewManifest: [ReviewManifestSchema, 'output'],
+    RecordingVerification: [RecordingVerificationSchema, 'output'], RecordingVerifyRequest: [RecordingVerifyRequestSchema, 'input'],
     TestCatalog: [TestCatalogSchema, 'output'], CatalogHealth: [CatalogHealthSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], TestReliability: [TestReliabilitySchema, 'output'], RunList: [RunListSchema, 'output'], ArtifactList: [ArtifactListSchema, 'output'], UiCatalog: [UiCatalogSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
     SpecIndex: [SpecIndexSchema, 'output'], ReportSources: [ReportSourcesSchema, 'output'], RunsIndex: [RunsIndexSchema, 'output'],
     RunEvent: [LiveRunSchema, 'output'], HelloEvent: [HelloEventSchema, 'output'], ReportEvent: [ReportEventSchema, 'output'], AtlasChangeEvent: [AtlasChangeSchema, 'output'], PingEvent: [PingEventSchema, 'output']
@@ -367,6 +368,27 @@ const BASE_OPERATIONS = [
         body: { description: 'The attachment and the tags to add and remove. At most 20 of each, 64 KiB.', contentType: 'application/json', required: true, schema: ref('ArtifactTagEdit') },
         responses: { '201': json('The recorded entry.', 'ArtifactTagEntry'), '401': UNAUTHORIZED, '403': FORBIDDEN, '413': problem('Request too large.'), '422': problem('Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.') }
     },
+    {
+        route: 'GET /api/reports/recordings/verification', path: '/api/reports/recordings/verification', operationId: 'getRecordingVerification', tag: 'Report', role: 'read',
+        summary: 'Which stored recordings the server last read back, and which were gone or damaged',
+        description: [
+            'The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run\'s recordings as stored-then-unavailable beside its test results.',
+            '',
+            'This route never reads a blob: it returns what a publish token\'s `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server\'s memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).'
+        ].join('\n'),
+        parameters: [
+            { name: 'run', in: 'query', description: 'Only layers of this run (a key from `GET /api/reports/runs`).', schema: str },
+            { name: 'layer', in: 'query', description: 'Only layers whose id starts with this prefix. Repeatable or comma-separated.', schema: str }
+        ],
+        responses: { '200': json('The held read-backs.', 'RecordingVerification'), '401': UNAUTHORIZED }
+    },
+    {
+        route: 'POST /api/reports/recordings/verification', path: '/api/reports/recordings/verification', operationId: 'verifyRecordings', tag: 'Report', role: 'publish',
+        summary: 'Read stored recordings back and check them (publish token)',
+        description: 'Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type\'s container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.',
+        body: { description: 'Optional `layers` (id prefixes) and `limit`. An empty body reads back the newest layers.', contentType: 'application/json', required: false, schema: ref('RecordingVerifyRequest') },
+        responses: { '200': json('The read-backs now held.', 'RecordingVerification'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('A read-back is already running.'), '413': problem('Request too large.'), '422': problem('Not a verification request.'), '502': problem('A store could not be read.'), '503': NOT_READY }
+    },
     {
         route: 'GET /api/reports/review-collections', path: '/api/reports/review-collections', operationId: 'listReviewCollections', tag: 'Report', role: 'read',
         summary: 'Review collections: curated sets of recordings, newest first',

package/dist/server/src/recording-verification.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module Recording verification routes
+ *
+ * `/api/reports/recordings/verification`: whether the videos a run published can still be read back from storage as
+ * they were published, apart from whether the run's tests passed. A viewer reads the newest result with a read token
+ * (`GET`, which never touches a blob). A publish token starts a read-back (`POST`), which does read blobs and so is
+ * bounded: the newest 20 layers unless asked for more, at most 200, one pass at a time. The result is kept in this
+ * process only (it is derived, not state: a restart means "not verified yet", never "fine"), and only for layers the
+ * store still holds. It adds nothing to any layer and changes no status, slot or winner. This is the same check as
+ * `atlas report verify-recordings`, and as that command it checks stored bytes, not browser playback.
+ *
+ * @see docs/rich-evidence.md#recording-completeness
+ */
+import type { Hono } from 'hono';
+import type { ObjectStore } from '../../reports/src/object-store.js';
+import type { ReportIndex } from '../../reports/src/report-index.js';
+import type { Auth } from './auth.js';
+/** What the verification routes need from the server around them. */
+export type RecordingVerificationDeps = {
+    /** Every backend's store: a layer is read back from the store that holds it. */
+    readonly stores: readonly ObjectStore[];
+    readonly auth: Auth;
+    readonly index: ReportIndex;
+    readonly now: () => number;
+    readonly unauthorized: (verdict: Extract<ReturnType<Auth['check']>, {
+        ok: false;
+    }>) => Response;
+};
+/**
+ * Registers `GET` and `POST /api/reports/recordings/verification` on `app`. The result of the last read-back of each
+ * layer is held in memory, replaced by a newer one, and served only for layers a store still holds. A layer held by
+ * two backends keeps the reading with more gaps, so a copy that lost its blobs is never hidden by one that did not.
+ */
+export declare function mountRecordingVerification(app: Hono, deps: RecordingVerificationDeps): void;

package/dist/server/src/recording-verification.js

@@ -0,0 +1,118 @@
+import { RecordingVerifyRequestSchema } from '../../schema/src/api.js';
+import { eachLimited } from '../../reports/src/completion-order.js';
+import { layerKey } from '../../reports/src/layer-store.js';
+import { verifyStoreRecordings } from '../../reports/src/recording-verify.js';
+import { runKey } from '../../reports/src/test-catalog.js';
+import { problemResponse } from './problem.js';
+import { readLimited } from './store-api.js';
+import { Refusal } from './validate.js';
+const NO_STORE = { 'cache-control': 'no-store' };
+const HELD_MS = 30_000;
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 200;
+/**
+ * Registers `GET` and `POST /api/reports/recordings/verification` on `app`. The result of the last read-back of each
+ * layer is held in memory, replaced by a newer one, and served only for layers a store still holds. A layer held by
+ * two backends keeps the reading with more gaps, so a copy that lost its blobs is never hidden by one that did not.
+ */
+export function mountRecordingVerification(app, deps) {
+    const { stores, auth, index, now } = deps;
+    const held = new Map();
+    let notices = [];
+    let running = false;
+    // Whether a layer's manifest is still in some store (garbage collection removes superseded layers), asked at most every
+    // HELD_MS. Only a `head` of the manifest: no recording is read.
+    const present = new Map();
+    const holds = async (ids) => {
+        const out = new Set();
+        await eachLimited(ids, 8, async (id) => {
+            const known = present.get(id);
+            let value = known !== undefined && now() - known.at < HELD_MS ? known.value : undefined;
+            if (value === undefined) {
+                value = false;
+                for (const store of stores) {
+                    if (await store.head(layerKey(id)).catch(() => false)) {
+                        value = true;
+                        break;
+                    }
+                }
+                present.set(id, { at: now(), value });
+            }
+            if (value)
+                out.add(id);
+        });
+        return out;
+    };
+    const document = async (request, extra = {}) => {
+        const search = new URL(request.url).searchParams;
+        const run = search.get('run');
+        const prefixes = search.getAll('layer').flatMap(value => value.split(',')).map(value => value.trim().toLowerCase()).filter(Boolean);
+        const wanted = [...held.values()].filter(entry => (!run || entry.run === run) && (!prefixes.length || prefixes.some(prefix => entry.layer.startsWith(prefix))));
+        const still = await holds(wanted.map(entry => entry.layer));
+        const layers = wanted.filter(entry => still.has(entry.layer))
+            .sort((a, b) => b.verifiedAtMs - a.verifiedAtMs || (a.layer < b.layer ? -1 : 1));
+        return { schemaVersion: 1, layers, notices, ...extra };
+    };
+    app.get('/api/reports/recordings/verification', async (c) => c.json(await document(c.req.raw), 200, NO_STORE));
+    app.post('/api/reports/recordings/verification', async (c) => {
+        const verdict = auth.check(c.req.raw, 'publish');
+        if (!verdict.ok)
+            return deps.unauthorized(verdict);
+        if (!index.ready)
+            return problemResponse(503, 'The report is still loading. Try again in a moment.', { 'retry-after': '2' });
+        let input = {};
+        try {
+            const bytes = await readLimited(c.req.raw, 16 * 1024);
+            if (bytes.length) {
+                try {
+                    input = JSON.parse(new TextDecoder().decode(bytes));
+                }
+                catch {
+                    return problemResponse(422, 'The body is not JSON.');
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Refusal)
+                return problemResponse(error.status, error.message);
+            throw error;
+        }
+        const parsed = RecordingVerifyRequestSchema.safeParse(input);
+        if (!parsed.success)
+            return problemResponse(422, `Not a verification request: ${parsed.error.issues[0]?.message ?? 'invalid'}.`);
+        if (running)
+            return problemResponse(409, 'A read-back is already running. Read the result with GET when it finishes.', { 'retry-after': '5' });
+        running = true;
+        try {
+            const limit = Math.min(MAX_LIMIT, parsed.data.limit ?? DEFAULT_LIMIT);
+            const runs = new Map();
+            const found = [];
+            const lost = [];
+            const at = now();
+            for (const store of stores) {
+                const result = await verifyStoreRecordings(store, {
+                    ...(parsed.data.layers?.length ? { ids: parsed.data.layers } : {}), limit,
+                    include: layer => { runs.set(layer.id, runKey(layer)); return true; }
+                });
+                lost.push(...result.notices);
+                for (const layer of result.layers)
+                    found.push({ ...layer, run: runs.get(layer.layer) ?? '', verifiedAtMs: at });
+            }
+            // A layer held by two backends keeps the copy with more gaps; a newer pass replaces an older one.
+            const fresh = new Map();
+            for (const entry of found)
+                if ((fresh.get(entry.layer)?.gaps.length ?? -1) < entry.gaps.length || !fresh.has(entry.layer))
+                    fresh.set(entry.layer, entry);
+            for (const [layer, entry] of fresh)
+                held.set(layer, entry);
+            notices = [...new Set(lost)];
+            return c.json(await document(c.req.raw, { verified: fresh.size }), 200, NO_STORE);
+        }
+        catch (error) {
+            return problemResponse(502, `The store could not be read: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+        }
+        finally {
+            running = false;
+        }
+    });
+}

package/docs/reference/http-api.md

@@ -694,6 +694,58 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `201` The recorded entry.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `413` Request too large.; `422` Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.
 
+### Which stored recordings the server last read back, and which were gone or damaged
+
+`GET /api/reports/recordings/verification` · role: read
+
+The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run's recordings as stored-then-unavailable beside its test results.
+
+This route never reads a blob: it returns what a publish token's `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server's memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).
+
+- `run` (query): Only layers of this run (a key from `GET /api/reports/runs`).
+- `layer` (query): Only layers whose id starts with this prefix. Repeatable or comma-separated.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The held read-backs.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Which stored recordings the server last read back, and which were gone or damaged
+
+`GET /api/projects/{project}/reports/recordings/verification` · role: read
+
+The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run's recordings as stored-then-unavailable beside its test results.
+
+This route never reads a blob: it returns what a publish token's `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server's memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `run` (query): Only layers of this run (a key from `GET /api/reports/runs`).
+- `layer` (query): Only layers whose id starts with this prefix. Repeatable or comma-separated.
+
+Responses: `200` The held read-backs.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Read stored recordings back and check them (publish token)
+
+`POST /api/reports/recordings/verification` · role: publish
+
+Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type's container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.
+
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The read-backs now held.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` A read-back is already running.; `413` Request too large.; `422` Not a verification request.; `502` A store could not be read.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Read stored recordings back and check them (publish token)
+
+`POST /api/projects/{project}/reports/recordings/verification` · role: publish
+
+Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type's container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The read-backs now held.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` A read-back is already running.; `413` Request too large.; `422` Not a verification request.; `502` A store could not be read.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
 ### Review collections: curated sets of recordings, newest first
 
 `GET /api/reports/review-collections` · role: read

package/docs/reference/schema.md

@@ -233,6 +233,47 @@ export const ArtifactTagsSchema = …
 
 `GET /api/reports/artifact-tags`: every recorded edit, oldest first. Fold them with `foldArtifactTags`.
 
+#### `StoredRecordingGapSchema`
+
+```ts
+export const StoredRecordingGapSchema = …
+```
+
+One stored video that failed the server's read-back: which check holds it and what is wrong with it.
+
+#### `LayerRecordingCheckSchema`
+
+```ts
+export const LayerRecordingCheckSchema = …
+```
+
+What reading back the stored videos of one layer found.
+
+#### `RecordingVerificationSchema`
+
+```ts
+export const RecordingVerificationSchema = …
+```
+
+`GET` and `POST /api/reports/recordings/verification`: the newest read-back the server did of stored videos, per layer.
+A layer that was never read back is absent, which means "not verified", never "fine".
+
+#### `RecordingVerification`
+
+```ts
+export type RecordingVerification = z.infer<typeof RecordingVerificationSchema>;
+```
+
+The document of {@link RecordingVerificationSchema}, as a type.
+
+#### `RecordingVerifyRequestSchema`
+
+```ts
+export const RecordingVerifyRequestSchema = …
+```
+
+The body of `POST /api/reports/recordings/verification`. Both fields are optional; an empty body reads back the newest layers.
+
 #### `ReviewSourceSchema`
 
 ```ts

package/docs/reference/server.md

@@ -627,6 +627,45 @@ export function projectServer(options: AtlasServerOptions, create: (options: Atl
 
 Wrap the single-project protocol in project selection. Auth, upload validation and composition stay identical.
 
+### Recording verification routes
+
+Source: `packages/server/src/recording-verification.ts`
+
+`/api/reports/recordings/verification`: whether the videos a run published can still be read back from storage as
+they were published, apart from whether the run's tests passed. A viewer reads the newest result with a read token
+(`GET`, which never touches a blob). A publish token starts a read-back (`POST`), which does read blobs and so is
+bounded: the newest 20 layers unless asked for more, at most 200, one pass at a time. The result is kept in this
+process only (it is derived, not state: a restart means "not verified yet", never "fine"), and only for layers the
+store still holds. It adds nothing to any layer and changes no status, slot or winner. This is the same check as
+`atlas report verify-recordings`, and as that command it checks stored bytes, not browser playback.
+
+See docs/rich-evidence.md#recording-completeness
+
+#### `RecordingVerificationDeps`
+
+```ts
+export type RecordingVerificationDeps = {
+  /** Every backend's store: a layer is read back from the store that holds it. */
+  readonly stores: readonly ObjectStore[];
+  readonly auth: Auth;
+  readonly index: ReportIndex;
+  readonly now: () => number;
+  readonly unauthorized: (verdict: Extract<ReturnType<Auth['check']>, { ok: false }>) => Response;
+};
+```
+
+What the verification routes need from the server around them.
+
+#### `mountRecordingVerification`
+
+```ts
+export function mountRecordingVerification(app: Hono, deps: RecordingVerificationDeps): void
+```
+
+Registers `GET` and `POST /api/reports/recordings/verification` on `app`. The result of the last read-back of each
+layer is held in memory, replaced by a newer one, and served only for layers a store still holds. A layer held by
+two backends keeps the reading with more gaps, so a copy that lost its blobs is never hidden by one that did not.
+
 ### Review collection routes
 
 Source: `packages/server/src/review-collections.ts`

package/docs/rich-evidence.md

@@ -504,6 +504,18 @@ two ways without touching a check's result:
   `--format json` prints the `verify-recordings-result` document. `--layer <id>` and `--limit <n>` narrow the work, since
   it reads blobs. A store that cannot answer is `unreadable`, never verified. Test results are unchanged either way.
 
+- **In the viewer.** A publish token starts the same read-back on the server with
+  `POST /api/reports/recordings/verification` (body optional: `{ "layers": ["<id prefix>"], "limit": 20 }`; the newest
+  20 layers by default, at most 200, one read-back at a time; a reader token, a browser sign-in box or an anonymous
+  caller is refused because it reads blobs). Anyone who can read the report then sees the result with
+  `GET /api/reports/recordings/verification` (which reads no blob): per layer, its run, how many videos were read back, how
+  many passed and each gap. The Runs tab and an opened run show `Recording unavailable: 1 of 3 stored videos failed the
+  read-back (1 file gone from storage)` beside the green outcomes, or `3 stored videos verified`, and a run whose stored
+  videos all failed offers no Watch action. A run whose layers were never read back shows nothing: unknown is not
+  verified. The result lives in the server's memory only, so a restart empties it, and a layer that garbage collection
+  removed drops out. An older server has no such route and the viewer then shows nothing. No status, slot or winner is
+  affected; `capabilities.recordingVerification` in `GET /api/server` says a server offers it.
+
 Both are statements about stored bytes. Atlas does not check that a stored video plays in a given browser (a valid header
 can still have an unsupported codec or be truncated), and acknowledging an upload is not playback. Videos given only by
 `uri` are counted as referenced and not checked.

package/docs/server.md

@@ -338,6 +338,14 @@ edit, and the server's time. Nothing about the layer, its results or the report'
 See [Tagging artifacts and demos](rich-evidence.md#tagging-artifacts-and-demos) for the tag rules. Reviewer tags are
 shown in the viewer's evidence; the tests API (`artifactTag`) searches the producers' tags.
 
+## Reading recordings back
+
+`POST /api/reports/recordings/verification` (publish, `Authorization: Bearer`) reads the stored videos of the newest layers
+back and checks them; `GET` (read) returns the newest result per layer without reading any blob, so the viewer can mark a
+run whose recording was stored and then lost, apart from its test results. The result is in memory only and layers
+that were never read back are absent (unknown, never "fine"). See
+[Is the recording still there?](rich-evidence.md#is-the-recording-still-there) for what is checked and what is not.
+
 ## Review collections
 
 A team can publish a named, curated review of a few behaviors: recordings from several explicit executions, notes on
@@ -517,6 +525,10 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `GET /api/projects/{project}/reports/artifact-tags` | read | Reviewer tags of attachments: every recorded edit. |
 | `POST /api/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
 | `POST /api/projects/{project}/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
+| `GET /api/reports/recordings/verification` | read | Which stored recordings the server last read back, and which were gone or damaged. |
+| `GET /api/projects/{project}/reports/recordings/verification` | read | Which stored recordings the server last read back, and which were gone or damaged. |
+| `POST /api/reports/recordings/verification` | publish | Read stored recordings back and check them (publish token). |
+| `POST /api/projects/{project}/reports/recordings/verification` | publish | Read stored recordings back and check them (publish token). |
 | `GET /api/reports/review-collections` | read | Review collections: curated sets of recordings, newest first. |
 | `GET /api/projects/{project}/reports/review-collections` | read | Review collections: curated sets of recordings, newest first. |
 | `POST /api/reports/review-collections` | publish | Publish an immutable review collection (or a new revision of one). |