@crvouga/atlas 0.15.0 → 0.16.0

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

@@ -80,6 +80,21 @@ export declare const BackendInfoSchema: z.ZodObject<{
     live: z.ZodBoolean;
     available: z.ZodBoolean;
 }, z.core.$loose>;
+/** One reference to a video held by a layer, check, retry attempt or step, found by the attachment's effective media type. */
+export declare const VideoRefSchema: z.ZodObject<{
+    name: z.ZodString;
+    owner: z.ZodString;
+    attempt: z.ZodOptional<z.ZodNumber>;
+    step: z.ZodOptional<z.ZodString>;
+    recording: z.ZodOptional<z.ZodString>;
+    available: z.ZodBoolean;
+}, z.core.$loose>;
+/** Video references as counts: how many are referenced, how many distinct recordings can be played, how many cannot. */
+export declare const VideoCountsSchema: z.ZodObject<{
+    references: z.ZodNumber;
+    recordings: z.ZodNumber;
+    unavailable: z.ZodNumber;
+}, z.core.$loose>;
 /** What a result carries beyond its outcome, as counts and short facts. Present only when there is something. */
 export declare const EvidenceSummarySchema: z.ZodObject<{
     attachments: z.ZodNumber;
@@ -91,6 +106,14 @@ export declare const EvidenceSummarySchema: z.ZodObject<{
     artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     labels: z.ZodRecord<z.ZodString, z.ZodString>;
     roles: z.ZodArray<z.ZodString>;
+    videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        owner: z.ZodString;
+        attempt: z.ZodOptional<z.ZodNumber>;
+        step: z.ZodOptional<z.ZodString>;
+        recording: z.ZodOptional<z.ZodString>;
+        available: z.ZodBoolean;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 /** A layer as the report shows it: its origin and its checks by status. */
 export declare const LayerHeaderSchema: z.ZodObject<{
@@ -133,6 +156,14 @@ export declare const LayerHeaderSchema: z.ZodObject<{
         artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         labels: z.ZodRecord<z.ZodString, z.ZodString>;
         roles: z.ZodArray<z.ZodString>;
+        videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            owner: z.ZodString;
+            attempt: z.ZodOptional<z.ZodNumber>;
+            step: z.ZodOptional<z.ZodString>;
+            recording: z.ZodOptional<z.ZodString>;
+            available: z.ZodBoolean;
+        }, z.core.$loose>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
 /** One check of a layer as the report shows it. */
@@ -167,6 +198,14 @@ export declare const LayerRowSchema: z.ZodObject<{
         artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         labels: z.ZodRecord<z.ZodString, z.ZodString>;
         roles: z.ZodArray<z.ZodString>;
+        videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            owner: z.ZodString;
+            attempt: z.ZodOptional<z.ZodNumber>;
+            step: z.ZodOptional<z.ZodString>;
+            recording: z.ZodOptional<z.ZodString>;
+            available: z.ZodBoolean;
+        }, z.core.$loose>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
 /** A layer with its checks: the rows of one layer, read apart from its header. */
@@ -203,6 +242,14 @@ export declare const LayerRowsSchema: z.ZodObject<{
             artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
+            videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                owner: z.ZodString;
+                attempt: z.ZodOptional<z.ZodNumber>;
+                step: z.ZodOptional<z.ZodString>;
+                recording: z.ZodOptional<z.ZodString>;
+                available: z.ZodBoolean;
+            }, z.core.$loose>>>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
     fingerprints: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -241,6 +288,14 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
             artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
+            videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                owner: z.ZodString;
+                attempt: z.ZodOptional<z.ZodNumber>;
+                step: z.ZodOptional<z.ZodString>;
+                recording: z.ZodOptional<z.ZodString>;
+                available: z.ZodBoolean;
+            }, z.core.$loose>>>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
     fingerprints: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -284,6 +339,14 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
             artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
+            videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                owner: z.ZodString;
+                attempt: z.ZodOptional<z.ZodNumber>;
+                step: z.ZodOptional<z.ZodString>;
+                recording: z.ZodOptional<z.ZodString>;
+                available: z.ZodBoolean;
+            }, z.core.$loose>>>;
         }, z.core.$loose>>;
     }, z.core.$loose>;
 }, z.core.$loose>;
