@crvouga/atlas 1.18.0 → 1.20.0

package/docs/reference/http-api.md

@@ -694,6 +694,58 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `201` The recorded entry.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `413` Request too large.; `422` Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.
 
+### Which stored recordings the server last read back, and which were gone or damaged
+
+`GET /api/reports/recordings/verification` · role: read
+
+The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run's recordings as stored-then-unavailable beside its test results.
+
+This route never reads a blob: it returns what a publish token's `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server's memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).
+
+- `run` (query): Only layers of this run (a key from `GET /api/reports/runs`).
+- `layer` (query): Only layers whose id starts with this prefix. Repeatable or comma-separated.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The held read-backs.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Which stored recordings the server last read back, and which were gone or damaged
+
+`GET /api/projects/{project}/reports/recordings/verification` · role: read
+
+The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run's recordings as stored-then-unavailable beside its test results.
+
+This route never reads a blob: it returns what a publish token's `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server's memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `run` (query): Only layers of this run (a key from `GET /api/reports/runs`).
+- `layer` (query): Only layers whose id starts with this prefix. Repeatable or comma-separated.
+
+Responses: `200` The held read-backs.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Read stored recordings back and check them (publish token)
+
+`POST /api/reports/recordings/verification` · role: publish
+
+Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type's container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.
+
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The read-backs now held.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` A read-back is already running.; `413` Request too large.; `422` Not a verification request.; `502` A store could not be read.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Read stored recordings back and check them (publish token)
+
+`POST /api/projects/{project}/reports/recordings/verification` · role: publish
+
+Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type's container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The read-backs now held.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` A read-back is already running.; `413` Request too large.; `422` Not a verification request.; `502` A store could not be read.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
 ### Review collections: curated sets of recordings, newest first
 
 `GET /api/reports/review-collections` · role: read

package/docs/reference/reports.md

@@ -2181,6 +2181,10 @@ export type VideoRef = {
   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;
 };

package/docs/reference/schema.md

@@ -233,6 +233,47 @@ export const ArtifactTagsSchema = …
 
 `GET /api/reports/artifact-tags`: every recorded edit, oldest first. Fold them with `foldArtifactTags`.
 
+#### `StoredRecordingGapSchema`
+
+```ts
+export const StoredRecordingGapSchema = …
+```
+
+One stored video that failed the server's read-back: which check holds it and what is wrong with it.
+
+#### `LayerRecordingCheckSchema`
+
+```ts
+export const LayerRecordingCheckSchema = …
+```
+
+What reading back the stored videos of one layer found.
+
+#### `RecordingVerificationSchema`
+
+```ts
+export const RecordingVerificationSchema = …
+```
+
+`GET` and `POST /api/reports/recordings/verification`: the newest read-back the server did of stored videos, per layer.
+A layer that was never read back is absent, which means "not verified", never "fine".
+
+#### `RecordingVerification`
+
+```ts
+export type RecordingVerification = z.infer<typeof RecordingVerificationSchema>;
+```
+
+The document of {@link RecordingVerificationSchema}, as a type.
+
+#### `RecordingVerifyRequestSchema`
+
+```ts
+export const RecordingVerifyRequestSchema = …
+```
+
+The body of `POST /api/reports/recordings/verification`. Both fields are optional; an empty body reads back the newest layers.
+
 #### `ReviewSourceSchema`
 
 ```ts

package/docs/reference/server.md

@@ -627,6 +627,45 @@ export function projectServer(options: AtlasServerOptions, create: (options: Atl
 
 Wrap the single-project protocol in project selection. Auth, upload validation and composition stay identical.
 
+### Recording verification routes
+
+Source: `packages/server/src/recording-verification.ts`
+
+`/api/reports/recordings/verification`: whether the videos a run published can still be read back from storage as
+they were published, apart from whether the run's tests passed. A viewer reads the newest result with a read token
+(`GET`, which never touches a blob). A publish token starts a read-back (`POST`), which does read blobs and so is
+bounded: the newest 20 layers unless asked for more, at most 200, one pass at a time. The result is kept in this
+process only (it is derived, not state: a restart means "not verified yet", never "fine"), and only for layers the
+store still holds. It adds nothing to any layer and changes no status, slot or winner. This is the same check as
+`atlas report verify-recordings`, and as that command it checks stored bytes, not browser playback.
+
+See docs/rich-evidence.md#recording-completeness
+
+#### `RecordingVerificationDeps`
+
+```ts
+export type RecordingVerificationDeps = {
+  /** Every backend's store: a layer is read back from the store that holds it. */
+  readonly stores: readonly ObjectStore[];
+  readonly auth: Auth;
+  readonly index: ReportIndex;
+  readonly now: () => number;
+  readonly unauthorized: (verdict: Extract<ReturnType<Auth['check']>, { ok: false }>) => Response;
+};
+```
+
+What the verification routes need from the server around them.
+
+#### `mountRecordingVerification`
+
+```ts
+export function mountRecordingVerification(app: Hono, deps: RecordingVerificationDeps): void
+```
+
+Registers `GET` and `POST /api/reports/recordings/verification` on `app`. The result of the last read-back of each
+layer is held in memory, replaced by a newer one, and served only for layers a store still holds. A layer held by
+two backends keeps the reading with more gaps, so a copy that lost its blobs is never hidden by one that did not.
+
 ### Review collection routes
 
 Source: `packages/server/src/review-collections.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. |
