@crvouga/atlas 1.17.0 → 1.19.0

package/llms-full.txt

@@ -172,6 +172,7 @@ JSON Schema (`@crvouga/atlas/schemas/<name>.schema.json`, draft 2020-12):
 | `atlas report merge` | `merge-result` |
 | `atlas report doctor` | `doctor-result` |
 | `atlas report status` | `report-status` |
+| `atlas report verify-recordings` | `verify-recordings-result` |
 | `a command that was wrong (standard error)` | `command-error` |
 <!-- /generated:json-command-schemas -->
 
@@ -1015,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. |
@@ -1196,7 +1198,8 @@ curl "$ATLAS_SERVER_URL/api/reports/artifacts?artifactTag=demo&type=video&domain
 - **Dimensions.** `artifactTag`, `type` (the media type as a role: `video`, `image`, `audio`, `snapshot`, `text`,
   `file`; `video` means a playable recording), `label` (`key=value`, or `key`), `domain` and `spec` (artifacts only),
   `environment` (the device or client), `producer`, `branch`, `sha` (seven or more characters), `outcome` (`passed`,
-  `failed`, `running`, `not-run`), `since` and `until` (epoch milliseconds or an ISO date), and `q` (words).
+  `failed`, `running`, `not-run`), `recordings` (runs only: `complete`, `incomplete`, `none-expected` or `unknown`, see
+  [recording completeness](#recording-completeness)), `since` and `until` (epoch milliseconds or an ISO date), and `q` (words).
 - **Semantics.** Filters combine with AND across dimensions and OR within one (`environment=ios,android`). With both
   `artifactTag` and `type`, one attachment must be both where the report says which video carries which tag: a tagged
   screenshot beside an untagged video is not a tagged video. `inherited=1` also counts the tags an attachment inherits
@@ -1463,10 +1466,36 @@ publish; it never contains a path or a token.
   retry (publishing again reuses the stored files).
 - `atlas report status --format json` has `recordings`: `state` is `complete`, `incomplete`, `none-expected` or
   `unknown`, with counts and each gap. It never changes `ok`. A layer without a receipt is `unknown`, never `complete`.
-- The viewer shows `Recordings 2 of 3: incomplete` beside the run's origin, apart from its green or red outcomes.
-
-This is a statement about publication. Atlas does not check that a stored video plays in a browser, and does not yet
-re-check later that a stored file is still readable.
+- The viewer shows `Recordings 2 of 3: incomplete` beside the run's origin and in each row of the Runs tab, apart from
+  its green or red outcomes.
+- **Find runs by completeness.** `GET /api/reports/runs?recordings=incomplete` (and the Runs tab's *Recordings* filter,
+  `?tab=runs&recordings=incomplete`) keep the runs whose layers have a skipped or unresolved expected recording. The
+  values are `complete`, `incomplete`, `none-expected` and `unknown`, comma-separated for OR, and they combine with the
+  other filters by AND. A run whose layers declared no expectations is `unknown`, never `complete`, and a run with any
+  layer without a receipt cannot be `complete`. It is answered from the layers' receipts, before the page limit, and
+  never reads a recording; the facet counts say how many runs have each state. It is a property of a run, so the
+  artifacts list does not take it. A server that predates it ignores the parameter and does not name it in `filters`, and
+  the viewer then says the list is not narrowed by it.
+
+### Is the recording still there?
+
+A receipt says a file was published. Whether it is still retrievable later is a separate question, and Atlas answers it
+two ways without touching a check's result:
+
+- **Layer bundle.** A video that names a `bundleKey` the layer's bundle does not list (the file was acknowledged and is
+  gone, or never arrived) is not offered to play. The report marks it `available: false` with `reason: "not-in-bundle"`,
+  the run counts it in `videos.unavailable` and `videos.missing`, and the Runs tab explains that the run stored the file
+  but no longer holds it, which is different from a reference that never named any bytes.
+- **`atlas report verify-recordings`** reads the videos of the stored layers back and checks, for each, that the bundle
+  lists it, that its blob is still in the store, that its size and SHA-256 are the recorded ones, and that it begins like
+  the container its media type names (WebM, MP4, QuickTime, Ogg, AVI). It exits 1 and names the layer and check for
+  every gap (`not-in-bundle`, `blob-missing`, `unreadable`, `size-mismatch`, `checksum-mismatch`, `undecodable`);
+  `--format json` prints the `verify-recordings-result` document. `--layer <id>` and `--limit <n>` narrow the work, since
+  it reads blobs. A store that cannot answer is `unreadable`, never verified. Test results are unchanged either way.
+
+Both are statements about stored bytes. Atlas does not check that a stored video plays in a given browser (a valid header
+can still have an unsupported codec or be truncated), and acknowledging an upload is not playback. Videos given only by
+`uri` are counted as referenced and not checked.
 </doc>
 
 <doc path="docs/ui-catalog.md">
@@ -2058,7 +2087,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>` |
 
@@ -4532,6 +4561,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
@@ -4637,7 +4697,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.
@@ -4778,6 +4845,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 |
@@ -5252,6 +5320,8 @@ atlas report — layered evidence for any kind of spec
                        [--specs <dir>] [--format text|json|markdown]
                        [--require-environments a,b] [--require-all-specs]
                        [--branch <name>]... [--ignore-modified]
+  atlas report verify-recordings [--store <dir|s3://…|id=url>]... [--backends <module>] [--layer <id>]...
+                       [--limit <n>] [--branch <name>]... [--ignore-modified] [--format text|json]
   atlas report merge   [--store …]... [--backends <module>] --into <dir|s3://…>
   atlas report doctor  [--store …]... [--role publisher|reader|both]
   atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]
@@ -5295,6 +5365,13 @@ atlas report — layered evidence for any kind of spec
             --require-all-specs    fail while any spec has no results
             --branch <name>        only layers recorded on this branch (repeatable)
             --ignore-modified      leave out layers from modified checkouts and unknown origins
+  verify-recordings   Read back the videos the layers published and check they are still there as published: the
+            layer still lists the file, its blob is still stored, its size and SHA-256 are the recorded ones, and it
+            begins like the container its media type names. Exit 1 when any video is missing, unreadable, corrupt or
+            not that container, naming the layer and check; test results are never changed. This checks stored bytes,
+            not playback in a browser. Videos given only by address are counted, not checked.
+            --layer <id>   only the layer whose id starts with this (repeatable; at least 7 digits)
+            --limit <n>    only the newest n layers
   merge     Copy the layers of several stores into one.
   doctor    Check that a store works: credentials, listing, writing, and what it holds.
   policy    Print the least-privilege IAM policy for publishers, readers, or both.
@@ -5303,8 +5380,8 @@ atlas report — layered evidence for any kind of spec
                        { id, label?, store } (or a function returning it): a device lab, anything
                        that implements ObjectStore.
 
-  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose
-                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command
+  --format json (alias --json)   publish, stream, merge, doctor, status and verify-recordings print one JSON document instead of prose
+                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status, verify-recordings-result). A command
                        that is wrong is {"ok":false,"error":{"message":…,"code":"usage"}} on standard error.
   A store may be an Atlas server (https://…): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.
 
@@ -6148,6 +6225,7 @@ Every run, newest first: layers grouped by their CI run URL (else branch and com
 - `branch` (query): Branches.
 - `sha` (query): Revisions: a full commit id or a prefix of at least seven characters.
 - `outcome` (query): Statuses: `passed`, `failed`, `running`, `not-run`. A run's outcome is `failed` when any result failed, else `running`, else `passed`, else `not-run`.
+- `recordings` (query): Recording completeness of the run, apart from its outcome: `complete`, `incomplete`, `none-expected` or `unknown` (a run whose layers declared no recording expectations is `unknown`, never `complete`). Repeatable or comma-separated. Answered from the layers' receipts; no recording is read. A server that does not know it ignores it and does not name it in `filters`.
 - `q` (query): Words that must all appear in the title, id, spec, branch, producer, environment, tags or labels.
 - `since` (query): Only records at or after this time: epoch milliseconds or an ISO date (a date alone is UTC). A result's recording time; a run's end.
 - `until` (query): Only records at or before this time (same forms as `since`).
@@ -6176,6 +6254,7 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 - `branch` (query): Branches.
 - `sha` (query): Revisions: a full commit id or a prefix of at least seven characters.
 - `outcome` (query): Statuses: `passed`, `failed`, `running`, `not-run`. A run's outcome is `failed` when any result failed, else `running`, else `passed`, else `not-run`.
+- `recordings` (query): Recording completeness of the run, apart from its outcome: `complete`, `incomplete`, `none-expected` or `unknown` (a run whose layers declared no recording expectations is `unknown`, never `complete`). Repeatable or comma-separated. Answered from the layers' receipts; no recording is read. A server that does not know it ignores it and does not name it in `filters`.
 - `q` (query): Words that must all appear in the title, id, spec, branch, producer, environment, tags or labels.
 - `since` (query): Only records at or after this time: epoch milliseconds or an ISO date (a date alone is UTC). A result's recording time; a run's end.
 - `until` (query): Only records at or before this time (same forms as `since`).

package/package.json

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

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

@@ -264,6 +264,19 @@
                             "type": "boolean",
                             "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                           },
+                          "reason": {
+                            "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                            "type": "string"
+                          },
+                          "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",
@@ -743,6 +756,19 @@
                           "type": "boolean",
                           "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                         },
+                        "reason": {
+                          "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                          "type": "string"
+                        },
+                        "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

@@ -264,6 +264,19 @@
                             "type": "boolean",
                             "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                           },
+                          "reason": {
+                            "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                            "type": "string"
+                          },
+                          "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",
@@ -743,6 +756,19 @@
                           "type": "boolean",
                           "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                         },
+                        "reason": {
+                          "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                          "type": "string"
+                        },
+                        "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

@@ -251,6 +251,19 @@
                       "type": "boolean",
                       "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
+                    "reason": {
+                      "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                      "type": "string"
+                    },
+                    "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

@@ -255,6 +255,19 @@
                       "type": "boolean",
                       "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
+                    "reason": {
+                      "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                      "type": "string"
+                    },
+                    "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

@@ -162,6 +162,12 @@
               "minimum": 0,
               "maximum": 9007199254740991,
               "description": "References that name no bytes, or bytes the layer does not hold"
+            },
+            "missing": {
+              "description": "Of `unavailable`, those that name a file the layer's bundle does not hold (stored, then gone). Absent when there are none",
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
             }
           },
           "required": [
@@ -171,6 +177,64 @@
           ],
           "additionalProperties": {}
         },
+        "recordings": {
+          "description": "Whether the recordings its layers expected were published, apart from its outcomes. Absent when no layer declared an expectation: its completeness is unknown, never complete. Matched by the `recordings` filter",
+          "type": "object",
+          "properties": {
+            "state": {
+              "type": "string",
+              "enum": [
+                "complete",
+                "incomplete",
+                "none-expected",
+                "unknown"
+              ],
+              "description": "`incomplete` when an expected recording was skipped or unresolved; else `unknown` when a layer declared no expectations; else `complete` when something was expected and `none-expected` when nothing was"
+            },
+            "expected": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "published": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991,
+              "description": "Of the expected recordings, uploaded or referenced by address"
+            },
+            "skipped": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "unresolved": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "notApplicable": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "layersWithoutReceipt": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991,
+              "description": "Layers of the run that declared no recording expectations: nothing is claimed for them"
+            }
+          },
+          "required": [
+            "state",
+            "expected",
+            "published",
+            "skipped",
+            "unresolved",
+            "notApplicable",
+            "layersWithoutReceipt"
+          ],
+          "additionalProperties": {}
+        },
         "attachments": {
           "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
           "type": "integer",
@@ -316,6 +380,19 @@
                   "type": "boolean",
                   "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                 },
+                "reason": {
+                  "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                  "type": "string"
+                },
+                "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",
@@ -517,6 +594,12 @@
                 "minimum": 0,
                 "maximum": 9007199254740991,
                 "description": "References that name no bytes, or bytes the layer does not hold"
+              },
+              "missing": {
+                "description": "Of `unavailable`, those that name a file the layer's bundle does not hold (stored, then gone). Absent when there are none",
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
               }
             },
             "required": [

package/packages/schema/schemas/report-runs.schema.json

@@ -170,6 +170,12 @@
                 "minimum": 0,
                 "maximum": 9007199254740991,
                 "description": "References that name no bytes, or bytes the layer does not hold"
+              },
+              "missing": {
+                "description": "Of `unavailable`, those that name a file the layer's bundle does not hold (stored, then gone). Absent when there are none",
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
               }
             },
             "required": [
@@ -179,6 +185,64 @@
             ],
             "additionalProperties": {}
           },
+          "recordings": {
+            "description": "Whether the recordings its layers expected were published, apart from its outcomes. Absent when no layer declared an expectation: its completeness is unknown, never complete. Matched by the `recordings` filter",
+            "type": "object",
+            "properties": {
+              "state": {
+                "type": "string",
+                "enum": [
+                  "complete",
+                  "incomplete",
+                  "none-expected",
+                  "unknown"
+                ],
+                "description": "`incomplete` when an expected recording was skipped or unresolved; else `unknown` when a layer declared no expectations; else `complete` when something was expected and `none-expected` when nothing was"
+              },
+              "expected": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "published": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Of the expected recordings, uploaded or referenced by address"
+              },
+              "skipped": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "unresolved": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "notApplicable": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "layersWithoutReceipt": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Layers of the run that declared no recording expectations: nothing is claimed for them"
+              }
+            },
+            "required": [
+              "state",
+              "expected",
+              "published",
+              "skipped",
+              "unresolved",
+              "notApplicable",
+              "layersWithoutReceipt"
+            ],
+            "additionalProperties": {}
+          },
           "attachments": {
             "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
             "type": "integer",
@@ -419,6 +483,28 @@
             ],
             "additionalProperties": {}
           }
+        },
+        "recordings": {
+          "description": "Only for runs: `complete`, `incomplete`, `none-expected` and `unknown` with how many runs have each. Absent on servers that predate the filter",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              },
+              "count": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "required": [
+              "value",
+              "count"
+            ],
+            "additionalProperties": {}
+          }
         }
       },
       "required": [

package/packages/schema/schemas/review-collection.schema.json

@@ -196,6 +196,19 @@
                       "type": "boolean",
                       "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
+                    "reason": {
+                      "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                      "type": "string"
+                    },
+                    "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/review-manifest.schema.json

@@ -221,6 +221,19 @@
                       "type": "boolean",
                       "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
+                    "reason": {
+                      "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                      "type": "string"
+                    },
+                    "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/test-catalog.schema.json

@@ -1003,6 +1003,19 @@
                             "type": "boolean",
                             "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                           },
+                          "reason": {
+                            "description": "Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable",
+                            "type": "string"
+                          },
+                          "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",