@@ -327,6 +390,14 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                 artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
+                videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    owner: z.ZodString;
+                    attempt: z.ZodOptional<z.ZodNumber>;
+                    step: z.ZodOptional<z.ZodString>;
+                    recording: z.ZodOptional<z.ZodString>;
+                    available: z.ZodBoolean;
+                }, z.core.$loose>>>;
             }, z.core.$loose>>;
         }, z.core.$loose>>;
         fingerprints: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -370,6 +441,14 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                 artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
+                videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    owner: z.ZodString;
+                    attempt: z.ZodOptional<z.ZodNumber>;
+                    step: z.ZodOptional<z.ZodString>;
+                    recording: z.ZodOptional<z.ZodString>;
+                    available: z.ZodBoolean;
+                }, z.core.$loose>>>;
             }, z.core.$loose>>;
         }, z.core.$loose>;
     }, z.core.$loose>>;
@@ -434,6 +513,14 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                 artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
+                videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    owner: z.ZodString;
+                    attempt: z.ZodOptional<z.ZodNumber>;
+                    step: z.ZodOptional<z.ZodString>;
+                    recording: z.ZodOptional<z.ZodString>;
+                    available: z.ZodBoolean;
+                }, z.core.$loose>>>;
             }, z.core.$loose>>;
         }, z.core.$loose>>;
         fingerprints: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -477,6 +564,14 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                 artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
+                videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    owner: z.ZodString;
+                    attempt: z.ZodOptional<z.ZodNumber>;
+                    step: z.ZodOptional<z.ZodString>;
+                    recording: z.ZodOptional<z.ZodString>;
+                    available: z.ZodBoolean;
+                }, z.core.$loose>>>;
             }, z.core.$loose>>;
         }, z.core.$loose>;
     }, z.core.$loose>>;
@@ -544,6 +639,14 @@ export declare const EvidencePageSchema: z.ZodObject<{
             artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
+            videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                owner: z.ZodString;
+                attempt: z.ZodOptional<z.ZodNumber>;
+                step: z.ZodOptional<z.ZodString>;
+                recording: z.ZodOptional<z.ZodString>;
+                available: z.ZodBoolean;
+            }, z.core.$loose>>>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
     cursor: z.ZodNullable<z.ZodString>;
@@ -923,6 +1026,14 @@ export declare const TestResultEntrySchema: z.ZodObject<{
         artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         labels: z.ZodRecord<z.ZodString, z.ZodString>;
         roles: z.ZodArray<z.ZodString>;
+        videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            owner: z.ZodString;
+            attempt: z.ZodOptional<z.ZodNumber>;
+            step: z.ZodOptional<z.ZodString>;
+            recording: z.ZodOptional<z.ZodString>;
+            available: z.ZodBoolean;
+        }, z.core.$loose>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
 /** One test of the catalog: what it is, its current result per environment, and how it has gone over its recorded history. */
