@crvouga/atlas 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog: @crvouga/atlas
 
-## 1.18.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
+
+- add a project-wide behavior index, a read-and-watch workspace and a scoped summary ([bb2d270](https://github.com/crvouga/atlas/commit/bb2d270fcfc2374c316db804e80af67885bdd8ee))
+- restore the watch playlist from the address and show clip posters and lengths ([2dfc480](https://github.com/crvouga/atlas/commit/2dfc4806a72621f67f304cd9fda7619a9dbbea3f))
+
+## 1.18.0 (2026-10-28)
 
 ### Features
 

package/dist/reports/src/evidence-detail.js

@@ -62,7 +62,7 @@ function summarize(holders, owner, inherited, firstIsParent = false, unstored) {
             for (const tag of normalizeTags(item.tags))
                 artifactTags.add(tag);
             roles.add(item.role ?? roleOfType(item.contentType ?? contentTypeOf(item.name)));
-            const video = videoOf(item, by, where, effectiveScope(item.scope, ...scopes), unstored);
+            const video = videoOf(item, by, where, effectiveScope(item.scope, ...scopes), unstored, list);
             if (video)
                 videos.push(video);
         }
@@ -110,14 +110,24 @@ export function isVideoAttachment(attachment) {
 export function attachmentIdentity(item) {
     return item.sha256 ? `sha256:${item.sha256}` : item.bundleKey ?? item.uri ?? (item.text === undefined ? undefined : `inline:${item.name}`);
 }
-function videoOf(item, owner, where, scope, unstored) {
+/** The bundle key of the image an attachment names as its poster among its siblings, when the layer's bundle holds it. */
+function posterKey(item, siblings, unstored) {
+    if (item.poster === undefined)
+        return undefined;
+    const poster = siblings?.find(other => other !== item && other.id === item.poster);
+    if (!poster?.bundleKey || unstored?.has(poster.bundleKey))
+        return undefined;
+    return (poster.contentType ?? contentTypeOf(poster.name)).toLowerCase().startsWith('image/') ? poster.bundleKey : undefined;
+}
+function videoOf(item, owner, where, scope, unstored, siblings) {
     if (!isVideoAttachment(item))
         return undefined;
     // A bundle key the layer's bundle does not hold names bytes that are not there: only an address or inline text can still carry them, and the digest of lost bytes identifies nothing playable.
     const lost = item.bundleKey !== undefined && unstored?.has(item.bundleKey) === true;
     const recording = lost ? attachmentIdentity({ name: item.name, uri: item.uri, text: item.text }) : attachmentIdentity(item);
     const tags = normalizeTags(item.tags);
-    return { name: item.name, owner, ...where, ...(tags.length ? { tags } : {}), ...(recording === undefined ? {} : { recording }), available: recording !== undefined, ...(lost && recording === undefined ? { reason: 'not-in-bundle' } : {}), ...(scope ? { scope } : {}) };
+    const poster = posterKey(item, siblings, unstored);
+    return { name: item.name, owner, ...where, ...(tags.length ? { tags } : {}), ...(recording === undefined ? {} : { recording }), available: recording !== undefined, ...(lost && recording === undefined ? { reason: 'not-in-bundle' } : {}), ...(item.durationMs !== undefined && Number.isFinite(item.durationMs) ? { durationMs: item.durationMs } : {}), ...(poster === undefined ? {} : { poster }), ...(scope ? { scope } : {}) };
 }
 /**
  * Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so

package/dist/reports/src/evidence-types.d.ts

@@ -60,6 +60,10 @@ export type VideoRef = {
     readonly available: boolean;
     /** Why it is unavailable, when the report can tell: `not-in-bundle` names a file the layer should hold (its bundle key) but does not, a recording that was acknowledged and is no longer there. Absent otherwise, and for an available video. An open vocabulary: treat an unknown reason as plain unavailable. */
     readonly reason?: 'not-in-bundle';
+    /** How long the recording is, in milliseconds, as its producer declared (`Attachment.durationMs`): a hint to show before the file is opened, never measured here and never a latency. Absent when none was declared, and in documents of older servers. */
+    readonly durationMs?: number;
+    /** The bundle key, in the same layer, of the image the producer named as this recording's poster (`Attachment.poster`): a hint to show before the file is opened. Only an image the layer's bundle holds; absent when there is none, and in documents of older servers. */
+    readonly poster?: string;
     /** What this recording shows, as declared for it: its own `scope`, else its attempt's, check's, part's or layer's. Absent when none declared one: its scope is unknown, not live, physical or audible. */
     readonly scope?: EvidenceScope;
 };

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

@@ -91,6 +91,8 @@ export declare const VideoRefSchema: z.ZodObject<{
     recording: z.ZodOptional<z.ZodString>;
     available: z.ZodBoolean;
     reason: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    poster: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodObject<{
         surface: z.ZodOptional<z.ZodString>;
         deviceKind: z.ZodOptional<z.ZodString>;
@@ -144,6 +146,8 @@ export declare const EvidenceSummarySchema: z.ZodObject<{
         recording: z.ZodOptional<z.ZodString>;
         available: z.ZodBoolean;
         reason: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        poster: z.ZodOptional<z.ZodString>;
         scope: z.ZodOptional<z.ZodObject<{
             surface: z.ZodOptional<z.ZodString>;
             deviceKind: z.ZodOptional<z.ZodString>;
@@ -221,6 +225,8 @@ export declare const LayerHeaderSchema: z.ZodObject<{
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
             reason: z.ZodOptional<z.ZodString>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+            poster: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -309,6 +315,8 @@ export declare const LayerRowSchema: z.ZodObject<{
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
             reason: z.ZodOptional<z.ZodString>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+            poster: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -415,6 +423,8 @@ export declare const LayerRowsSchema: z.ZodObject<{
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
                 reason: z.ZodOptional<z.ZodString>;
+                durationMs: z.ZodOptional<z.ZodNumber>;
+                poster: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -523,6 +533,8 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
                 reason: z.ZodOptional<z.ZodString>;
+                durationMs: z.ZodOptional<z.ZodNumber>;
+                poster: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -625,6 +637,8 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
                 reason: z.ZodOptional<z.ZodString>;
+                durationMs: z.ZodOptional<z.ZodNumber>;
+                poster: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -722,6 +736,8 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                     reason: z.ZodOptional<z.ZodString>;
+                    durationMs: z.ZodOptional<z.ZodNumber>;
+                    poster: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -824,6 +840,8 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                     reason: z.ZodOptional<z.ZodString>;
+                    durationMs: z.ZodOptional<z.ZodNumber>;
+                    poster: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -942,6 +960,8 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                     reason: z.ZodOptional<z.ZodString>;
+                    durationMs: z.ZodOptional<z.ZodNumber>;
+                    poster: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -1044,6 +1064,8 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                     reason: z.ZodOptional<z.ZodString>;
+                    durationMs: z.ZodOptional<z.ZodNumber>;
+                    poster: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -1154,6 +1176,8 @@ export declare const EvidencePageSchema: z.ZodObject<{
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
                 reason: z.ZodOptional<z.ZodString>;
+                durationMs: z.ZodOptional<z.ZodNumber>;
+                poster: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -1655,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;
@@ -1735,6 +1814,8 @@ export declare const ReviewSnapshotSchema: z.ZodObject<{
         recording: z.ZodOptional<z.ZodString>;
         available: z.ZodBoolean;
         reason: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        poster: z.ZodOptional<z.ZodString>;
         scope: z.ZodOptional<z.ZodObject<{
             surface: z.ZodOptional<z.ZodString>;
             deviceKind: z.ZodOptional<z.ZodString>;
@@ -1799,6 +1880,8 @@ export declare const ReviewEntrySchema: z.ZodObject<{
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
             reason: z.ZodOptional<z.ZodString>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+            poster: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -1882,6 +1965,8 @@ export declare const ReviewCollectionSchema: z.ZodObject<{
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
                 reason: z.ZodOptional<z.ZodString>;
+                durationMs: z.ZodOptional<z.ZodNumber>;
+                poster: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -2042,6 +2127,8 @@ export declare const ReviewCollectionDetailSchema: z.ZodObject<{
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                     reason: z.ZodOptional<z.ZodString>;
+                    durationMs: z.ZodOptional<z.ZodNumber>;
+                    poster: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -2174,6 +2261,8 @@ export declare const ReviewManifestSchema: z.ZodObject<{
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
                 reason: z.ZodOptional<z.ZodString>;
+                durationMs: z.ZodOptional<z.ZodNumber>;
+                poster: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -2303,6 +2392,8 @@ export declare const TestResultEntrySchema: z.ZodObject<{
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
             reason: z.ZodOptional<z.ZodString>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+            poster: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -2414,6 +2505,8 @@ export declare const TestSummarySchema: z.ZodObject<{
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
                 reason: z.ZodOptional<z.ZodString>;
+                durationMs: z.ZodOptional<z.ZodNumber>;
+                poster: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -2721,6 +2814,8 @@ export declare const TestCatalogSchema: z.ZodObject<{
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                     reason: z.ZodOptional<z.ZodString>;
+                    durationMs: z.ZodOptional<z.ZodNumber>;
+                    poster: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -2960,6 +3055,8 @@ export declare const TestHistorySchema: z.ZodObject<{
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                     reason: z.ZodOptional<z.ZodString>;
+                    durationMs: z.ZodOptional<z.ZodNumber>;
+                    poster: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -3089,6 +3186,8 @@ export declare const TestHistorySchema: z.ZodObject<{
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
                 reason: z.ZodOptional<z.ZodString>;
+                durationMs: z.ZodOptional<z.ZodNumber>;
+                poster: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -3497,6 +3596,8 @@ export declare const ArtifactResultSchema: z.ZodObject<{
         recording: z.ZodOptional<z.ZodString>;
         available: z.ZodBoolean;
         reason: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        poster: z.ZodOptional<z.ZodString>;
         scope: z.ZodOptional<z.ZodObject<{
             surface: z.ZodOptional<z.ZodString>;
             deviceKind: z.ZodOptional<z.ZodString>;
@@ -3568,6 +3669,8 @@ export declare const ArtifactListSchema: z.ZodObject<{
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
             reason: z.ZodOptional<z.ZodString>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+            poster: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -3722,6 +3825,8 @@ export declare const RunDetailSchema: z.ZodObject<{
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
             reason: z.ZodOptional<z.ZodString>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+            poster: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;

package/dist/schema/src/api.js

@@ -72,6 +72,8 @@ export const VideoRefSchema = z.looseObject({
     recording: z.string().optional().describe('What identifies the bytes; references with the same value are one recording. Absent when it cannot be played'),
     available: z.boolean().describe('False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer\'s own bundle does not hold'),
     reason: z.string().optional().describe('Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable'),
+    durationMs: z.number().nonnegative().optional().describe('How long the recording is, in milliseconds, as its producer declared it: a hint to show before the file is opened, never a latency. Absent when none was declared, and in documents of older servers'),
+    poster: z.string().optional().describe('The bundle key, in the same layer, of the image the producer named as this recording\'s poster: a hint to show before the file is opened. Absent when there is none or the layer\'s bundle does not hold it, and in documents of older servers'),
     scope: EvidenceScopeSchema.optional().describe('What this recording shows as its producer declared it: its own `scope`, else its attempt\'s, check\'s, part\'s or layer\'s. Absent: the scope is unknown, never live, physical or audible')
 });
 /** Video references as counts: how many are referenced, how many distinct recordings can be played, how many cannot. */
@@ -252,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;
+        }
+    });
+}