@crvouga/atlas 1.17.0 → 1.19.0

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,12 @@ 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';
+  /** How long the recording is, in milliseconds, as its producer declared (`Attachment.durationMs`): a hint to show before the file is opened, never measured here and never a latency. Absent when none was declared, and in documents of older servers. */
+  readonly durationMs?: number;
+  /** The bundle key, in the same layer, of the image the producer named as this recording's poster (`Attachment.poster`): a hint to show before the file is opened. Only an image the layer's bundle holds; absent when there is none, and in documents of older servers. */
+  readonly poster?: string;
   /** 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 +2204,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 +6434,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 +6947,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 +10122,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 +10461,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

@@ -27,6 +27,7 @@ decided exactly as before ([the report contract](report-contract.md)). Evidence
 | `attempts` | check | Every try of a retried check, with its own status, detail, steps and attachments. A check that passed after failing is flaky. |
 | `tags`, `labels` | check, layer | Filters and groups (`smoke`, `flaky`, an owner, a browser). |
 | `tags` | attachment | Marks one recording or screenshot, for example `demo`: shown as a `#demo` chip, and searchable. See [Tagging artifacts and demos](#tagging-artifacts-and-demos). |
+| `poster` (the `id` of an image in the same list) and `durationMs` | attachment (video) | Shown beside the recording in a watch playlist before anything is opened: the report carries them as the optional `poster` (a bundle key) and `durationMs` of each video reference, so no evidence is read per entry. Neither is ever a latency. |
 | `extensions['atlas.media']` | attachment (video) | Where the check's steps are in the recording, so a click on a step seeks the video. See [Place steps in a recording](#place-steps-in-a-recording). |
 | `scope` | attachment, attempt, check, part, layer | What a recording does and does not show: where it ran, whether data and dependencies were real, whether audio was captured. See [Evidence scope](#evidence-scope). |
 | `annotations`, `links` | check, step, attempt, layer | Notes, warnings and issue links next to the result. |
@@ -208,7 +209,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 +477,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

@@ -104,6 +104,37 @@ when Watch is on screen.
 - The spec index searches titles, paths and declared domains, and can group by the domain from spec metadata (specs with
   none are listed under "No domain declared"; the Tests view reports domain problems).
 
+## Behaviors across the project
+
+`/behaviors` (`evidence/behaviors-page.tsx`, **Behaviors** in the spec-type menu) lists every behavior of every Gherkin feature in one
+place, so the question "what does this product promise?" needs no knowledge of which file holds the answer. It adds no source of
+truth: `evidence/behavior-index.ts` reads each feature through the same `featureBehaviors` the feature page uses, so a behavior has the
+same coverage state, revisions and recording in both.
+
+- The list is searched with the shared matcher (`find/`: words, quoted phrases, `status:`, `domain:`, `tag:`, `has:video`), grouped by
+  the domain spec metadata declares ("No domain declared" when it declares none), or ranked best match first when words are typed.
+  A coverage state is a filter with its own count; `demonstrated` is always named. A long list is bounded with *Show more*.
+- Features whose text has not arrived are counted ("3 of 12 read"), and features that cannot be parsed are named, so an empty answer is
+  never taken for "no such behavior" while it is still incomplete.
+- The search words (`q`), the coverage filter (`coverage`), the selection (`behavior`) and the expanded state (`workspace`) are in the
+  address. Selecting shows the Read / Watch / Inspect panel beside the list (below it on narrow screens), and *Read and watch* in the
+  selected-behavior bar is reachable before the list in keyboard order.
+- **Read and watch workspace.** Expanding a behavior replaces the index with a page that uses the width: a two-column
+  `SimpleGrid` (one column below `md`) with *What should happen* (the steps, an outline's example filled in) beside *Recording* (the
+  player, status and provenance, promise and evidence revisions, applicability), the scoped summary below, and Inspect behind a
+  disclosure that reads the technical record only when opened. Keyboard focus moves to the behavior's heading on arrival, and
+  *Previous behavior* / *Next behavior* move through the same search. A recording is labelled illustrative.
+- **Returning** from the workspace restores the search words, the filter and the selection from the address, and the scroll position,
+  the number of rows shown and the focused row from `evidence/behavior-return.ts`, which remembers them for the session against the
+  scope they were taken in and gives them back once, only to that scope. Storage that is unavailable means the list opens at its top.
+- **Scoped summary** (`evidence/scoped-summary.ts`, `scoped-summary-view.tsx`, on Watch and in the workspace) answers three questions
+  apart, for the check in the environment of the recording shown (environments are not pooled; with none named it says they are):
+  the **outcome** of the shown result (`outcomeHeadline`), **reliability** (`reports/reliability`: always with the independent
+  executions it rests on, "Insufficient evidence" below the minimum, first-try success only from recorded tries, the library's
+  warnings) and **performance** (`reports/latency`: only measurements named `product-latency`, percentiles withheld with the reason,
+  budget and breaches). Absent evidence is stated as unknown, never as good; the test's duration is not product latency, and the
+  summary says it describes the checks Atlas holds, not production. The full reliability and latency detail is one link away.
+
 ## Catalog health
 
 The **Catalog health** tab (`explorer/HealthView.tsx`, `?tab=health`; `@crvouga/atlas/reports/catalog-health`) explains why the Specs
@@ -209,7 +240,14 @@ over the same filtered set the page lists, in the same order (`explorer/playlist
   demonstrated. A set longer than the page's limit says it is only the newest results.
 - Only the selected clip is read: the list is the metadata the catalog already sent, the selected result's evidence is read
   when it is selected, and the one `<video>` uses `preload="metadata"`. Opening the playlist downloads no recordings in bulk.
-  Posters and durations of unselected entries are not shown for that reason.
+  An unselected entry still shows a poster and a length when the catalog already carries them: the producer's declared
+  `Attachment.durationMs` and `Attachment.poster` (an image of the same list that the layer's bundle holds) travel as the
+  optional `durationMs` and `poster` of the result's video reference. The poster is an `<img loading="lazy">`, fetched when
+  its row nears the screen; an entry whose producer declared neither shows neither, and nothing is read to find out.
+- The open playlist is in the address (`watch=true`, and `watchClip` for the entry playing), so a link restores it over
+  the same filters, run or collection. Opening it adds a history entry (Back closes it); moving between clips and closing
+  it replace the current one. A `watchClip` the set no longer holds opens the first watchable entry and the address then
+  names that one.
 - One player: selecting another clip replaces it, and the position of the clip left is kept for the session so returning
   resumes there. Previous/next and advancing on end move over the watchable entries; a result with nothing to play is
   selected from the list to read why.
@@ -350,6 +388,7 @@ The narrowly scoped exceptions are:
 | Project home | Tests/runs/artifacts/compare/catalog health tabs, a two-run comparison with promise, outcome, recording and figure tabs per behavior, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion, Modal, Grid, Switch |
 | Test detail | Current outcomes, statistics, duration graph, product latency with budgets and baselines, history, artifacts, recording; the `layer` address parameter pins it to one run's result, labelled "This run" against "Latest combined evidence" | Drawer, Table, Badge, Alert, Stage |
 | Specs | All six existing kinds, overview/index with title search and folder or declared-domain grouping, Gherkin rules/scenarios/examples with a coverage summary and Read / Watch / Inspect per behavior, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Tabs, Table, CodeHighlightTabs, ResultRow |
+| Behaviors | Project-wide behavior index with search, coverage filters and a selected behavior's Read / Watch / Inspect; an expanded read-and-watch workspace with a scoped outcome, reliability and performance summary that restores scope, scroll, selection and focus on return | Container, Grid, SimpleGrid, NavLink, TextInput, Button, Paper, Accordion, Tabs |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
 | Recordings | Pictures/video/timeline, actor selection, moments, failure jumps, timing, model-state differences | Tabs, Slider, Button, ScrollArea, Table, Progress |