@@ -975,6 +1086,14 @@ export declare const TestSummarySchema: z.ZodObject<{
             artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
+            videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                owner: z.ZodString;
+                attempt: z.ZodOptional<z.ZodNumber>;
+                step: z.ZodOptional<z.ZodString>;
+                recording: z.ZodOptional<z.ZodString>;
+                available: z.ZodBoolean;
+            }, z.core.$loose>>>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
     stats: z.ZodObject<{
@@ -1217,6 +1336,14 @@ export declare const TestCatalogSchema: z.ZodObject<{
                 artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
+                videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    owner: z.ZodString;
+                    attempt: z.ZodOptional<z.ZodNumber>;
+                    step: z.ZodOptional<z.ZodString>;
+                    recording: z.ZodOptional<z.ZodString>;
+                    available: z.ZodBoolean;
+                }, z.core.$loose>>>;
             }, z.core.$loose>>;
         }, z.core.$loose>>;
         stats: z.ZodObject<{
@@ -1390,6 +1517,14 @@ export declare const TestHistorySchema: z.ZodObject<{
                 artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
+                videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    owner: z.ZodString;
+                    attempt: z.ZodOptional<z.ZodNumber>;
+                    step: z.ZodOptional<z.ZodString>;
+                    recording: z.ZodOptional<z.ZodString>;
+                    available: z.ZodBoolean;
+                }, z.core.$loose>>>;
             }, z.core.$loose>>;
         }, z.core.$loose>>;
         stats: z.ZodObject<{
@@ -1460,6 +1595,14 @@ export declare const TestHistorySchema: z.ZodObject<{
             artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
+            videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                owner: z.ZodString;
+                attempt: z.ZodOptional<z.ZodNumber>;
+                step: z.ZodOptional<z.ZodString>;
+                recording: z.ZodOptional<z.ZodString>;
+                available: z.ZodBoolean;
+            }, z.core.$loose>>>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
@@ -1495,6 +1638,11 @@ export declare const ReportRunSchema: z.ZodObject<{
         environment: z.ZodNullable<z.ZodString>;
         detail: z.ZodString;
     }, z.core.$loose>>;
+    videos: z.ZodOptional<z.ZodObject<{
+        references: z.ZodNumber;
+        recordings: z.ZodNumber;
+        unavailable: z.ZodNumber;
+    }, z.core.$loose>>;
 }, z.core.$loose>;
 /** `GET /api/reports/runs`: runs, newest first. */
 export declare const RunListSchema: z.ZodObject<{
@@ -1532,7 +1680,13 @@ export declare const RunListSchema: z.ZodObject<{
             environment: z.ZodNullable<z.ZodString>;
             detail: z.ZodString;
         }, z.core.$loose>>;
+        videos: z.ZodOptional<z.ZodObject<{
+            references: z.ZodNumber;
+            recordings: z.ZodNumber;
+            unavailable: z.ZodNumber;
+        }, z.core.$loose>>;
     }, z.core.$loose>>;