@@ -503,6 +504,18 @@ two ways without touching a check's result:
   `--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.
 
+- **In the viewer.** A publish token starts the same read-back on the server with
+  `POST /api/reports/recordings/verification` (body optional: `{ "layers": ["<id prefix>"], "limit": 20 }`; the newest
+  20 layers by default, at most 200, one read-back at a time; a reader token, a browser sign-in box or an anonymous
+  caller is refused because it reads blobs). Anyone who can read the report then sees the result with
+  `GET /api/reports/recordings/verification` (which reads no blob): per layer, its run, how many videos were read back, how
+  many passed and each gap. The Runs tab and an opened run show `Recording unavailable: 1 of 3 stored videos failed the
+  read-back (1 file gone from storage)` beside the green outcomes, or `3 stored videos verified`, and a run whose stored
+  videos all failed offers no Watch action. A run whose layers were never read back shows nothing: unknown is not
+  verified. The result lives in the server's memory only, so a restart empties it, and a layer that garbage collection
+  removed drops out. An older server has no such route and the viewer then shows nothing. No status, slot or winner is
+  affected; `capabilities.recordingVerification` in `GET /api/server` says a server offers it.
+
 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

@@ -338,6 +338,14 @@ edit, and the server's time. Nothing about the layer, its results or the report'
 See [Tagging artifacts and demos](rich-evidence.md#tagging-artifacts-and-demos) for the tag rules. Reviewer tags are
 shown in the viewer's evidence; the tests API (`artifactTag`) searches the producers' tags.
 
+## Reading recordings back
+
+`POST /api/reports/recordings/verification` (publish, `Authorization: Bearer`) reads the stored videos of the newest layers
+back and checks them; `GET` (read) returns the newest result per layer without reading any blob, so the viewer can mark a
+run whose recording was stored and then lost, apart from its test results. The result is in memory only and layers
+that were never read back are absent (unknown, never "fine"). See
+[Is the recording still there?](rich-evidence.md#is-the-recording-still-there) for what is checked and what is not.
+
 ## Review collections
 
 A team can publish a named, curated review of a few behaviors: recordings from several explicit executions, notes on
@@ -517,6 +525,10 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `GET /api/projects/{project}/reports/artifact-tags` | read | Reviewer tags of attachments: every recorded edit. |
 | `POST /api/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
 | `POST /api/projects/{project}/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
+| `GET /api/reports/recordings/verification` | read | Which stored recordings the server last read back, and which were gone or damaged. |
+| `GET /api/projects/{project}/reports/recordings/verification` | read | Which stored recordings the server last read back, and which were gone or damaged. |
+| `POST /api/reports/recordings/verification` | publish | Read stored recordings back and check them (publish token). |
+| `POST /api/projects/{project}/reports/recordings/verification` | publish | Read stored recordings back and check them (publish token). |
 | `GET /api/reports/review-collections` | read | Review collections: curated sets of recordings, newest first. |
 | `GET /api/projects/{project}/reports/review-collections` | read | Review collections: curated sets of recordings, newest first. |
 | `POST /api/reports/review-collections` | publish | Publish an immutable review collection (or a new revision of one). |

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 |

package/llms-full.txt

@@ -1016,6 +1016,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. |
@@ -1492,6 +1493,18 @@ two ways without touching a check's result:
   `--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.
 
