@crvouga/atlas 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog: @crvouga/atlas
 
+## 1.5.0 (2026-10-29)
+
+### Features
+
+- connect readable behavior with recordings and coverage gaps (#55) ([0a22022](https://github.com/crvouga/atlas/commit/0a22022dac9f9956aa77214af5de7af4fd2b2d88))
+
+## 1.4.0 (2026-10-28)
+
+### Features
+
+- surface run attachments and link directly to a recording ([879f049](https://github.com/crvouga/atlas/commit/879f049e9f7bdae1ff1d869125640aa063a9f653))
+
 ## 1.3.0 (2026-10-28)
 
 ### Features

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

@@ -57,6 +57,12 @@ export declare function summarizeLayerEvidence(...holders: readonly EvidenceHold
  * settles a file whose type nothing says (`application/octet-stream`).
  */
 export declare function isVideoAttachment(attachment: Pick<Attachment, 'name' | 'role' | 'contentType'>): boolean;
+/**
+ * What identifies an attachment's bytes: its digest, else its bundle key, address or inline text. Attachments with the
+ * same identity are the same file however many results reference them. Undefined when it names no bytes at all (it can
+ * never be opened). This is the `recording` of a {@link VideoRef}.
+ */
+export declare function attachmentIdentity(item: Pick<Attachment, 'name' | 'sha256' | 'bundleKey' | 'uri' | 'text'>): string | 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.
@@ -88,5 +94,22 @@ export declare function checkDetailOf(layer: {
 } & EvidenceHolder, checkId: string, kind?: string): CheckDetail | null;
 /** What a layer carries as a whole (its scope, tags, labels, links, attachments, annotations and extensions; not its parts' checks). Absent fields stay absent. */
 export declare function runEvidence(layer: EvidenceHolder): EvidenceHolder;
+/** What one part of a layer (one kind of report) carries as a whole, named by the part. */
+export type PartEvidence = EvidenceHolder & {
+    readonly kind: string;
+    readonly id: string;
+    readonly title: string;
+};
+/**
+ * The parts of a layer that carry evidence of their own (attachments, links, labels…), each with its name. Parts
+ * that carry none are left out. A part's files belong to the run, not to any one check.
+ */
+export declare function partsEvidence(layer: {
+    readonly parts: readonly (EvidenceHolder & {
+        readonly kind: string;
+        readonly id: string;
+        readonly title: string;
+    })[];
+}): PartEvidence[];
 /** Every distinct bundle key (`bundleKey`) that the attachments of a holder, its steps and its attempts point to, so a layer's files can be copied. Attachments held by `uri` or inline `text` have none. */
 export declare function bundleKeysOf(holder: EvidenceHolder): string[];

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

@@ -85,10 +85,18 @@ export function isVideoAttachment(attachment) {
     const type = (attachment.contentType ?? contentTypeOf(attachment.name)).toLowerCase();
     return type.startsWith('video/') || (attachment.role === 'video' && type.startsWith('application/octet-stream'));
 }
+/**
+ * What identifies an attachment's bytes: its digest, else its bundle key, address or inline text. Attachments with the
+ * same identity are the same file however many results reference them. Undefined when it names no bytes at all (it can
+ * never be opened). This is the `recording` of a {@link VideoRef}.
+ */
+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) {
     if (!isVideoAttachment(item))
         return undefined;
-    const recording = item.sha256 ? `sha256:${item.sha256}` : item.bundleKey ?? item.uri ?? (item.text === undefined ? undefined : `inline:${item.name}`);
+    const recording = attachmentIdentity(item);
     const tags = normalizeTags(item.tags);
     return { name: item.name, owner, ...where, ...(tags.length ? { tags } : {}), ...(recording === undefined ? {} : { recording }), available: recording !== undefined, ...(scope ? { scope } : {}) };
 }
@@ -142,6 +150,16 @@ export function runEvidence(layer) {
     const { tags, labels, links, attachments, annotations, extensions, scope } = layer;
     return { ...(scope ? { scope } : {}), ...(tags ? { tags } : {}), ...(labels ? { labels } : {}), ...(links ? { links } : {}), ...(attachments ? { attachments } : {}), ...(annotations ? { annotations } : {}), ...(extensions ? { extensions } : {}) };
 }
+/**
+ * The parts of a layer that carry evidence of their own (attachments, links, labels…), each with its name. Parts
+ * that carry none are left out. A part's files belong to the run, not to any one check.
+ */
+export function partsEvidence(layer) {
+    return layer.parts.flatMap(part => {
+        const evidence = runEvidence(part);
+        return Object.keys(evidence).length ? [{ kind: part.kind, id: part.id, title: part.title, ...evidence }] : [];
+    });
+}
 /** Every distinct bundle key (`bundleKey`) that the attachments of a holder, its steps and its attempts point to, so a layer's files can be copied. Attachments held by `uri` or inline `text` have none. */
 export function bundleKeysOf(holder) {
     const keys = new Set();

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

@@ -109,7 +109,7 @@ export async function exportEvidence(args) {
                     if (!text)
                         return;
                     const read = JSON.parse(text);
-                    const keys = new Set([...bundleKeysOf('check' in read ? read.check : {}), ...bundleKeysOf(read.run)]);
+                    const keys = new Set([...bundleKeysOf('check' in read ? read.check : {}), ...bundleKeysOf(read.run), ...('parts' in read ? (read.parts ?? []).flatMap(bundleKeysOf) : [])]);
                     await eachLimited([...keys], 4, key => copy(`/layers/${encodeURIComponent(layer.id)}/blobs/${key.split('/').map(encodeURIComponent).join('/')}`).then(() => { }));
                 };
                 const base = `/evidence/detail/${encodeURIComponent(layer.backend)}/${encodeURIComponent(layer.id)}`;

package/dist/reports/src/layers-route.d.ts

@@ -51,7 +51,8 @@ export declare function reportBackends(deps: ReportsAppDeps): Backend[];
  *   runs of this machine. `cursor` is the previous page's; 409 when it no longer matches the listing (refresh).
  *   Any `retry` value re-lists backends that were unavailable now instead of after the wait.
  * - `GET /evidence/rows/:backend/:id` the checks and spec fingerprints of one layer (`LayerRows`).
- * - `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer, or one check's detail.
+ * - `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer (and, as `parts`, what its
+ *   parts carry as a whole), or one check's detail.
  * - `GET /layers/:id/blobs/*` an attachment of an immutable layer by its bundle key, served by `attachmentResponse`.
  * - `GET /layers/:id/*` the recorded `frame.css`, `tests/<test>/report.json` and `tests/<test>/files/<frame>` of a layer.
  * - `GET /live/:source/frame.css` and `GET /live/:source/tests/:testId/*` the same for a run still writing (uncached).

package/dist/reports/src/layers-route.js

@@ -19,7 +19,7 @@ import { createLiveEvidence, liveRunRecord } from './evidence-live.js';
 import { isFramePath, isKeySegment } from './keys.js';
 import { catalogEntries, catalogLayers } from './layer-catalog.js';
 import { attachmentResponse } from './attachment-response.js';
-import { checkDetailOf, runEvidence } from './evidence-detail.js';
+import { checkDetailOf, partsEvidence, runEvidence } from './evidence-detail.js';
 import { layerEvidence } from './layer-merge.js';
 import { layerSummary, readLayer } from './layer-store.js';
 import { readBytes, readUtf8 } from './object-io.js';
@@ -69,7 +69,8 @@ function archived(id) {
  *   runs of this machine. `cursor` is the previous page's; 409 when it no longer matches the listing (refresh).
  *   Any `retry` value re-lists backends that were unavailable now instead of after the wait.
  * - `GET /evidence/rows/:backend/:id` the checks and spec fingerprints of one layer (`LayerRows`).
- * - `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer, or one check's detail.
+ * - `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer (and, as `parts`, what its
+ *   parts carry as a whole), or one check's detail.
  * - `GET /layers/:id/blobs/*` an attachment of an immutable layer by its bundle key, served by `attachmentResponse`.
  * - `GET /layers/:id/*` the recorded `frame.css`, `tests/<test>/report.json` and `tests/<test>/files/<frame>` of a layer.
  * - `GET /live/:source/frame.css` and `GET /live/:source/tests/:testId/*` the same for a run still writing (uncached).
@@ -286,8 +287,11 @@ export function createLayersApp(deps) {
             return c.notFound();
         const checkId = c.req.query('check');
         const headers = { 'cache-control': 'public, max-age=31536000, immutable' };
-        if (checkId === undefined)
-            return c.json({ layer: id, run: runEvidence(layer) }, 200, headers);
+        if (checkId === undefined) {
+            // The parts' own evidence is optional: a client that does not know `parts` still has the run's.
+            const parts = partsEvidence(layer);
+            return c.json({ layer: id, run: runEvidence(layer), ...(parts.length ? { parts } : {}) }, 200, headers);
+        }
         const detail = checkDetailOf(layer, checkId, c.req.query('kind'));
         return detail ? c.json(detail, 200, headers) : c.notFound();
     });

package/dist/reports/src/test-catalog.d.ts

@@ -270,6 +270,11 @@ export type RunSummary = {
      * and references that cannot be played. Absent when it has none, and in a report that carries no video information.
      */
     readonly videos?: VideoCounts;
+    /**
+     * Files attached to the run itself, in its layers (and their parts), not to any one check: review movies, archives,
+     * summaries. All kinds, videos included. Absent when none, and in a report that carries no such information.
+     */
+    readonly attachments?: number;
     /** The normalized tags of the attachments of its results and layers, sorted and distinct. Absent when none is tagged. */
     readonly artifactTags?: readonly string[];
     /** The tags of its checks and layers, which its attachments inherit (what `inherited=1` also matches), sorted and distinct. Absent when none. */
@@ -314,12 +319,33 @@ export type RunResult = {
     /** Every video its evidence references, with who holds it (check, retry attempt or step). Absent when there is none. */
     readonly videos?: readonly VideoRef[];
 };
+/**
+ * One layer of a run, as the run's artifact hub names it: who recorded it, how many checks it holds (zero is possible
+ * and is not a pass) and the files it carries as a whole. Read the files with `GET /evidence/detail/{backend}/{id}`.
+ */
+export type RunLayer = {
+    /** The layer's id: 64 hex digits for an archived layer. */
+    readonly id: string;
+    /** The backend it was read from, for `GET /evidence/detail/{backend}/{id}`. */
+    readonly backend: string;
+    readonly producer: string;
+    readonly environment: string | null;
+    readonly recordedAtMs: number;
+    /** How many checks the layer recorded. A layer of zero checks is evidence only: it is not a passing test. */
+    readonly checks: number;
+    /** Files the layer carries as a whole (not those of its checks). */
+    readonly attachments: number;
+    /** Its videos, when it has any. */
+    readonly videos?: VideoCounts;
+};
 /** `GET /api/reports/runs/detail`: one run and every result it recorded. */
 export type RunDetail = {
     readonly schemaVersion: typeof TEST_CATALOG_VERSION;
     readonly version: string;
     readonly run: RunSummary;
     readonly results: readonly RunResult[];
+    /** Every layer of the run, oldest first, so its run-level files can be found even in a layer with no checks. Absent from an older server. */
+    readonly layers?: readonly RunLayer[];
 };
 /**
  * One recorded result that carries evidence (an attachment: a recording, a screenshot, a trace), with where and when it
@@ -423,6 +449,7 @@ export declare class TestHistory {
     run(key: string): {
         readonly run: RunSummary;
         readonly results: RunResult[];
+        readonly layers: RunLayer[];
     } | null;
     /**
      * Every recorded result that carries an attachment, newest first, with the values a query looks at. Built once per

package/dist/reports/src/test-catalog.js

@@ -132,7 +132,7 @@ export class TestHistory {
         const key = runKey(layer);
         let run = this.#runs.get(key);
         if (!run) {
-            run = { key, runUrl: layer.runUrl, branch: layer.branch, sha: layer.sha, start: layer.recordedAtMs, end: layer.recordedAtMs, firstAt: layer.recordedAtMs, first: layer.id, producers: new Set(), environments: new Set(), layers: 0, runId: layer.run?.id, title: undefined, titledAt: 0, titledBy: '', freshness: undefined, videos: [], evidence: { tags: new Set(), artifactTags: new Set(), roles: new Set(), labels: new Set() } };
+            run = { key, runUrl: layer.runUrl, branch: layer.branch, sha: layer.sha, start: layer.recordedAtMs, end: layer.recordedAtMs, firstAt: layer.recordedAtMs, first: layer.id, producers: new Set(), environments: new Set(), layers: 0, runId: layer.run?.id, title: undefined, titledAt: 0, titledBy: '', freshness: undefined, videos: [], attachments: 0, members: [], evidence: { tags: new Set(), artifactTags: new Set(), roles: new Set(), labels: new Set() } };
             this.#runs.set(key, run);
         }
         // A run is told by its first layer (by time, then id), whatever order its layers arrive in.
@@ -161,6 +161,10 @@ export class TestHistory {
         run.layers += 1;
         if (layer.evidence?.videos)
             run.videos.push(...layer.evidence.videos);
+        const held = layer.evidence?.attachments ?? 0;
+        run.attachments += held;
+        const layerVideos = videoCounts(layer.evidence?.videos);
+        run.members.push({ id: layer.id, backend, producer: layer.producer, environment: layer.environment, recordedAtMs: layer.recordedAtMs, checks: rows.length, attachments: held, ...(layerVideos ? { videos: layerVideos } : {}) });
         if (layer.evidence)
             takeEvidence(run.evidence, layer.evidence);
         const origin = originOf(layer, backend);
@@ -253,7 +257,8 @@ export class TestHistory {
             ...(r.e?.videos ? { videos: r.e.videos } : {}),
         }));
         results.sort((a, b) => FAILURE_RANK[b.status] - FAILURE_RANK[a.status] || compareText(a.specPath ?? '', b.specPath ?? '') || compareText(a.title, b.title) || compareText(a.environment ?? '', b.environment ?? '') || compareText(a.producer, b.producer) || compareText(a.key, b.key));
-        return { run: runSummary(run, cells), results };
+        const layers = [...run.members].sort((a, b) => a.recordedAtMs - b.recordedAtMs || compareText(a.id, b.id));
+        return { run: runSummary(run, cells), results, layers };
     }
     /**
      * Every recorded result that carries an attachment, newest first, with the values a query looks at. Built once per
@@ -352,6 +357,7 @@ function runSummary(run, cells) {
         producers: [...run.producers].sort(), environments: [...run.environments].sort(),
         layers: run.layers, tests: tests.size, counts, totalDurationMs: measured ? total : null, failing,
         ...(video ? { videos: video } : {}),
+        ...(run.attachments ? { attachments: run.attachments } : {}),
         ...(carried.artifactTags.size ? { artifactTags: [...carried.artifactTags].sort() } : {}),
         ...(carried.roles.size ? { types: typesOf(carried.roles, (video?.recordings ?? 0) > 0) } : {}),
         ...(carried.labels.size ? { labels: [...carried.labels].sort() } : {}),

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

@@ -1317,6 +1317,11 @@ export declare const CheckDetailSchema: z.ZodObject<{
         recordingExpectation: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>;
     run: z.ZodObject<{}, z.core.$loose>;
+    parts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$loose>>>;
     inheritedScope: z.ZodOptional<z.ZodObject<{
         surface: z.ZodOptional<z.ZodString>;
         deviceKind: z.ZodOptional<z.ZodString>;
@@ -2188,6 +2193,7 @@ export declare const ReportRunSchema: z.ZodObject<{
         recordings: z.ZodNumber;
         unavailable: z.ZodNumber;
     }, z.core.$loose>>;
+    attachments: z.ZodOptional<z.ZodNumber>;
     artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     types: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2274,6 +2280,7 @@ export declare const RunListSchema: z.ZodObject<{
             recordings: z.ZodNumber;
             unavailable: z.ZodNumber;
         }, z.core.$loose>>;
+        attachments: z.ZodOptional<z.ZodNumber>;
         artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         types: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2514,6 +2521,7 @@ export declare const RunDetailSchema: z.ZodObject<{
             recordings: z.ZodNumber;
             unavailable: z.ZodNumber;
         }, z.core.$loose>>;
+        attachments: z.ZodOptional<z.ZodNumber>;
         artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         types: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2565,4 +2573,18 @@ export declare const RunDetailSchema: z.ZodObject<{
             }, z.core.$loose>>;
         }, z.core.$loose>>>;
     }, z.core.$loose>>;
+    layers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        backend: z.ZodString;
+        producer: z.ZodString;
+        environment: z.ZodNullable<z.ZodString>;
+        recordedAtMs: z.ZodNumber;
+        checks: z.ZodNumber;
+        attachments: z.ZodNumber;
+        videos: z.ZodOptional<z.ZodObject<{
+            references: z.ZodNumber;
+            recordings: z.ZodNumber;
+            unavailable: z.ZodNumber;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;

package/dist/schema/src/api.js

@@ -191,6 +191,7 @@ export const CheckDetailSchema = z.looseObject({
     kind: z.string(),
     check: CheckSchema,
     run: z.looseObject({}).describe('What the run as a whole carries: its logs, links, labels, annotations, scope and extensions'),
+    parts: z.array(z.looseObject({ kind: z.string(), id: z.string(), title: z.string() })).optional().describe('Without `check` only: the parts of the layer that carry files or links of their own, each with what it carries. Absent when none'),
     inheritedScope: EvidenceScopeSchema.optional().describe('The scope the check inherits: its part\'s declaration, else its layer\'s. Absent when neither declared one: unknown, not live or physical')
 });
 /** `GET /api/store?prefix=…`: one page of keys under `layers/`, in code-unit order. */
@@ -401,6 +402,7 @@ export const ReportRunSchema = z.looseObject({
     totalDurationMs: z.number().nullable(),
     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'),
+    attachments: z.number().int().positive().optional().describe('Files attached to the run itself, in its layers, not to a check. Absent when there are none'),
     artifactTags: z.array(z.string()).optional().describe('The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers'),
     tags: z.array(z.string()).optional().describe('The tags of its checks and layers, which its attachments inherit (what `inherited=1` also matches). Absent when none'),
     types: z.array(z.string()).optional().describe('The media types (roles) of its attachments, sorted and distinct; `video` only for a playable recording. Absent when it has no attachment'),
@@ -457,5 +459,12 @@ export const RunDetailSchema = 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(),
         videos: z.array(VideoRefSchema).optional().describe('Every video its evidence references, with who holds it')
-    }))
+    })),
+    layers: z.array(z.looseObject({
+        id: z.string().describe('The layer id; read its files with `/api/reports/evidence/detail/{backend}/{id}`'),
+        backend: z.string(), producer: z.string(), environment: z.string().nullable(), recordedAtMs: z.number(),
+        checks: z.number().int().nonnegative().describe('How many checks the layer recorded. Zero means evidence only, not a pass'),
+        attachments: z.number().int().nonnegative().describe('Files the layer carries as a whole, not those of its checks'),
+        videos: VideoCountsSchema.optional()
+    })).optional().describe('Every layer of the run, oldest first. Absent from an older server')
 });