+    withVideo: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 /** `GET /api/reports/runs/detail`: one run and its last result for every test, environment and producer it recorded. */
 export declare const RunDetailSchema: z.ZodObject<{
@@ -1569,6 +1723,11 @@ export declare const RunDetailSchema: z.ZodObject<{
             environment: z.ZodNullable<z.ZodString>;
             detail: z.ZodString;
         }, z.core.$loose>>;
+        videos: z.ZodOptional<z.ZodObject<{
+            references: z.ZodNumber;
+            recordings: z.ZodNumber;
+            unavailable: z.ZodNumber;
+        }, z.core.$loose>>;
     }, z.core.$loose>;
     results: z.ZodArray<z.ZodObject<{
         key: z.ZodString;
@@ -1587,5 +1746,13 @@ export declare const RunDetailSchema: z.ZodObject<{
         at: z.ZodNumber;
         layer: z.ZodString;
         detail: z.ZodString;
+        videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            owner: z.ZodString;
+            attempt: z.ZodOptional<z.ZodNumber>;
+            step: z.ZodOptional<z.ZodString>;
+            recording: z.ZodOptional<z.ZodString>;
+            available: z.ZodBoolean;
+        }, z.core.$loose>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;

package/dist/schema/src/api.js

@@ -62,6 +62,21 @@ export const BackendInfoSchema = z.looseObject({
     live: z.boolean().describe('Always false on a server'),
     available: z.boolean().describe('False when the backend could not be read; its results are then unknown, never passed')
 });
+/** One reference to a video held by a layer, check, retry attempt or step, found by the attachment's effective media type. */
+export const VideoRefSchema = z.looseObject({
+    name: z.string().describe('The attachment name'),
+    owner: z.string().describe('Who holds it: `layer`, `check`, `attempt` or `step`. An open vocabulary: treat an unknown owner as a check'),
+    attempt: z.number().int().nonnegative().optional().describe('The retry attempt that holds it, or that holds the step that does'),
+    step: z.string().optional().describe('The name of the step that holds it'),
+    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)')
+});
+/** Video references as counts: how many are referenced, how many distinct recordings can be played, how many cannot. */
+export const VideoCountsSchema = z.looseObject({
+    references: z.number().int().nonnegative().describe('Every reference to a video; identical bytes referenced twice count twice'),
+    recordings: z.number().int().nonnegative().describe('Distinct playable recordings'),
+    unavailable: z.number().int().nonnegative().describe('References that name no bytes')
+});
 /** What a result carries beyond its outcome, as counts and short facts. Present only when there is something. */
 export const EvidenceSummarySchema = z.looseObject({
     attachments: z.number().int().nonnegative(),
@@ -72,7 +87,8 @@ export const EvidenceSummarySchema = z.looseObject({
     tags: z.array(z.string()),
     artifactTags: z.array(z.string()).optional().describe('Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run'),
     labels: z.record(z.string(), z.string()),
-    roles: z.array(z.string())
+    roles: z.array(z.string()),
+    videos: z.array(VideoRefSchema).optional().describe('Its references to videos and who holds each. Absent when it has none, and in reports written before this was recorded')
 });
 /** A layer as the report shows it: its origin and its checks by status. */
 export const LayerHeaderSchema = z.looseObject({
@@ -374,10 +390,17 @@ export const ReportRunSchema = z.looseObject({
     producers: z.array(z.string()), environments: z.array(z.string()),
     layers: z.number().int().nonnegative(), tests: z.number().int().nonnegative(), counts: StatusCountsSchema,
     totalDurationMs: z.number().nullable(),
-    failing: z.array(z.looseObject({ key: z.string(), title: z.string(), environment: z.string().nullable(), detail: z.string() }))
+    failing: z.array(z.looseObject({ key: z.string(), title: z.string(), environment: z.string().nullable(), detail: z.string() })),
+    videos: VideoCountsSchema.optional().describe('Its videos, from its layers and the last result of each test. Absent when it has none or the report carries no video information')
 });
 /** `GET /api/reports/runs`: runs, newest first. */
-export const RunListSchema = z.looseObject({ schemaVersion: z.literal(1), version: z.string(), total: z.number().int().nonnegative(), runs: z.array(ReportRunSchema) });
+export const RunListSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    version: z.string(),
+    total: z.number().int().nonnegative().describe('Runs that matched, before `limit`'),
+    runs: z.array(ReportRunSchema),
+    withVideo: z.number().int().nonnegative().optional().describe('How many of all runs (before `video` and `limit`) have a playable video recording')
+});
 /** `GET /api/reports/runs/detail`: one run and its last result for every test, environment and producer it recorded. */
 export const RunDetailSchema = z.looseObject({
     schemaVersion: z.literal(1),
@@ -385,6 +408,7 @@ export const RunDetailSchema = z.looseObject({
     run: ReportRunSchema,
     results: z.array(z.looseObject({
         key: z.string(), id: z.string(), title: z.string(), specPath: z.string().nullable(), environment: z.string().nullable(), producer: z.string(),
-        status: EvidenceStatusSchema, durationMs: z.number().nullable(), at: z.number(), layer: z.string(), detail: z.string()
+        status: EvidenceStatusSchema, durationMs: z.number().nullable(), at: z.number(), layer: z.string(), detail: z.string(),
+        videos: z.array(VideoRefSchema).optional().describe('Every video its evidence references, with who holds it')
     }))
 });

package/dist/server/src/app.js

@@ -426,8 +426,9 @@ function createProjectApplication(options) {
             return notReady(c);
         const found = await catalog();
         const limit = /^\d+$/.test(c.req.query('limit') ?? '') ? Number(c.req.query('limit')) : 100;
-        const document = () => runList(index.history, found.version, limit);
-        return answer(c, found.version, document, () => runsMarkdown(document()), `runs|${limit}|${wantsMarkdown(c)}`);
+        const video = ['1', 'true'].includes(c.req.query('video') ?? '');
+        const document = () => runList(index.history, found.version, limit, { video });
+        return answer(c, found.version, document, () => runsMarkdown(document()), `runs|${limit}|${video}|${wantsMarkdown(c)}`);
     });
     app.get('/api/reports/runs/detail', async (c) => {
         if (!index.ready)

package/dist/server/src/llms.js

@@ -69,7 +69,8 @@ curl "${url}/api/projects/$ATLAS_PROJECT/reports/tests?format=markdown&limit=50"
 curl "${url}/api/projects/$ATLAS_PROJECT/reports/tests?status=failed,flaky&environment=desktop-web" # filter: q, status, environment, producer, domain, spec, tag, run; sort, offset, limit
 curl "${url}/api/projects/$ATLAS_PROJECT/reports/tests/history?key=<url-encoded test key>"         # one test: every recorded result, durations, branches, CI runs
 curl "${url}/api/projects/$ATLAS_PROJECT/reports/tests/health?format=markdown"                      # why Specs, domains and counts disagree; add root=<from>><to> to declare a path-root mapping
-curl "${url}/api/projects/$ATLAS_PROJECT/reports/runs?format=markdown"                             # CI runs, newest first, with their results by status
+curl "${url}/api/projects/$ATLAS_PROJECT/reports/runs?format=markdown"                             # CI runs, newest first, with their results by status and video counts
+curl "${url}/api/projects/$ATLAS_PROJECT/reports/runs?video=true&format=markdown"                 # only runs with a playable video recording
 curl "${url}/api/projects/$ATLAS_PROJECT/reports/runs/detail?key=<url-encoded run key>"            # every test one run recorded
 \`\`\`
 

package/dist/server/src/openapi.js

@@ -324,9 +324,10 @@ const BASE_OPERATIONS = [
     {
         route: 'GET /api/reports/runs', path: '/api/reports/runs', operationId: 'getReportRuns', tag: 'Report', role: 'read',
         summary: 'The runs that recorded the report',
-        description: 'Every run, newest first: layers grouped by their CI run URL (else branch and commit), with their environments, producers, how many tests they recorded, their results by status, the time they spanned and up to twenty failures. Send `format=markdown` for Markdown.',
+        description: 'Every run, newest first: layers grouped by their CI run URL (else branch and commit), with their environments, producers, how many tests they recorded, their results by status, the time they spanned, up to twenty failures and their video counts (references, distinct playable recordings, unavailable). Send `format=markdown` for Markdown.',
         parameters: [
             { name: 'limit', in: 'query', description: 'At most this many runs (default 100).', schema: { type: 'integer', minimum: 0 } },
+            { name: 'video', in: 'query', description: '`true` to list only runs that have a playable video recording. Applied to every run before `limit`; `total` counts the matches. A server that does not know it answers with every run.', schema: { type: 'boolean' } },
             { name: 'format', in: 'query', description: '`markdown` for Markdown instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
         ],
         responses: { '200': json('The runs.', 'RunList'), '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }

package/docs/reference/http-api.md

@@ -616,9 +616,10 @@ Responses: `201` The recorded entry.; `401` No token, or an unknown one. Send `A
 
 `GET /api/reports/runs` · role: read
 
-Every run, newest first: layers grouped by their CI run URL (else branch and commit), with their environments, producers, how many tests they recorded, their results by status, the time they spanned and up to twenty failures. Send `format=markdown` for Markdown.
+Every run, newest first: layers grouped by their CI run URL (else branch and commit), with their environments, producers, how many tests they recorded, their results by status, the time they spanned, up to twenty failures and their video counts (references, distinct playable recordings, unavailable). Send `format=markdown` for Markdown.
 
 - `limit` (query): At most this many runs (default 100).
+- `video` (query): `true` to list only runs that have a playable video recording. Applied to every run before `limit`; `total` counts the matches. A server that does not know it answers with every run.
 - `format` (query): `markdown` for Markdown instead of JSON.
 - `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
 
@@ -628,12 +629,13 @@ Responses: `200` The runs.; `304` Unchanged since the `If-None-Match` ETag.; `40
 
 `GET /api/projects/{project}/reports/runs` · role: read
 
-Every run, newest first: layers grouped by their CI run URL (else branch and commit), with their environments, producers, how many tests they recorded, their results by status, the time they spanned and up to twenty failures. Send `format=markdown` for Markdown.
+Every run, newest first: layers grouped by their CI run URL (else branch and commit), with their environments, producers, how many tests they recorded, their results by status, the time they spanned, up to twenty failures and their video counts (references, distinct playable recordings, unavailable). Send `format=markdown` for Markdown.
 
 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.
 - `limit` (query): At most this many runs (default 100).
+- `video` (query): `true` to list only runs that have a playable video recording. Applied to every run before `limit`; `total` counts the matches. A server that does not know it answers with every run.
 - `format` (query): `markdown` for Markdown instead of JSON.
 
 Responses: `200` The runs.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.

package/docs/reference/reports.md

@@ -1426,7 +1426,36 @@ read when someone asks for it. Undefined when there is none.
 Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
 attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
 label the later holder wins. `artifactTags` are the attachments' own normalized tags and are never inherited. `roles` are the attachments' roles (or, without one, what their media type or file
-name implies), sorted and distinct.
+name implies), sorted and distinct. `videos` lists every attachment whose effective media type is video, with the
+check, retry attempt or step that holds it (see {@link isVideoAttachment}).
+
+#### `summarizeLayerEvidence`
+
+```ts
+export function summarizeLayerEvidence(...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined
+```
+
+Like {@link summarizeEvidence} for a layer and its parts: the same summary, but a video attached to the layer or a
+part is owned by the `layer`, not by a check.
+
+#### `isVideoAttachment`
+
+```ts
+export function isVideoAttachment(attachment: Pick<Attachment, 'name' | 'role' | 'contentType'>): boolean
+```
+
+Whether an attachment is a video, by its effective media type: the producer's `contentType`, else the one its file
+name implies. A role never decides this on its own (`demo` on a PNG is not a video), except that a `video` role
+settles a file whose type nothing says (`application/octet-stream`).
+
+#### `videoCounts`
+
+```ts
+export function videoCounts(videos: readonly VideoRef[] | undefined): VideoCounts | undefined
+```
+
+Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so
+"no video" and "nothing known about video" look the same on the wire.
 
 #### `roleOfType`
 
@@ -1609,6 +1638,51 @@ export type StatusCounts = Readonly<Record<EvidenceStatus, number>>;
 
 How many results have each status (`passed`, `failed`, `running`, `not-run`).
 
+#### `VideoOwner`
+
+```ts
+export type VideoOwner = 'layer' | 'check' | 'attempt' | 'step';
+```
+
+Who holds a recording: the whole layer (or one of its parts), one check, one retry attempt of a check, or one step.
+
+#### `VideoRef`
+
+```ts
+export type VideoRef = {
+  /** The attachment's name, for a person. */
+  readonly name: string;
+  readonly owner: VideoOwner;
+  /** The try that holds it, when `owner` is `attempt` or the step is inside one. */
+  readonly attempt?: number;
+  /** The name of the step that holds it, when `owner` is `step`. */
+  readonly step?: string;
+  /** What identifies the bytes (digest, bundle key or address); references with the same one are the same recording. Absent when `available` is false. */
+  readonly recording?: string;
+  /** False when the reference names no bytes at all (no bundle key, address or inline text), so it can never be played. */
+  readonly available: boolean;
+};
+```
+
+One reference to a video, found by its effective media type (the producer's `contentType`, else the one the file
+name implies; a `video` role alone counts only when nothing else says what the file is). A reference is not a
+recording: the same bytes referenced from three checks are three references and one recording.
+
+#### `VideoCounts`
+
+```ts
+export type VideoCounts = {
+  /** Every reference to a video, playable or not. */
+  readonly references: number;
+  /** Distinct playable recordings: identical bytes referenced twice are one. */
+  readonly recordings: number;
+  /** References that name no bytes. A report that predates availability metadata has none of these and none of the others. */
+  readonly unavailable: number;
+};
+```
+
+Video availability as counts: references, distinct playable recordings (deduplicated), and references that cannot be played.
+
 #### `EvidenceSummary`
 
 ```ts
@@ -1626,6 +1700,8 @@ export type EvidenceSummary = {
   readonly labels: Readonly<Record<string, string>>;
   /** The distinct roles of its attachments (or what their media types say), to show what kind of evidence there is. */
   readonly roles: readonly string[];
+  /** Its references to videos, wherever they are held (layer, check, attempt, step). Only there when it has any. */
+  readonly videos?: readonly VideoRef[];
 };
 ```
 
@@ -7930,20 +8006,39 @@ export type RunSummary = {
   readonly totalDurationMs: number | null;
   /** Up to twenty tests that failed in it. */
   readonly failing: readonly { readonly key: string; readonly title: string; readonly environment: string | null; readonly detail: string }[];
+  /**
+   * Its videos, from the run's layers and from the last result of each test: references, distinct playable recordings
+   * and references that cannot be played. Absent when it has none, and in a report that carries no video information.
+   */
+  readonly videos?: VideoCounts;
 };
 ```
 
 A run: the layers that name the same execution (`run.id`), else share a CI run URL, else a branch and commit. When,
 where, and how its tests went.
 
+#### `RunQuery`
+
+```ts
+export type RunQuery = {
+  /** Only runs that have at least one playable video recording. `total` then counts only those. */
+  readonly video?: boolean;
+};
+```
+
+What `runList` can be asked.
+
 #### `RunList`
 
 ```ts
 export type RunList = {
   readonly schemaVersion: typeof TEST_CATALOG_VERSION;
   readonly version: string;
+  /** Runs that matched, before `limit`. */
   readonly total: number;
   readonly runs: readonly RunSummary[];
+  /** How many of all runs (whatever was asked, before `limit`) have a playable video recording. */
+  readonly withVideo?: number;
 };
 ```
 
@@ -7964,6 +8059,8 @@ export type RunResult = {
   readonly at: number;
   readonly layer: string;
   readonly detail: string;
+  /** Every video its evidence references, with who holds it (check, retry attempt or step). Absent when there is none. */
+  readonly videos?: readonly VideoRef[];
 };
 ```
 
@@ -8114,13 +8211,23 @@ export function testHistory(model: CatalogModel, key: string): TestHistoryDocume
 
 One test and its recorded results, or null when the report has no test with that key.
 
+#### `hasVideo`
+
+```ts
+export function hasVideo(run: Pick<RunSummary, 'videos'>): boolean
+```
+
+Whether a run has at least one playable video recording.
+
 #### `runList`
 
 ```ts
-export function runList(history: TestHistory, version: string, limit = 100): RunList
+export function runList(history: TestHistory, version: string, limit = 100, query: RunQuery = {}): RunList
 ```
 
-Every run the history knows of, newest first, `limit` at most (default 100).
+Every run the history knows of, newest first, `limit` at most (default 100). With `query.video` only the runs that
+have a playable video recording: the filter and `total` apply to every run before `limit`, and nothing is read from
+any recording's bytes. `withVideo` always counts every run that has one.
 
 #### `runDetail`
 

package/docs/reference/schema.md

@@ -69,6 +69,22 @@ export const BackendInfoSchema = …
 
 A backend as the report shows it: where results came from, and whether it could be read.
 
+#### `VideoRefSchema`
+
+```ts
+export const VideoRefSchema = …
+```
+
+One reference to a video held by a layer, check, retry attempt or step, found by the attachment's effective media type.
+
+#### `VideoCountsSchema`
+
+```ts
+export const VideoCountsSchema = …
+```
+
+Video references as counts: how many are referenced, how many distinct recordings can be played, how many cannot.
+
 #### `EvidenceSummarySchema`
 
 ```ts

package/docs/server.md

@@ -276,7 +276,7 @@ with `format=markdown` (or `Accept: text/markdown`), and takes the project prefi
 | Only some: `q` (all words), `status` (or `flaky`), `environment`, `producer`, `domain`, `spec`, `tag`, `run`; `sort`, `offset`, `limit` | `GET /api/reports/tests?status=failed&environment=ios` |
 | One test: every recorded result (status, duration, environment, branch, commit, CI run), newest first | `GET /api/reports/tests/history?key=<key>` |
 | Why Specs, domains and counts disagree: ambiguous spec paths, shared domains, gaps, a reconciliation of the totals | `GET /api/reports/tests/health` |
-| The runs that recorded the report (by CI run URL, else branch and commit) | `GET /api/reports/runs` |
+| The runs that recorded the report (by CI run URL, else branch and commit); `?video=true` keeps those with a playable video | `GET /api/reports/runs` |
 | Every test one run recorded | `GET /api/reports/runs/detail?key=<run key>` |
 
 ```sh