@crvouga/atlas 1.17.0 → 1.18.0

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.
@@ -9942,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. */
   …
 ```
 
@@ -10281,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/llms-full.txt

@@ -172,6 +172,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 -->
 
@@ -1196,7 +1197,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
@@ -1463,10 +1465,36 @@ 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.
 </doc>
 
 <doc path="docs/ui-catalog.md">
@@ -2058,7 +2086,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>` |
 
@@ -5252,6 +5280,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]
@@ -5295,6 +5325,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.
@@ -5303,8 +5340,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.
 
@@ -6148,6 +6185,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`).
@@ -6176,6 +6214,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",

package/packages/schema/schemas/effective-delta.schema.json

@@ -264,6 +264,10 @@
                             "type": "boolean",
                             "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                           },
+                          "reason": {
+                            "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                            "type": "string"
+                          },
                           "scope": {
                             "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
                             "type": "object",
@@ -743,6 +747,10 @@
                           "type": "boolean",
                           "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                         },
+                        "reason": {
+                          "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                          "type": "string"
+                        },
                         "scope": {
                           "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
                           "type": "object",

package/packages/schema/schemas/effective-evidence.schema.json

@@ -264,6 +264,10 @@
                             "type": "boolean",
                             "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                           },
+                          "reason": {
+                            "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                            "type": "string"
+                          },
                           "scope": {
                             "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
                             "type": "object",
@@ -743,6 +747,10 @@
                           "type": "boolean",
                           "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                         },
+                        "reason": {
+                          "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                          "type": "string"
+                        },
                         "scope": {
                           "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
                           "type": "object",

package/packages/schema/schemas/evidence-page.schema.json

@@ -251,6 +251,10 @@
                       "type": "boolean",
                       "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
+                    "reason": {
+                      "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                      "type": "string"
+                    },
                     "scope": {
                       "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
                       "type": "object",

package/packages/schema/schemas/layer-rows.schema.json

@@ -255,6 +255,10 @@
                       "type": "boolean",
                       "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
+                    "reason": {
+                      "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                      "type": "string"
+                    },
                     "scope": {
                       "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
                       "type": "object",