@crvouga/atlas 1.16.0 → 1.18.0

package/dist/schema/src/cli-results.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module Command results (`--format json`)
  *
- * What `atlas report publish`, `stream`, `merge` and `doctor` print on standard output with `--format json` (alias
+ * What `atlas report publish`, `stream`, `merge`, `doctor` and `verify-recordings` print on standard output with `--format json` (alias
  * `--json`), and what any `atlas` command prints on standard error for a command that was wrong: one JSON document,
  * so an agent or a script never has to parse prose. (`status` and `policy` already print documents:
  * `ReportStatusSchema`, and an IAM policy.) Each is also published as a JSON Schema.
@@ -152,6 +152,36 @@ export declare const DoctorResultSchema: z.ZodObject<{
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
+/** A published video that could not be read back from the store as published (see `atlas report verify-recordings`). */
+export declare const RecordingGapSchema: z.ZodObject<{
+    layer: z.ZodString;
+    check: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    bundleKey: z.ZodString;
+    problem: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$loose>;
+/**
+ * What `atlas report verify-recordings --format json` prints: whether the videos the layers published can still be read
+ * back from the store as they were published. It describes stored bytes, never playback in a browser, and it never changes
+ * a check\'s result.
+ */
+export declare const VerifyRecordingsResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    layers: z.ZodNumber;
+    checked: z.ZodNumber;
+    verified: z.ZodNumber;
+    referenced: z.ZodNumber;
+    gaps: z.ZodArray<z.ZodObject<{
+        layer: z.ZodString;
+        check: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        bundleKey: z.ZodString;
+        problem: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$loose>>;
+    notices: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
 /** What any `atlas` command prints on standard error, with `--format json`, when the command itself was wrong (exit code 2). */
 export declare const CommandErrorSchema: z.ZodObject<{
     ok: z.ZodLiteral<false>;
@@ -532,6 +562,26 @@ export declare const CLI_RESULTS: {
             }, z.core.$loose>>;
         }, z.core.$loose>;
     };
+    readonly verifyRecordings: {
+        readonly command: "atlas report verify-recordings";
+        readonly schemaName: "verify-recordings-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodBoolean;
+            layers: z.ZodNumber;
+            checked: z.ZodNumber;
+            verified: z.ZodNumber;
+            referenced: z.ZodNumber;
+            gaps: z.ZodArray<z.ZodObject<{
+                layer: z.ZodString;
+                check: z.ZodNullable<z.ZodString>;
+                name: z.ZodString;
+                bundleKey: z.ZodString;
+                problem: z.ZodString;
+                reason: z.ZodString;
+            }, z.core.$loose>>;
+            notices: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    };
     readonly error: {
         readonly command: "a command that was wrong (standard error)";
         readonly schemaName: "command-error";

package/dist/schema/src/cli-results.js

@@ -1,7 +1,7 @@
 /**
  * @module Command results (`--format json`)
  *
- * What `atlas report publish`, `stream`, `merge` and `doctor` print on standard output with `--format json` (alias
+ * What `atlas report publish`, `stream`, `merge`, `doctor` and `verify-recordings` print on standard output with `--format json` (alias
  * `--json`), and what any `atlas` command prints on standard error for a command that was wrong: one JSON document,
  * so an agent or a script never has to parse prose. (`status` and `policy` already print documents:
  * `ReportStatusSchema`, and an IAM policy.) Each is also published as a JSON Schema.
@@ -75,6 +75,29 @@ export const DoctorResultSchema = z.looseObject({
     ok: z.boolean().describe('True when every check of every store passed (otherwise the exit code is 1)'),
     stores: z.array(z.looseObject({ id: z.string(), checks: z.array(DoctorCheckSchema) }))
 });
+/** A published video that could not be read back from the store as published (see `atlas report verify-recordings`). */
+export const RecordingGapSchema = z.looseObject({
+    layer: z.string().describe('The layer that holds the video'),
+    check: z.string().nullable().describe('The check that holds it, or null for a video attached to the layer or a part'),
+    name: z.string().describe('The attachment\'s name'),
+    bundleKey: z.string().describe('Its key in the layer\'s bundle (`attachments/<sha256>`)'),
+    problem: z.string().describe('`not-in-bundle` (the layer names a file its bundle does not list), `blob-missing` (a blob holding it is gone: a 404 when played), `unreadable` (the store could not be read: not proof it is gone), `size-mismatch`, `checksum-mismatch` or `undecodable` (empty, or not the container its media type names). An open vocabulary: treat an unknown problem as a gap'),
+    reason: z.string().describe('A short explanation without tokens, paths or payload')
+});
+/**
+ * What `atlas report verify-recordings --format json` prints: whether the videos the layers published can still be read
+ * back from the store as they were published. It describes stored bytes, never playback in a browser, and it never changes
+ * a check\'s result.
+ */
+export const VerifyRecordingsResultSchema = z.looseObject({
+    ok: z.boolean().describe('True when no layer has a gap and every layer could be read (otherwise the exit code is 1). Test results are unaffected either way'),
+    layers: z.number().int().nonnegative().describe('Layers examined'),
+    checked: z.number().int().nonnegative().describe('Videos read back from the store (those that name a bundle key)'),
+    verified: z.number().int().nonnegative().describe('Of those, the ones that passed every check'),
+    referenced: z.number().int().nonnegative().describe('Videos given only by address, which Atlas holds no bytes for and does not check'),
+    gaps: z.array(RecordingGapSchema).describe('Every video that is missing, unreadable, corrupt or not the container it claims. Re-publish the layer\'s recordings to repair them'),
+    notices: z.array(z.string()).describe('Layers that could not be read at all: their recordings are unknown, never verified')
+});
 /** What any `atlas` command prints on standard error, with `--format json`, when the command itself was wrong (exit code 2). */
 export const CommandErrorSchema = z.looseObject({
     ok: z.literal(false),
@@ -142,5 +165,6 @@ export const CLI_RESULTS = {
     merge: { command: 'atlas report merge', schemaName: 'merge-result', schema: MergeResultSchema },
     doctor: { command: 'atlas report doctor', schemaName: 'doctor-result', schema: DoctorResultSchema },
     status: { command: 'atlas report status', schemaName: 'report-status', schema: ReportStatusSchema },
+    verifyRecordings: { command: 'atlas report verify-recordings', schemaName: 'verify-recordings-result', schema: VerifyRecordingsResultSchema },
     error: { command: 'a command that was wrong (standard error)', schemaName: 'command-error', schema: CommandErrorSchema }
 };

package/dist/server/src/openapi.js

@@ -427,6 +427,7 @@ const BASE_OPERATIONS = [
             { name: 'branch', in: 'query', description: 'Branches.', schema: str },
             { name: 'sha', in: 'query', description: 'Revisions: a full commit id or a prefix of at least seven characters.', schema: str },
             { name: 'outcome', in: 'query', description: 'Statuses: `passed`, `failed`, `running`, `not-run`. A run\'s outcome is `failed` when any result failed, else `running`, else `passed`, else `not-run`.', schema: str },
+            { name: 'recordings', in: 'query', description: 'Recording completeness of the run, apart from its outcome: `complete`, `incomplete`, `none-expected` or `unknown` (a run whose layers declared no recording expectations is `unknown`, never `complete`). Repeatable or comma-separated. Answered from the layers\' receipts; no recording is read. A server that does not know it ignores it and does not name it in `filters`.', schema: str },
             { name: 'q', in: 'query', description: 'Words that must all appear in the title, id, spec, branch, producer, environment, tags or labels.', schema: str },
             { name: 'since', in: 'query', description: 'Only records at or after this time: epoch milliseconds or an ISO date (a date alone is UTC). A result\'s recording time; a run\'s end.', schema: str },
             { name: 'until', in: 'query', description: 'Only records at or before this time (same forms as `since`).', schema: str },

package/docs/agents.md

@@ -163,6 +163,7 @@ JSON Schema (`@crvouga/atlas/schemas/<name>.schema.json`, draft 2020-12):
 | `atlas report merge` | `merge-result` |
 | `atlas report doctor` | `doctor-result` |
 | `atlas report status` | `report-status` |
+| `atlas report verify-recordings` | `verify-recordings-result` |
 | `a command that was wrong (standard error)` | `command-error` |
 <!-- /generated:json-command-schemas -->
 

package/docs/extending.md

@@ -30,7 +30,7 @@ carry any of these. Every one is optional.
 | `annotations[]` | Notes about the result: a warning, a deprecation, an accessibility finding, a coverage figure. |
 | `attempts[]` | Every try, when the check was retried. |
 | `tags[]` | Free labels to filter by: `smoke`, `payments`. |
-| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). `behavior-id` and `example-id` declare a stable id for the behavior and for one example of an outline, and `outline` names the outline; the [catalog health](server.md#reading-the-report-as-an-agent) report counts them and names an id shared by several checks. They never change which check a result belongs to. |
+| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release, and `published-at` and `enriched-at` (epoch milliseconds or an ISO date) to show when it was published or enriched apart from when the checks ran (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). `behavior-id` and `example-id` declare a stable id for the behavior and for one example of an outline, and `outline` names the outline; the [catalog health](server.md#reading-the-report-as-an-agent) report counts them and names an id shared by several checks. They never change which check a result belongs to. |
 | `scope{}` | What the evidence does and does not show: surface, device kind, synthetic data, scripted dependencies, audio, pacing, what was asserted and its limits. Unknown when absent. See [Evidence scope](rich-evidence.md#evidence-scope). |
 | `links[]` | Where to read more: the CI run, the issue, the trace client. |
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |

package/docs/reference/cli.md

@@ -105,6 +105,8 @@ atlas report — layered evidence for any kind of spec
                        [--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]
@@ -148,6 +150,13 @@ atlas report — layered evidence for any kind of spec
             --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.
@@ -156,8 +165,8 @@ atlas report — layered evidence for any kind of spec
                        { 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.
 

package/docs/reference/http-api.md

@@ -833,6 +833,7 @@ Every run, newest first: layers grouped by their CI run URL (else branch and com
 - `branch` (query): Branches.
 - `sha` (query): Revisions: a full commit id or a prefix of at least seven characters.
 - `outcome` (query): Statuses: `passed`, `failed`, `running`, `not-run`. A run's outcome is `failed` when any result failed, else `running`, else `passed`, else `not-run`.
+- `recordings` (query): Recording completeness of the run, apart from its outcome: `complete`, `incomplete`, `none-expected` or `unknown` (a run whose layers declared no recording expectations is `unknown`, never `complete`). Repeatable or comma-separated. Answered from the layers' receipts; no recording is read. A server that does not know it ignores it and does not name it in `filters`.
 - `q` (query): Words that must all appear in the title, id, spec, branch, producer, environment, tags or labels.
 - `since` (query): Only records at or after this time: epoch milliseconds or an ISO date (a date alone is UTC). A result's recording time; a run's end.
 - `until` (query): Only records at or before this time (same forms as `since`).
@@ -861,6 +862,7 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 - `branch` (query): Branches.
 - `sha` (query): Revisions: a full commit id or a prefix of at least seven characters.
 - `outcome` (query): Statuses: `passed`, `failed`, `running`, `not-run`. A run's outcome is `failed` when any result failed, else `running`, else `passed`, else `not-run`.
+- `recordings` (query): Recording completeness of the run, apart from its outcome: `complete`, `incomplete`, `none-expected` or `unknown` (a run whose layers declared no recording expectations is `unknown`, never `complete`). Repeatable or comma-separated. Answered from the layers' receipts; no recording is read. A server that does not know it ignores it and does not name it in `filters`.
 - `q` (query): Words that must all appear in the title, id, spec, branch, producer, environment, tags or labels.
 - `since` (query): Only records at or after this time: epoch milliseconds or an ISO date (a date alone is UTC). A result's recording time; a run's end.
 - `until` (query): Only records at or before this time (same forms as `since`).

package/docs/reference/reports.md

@@ -10,7 +10,7 @@ Source: `packages/reports/src/artifact-query.ts`. Import: `@crvouga/atlas/report
 
 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:
@@ -81,6 +81,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). */
@@ -124,6 +130,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;
 };
 ```
@@ -143,6 +151,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[];
 };
 ```
 
@@ -204,6 +214,14 @@ export function usedFilters(filter: ArtifactFilter): FilterName[]
 
 Which filters a query uses, by the names an address gives them.
 
+#### `forArtifacts`
+
+```ts
+export function forArtifacts(filter: ArtifactFilter): ArtifactFilter
+```
+
+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).
+
 #### `isFiltered`
 
 ```ts
@@ -218,7 +236,7 @@ Whether a query narrows anything.
 export function forRuns(filter: ArtifactFilter): ArtifactFilter
 ```
 
-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).
 
 #### `matchesFilter`
 
@@ -2161,6 +2179,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;
 };
@@ -2180,6 +2200,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;
 };
 ```
 
@@ -6408,6 +6430,160 @@ skipped or unresolved; otherwise `unknown` when a contributing layer has no rece
 report with no results at all is unknown too); otherwise `complete` when something was expected and `none-expected` when
 nothing was. Gaps are sorted so the output never depends on read order.
 
+#### `RunRecordings`
+
+```ts
+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;
+};
+```
+
+A run's recording completeness, from the receipts of its layers (see {@link runRecordings}).
+
+#### `runRecordings`
+
+```ts
+export function runRecordings(layers: readonly (RecordingCounts | undefined)[]): RunRecordings | undefined
+```
+
+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.
+
+### Recording verification
+
+Source: `packages/reports/src/recording-verify.ts`. Import: `@crvouga/atlas/reports/recording-verify`
+
+Answers "is the recording we published still there, and does it still look like the video we published?" apart from
+"did the tests pass?" and apart from "was it uploaded?" (the receipt, see `recording-receipt.ts`). `verifyLayerRecordings`
+reads each video a layer keeps in its bundle back from the store and checks, in order, that the layer's bundle still
+lists its file, that the blob it lives in is still stored, that its size and SHA-256 are the ones recorded at upload,
+and that its first bytes are the container header its media type promises. A problem is a gap in the evidence, named
+with the check that holds the video; it never changes a status, a slot or a winner.
+
+Trap: this is a stored-bytes check, not a playback test. A file with a valid header can still fail to play in a given
+browser (codec, truncation), and acknowledging an upload is not playback either. Videos given only by `uri` are counted
+as `referenced`, not checked: Atlas holds no bytes to read back.
+
+See docs/rich-evidence.md#recording-completeness
+
+#### `RecordingProblem`
+
+```ts
+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';
+```
+
+What is wrong with a stored recording. An open vocabulary: a reader treats an unknown problem as a gap.
+
+#### `RecordingGap`
+
+```ts
+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;
+};
+```
+
+One video of a layer that failed verification.
+
+#### `LayerRecordingVerification`
+
+```ts
+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[];
+};
+```
+
+What verifying one layer found.
+
+#### `containerProblem`
+
+```ts
+export function containerProblem(bytes: Uint8Array, contentType: string): string | null
+```
+
+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.
+
+#### `verifyLayerRecordings`
+
+```ts
+export async function verifyLayerRecordings(store: ObjectStore, layer: ReportLayer): Promise<LayerRecordingVerification>
+```
+
+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}`);
+```
+
+#### `StoreRecordingVerification`
+
+```ts
+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[];
+};
+```
+
+What verifying the layers of one store found.
+
+#### `verifyStoreRecordings`
+
+```ts
+export async function verifyStoreRecordings(store: ObjectStore, options: { readonly ids?: readonly string[]; readonly limit?: number; readonly include?: (layer: ReportLayer) => boolean } = {}): Promise<StoreRecordingVerification>
+```
+
+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.
+
 ### Reliability of a test
 
 Source: `packages/reports/src/reliability.ts`. Import: `@crvouga/atlas/reports/reliability`
@@ -6767,7 +6943,7 @@ Call this inside a Solid root: it creates signals and a store.
 
 Source: `packages/reports/src/report-cli.ts`. Import: `@crvouga/atlas/reports/report-cli`
 
-`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.
@@ -9578,6 +9754,17 @@ export const HISTORY_PER_TEST = …
 
 Recorded results kept per test, newest first. Older ones are counted in no statistic.
 
+#### `APPLICABILITY_LABELS`
+
+```ts
+export const APPLICABILITY_LABELS = …
+```
+
+The open `labels` (see docs/extending.md) that say what a result's evidence ran against and who vouches for it: `build`,
+`platform`, `applies-to` (builds or commits it is asserted to still hold for), `applies-to-by` (the policy or person that
+asserts it), `published-at` and `enriched-at` (when the evidence was published or enriched, epoch milliseconds or an ISO
+date: never when the checks ran). A test's current results carry them as `provenance`.
+
 #### `TestResultEntry`
 
 ```ts
@@ -9606,6 +9793,10 @@ export type TestResultEntry = {
   readonly detail: string;
   /** The fingerprint of its spec text the layer recorded, when it recorded one: results with different revisions were recorded against different promises. Absent means not recorded, never "the same". */
   readonly specRevision?: string;
+  /** `modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Absent for a clean checkout, and on results other than a test's current ones. Advisory; never changes a status. */
+  readonly freshness?: 'unknown' | 'modified';
+  /** The labels of its layer and check that say what it ran against and who vouches for it: only those named in {@link APPLICABILITY_LABELS}. Present on a test's current results when it has any. Read by the viewer's evidence applicability; never decides a result. */
+  readonly provenance?: Readonly<Record<string, string>>;
   /** What it carried beyond its outcome (attachments, steps, retries, tags, labels), when anything. */
   readonly evidence?: EvidenceSummary;
   /** Its product-latency measurements (`kind: product-latency`), when it recorded any. Separate from `durationMs`, which is how long the test took (setup, waits and pacing included). */
@@ -9680,6 +9871,8 @@ export type CatalogSpec = {
   /** The group it belongs to: the spec's own domain, else the folder under `specs/`. */
   readonly domain: string;
   readonly kind: string;
+  /** The fingerprint of the spec text now (the promise), when the spec set or a layer recorded one. A result's `specRevision` is compared with it: different means the promise changed after the result was recorded. Absent: unknown, never "the same". */
+  readonly fingerprint?: string;
 };
 ```
 
@@ -9925,14 +10118,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;
+  /**
+   * 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.
-   */
-  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. */
   …
 ```
 
@@ -10264,7 +10457,7 @@ What a query looks at in a run: see {@link ArtifactFilter}. A run's outcome is `
 #### `artifactList`
 
 ```ts
-export function artifactList(history: TestHistory, version: string, query: ArtifactFilter = {}, page: { readonly limit?: number; readonly offset?: number; readonly domainOf?: (specPath: string) => string | undefined } = {}): ArtifactList
+export function artifactList(history: TestHistory, version: string, asked: ArtifactFilter = {}, page: { readonly limit?: number; readonly offset?: number; readonly domainOf?: (specPath: string) => string | undefined } = {}): ArtifactList
 ```
 
 The recorded results that carry evidence and match a query, newest first, across the whole history (`limit` default

package/docs/reference/schema.md

@@ -535,7 +535,7 @@ of every layer. States are in id order and cells in profile order, so the same l
 
 Source: `packages/schema/src/cli-results.ts`
 
-What `atlas report publish`, `stream`, `merge` and `doctor` print on standard output with `--format json` (alias
+What `atlas report publish`, `stream`, `merge`, `doctor` and `verify-recordings` print on standard output with `--format json` (alias
 `--json`), and what any `atlas` command prints on standard error for a command that was wrong: one JSON document,
 so an agent or a script never has to parse prose. (`status` and `policy` already print documents:
 `ReportStatusSchema`, and an IAM policy.) Each is also published as a JSON Schema.
@@ -594,6 +594,24 @@ export const DoctorResultSchema = …
 
 What `atlas report doctor --format json` prints.
 
+#### `RecordingGapSchema`
+
+```ts
+export const RecordingGapSchema = …
+```
+
+A published video that could not be read back from the store as published (see `atlas report verify-recordings`).
+
+#### `VerifyRecordingsResultSchema`
+
+```ts
+export const VerifyRecordingsResultSchema = …
+```
+
+What `atlas report verify-recordings --format json` prints: whether the videos the layers published can still be read
+back from the store as they were published. It describes stored bytes, never playback in a browser, and it never changes
+a check\'s result.
+
 #### `CommandErrorSchema`
 
 ```ts

package/docs/rich-evidence.md

@@ -208,7 +208,8 @@ curl "$ATLAS_SERVER_URL/api/reports/artifacts?artifactTag=demo&type=video&domain
 - **Dimensions.** `artifactTag`, `type` (the media type as a role: `video`, `image`, `audio`, `snapshot`, `text`,
   `file`; `video` means a playable recording), `label` (`key=value`, or `key`), `domain` and `spec` (artifacts only),
   `environment` (the device or client), `producer`, `branch`, `sha` (seven or more characters), `outcome` (`passed`,
-  `failed`, `running`, `not-run`), `since` and `until` (epoch milliseconds or an ISO date), and `q` (words).
+  `failed`, `running`, `not-run`), `recordings` (runs only: `complete`, `incomplete`, `none-expected` or `unknown`, see
+  [recording completeness](#recording-completeness)), `since` and `until` (epoch milliseconds or an ISO date), and `q` (words).
 - **Semantics.** Filters combine with AND across dimensions and OR within one (`environment=ios,android`). With both
   `artifactTag` and `type`, one attachment must be both where the report says which video carries which tag: a tagged
   screenshot beside an untagged video is not a tagged video. `inherited=1` also counts the tags an attachment inherits
@@ -475,7 +476,33 @@ publish; it never contains a path or a token.
   retry (publishing again reuses the stored files).
 - `atlas report status --format json` has `recordings`: `state` is `complete`, `incomplete`, `none-expected` or
   `unknown`, with counts and each gap. It never changes `ok`. A layer without a receipt is `unknown`, never `complete`.
-- The viewer shows `Recordings 2 of 3: incomplete` beside the run's origin, apart from its green or red outcomes.
-
-This is a statement about publication. Atlas does not check that a stored video plays in a browser, and does not yet
-re-check later that a stored file is still readable.
+- The viewer shows `Recordings 2 of 3: incomplete` beside the run's origin and in each row of the Runs tab, apart from
+  its green or red outcomes.
+- **Find runs by completeness.** `GET /api/reports/runs?recordings=incomplete` (and the Runs tab's *Recordings* filter,
+  `?tab=runs&recordings=incomplete`) keep the runs whose layers have a skipped or unresolved expected recording. The
+  values are `complete`, `incomplete`, `none-expected` and `unknown`, comma-separated for OR, and they combine with the
+  other filters by AND. A run whose layers declared no expectations is `unknown`, never `complete`, and a run with any
+  layer without a receipt cannot be `complete`. It is answered from the layers' receipts, before the page limit, and
+  never reads a recording; the facet counts say how many runs have each state. It is a property of a run, so the
+  artifacts list does not take it. A server that predates it ignores the parameter and does not name it in `filters`, and
+  the viewer then says the list is not narrowed by it.
+
+### Is the recording still there?
+
+A receipt says a file was published. Whether it is still retrievable later is a separate question, and Atlas answers it
+two ways without touching a check's result:
+
+- **Layer bundle.** A video that names a `bundleKey` the layer's bundle does not list (the file was acknowledged and is
+  gone, or never arrived) is not offered to play. The report marks it `available: false` with `reason: "not-in-bundle"`,
+  the run counts it in `videos.unavailable` and `videos.missing`, and the Runs tab explains that the run stored the file
+  but no longer holds it, which is different from a reference that never named any bytes.
+- **`atlas report verify-recordings`** reads the videos of the stored layers back and checks, for each, that the bundle
+  lists it, that its blob is still in the store, that its size and SHA-256 are the recorded ones, and that it begins like
+  the container its media type names (WebM, MP4, QuickTime, Ogg, AVI). It exits 1 and names the layer and check for
+  every gap (`not-in-bundle`, `blob-missing`, `unreadable`, `size-mismatch`, `checksum-mismatch`, `undecodable`);
+  `--format json` prints the `verify-recordings-result` document. `--layer <id>` and `--limit <n>` narrow the work, since
+  it reads blobs. A store that cannot answer is `unreadable`, never verified. Test results are unchanged either way.
+
+Both are statements about stored bytes. Atlas does not check that a stored video plays in a given browser (a valid header
+can still have an unsupported codec or be truncated), and acknowledging an upload is not playback. Videos given only by
+`uri` are counted as referenced and not checked.

package/docs/server.md

@@ -410,7 +410,7 @@ with `format=markdown` (or `Accept: text/markdown`), and takes the project prefi
 | One test: every recorded result (status, duration, environment, branch, commit, CI run), newest first | `GET /api/reports/tests/history?key=<key>` |
 | How reliable one test is in a scope (environment, producer, parameters, branch, commit, spec revision, time window): independent executions, first-try and eventual success, what was left out and why | `GET /api/reports/tests/reliability?key=<key>&environment=phone` |
 | Why Specs, domains and counts disagree: ambiguous spec paths, shared domains, gaps, a reconciliation of the totals | `GET /api/reports/tests/health` |
-| The runs that recorded the report (by CI run URL, else branch and commit); `?video=true` keeps those with a playable video; `artifactTag`, `type`, `label`, `environment`, `branch`, `outcome`, `since`, `until` narrow it ([filtering](rich-evidence.md#finding-runs-and-artifacts)) | `GET /api/reports/runs` |
+| The runs that recorded the report (by CI run URL, else branch and commit); `?video=true` keeps those with a playable video; `artifactTag`, `type`, `label`, `environment`, `branch`, `outcome`, `recordings` (completeness of the recordings the run's layers expected), `since`, `until` narrow it ([filtering](rich-evidence.md#finding-runs-and-artifacts)) | `GET /api/reports/runs` |
 | Recorded results that carry evidence, across the whole history, found by tag, media type, label, feature, environment, branch, revision, outcome and time | `GET /api/reports/artifacts?artifactTag=demo&type=video` |
 | Every test one run recorded | `GET /api/reports/runs/detail?key=<run key>` |
 

package/docs/ui.md

@@ -91,6 +91,14 @@ when Watch is on screen.
   what they know with labels: `build`, `platform`, and `applies-to` with `applies-to-by` (the policy that asserts the
   evidence still holds for those builds; without it the assertion is refused). The "Stale or unverified" filter
   (`evidence=stale`) lists every behavior whose evidence does not apply, including those with none.
+- The test explorer makes the same reading of every test from the catalog (`explorer/applicability.ts`): the catalog
+  carries the spec's fingerprint now (`spec.fingerprint`) and, on each current result, `specRevision`, `freshness` and
+  `provenance` (the labels above), all optional. The same address names (`release`, `releaseSha`, `releasePlatform`,
+  `evidence=stale`) give the "Stale or unverified" button, the "Stale evidence first" sort, a verdict badge on rows
+  (stale always; unknown or none when a release is named or evidence is filtered or sorted), and the summary in test
+  detail. Layers carry no publication time, because a layer's id is the digest of its content and a time of upload in
+  it would make a retried publish a different layer: a producer that knows states `published-at` and `enriched-at`
+  labels, shown apart from "Checks ran", which alone is the age.
 - 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