package/dist/server/src/openapi.js

@@ -393,7 +393,7 @@ const BASE_OPERATIONS = [
     {
         route: 'GET /api/reports/runs/detail', path: '/api/reports/runs/detail', operationId: 'getReportRun', tag: 'Report', role: 'read',
         summary: 'Every test one run recorded',
-        description: 'One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.',
+        description: 'One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer\'s files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.',
         parameters: [
             { name: 'key', in: 'query', required: true, description: 'The run\'s `key` from `/api/reports/runs`, URL-encoded.', schema: str },
             { name: 'format', in: 'query', description: '`markdown` for Markdown instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
@@ -430,7 +430,7 @@ const BASE_OPERATIONS = [
     {
         route: 'GET /api/reports/evidence/detail/:backend/:id', path: '/api/reports/evidence/detail/{backend}/{id}', operationId: 'getCheckDetail', tag: 'Report', role: 'read',
         summary: 'Everything one result carries',
-        description: 'The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run\'s. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.',
+        description: 'The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run\'s, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.',
         parameters: [BACKEND, LAYER_ID, { name: 'check', in: 'query', description: 'The check id.', schema: str }, { name: 'kind', in: 'query', description: 'The kind of the part, when the same id is in several.', schema: str }],
         responses: { '200': json('The detail.', 'CheckDetail'), '401': UNAUTHORIZED, '404': problem('No such layer or check.') }
     },

package/docs/reference/http-api.md

@@ -756,7 +756,7 @@ Responses: `200` The matching results and the facets.; `304` Unchanged since the
 
 `GET /api/reports/runs/detail` · role: read
 
-One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.
+One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.
 
 - `key` (query, required): The run's `key` from `/api/reports/runs`, URL-encoded.
 - `format` (query): `markdown` for Markdown instead of JSON.
@@ -768,7 +768,7 @@ Responses: `200` The run and its results.; `304` Unchanged since the `If-None-Ma
 
 `GET /api/projects/{project}/reports/runs/detail` · role: read
 
-One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.
+One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. 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.
 
@@ -878,7 +878,7 @@ Responses: `200` The rows.; `401` No token, or an unknown one. Send `Authorizati
 
 `GET /api/reports/evidence/detail/{backend}/{id}` · role: read
 
-The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
+The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
 
 - `backend` (path, required): A backend id from `/api/server`.
 - `id` (path, required): A layer id: 64 lowercase hex digits.
@@ -892,7 +892,7 @@ Responses: `200` The detail.; `401` No token, or an unknown one. Send `Authoriza
 
 `GET /api/projects/{project}/reports/evidence/detail/{backend}/{id}` · role: read
 
-The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
+The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
 
 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.
 

package/docs/reference/reports.md

@@ -1713,6 +1713,16 @@ Whether an attachment is a video, by its effective media type: the producer's `c
 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`).
 
+#### `attachmentIdentity`
+
+```ts
+export function attachmentIdentity(item: Pick<Attachment, 'name' | 'sha256' | 'bundleKey' | 'uri' | 'text'>): string | undefined
+```
+
+What identifies an attachment's bytes: its digest, else its bundle key, address or inline text. Attachments with the
+same identity are the same file however many results reference them. Undefined when it names no bytes at all (it can
+never be opened). This is the `recording` of a {@link VideoRef}.
+
 #### `videoCounts`
 
 ```ts
@@ -1765,6 +1775,27 @@ export function runEvidence(layer: EvidenceHolder): EvidenceHolder
 
 What a layer carries as a whole (its scope, tags, labels, links, attachments, annotations and extensions; not its parts' checks). Absent fields stay absent.
 
+#### `PartEvidence`
+
+```ts
+export type PartEvidence = EvidenceHolder & {
+  readonly kind: string;
+  readonly id: string;
+  readonly title: string;
+};
+```
+
+What one part of a layer (one kind of report) carries as a whole, named by the part.
+
+#### `partsEvidence`
+
+```ts
+export function partsEvidence(layer: { readonly parts: readonly (EvidenceHolder & { readonly kind: string; readonly id: string; readonly title: string })[] }): PartEvidence[]
+```
+
+The parts of a layer that carry evidence of their own (attachments, links, labels…), each with its name. Parts
+that carry none are left out. A part's files belong to the run, not to any one check.
+
 #### `bundleKeysOf`
 
 ```ts
@@ -4639,7 +4670,8 @@ Routes, relative to where it is mounted:
   runs of this machine. `cursor` is the previous page's; 409 when it no longer matches the listing (refresh).
   Any `retry` value re-lists backends that were unavailable now instead of after the wait.
 - `GET /evidence/rows/:backend/:id` the checks and spec fingerprints of one layer (`LayerRows`).
-- `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer, or one check's detail.
+- `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer (and, as `parts`, what its
+  parts carry as a whole), or one check's detail.
 - `GET /layers/:id/blobs/*` an attachment of an immutable layer by its bundle key, served by `attachmentResponse`.
 - `GET /layers/:id/*` the recorded `frame.css`, `tests/<test>/report.json` and `tests/<test>/files/<frame>` of a layer.
 - `GET /live/:source/frame.css` and `GET /live/:source/tests/:testId/*` the same for a run still writing (uncached).
@@ -8601,14 +8633,14 @@ export type RunSummary = {
    * and references that cannot be played. Absent when it has none, and in a report that carries no video information.
    */
   readonly videos?: VideoCounts;
+  /**
+   * Files attached to the run itself, in its layers (and their parts), not to any one check: review movies, archives,
+   * summaries. All kinds, videos included. Absent when none, and in a report that carries no such information.
+   */
+  readonly attachments?: number;
   /** The normalized tags of the attachments of its results and layers, sorted and distinct. Absent when none is tagged. */
   readonly artifactTags?: readonly string[];
   /** The tags of its checks and layers, which its attachments inherit (what `inherited=1` also matches), sorted and distinct. Absent when none. */
-  readonly tags?: readonly string[];
-  /** The media types (roles) of its attachments, sorted and distinct; `video` only for a playable recording. Absent when it has no attachment. */
-  readonly types?: readonly string[];
-  /** The `key=value` labels of its results and layers, sorted and distinct. Absent when none. */
-  readonly labels?: readonly string[];
   …
 ```
 
@@ -8666,6 +8698,29 @@ export type RunResult = {
 
 One test's last result within one run.
 
+#### `RunLayer`
+
+```ts
+export type RunLayer = {
+  /** The layer's id: 64 hex digits for an archived layer. */
+  readonly id: string;
+  /** The backend it was read from, for `GET /evidence/detail/{backend}/{id}`. */
+  readonly backend: string;
+  readonly producer: string;
+  readonly environment: string | null;
+  readonly recordedAtMs: number;
+  /** How many checks the layer recorded. A layer of zero checks is evidence only: it is not a passing test. */
+  readonly checks: number;
+  /** Files the layer carries as a whole (not those of its checks). */
+  readonly attachments: number;
+  /** Its videos, when it has any. */
+  readonly videos?: VideoCounts;
+};
+```
+
+One layer of a run, as the run's artifact hub names it: who recorded it, how many checks it holds (zero is possible
+and is not a pass) and the files it carries as a whole. Read the files with `GET /evidence/detail/{backend}/{id}`.
+
 #### `RunDetail`
 
 ```ts
@@ -8674,6 +8729,8 @@ export type RunDetail = {
   readonly version: string;
   readonly run: RunSummary;
   readonly results: readonly RunResult[];
+  /** Every layer of the run, oldest first, so its run-level files can be found even in a layer with no checks. Absent from an older server. */
+  readonly layers?: readonly RunLayer[];
 };
 ```
 
@@ -8779,7 +8836,7 @@ const catalog = testCatalog(catalogModel(layers, { history }));
 - `of(key: string): readonly TestResultEntry[]` — The recorded results of one test (by `TestSummary.key`), newest first. Empty when none.
 - `get runCount(): number { return this.#runs.size; }` — How many runs it knows of.
 - `runs(): RunSummary[]` — Every run, newest first.
-- `run(key: string): { readonly run: RunSummary; readonly results: RunResult[] } | null` — One run and its results (failed first, then by spec and title), or null.
+- `run(key: string): { readonly run: RunSummary; readonly results: RunResult[]; readonly layers: RunLayer[] } | null` — One run and its results (failed first, then by spec and title), or null.
 - `evidenceResults(): readonly { readonly result: ArtifactResult; readonly fields: FilterFields }[]` — Every recorded result that carries an attachment, newest first, with the values a query looks at. Built once per layer added. The domain is left to the caller (`artifactList`), which may know more specs than the layers recorded.
 - `testsIn(key: string): ReadonlySet<string>` — The keys of the tests one run recorded.
 

package/docs/rich-evidence.md

@@ -303,6 +303,29 @@ or the command line, an attachment may name a `path` instead; `atlas report publ
 `atlas report publish --ctrf` keeps it ([native runner reporters](runners.md) cover CodeceptJS, Mocha, Jest and Node's
 test runner).
 
+## Run artifacts and direct links
+
+Files attached to a run as a whole (top-level `attachments`: a review movie, a ZIP, an HTML gallery, a summary) are
+shown under **Artifacts** when you open a run in the viewer's Runs tab, without opening any test. The movie plays
+inline, an archive is a download, and each file keeps its name, role, type, size, duration and tags. They are grouped
+by the layer that carries them, with who recorded it and when. A layer may hold no checks at all, only files: it is
+listed with `No checks in this layer`, and a run of only such layers shows `No checks recorded`, never `0 passed`.
+
+- **Direct link.** *Link to this file* gives an address that names the project, the run, one immutable layer and one
+  attachment: `#/?tab=runs&openRun=<run key>&layer=<layer id>&artifact=<id:… | key:… | name:…>`. Opened in a fresh tab
+  it selects that same file of that same layer, whatever runs arrived since. A link whose file is not in the layer says
+  so instead of showing another file.
+- **Shared recordings.** Tests that reference the same bytes (same SHA-256 or bundle key) are one recording. The run's
+  *Recordings in tests* lists each once, with every test that references it, and a run-level file that a test also
+  references says so.
+- **Unplayable files.** A file with no stored bytes, with an address that is not a web address, in a type the viewer
+  has no preview for, or that the browser cannot play, shows what is wrong and, when it can, a download.
+- **Safety is unchanged.** Files are served only through the attachment route (never sniffed, sandboxed), and an HTML
+  archive renders in an iframe with an empty `sandbox`: it cannot run script.
+- **API.** `GET /api/reports/runs/detail` lists the run's `layers` (backend, check count, file count) and
+  `GET /api/reports/evidence/detail/{backend}/{id}` returns what a layer carries as a whole (and, as `parts`, what its
+  parts carry). Both only gained optional fields.
+
 ## Recording completeness
 
 A green run does not say whether the videos you expected were kept and published. Atlas answers that separately from

package/docs/ui.md

@@ -67,6 +67,26 @@ and component defaults still live only in `ui/theme.tsx`. Quint/Alloy grammar so
 [`ui/grammars/README.md`](../packages/visualizer/src/ui/grammars/README.md). Unknown formats remain plain
 text, and parse failures must leave the source visible. Syntax highlighting never means a spec passed.
 
+## Behaviors: Read, Watch, Inspect
+
+A Gherkin page reads as behaviors: each scenario, or each example row of an outline (never the outline template as an
+extra), is one behavior in one coverage state (`evidence/behavior.ts`). Opening a behavior shows Mantine `Tabs`:
+**Read** (the steps with the example's values filled in), **Watch** (what is expected next to the matched recording,
+its status and provenance) and **Inspect** (the existing check detail: runs, environments, attempts, files). A behavior
+with a playable recording opens on Watch, one in a run in progress on Inspect, otherwise on Read. The video is read only
+when Watch is on screen.
+
+- States stay distinct and none but `demonstrated` is a pass with proof: recording missing, recording of an older spec
+  revision, no recording, API only, failed, running, skipped, parked (tagged `@parked`, `@wip`, `@pending`) and not executed.
+  Counts are in the Coverage section above the source; an empty state is left out except `demonstrated`.
+- The promise's revision (the spec's fingerprint now) and the evidence's revision (the fingerprint the layer recorded)
+  are shown separately. A known difference demotes a recording to "Recording is older" with an alert; a missing
+  fingerprint is "not recorded", never a match.
+- A recording is always labelled illustrative: it shows one run and does not approve a behavior for production.
+  `demo`/`representative` tags only add a "Representative demo" label.
+- The spec index searches titles, paths and declared domains, and can group by the domain from spec metadata (specs with
+  none are listed under "No domain declared"; the Tests view reports domain problems).
+
 ## Icons and notation marks
 
 Use named imports from `@tabler/icons-react` for all UI glyphs. The icon package supplies SVG paths;
@@ -125,9 +145,9 @@ The narrowly scoped exceptions are:
 | Area | Screens/interactions | Mantine composition |
 | --- | --- | --- |
 | Shared shell | Project switching, spec navigation, run selection, connection status, diagnostics, mobile index | AppShell, Burger, NavLink, Menu, Popover, NativeSelect, Drawer |
-| Project home | Tests/runs/artifacts tabs, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion |
+| Project home | Tests/runs/artifacts tabs, a run's Artifacts (files of its layers, shared recordings, direct links), metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion |
 | Test detail | Current outcomes, statistics, duration graph, history, artifacts, recording; the `layer` address parameter pins it to one run's result, labelled "This run" against "Latest combined evidence" | Drawer, Table, Badge, Alert, Stage |
-| Specs | All six existing kinds, overview/index, Gherkin rules/scenarios/examples, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Table, CodeHighlightTabs, ResultRow |
+| Specs | All six existing kinds, overview/index with title search and folder or declared-domain grouping, Gherkin rules/scenarios/examples with a coverage summary and Read / Watch / Inspect per behavior, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Tabs, Table, CodeHighlightTabs, ResultRow |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
 | Recordings | Pictures/video/timeline, actor selection, moments, failure jumps, timing, model-state differences | Tabs, Slider, Button, ScrollArea, Table, Progress |