+- **In the viewer.** A publish token starts the same read-back on the server with
+  `POST /api/reports/recordings/verification` (body optional: `{ "layers": ["<id prefix>"], "limit": 20 }`; the newest
+  20 layers by default, at most 200, one read-back at a time; a reader token, a browser sign-in box or an anonymous
+  caller is refused because it reads blobs). Anyone who can read the report then sees the result with
+  `GET /api/reports/recordings/verification` (which reads no blob): per layer, its run, how many videos were read back, how
+  many passed and each gap. The Runs tab and an opened run show `Recording unavailable: 1 of 3 stored videos failed the
+  read-back (1 file gone from storage)` beside the green outcomes, or `3 stored videos verified`, and a run whose stored
+  videos all failed offers no Watch action. A run whose layers were never read back shows nothing: unknown is not
+  verified. The result lives in the server's memory only, so a restart empties it, and a layer that garbage collection
+  removed drops out. An older server has no such route and the viewer then shows nothing. No status, slot or winner is
+  affected; `capabilities.recordingVerification` in `GET /api/server` says a server offers it.
+
 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.
@@ -2014,6 +2027,14 @@ edit, and the server's time. Nothing about the layer, its results or the report'
 See [Tagging artifacts and demos](rich-evidence.md#tagging-artifacts-and-demos) for the tag rules. Reviewer tags are
 shown in the viewer's evidence; the tests API (`artifactTag`) searches the producers' tags.
 
+## Reading recordings back
+
+`POST /api/reports/recordings/verification` (publish, `Authorization: Bearer`) reads the stored videos of the newest layers
+back and checks them; `GET` (read) returns the newest result per layer without reading any blob, so the viewer can mark a
+run whose recording was stored and then lost, apart from its test results. The result is in memory only and layers
+that were never read back are absent (unknown, never "fine"). See
+[Is the recording still there?](rich-evidence.md#is-the-recording-still-there) for what is checked and what is not.
+
 ## Review collections
 
 A team can publish a named, curated review of a few behaviors: recordings from several explicit executions, notes on
@@ -2193,6 +2214,10 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `GET /api/projects/{project}/reports/artifact-tags` | read | Reviewer tags of attachments: every recorded edit. |
 | `POST /api/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
 | `POST /api/projects/{project}/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
+| `GET /api/reports/recordings/verification` | read | Which stored recordings the server last read back, and which were gone or damaged. |
+| `GET /api/projects/{project}/reports/recordings/verification` | read | Which stored recordings the server last read back, and which were gone or damaged. |
+| `POST /api/reports/recordings/verification` | publish | Read stored recordings back and check them (publish token). |
+| `POST /api/projects/{project}/reports/recordings/verification` | publish | Read stored recordings back and check them (publish token). |
 | `GET /api/reports/review-collections` | read | Review collections: curated sets of recordings, newest first. |
 | `GET /api/projects/{project}/reports/review-collections` | read | Review collections: curated sets of recordings, newest first. |
 | `POST /api/reports/review-collections` | publish | Publish an immutable review collection (or a new revision of one). |
@@ -4560,6 +4585,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
@@ -4665,7 +4721,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.
@@ -4806,6 +4869,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 |
@@ -6046,6 +6110,58 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `201` The recorded entry.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `413` Request too large.; `422` Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.
 
+### Which stored recordings the server last read back, and which were gone or damaged
+
+`GET /api/reports/recordings/verification` · role: read
+
+The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run's recordings as stored-then-unavailable beside its test results.
+
+This route never reads a blob: it returns what a publish token's `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server's memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).
+
+- `run` (query): Only layers of this run (a key from `GET /api/reports/runs`).
+- `layer` (query): Only layers whose id starts with this prefix. Repeatable or comma-separated.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The held read-backs.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Which stored recordings the server last read back, and which were gone or damaged
+
+`GET /api/projects/{project}/reports/recordings/verification` · role: read
+
+The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run's recordings as stored-then-unavailable beside its test results.
+
+This route never reads a blob: it returns what a publish token's `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server's memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `run` (query): Only layers of this run (a key from `GET /api/reports/runs`).
+- `layer` (query): Only layers whose id starts with this prefix. Repeatable or comma-separated.
+
+Responses: `200` The held read-backs.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Read stored recordings back and check them (publish token)
+
+`POST /api/reports/recordings/verification` · role: publish
+
+Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type's container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.
+
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The read-backs now held.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` A read-back is already running.; `413` Request too large.; `422` Not a verification request.; `502` A store could not be read.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Read stored recordings back and check them (publish token)
+
+`POST /api/projects/{project}/reports/recordings/verification` · role: publish
+
+Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type's container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The read-backs now held.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` A read-back is already running.; `413` Request too large.; `422` Not a verification request.; `502` A store could not be read.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
 ### Review collections: curated sets of recordings, newest first
 
 `GET /api/reports/review-collections` · role: read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.18.0",
+  "version": "1.20.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

@@ -268,6 +268,15 @@
                             "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"
                           },
