@crvouga/atlas 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog: @crvouga/atlas
 
-## 1.17.0 (2026-10-29)
+## 1.18.0 (2026-10-29)
+
+### Features
+
+- verify stored recordings and filter runs by recording completeness ([576d9ea](https://github.com/crvouga/atlas/commit/576d9ea3f8b1abfa45906e71c1cf329cae75d303))
+
+## 1.17.0 (2026-10-28)
 
 ### Features
 

package/dist/reports/src/artifact-query.d.ts

@@ -4,7 +4,7 @@ export type QueryFacetValue = {
     readonly count: number;
 };
 /** The dimensions a query narrows by, with their address parameters. */
-export declare const QUERY_DIMENSIONS: readonly ["artifactTag", "type", "label", "environment", "producer", "branch", "sha", "outcome", "domain", "spec"];
+export declare const QUERY_DIMENSIONS: readonly ["artifactTag", "type", "label", "environment", "producer", "branch", "sha", "outcome", "domain", "spec", "recordings"];
 /** One of {@link QUERY_DIMENSIONS}. */
 export type QueryDimension = (typeof QUERY_DIMENSIONS)[number];
 /** What a query asks for. Every field is optional; nothing asked is everything. See the module comment for the semantics. */
@@ -31,6 +31,12 @@ export type ArtifactFilter = {
     readonly domain?: readonly string[];
     /** Spec paths. Not applicable to runs. */
     readonly spec?: readonly string[];
+    /**
+     * Recording completeness of a run: `complete`, `incomplete`, `none-expected` or `unknown` (a run whose layers declared no
+     * recording expectations is `unknown`, never `complete`). Answered from the layers' receipts alone, without reading any
+     * recording. Applies to runs only; it is independent of `outcome`.
+     */
+    readonly recordings?: readonly string[];
     /** Only records at or after this time (epoch ms): a result's recording time, a run's end. */
     readonly since?: number;
     /** Only records at or before this time (epoch ms). */
@@ -65,6 +71,8 @@ export type FilterFields = {
     /** Absent when the dimension does not apply (runs have no domain). */
     readonly domains?: readonly string[];
     readonly specs?: readonly string[];
+    /** The recording completeness of a run (one value). Absent when the dimension does not apply (results). */
+    readonly recordings?: readonly string[];
     readonly at: number;
 };
 /** The facets of a query: for each dimension, its values with disjunctive counts (see the module comment). */
@@ -78,6 +86,8 @@ export type QueryFacets = {
     readonly branches: readonly QueryFacetValue[];
     readonly outcomes: readonly QueryFacetValue[];
     readonly domains?: readonly QueryFacetValue[];
+    /** Runs only: `complete`, `incomplete`, `none-expected` and `unknown`, with how many runs have each. */
+    readonly recordings?: readonly QueryFacetValue[];
 };
 /**
  * Splits a comma-separated list from an address: `a,b` is two values; `\,` is a comma and `\\` a backslash inside a
@@ -102,9 +112,11 @@ export declare function parseArtifactFilter(params: URLSearchParams): ArtifactFi
 export declare function filterParams(filter: ArtifactFilter): URLSearchParams;
 /** Which filters a query uses, by the names an address gives them. */
 export declare function usedFilters(filter: ArtifactFilter): FilterName[];
+/** Every filter in `filter` that may be applied to a recorded result, as the artifacts query applies them (no recording completeness, which is a property of a run). */
+export declare function forArtifacts(filter: ArtifactFilter): ArtifactFilter;
 /** Whether a query narrows anything. */
 export declare function isFiltered(filter: ArtifactFilter): boolean;
-/** Every filter in `filter` that may be applied to a record with these fields, as the runs query applies them (no domain or spec). */
+/** Every filter in `filter` that may be applied to a run, as the runs query applies them (no domain or spec). */
 export declare function forRuns(filter: ArtifactFilter): ArtifactFilter;
 /**
  * Whether a record satisfies a query. `skip` leaves one dimension out: what {@link facetsOf} uses to count the values of

package/dist/reports/src/artifact-query.js

@@ -3,7 +3,7 @@
  *
  * One shareable query for the runs of a project and for the recorded results that carry evidence (recordings,
  * screenshots, traces): by artifact tag, label, media type, feature (domain, spec), environment or device, producer,
- * branch, revision, outcome and time. The same rules answer `GET /api/reports/runs`, `GET /api/reports/artifacts`
+ * branch, revision, outcome, time and (runs only) recording completeness. The same rules answer `GET /api/reports/runs`, `GET /api/reports/artifacts`
  * and the viewer's Runs and Artifacts views, so a link means the same thing everywhere.
  *
  * The semantics are fixed, not inferred:
@@ -26,7 +26,7 @@
  */
 import { normalizeTag } from './artifact-tags.js';
 /** The dimensions a query narrows by, with their address parameters. */
-export const QUERY_DIMENSIONS = ['artifactTag', 'type', 'label', 'environment', 'producer', 'branch', 'sha', 'outcome', 'domain', 'spec'];
+export const QUERY_DIMENSIONS = ['artifactTag', 'type', 'label', 'environment', 'producer', 'branch', 'sha', 'outcome', 'domain', 'spec', 'recordings'];
 /**
  * Splits a comma-separated list from an address: `a,b` is two values; `\,` is a comma and `\\` a backslash inside a
  * value. Values are trimmed and empty ones dropped.
@@ -133,11 +133,16 @@ export function usedFilters(filter) {
         used.push('video');
     return used;
 }
+/** Every filter in `filter` that may be applied to a recorded result, as the artifacts query applies them (no recording completeness, which is a property of a run). */
+export function forArtifacts(filter) {
+    const { recordings: _recordings, ...rest } = filter;
+    return rest;
+}
 /** Whether a query narrows anything. */
 export function isFiltered(filter) {
     return usedFilters(filter).some(name => name !== 'inherited');
 }
-/** Every filter in `filter` that may be applied to a record with these fields, as the runs query applies them (no domain or spec). */
+/** Every filter in `filter` that may be applied to a run, as the runs query applies them (no domain or spec). */
 export function forRuns(filter) {
     const { domain: _domain, spec: _spec, ...rest } = filter;
     return rest;
@@ -186,6 +191,8 @@ export function matchesFilter(fields, filter, skip) {
         return false;
     if (skip !== 'spec' && filter.spec?.length && fields.specs && !filter.spec.some(value => fields.specs.includes(value)))
         return false;
+    if (skip !== 'recordings' && filter.recordings?.length && fields.recordings && !filter.recordings.some(value => fields.recordings.includes(value)))
+        return false;
     if (filter.since !== undefined && fields.at < filter.since)
         return false;
     if (filter.until !== undefined && fields.at > filter.until)
@@ -213,6 +220,7 @@ export function facetsOf(records, filter) {
     const dimension = (skip, pick, chosen) => withChosen(tally(scope(skip).map(pick)), chosen);
     const normalTags = (filter.artifactTag ?? []).map(tag => normalizeTag(tag)).filter((tag) => tag !== null);
     const domains = records.some(record => record.domains);
+    const recordings = records.some(record => record.recordings);
     return {
         artifactTags: dimension('artifactTag', fields => fields.artifactTags, normalTags),
         types: dimension('type', fields => fields.types, filter.type),
@@ -221,7 +229,8 @@ export function facetsOf(records, filter) {
         producers: dimension('producer', fields => fields.producers, filter.producer),
         branches: dimension('branch', fields => fields.branches, filter.branch),
         outcomes: dimension('outcome', fields => fields.outcomes, filter.outcome),
-        ...(domains ? { domains: dimension('domain', fields => fields.domains ?? [], filter.domain) } : {})
+        ...(domains ? { domains: dimension('domain', fields => fields.domains ?? [], filter.domain) } : {}),
+        ...(recordings ? { recordings: dimension('recordings', fields => fields.recordings ?? [], filter.recordings) } : {})
     };
 }
 /** The outcome of a run from its results by status: `failed`, else `running`, else `passed`, else `not-run`. */

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

@@ -117,7 +117,7 @@ function videoOf(item, owner, where, scope, unstored) {
     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, ...(scope ? { scope } : {}) };
+    return { name: item.name, owner, ...where, ...(tags.length ? { tags } : {}), ...(recording === undefined ? {} : { recording }), available: recording !== undefined, ...(lost && recording === undefined ? { reason: 'not-in-bundle' } : {}), ...(scope ? { scope } : {}) };
 }
 /**
  * Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so
@@ -127,14 +127,17 @@ export function videoCounts(videos) {
     if (!videos?.length)
         return undefined;
     const distinct = new Set();
-    let unavailable = 0;
+    let unavailable = 0, missing = 0;
     for (const video of videos) {
         if (video.available && video.recording !== undefined)
             distinct.add(video.recording);
-        else
+        else {
             unavailable += 1;
+            if (video.reason === 'not-in-bundle')
+                missing += 1;
+        }
     }
-    return { references: videos.length, recordings: distinct.size, unavailable };
+    return { references: videos.length, recordings: distinct.size, unavailable, ...(missing ? { missing } : {}) };
 }
 /** A role to show when a producer gave none, from the media type: `image`, `video`, `audio`, `snapshot` (text/html), `text` (text, JSON, XML) or `file`. Roles are an open vocabulary; a producer's own role always wins. */
 export function roleOfType(contentType) {

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

@@ -58,6 +58,8 @@ export type VideoRef = {
     readonly recording?: string;
     /** False when the reference names no bytes at all (no bundle key, address or inline text), or a bundle key that the layer's own bundle does not hold, so it can never be played. */
     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';
     /** 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;
 };
@@ -69,6 +71,8 @@ export type VideoCounts = {
     readonly recordings: number;
     /** References that name no bytes, or bytes the layer does not hold. A report that predates availability metadata has none of these and none of the others. */
     readonly unavailable: number;
+    /** Of `unavailable`, those that name a file the layer's bundle does not hold (stored, then gone). Absent when there are none. */
+    readonly missing?: number;
 };
 /**
  * What a result (or a run) carries beyond its outcome, as counts and short facts: attachments, steps,

package/dist/reports/src/recording-receipt.d.ts

@@ -11,6 +11,7 @@
  * @see docs/rich-evidence.md#recording-completeness
  */
 import type { RecordingCompleteness, RecordingReceipt } from '../../schema/src/layer.js';
+import type { RecordingCounts } from './evidence-types.js';
 type Loose = Record<string, unknown>;
 /** Is this attachment a screen recording: a role of `video`, or a `video/*` media type? */
 export declare function isVideoAttachment(attachment: Loose): boolean;
@@ -45,4 +46,26 @@ export type RecordingResult = {
  * nothing was. Gaps are sorted so the output never depends on read order.
  */
 export declare function recordingCompleteness(results: readonly RecordingResult[]): RecordingCompleteness;
+/** A run's recording completeness, from the receipts of its layers (see {@link runRecordings}). */
+export type RunRecordings = {
+    /** `incomplete`: a recording is skipped or unresolved. `unknown`: no gap is known, but a layer declared no expectations. `complete`: everything expected was published. `none-expected`: every layer declared expectations and none required a recording. */
+    readonly state: 'complete' | 'incomplete' | 'none-expected' | 'unknown';
+    /** Recordings the layers expected. */
+    readonly expected: number;
+    /** Of those, uploaded or referenced by address. */
+    readonly published: number;
+    readonly skipped: number;
+    readonly unresolved: number;
+    /** Intentionally unrecorded checks: neither expected nor missing. */
+    readonly notApplicable: number;
+    /** Layers of the run that declared no expectations: nothing is claimed for them. */
+    readonly layersWithoutReceipt: number;
+};
+/**
+ * The recording completeness of a run, from the `recordings` counts of each of its layers (`undefined` for a layer that
+ * has no receipt). `undefined` when no layer has a receipt: the run claims nothing, which a reader treats as `unknown`.
+ * A gap always wins (`incomplete`); otherwise a layer without a receipt keeps the run `unknown`, never `complete`. Reads
+ * only the counts, never a recording, and never changes a status.
+ */
+export declare function runRecordings(layers: readonly (RecordingCounts | undefined)[]): RunRecordings | undefined;
 export {};

package/dist/reports/src/recording-receipt.js

@@ -101,3 +101,19 @@ export function recordingCompleteness(results) {
     const state = gaps.length ? 'incomplete' : without.size || !results.length ? 'unknown' : count.expected ? 'complete' : 'none-expected';
     return { state, ...count, layersWithoutReceipt: without.size, gaps };
 }
+/**
+ * The recording completeness of a run, from the `recordings` counts of each of its layers (`undefined` for a layer that
+ * has no receipt). `undefined` when no layer has a receipt: the run claims nothing, which a reader treats as `unknown`.
+ * A gap always wins (`incomplete`); otherwise a layer without a receipt keeps the run `unknown`, never `complete`. Reads
+ * only the counts, never a recording, and never changes a status.
+ */
+export function runRecordings(layers) {
+    const receipts = layers.filter((layer) => layer !== undefined);
+    if (!receipts.length)
+        return undefined;
+    const sum = (pick) => receipts.reduce((total, counts) => total + pick(counts), 0);
+    const skipped = sum(counts => counts.skipped), unresolved = sum(counts => counts.unresolved), expected = sum(counts => counts.expected);
+    const layersWithoutReceipt = layers.length - receipts.length;
+    const state = skipped + unresolved > 0 ? 'incomplete' : layersWithoutReceipt > 0 ? 'unknown' : expected > 0 ? 'complete' : 'none-expected';
+    return { state, expected, published: sum(counts => counts.uploaded + counts.referenced), skipped, unresolved, notApplicable: sum(counts => counts.notApplicable), layersWithoutReceipt };
+}

package/dist/reports/src/recording-verify.d.ts

@@ -0,0 +1,74 @@
+import type { ObjectStore } from './object-store.js';
+import type { ReportLayer } from './layer-types.js';
+/** What is wrong with a stored recording. An open vocabulary: a reader treats an unknown problem as a gap. */
+export type RecordingProblem = 
+/** The layer names the file but its bundle does not list it: stored, then gone (or never arrived). */
+'not-in-bundle'
+/** The bundle lists the file but a blob holding its bytes is no longer in the store (a 404 when played). */
+ | 'blob-missing'
+/** The store could not be read just now. Not proof the bytes are gone, and not a pass. */
+ | 'unreadable'
+/** The stored bytes are not as many as were recorded. */
+ | 'size-mismatch'
+/** The stored bytes do not hash to the SHA-256 recorded at upload. */
+ | 'checksum-mismatch'
+/** The stored bytes do not begin like the container their media type names, or are empty: incompatible or corrupt. */
+ | 'undecodable';
+/** One video of a layer that failed verification. */
+export type RecordingGap = {
+    /** The check that holds the video, or `null` for a video attached to the layer or a part. */
+    readonly check: string | null;
+    /** The attachment's name. */
+    readonly name: string;
+    readonly bundleKey: string;
+    readonly problem: RecordingProblem;
+    /** A short, non-secret explanation: sizes or the container found. */
+    readonly reason: string;
+};
+/** What verifying one layer found. */
+export type LayerRecordingVerification = {
+    readonly layer: string;
+    /** Videos read back from the store: those that name a bundle key. */
+    readonly checked: number;
+    /** Of those, the ones that passed every check. */
+    readonly ok: number;
+    /** Videos given only by `uri`, which Atlas cannot read back. */
+    readonly referenced: number;
+    readonly gaps: readonly RecordingGap[];
+};
+/**
+ * Whether the first bytes of a stored video are the container its media type names, as a reason it is not, or `null` when
+ * it looks right or the type is one this check has no signature for (then nothing is claimed). Recognizes WebM and
+ * Matroska (EBML), MP4, QuickTime and 3GPP (an ISO box), Ogg and AVI. An empty file is never a video.
+ */
+export declare function containerProblem(bytes: Uint8Array, contentType: string): string | null;
+/**
+ * Reads back every video of `layer` that is kept in its bundle and reports the ones that are no longer retrievable or no
+ * longer look like what was published (see {@link RecordingProblem}). Each blob is read once however many checks
+ * reference it. A store that fails to answer is `unreadable`, never a pass. It only reads: nothing is written, and no
+ * status changes.
+ *
+ * @example
+ * ```ts
+ * const layer = await readLayer(store, id);
+ * const { gaps } = await verifyLayerRecordings(store, layer!);
+ * gaps.map(gap => `${gap.check}: ${gap.problem}`);
+ * ```
+ */
+export declare function verifyLayerRecordings(store: ObjectStore, layer: ReportLayer): Promise<LayerRecordingVerification>;
+/** What verifying the layers of one store found. */
+export type StoreRecordingVerification = {
+    readonly layers: readonly LayerRecordingVerification[];
+    /** Layers that could not be read at all (their manifest is unreadable or gone): their recordings are unknown, not verified. */
+    readonly notices: readonly string[];
+};
+/**
+ * Verifies the recordings of the layers a store lists, newest first. `ids` narrows to layers whose id starts with one of
+ * them (at least 7 hex digits); `limit` keeps only that many of the newest. A layer that cannot be read is a notice, never
+ * skipped silently and never counted as verified. A store that cannot be listed rejects.
+ */
+export declare function verifyStoreRecordings(store: ObjectStore, options?: {
+    readonly ids?: readonly string[];
+    readonly limit?: number;
+    readonly include?: (layer: ReportLayer) => boolean;
+}): Promise<StoreRecordingVerification>;

package/dist/reports/src/recording-verify.js

@@ -0,0 +1,142 @@
+import { createBundleReader } from './bundle.js';
+import { isVideoAttachment } from './evidence-detail.js';
+import { contentTypeOf } from './media-types.js';
+import { LAYER_INDEX, readLayer } from './layer-store.js';
+import { sha256Hex } from './sigv4.js';
+const MP4_BOXES = new Set(['ftyp', 'moov', 'mdat', 'free', 'wide', 'skip', 'pnot']);
+const ascii = (bytes, from, to) => String.fromCharCode(...bytes.subarray(from, to));
+/**
+ * Whether the first bytes of a stored video are the container its media type names, as a reason it is not, or `null` when
+ * it looks right or the type is one this check has no signature for (then nothing is claimed). Recognizes WebM and
+ * Matroska (EBML), MP4, QuickTime and 3GPP (an ISO box), Ogg and AVI. An empty file is never a video.
+ */
+export function containerProblem(bytes, contentType) {
+    if (!bytes.length)
+        return 'the file is empty';
+    const type = contentType.toLowerCase();
+    const found = () => `its first bytes are not ${type}`;
+    if (type.includes('webm') || type.includes('matroska'))
+        return bytes[0] === 0x1a && bytes[1] === 0x45 && bytes[2] === 0xdf && bytes[3] === 0xa3 ? null : found();
+    if (type.includes('mp4') || type.includes('quicktime') || type.includes('3gpp') || type.includes('m4v'))
+        return bytes.length >= 8 && MP4_BOXES.has(ascii(bytes, 4, 8)) ? null : found();
+    if (type.includes('ogg'))
+        return ascii(bytes, 0, 4) === 'OggS' ? null : found();
+    if (type.includes('msvideo'))
+        return ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 12) === 'AVI ' ? null : found();
+    return null;
+}
+/** Every video attachment of a holder, its steps and its attempts. */
+function videosOf(holder, check) {
+    const found = [];
+    const take = (list) => { for (const attachment of list ?? [])
+        if (isVideoAttachment(attachment))
+            found.push({ check, attachment }); };
+    take(holder.attachments);
+    for (const step of holder.steps ?? [])
+        take(step.attachments);
+    for (const attempt of holder.attempts ?? []) {
+        take(attempt.attachments);
+        for (const step of attempt.steps ?? [])
+            take(step.attachments);
+    }
+    return found;
+}
+/**
+ * Reads back every video of `layer` that is kept in its bundle and reports the ones that are no longer retrievable or no
+ * longer look like what was published (see {@link RecordingProblem}). Each blob is read once however many checks
+ * reference it. A store that fails to answer is `unreadable`, never a pass. It only reads: nothing is written, and no
+ * status changes.
+ *
+ * @example
+ * ```ts
+ * const layer = await readLayer(store, id);
+ * const { gaps } = await verifyLayerRecordings(store, layer!);
+ * gaps.map(gap => `${gap.check}: ${gap.problem}`);
+ * ```
+ */
+export async function verifyLayerRecordings(store, layer) {
+    const holders = [...videosOf(layer, null)];
+    for (const part of layer.parts) {
+        holders.push(...videosOf(part, null));
+        for (const check of part.checks)
+            holders.push(...videosOf(check, check.id));
+    }
+    const read = createBundleReader(store, layer.bundle);
+    const bytesOf = new Map();
+    const load = (key) => {
+        let pending = bytesOf.get(key);
+        if (!pending) {
+            pending = read(key).then(entry => entry ?? 'missing', () => 'unreadable');
+            bytesOf.set(key, pending);
+        }
+        return pending;
+    };
+    const gaps = [];
+    let checked = 0, ok = 0, referenced = 0;
+    for (const { check, attachment } of holders) {
+        const key = attachment.bundleKey;
+        if (key === undefined) {
+            if (attachment.uri !== undefined)
+                referenced += 1;
+            continue;
+        }
+        checked += 1;
+        const gap = (problem, reason) => { gaps.push({ check, name: attachment.name, bundleKey: key, problem, reason }); };
+        if (!Object.hasOwn(layer.bundle, key)) {
+            gap('not-in-bundle', 'the layer names this file but its bundle does not list it');
+            continue;
+        }
+        const stored = await load(key);
+        if (stored === 'unreadable') {
+            gap('unreadable', 'the store could not be read');
+            continue;
+        }
+        if (stored === 'missing') {
+            gap('blob-missing', 'a blob holding this file is no longer in the store');
+            continue;
+        }
+        if (attachment.bytes !== undefined && attachment.bytes !== stored.bytes.length) {
+            gap('size-mismatch', `${stored.bytes.length} bytes stored, ${attachment.bytes} recorded`);
+            continue;
+        }
+        if (attachment.sha256 !== undefined && attachment.sha256 !== await sha256Hex(stored.bytes)) {
+            gap('checksum-mismatch', 'the stored bytes do not match the recorded SHA-256');
+            continue;
+        }
+        const problem = containerProblem(stored.bytes, attachment.contentType ?? (stored.contentType || contentTypeOf(attachment.name)));
+        if (problem) {
+            gap('undecodable', problem);
+            continue;
+        }
+        ok += 1;
+    }
+    return { layer: layer.id, checked, ok, referenced, gaps };
+}
+/**
+ * Verifies the recordings of the layers a store lists, newest first. `ids` narrows to layers whose id starts with one of
+ * them (at least 7 hex digits); `limit` keeps only that many of the newest. A layer that cannot be read is a notice, never
+ * skipped silently and never counted as verified. A store that cannot be listed rejects.
+ */
+export async function verifyStoreRecordings(store, options = {}) {
+    const keys = await store.listKeys(LAYER_INDEX);
+    const wanted = options.ids?.length ? options.ids.map(id => id.toLowerCase()) : null;
+    const ids = keys.flatMap(key => { const id = /-([0-9a-f]{64})\.json$/.exec(key)?.[1]; return id && (!wanted || wanted.some(prefix => id.startsWith(prefix))) ? [id] : []; });
+    const layers = [];
+    const notices = [];
+    for (const id of ids.slice(0, options.limit ?? ids.length)) {
+        try {
+            const layer = await readLayer(store, id);
+            if (!layer) {
+                notices.push(`layer ${id.slice(0, 12)} is listed but its manifest is missing`);
+                continue;
+            }
+            if (options.include && !options.include(layer))
+                continue;
+            layers.push(await verifyLayerRecordings(store, layer));
+        }
+        catch (error) {
+            notices.push(`layer ${id.slice(0, 12)} could not be read: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+        }
+    }
+    return { layers, notices };
+}

package/dist/reports/src/report-cli.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module The `atlas report` command
  *
- * `reportMain` is `atlas report publish | stream | status | merge | doctor | policy`, written so it can be called from code and
+ * `reportMain` is `atlas report publish | stream | status | verify-recordings | merge | doctor | policy`, written so it can be called from code and
  * tests as well as a terminal: it takes its arguments, environment, working directory, clock, git and standard input as
  * parameters and returns the exit code. Every command can print a JSON document (`--format json`) instead of prose, and a
  * command that is wrong throws, which `runReportCommand` turns into a message (or a JSON error) and exit code 2.
@@ -13,7 +13,7 @@
  * @see docs/agents.md
  */
 /** The text `atlas report --help` prints: every subcommand, its flags, what each does and the exit codes. Also the source of the command reference in `docs/reference/cli.md`. */
-export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--run-id <id>] [--run-title <t>] [--run-started-at <iso|ms>] [--run-ended-at <iso|ms>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n                       [--require-recordings]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--run-id <id>] [--run-title <t>]\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.\n  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --run-id <id>   name this execution (a local or manual run with no CI run URL; also ATLAS_RUN_ID).\n                            Layers that share an id are one run, however many shards or batches uploaded them;\n                            another invocation at the same commit gets another id. Never part of what a check is\n            --run-title <t> a human name for the run (also ATLAS_RUN_TITLE); --run-started-at and --run-ended-at\n                            record when it ran. Without --run-id a run is its CI run URL, else branch@sha\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            --require-recordings   exit 1 when a check that declared recordingExpectation \"required\" has no\n                              uploaded video (absent, left out as too large or not allowed, or refused). The layer is\n                              still written and the checks keep their results; only this command fails. The receipt of\n                              what was uploaded (counts, sizes, checksums) is in the JSON result under layer.recordings.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
+export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--run-id <id>] [--run-title <t>] [--run-started-at <iso|ms>] [--run-ended-at <iso|ms>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n                       [--require-recordings]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--run-id <id>] [--run-title <t>]\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report verify-recordings [--store <dir|s3://\u2026|id=url>]... [--backends <module>] [--layer <id>]...\n                       [--limit <n>] [--branch <name>]... [--ignore-modified] [--format text|json]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.\n  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --run-id <id>   name this execution (a local or manual run with no CI run URL; also ATLAS_RUN_ID).\n                            Layers that share an id are one run, however many shards or batches uploaded them;\n                            another invocation at the same commit gets another id. Never part of what a check is\n            --run-title <t> a human name for the run (also ATLAS_RUN_TITLE); --run-started-at and --run-ended-at\n                            record when it ran. Without --run-id a run is its CI run URL, else branch@sha\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            --require-recordings   exit 1 when a check that declared recordingExpectation \"required\" has no\n                              uploaded video (absent, left out as too large or not allowed, or refused). The layer is\n                              still written and the checks keep their results; only this command fails. The receipt of\n                              what was uploaded (counts, sizes, checksums) is in the JSON result under layer.recordings.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  verify-recordings   Read back the videos the layers published and check they are still there as published: the\n            layer still lists the file, its blob is still stored, its size and SHA-256 are the recorded ones, and it\n            begins like the container its media type names. Exit 1 when any video is missing, unreadable, corrupt or\n            not that container, naming the layer and check; test results are never changed. This checks stored bytes,\n            not playback in a browser. Videos given only by address are counted, not checked.\n            --layer <id>   only the layer whose id starts with this (repeatable; at least 7 digits)\n            --limit <n>    only the newest n layers\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor, status and verify-recordings print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status, verify-recordings-result). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
 type Env = Readonly<Record<string, string | undefined>>;
 type Git = (args: readonly string[]) => string | null;
 /** What `reportMain` is given besides arguments: where output goes (`out`), and, for tests and embedding, the environment, working directory, git, clock and standard input (`stdin`, where `stream` reads checks from). Defaults are the real ones. */

package/dist/reports/src/report-cli.js

@@ -1,7 +1,7 @@
 /**
  * @module The `atlas report` command
  *
- * `reportMain` is `atlas report publish | stream | status | merge | doctor | policy`, written so it can be called from code and
+ * `reportMain` is `atlas report publish | stream | status | verify-recordings | merge | doctor | policy`, written so it can be called from code and
  * tests as well as a terminal: it takes its arguments, environment, working directory, clock, git and standard input as
  * parameters and returns the exit code. Every command can print a JSON document (`--format json`) instead of prose, and a
  * command that is wrong throws, which `runReportCommand` turns into a message (or a JSON error) and exit code 2.
@@ -28,6 +28,7 @@ import { parseWith } from './parse-with.js';
 import { publishChecks } from './publish-checks.js';
 import { createReporter } from './reporter.js';
 import { formatStatusMarkdown, formatStatusText, reportStatus } from './report-status.js';
+import { verifyStoreRecordings } from './recording-verify.js';
 import { publishRunBundle } from './run-bundle.js';
 import { collectSpecFiles, latestSpecSet, publishSpecSet } from './spec-set.js';
 import { linkChecksToSpecs } from './spec-link.js';
@@ -52,6 +53,8 @@ export const REPORT_USAGE = `atlas report — layered evidence for any kind of s
                        [--specs <dir>] [--format text|json|markdown]
                        [--require-environments a,b] [--require-all-specs]
                        [--branch <name>]... [--ignore-modified]
+  atlas report verify-recordings [--store <dir|s3://…|id=url>]... [--backends <module>] [--layer <id>]...
+                       [--limit <n>] [--branch <name>]... [--ignore-modified] [--format text|json]
   atlas report merge   [--store …]... [--backends <module>] --into <dir|s3://…>
   atlas report doctor  [--store …]... [--role publisher|reader|both]
   atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]
@@ -95,6 +98,13 @@ export const REPORT_USAGE = `atlas report — layered evidence for any kind of s
             --require-all-specs    fail while any spec has no results
             --branch <name>        only layers recorded on this branch (repeatable)
             --ignore-modified      leave out layers from modified checkouts and unknown origins
+  verify-recordings   Read back the videos the layers published and check they are still there as published: the
+            layer still lists the file, its blob is still stored, its size and SHA-256 are the recorded ones, and it
+            begins like the container its media type names. Exit 1 when any video is missing, unreadable, corrupt or
+            not that container, naming the layer and check; test results are never changed. This checks stored bytes,
+            not playback in a browser. Videos given only by address are counted, not checked.
+            --layer <id>   only the layer whose id starts with this (repeatable; at least 7 digits)
+            --limit <n>    only the newest n layers
   merge     Copy the layers of several stores into one.
   doctor    Check that a store works: credentials, listing, writing, and what it holds.
   policy    Print the least-privilege IAM policy for publishers, readers, or both.
@@ -103,8 +113,8 @@ export const REPORT_USAGE = `atlas report — layered evidence for any kind of s
                        { id, label?, store } (or a function returning it): a device lab, anything
                        that implements ObjectStore.
 
-  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose
-                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command
+  --format json (alias --json)   publish, stream, merge, doctor, status and verify-recordings print one JSON document instead of prose
+                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status, verify-recordings-result). A command
                        that is wrong is {"ok":false,"error":{"message":…,"code":"usage"}} on standard error.
   A store may be an Atlas server (https://…): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.
 
@@ -475,6 +485,46 @@ export async function reportMain(argv, io = { out: text => process.stdout.write(
         io.out(format === 'json' ? `${JSON.stringify(status, null, 2)}\n` : format === 'markdown' ? formatStatusMarkdown(status) : formatStatusText(status));
         return status.ok ? 0 : 1;
     }
+    if (command === 'verify-recordings') {
+        const format = value(rest, 'format') ?? (rest.includes('--json') ? 'json' : 'text');
+        if (!['text', 'json'].includes(format))
+            throw new Error(`--format takes text|json (got "${format}")`);
+        const ids = values(rest, 'layer');
+        const short = ids.find(id => !/^[0-9a-f]{7,64}$/i.test(id));
+        if (short)
+            throw new Error(`--layer takes at least 7 hexadecimal digits of a layer id (got "${short}")`);
+        const limitText = value(rest, 'limit');
+        if (limitText !== undefined && !/^\d+$/.test(limitText))
+            throw new Error(`--limit takes a whole number (got "${limitText}")`);
+        const include = layerFilter(rest, env);
+        let layers = 0, checked = 0, verified = 0, referenced = 0;
+        const gaps = [];
+        const notices = [];
+        for (const backend of await backendsOf(rest, base, env)) {
+            const found = await verifyStoreRecordings(backend.store, { ids, ...(limitText !== undefined ? { limit: Number(limitText) } : {}), ...(include ? { include } : {}) });
+            for (const layer of found.layers) {
+                layers += 1;
+                checked += layer.checked;
+                verified += layer.ok;
+                referenced += layer.referenced;
+                gaps.push(...layer.gaps.map(gap => ({ ...gap, layer: layer.layer })));
+            }
+            notices.push(...found.notices);
+        }
+        const ok = gaps.length === 0 && notices.length === 0;
+        if (format === 'json') {
+            io.out(`${JSON.stringify({ ok, layers, checked, verified, referenced, gaps, notices }, null, 2)}\n`);
+            return ok ? 0 : 1;
+        }
+        io.out(`Recordings in ${layers} layer${layers === 1 ? '' : 's'}: ${verified} of ${checked} stored video${checked === 1 ? '' : 's'} verified${referenced ? `, ${referenced} given by address (not checked)` : ''}\n`);
+        for (const gap of gaps)
+            io.out(`! ${gap.problem}: ${gap.check ?? 'the run'} / ${gap.name} in layer ${gap.layer.slice(0, 12)} (${gap.reason})\n`);
+        for (const notice of notices)
+            io.out(`! ${notice}\n`);
+        if (!ok)
+            io.out('Test results are unchanged. Publish the missing recordings again to repair the gaps.\n');
+        return ok ? 0 : 1;
+    }
     if (command === 'merge') {
         const into = value(rest, 'into');
         if (!into)

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

@@ -1,6 +1,7 @@
 import { type ArtifactFilter, type FilterFields, type FilterName, type QueryFacets } from './artifact-query.js';
 import type { EvidenceMeasurement, EvidenceStatus, SpecEntry } from './explorer-types.js';
 import type { EvidenceSummary, LayerEvidence, LayerHeader, LayerRow, StatusCounts, VideoCounts, VideoRef } from './evidence-types.js';
+import { type RunRecordings } from './recording-receipt.js';
 import { RecordedSpecs } from './recorded-specs.js';
 /** The version of the documents this module writes (`TestCatalog`, `TestHistoryDocument`, `RunList`, `RunDetail`). Only optional fields are added within it. */
 export declare const TEST_CATALOG_VERSION = 1;
@@ -287,6 +288,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;
+    /**
+     * Whether the recordings its layers expected were published, apart from its outcomes (see `runRecordings`). Absent when
+     * none of its layers declared a recording expectation: its completeness is unknown, never complete. Never changes a status.
+     */
+    readonly recordings?: RunRecordings;
     /**
      * 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.
@@ -556,7 +562,7 @@ export declare function fieldsOfRun(run: RunSummary): FilterFields;
  * list.results.map(r => [r.title, r.run, r.sha, r.status]);
  * ```
  */
-export declare function artifactList(history: TestHistory, version: string, query?: ArtifactFilter, page?: {
+export declare function artifactList(history: TestHistory, version: string, asked?: ArtifactFilter, page?: {
     readonly limit?: number;
     readonly offset?: number;
     readonly domainOf?: (specPath: string) => string | undefined;