+                          "durationMs": {
+                            "description": "How long the recording is, in milliseconds, as its producer declared it: a hint to show before the file is opened, never a latency. Absent when none was declared, and in documents of older servers",
+                            "type": "number",
+                            "minimum": 0
+                          },
+                          "poster": {
+                            "description": "The bundle key, in the same layer, of the image the producer named as this recording's poster: a hint to show before the file is opened. Absent when there is none or the layer's bundle does not hold it, and in documents of older servers",
+                            "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",
@@ -751,6 +760,15 @@
                           "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"
                         },
+                        "durationMs": {
+                          "description": "How long the recording is, in milliseconds, as its producer declared it: a hint to show before the file is opened, never a latency. Absent when none was declared, and in documents of older servers",
+                          "type": "number",
+                          "minimum": 0
+                        },
+                        "poster": {
+                          "description": "The bundle key, in the same layer, of the image the producer named as this recording's poster: a hint to show before the file is opened. Absent when there is none or the layer's bundle does not hold it, and in documents of older servers",
+                          "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

@@ -268,6 +268,15 @@
                             "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"
                           },
+                          "durationMs": {
+                            "description": "How long the recording is, in milliseconds, as its producer declared it: a hint to show before the file is opened, never a latency. Absent when none was declared, and in documents of older servers",
+                            "type": "number",
+                            "minimum": 0
+                          },
+                          "poster": {
+                            "description": "The bundle key, in the same layer, of the image the producer named as this recording's poster: a hint to show before the file is opened. Absent when there is none or the layer's bundle does not hold it, and in documents of older servers",
+                            "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",
@@ -751,6 +760,15 @@
                           "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"
                         },
+                        "durationMs": {
+                          "description": "How long the recording is, in milliseconds, as its producer declared it: a hint to show before the file is opened, never a latency. Absent when none was declared, and in documents of older servers",
+                          "type": "number",
+                          "minimum": 0
+                        },
+                        "poster": {
+                          "description": "The bundle key, in the same layer, of the image the producer named as this recording's poster: a hint to show before the file is opened. Absent when there is none or the layer's bundle does not hold it, and in documents of older servers",
+                          "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

@@ -255,6 +255,15 @@
                       "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"
                     },
+                    "durationMs": {
+                      "description": "How long the recording is, in milliseconds, as its producer declared it: a hint to show before the file is opened, never a latency. Absent when none was declared, and in documents of older servers",
+                      "type": "number",
+                      "minimum": 0
+                    },
+                    "poster": {
+                      "description": "The bundle key, in the same layer, of the image the producer named as this recording's poster: a hint to show before the file is opened. Absent when there is none or the layer's bundle does not hold it, and in documents of older servers",
+                      "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

@@ -259,6 +259,15 @@
                       "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"
                     },
+                    "durationMs": {
+                      "description": "How long the recording is, in milliseconds, as its producer declared it: a hint to show before the file is opened, never a latency. Absent when none was declared, and in documents of older servers",
+                      "type": "number",
+                      "minimum": 0
+                    },
+                    "poster": {
+                      "description": "The bundle key, in the same layer, of the image the producer named as this recording's poster: a hint to show before the file is opened. Absent when there is none or the layer's bundle does not hold it, and in documents of older servers",
+                      "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/report-run.schema.json

@@ -384,6 +384,15 @@
                   "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"
                 },
+                "durationMs": {
+                  "description": "How long the recording is, in milliseconds, as its producer declared it: a hint to show before the file is opened, never a latency. Absent when none was declared, and in documents of older servers",
+                  "type": "number",
+                  "minimum": 0
+                },
+                "poster": {
+                  "description": "The bundle key, in the same layer, of the image the producer named as this recording's poster: a hint to show before the file is opened. Absent when there is none or the layer's bundle does not hold it, and in documents of older servers",
+                  "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",