@crvouga/atlas 1.2.0 → 1.4.0

package/dist/schema/src/layer.js

@@ -88,6 +88,31 @@ export const MomentSchema = z.looseObject({
     step: z.string().optional().describe('The `id` of a step'),
     offsetMs: z.number().nonnegative().optional()
 });
+/**
+ * What a piece of evidence does and does not show, declared by the producer that made it: where it ran, whether its
+ * data and dependencies were real, whether audio was captured, how it was paced and which assertions the result
+ * stands on. Every field is optional and a field that is absent is unknown, never assumed live, physical or end to end.
+ *
+ * It is a declaration, not a finding: Atlas shows it as the producer's word, apart from the dimensions the producer
+ * names in `verified` (facts something independent checked). It describes evidence and never decides a status, a slot
+ * or a winner. The nearest declaration wins as a whole, never field by field: an attachment's `scope`, else its
+ * attempt's, else its check's, else its part's, else its layer's.
+ */
+export const EvidenceScopeSchema = z.looseObject({
+    surface: z.string().min(1).optional().describe('Where the product ran, in an open vocabulary: `browser`, `native-app`, `api`, `cli`…'),
+    deviceKind: z.string().min(1).optional().describe('What it ran on, in an open vocabulary: `simulator`, `emulator`, `physical`, `virtual-machine`, `desktop`… A simulator and a physical phone stay distinct values; they are filtered separately'),
+    syntheticData: z.boolean().optional().describe('True: the data was made up for the run. False: real data. Absent: unknown'),
+    dependencies: z.string().min(1).optional().describe('Whether what the product talks to was `scripted` (replies fixed in advance), `live` or `mixed`. An open vocabulary; absent is unknown'),
+    audioCaptured: z.boolean().optional().describe('True: the recording has real audio. False: it is silent. Absent: unknown'),
+    pacing: z.string().min(1).optional().describe('How time ran, in an open vocabulary: `paced` (slowed or scripted for a viewer), `real-time`. Absent: unknown'),
+    asserted: z.array(z.string()).optional().describe('The boundaries the result actually asserts. Activity visible in a recording beyond them is not verified behavior'),
+    limitations: z.array(z.string()).optional().describe('Known limits of what this evidence shows, in the producer\'s words'),
+    declaredBy: z.string().optional().describe('Who or what made this declaration: a tool, a team, a person'),
+    verified: z.array(z.string()).optional().describe('The names of the fields above (`surface`, `deviceKind`, `syntheticData`, `dependencies`, `audioCaptured`, `pacing`) that something independent of the producer checked. Every other field is only declared'),
+    verifiedBy: z.string().optional().describe('What checked the `verified` fields'),
+    provenance: z.array(LinkSchema).optional().describe('Where the declaration comes from and how to check it: a document, a CI step, a device log'),
+    extensions: ExtensionsSchema.optional()
+});
 /**
  * A file or a value that goes with a result: a screenshot, a video, a trace, a log, a DOM or accessibility
  * snapshot, a HAR, a coverage report, a diff, anything. `contentType` says how to read it; `role` says what
@@ -110,6 +135,7 @@ export const AttachmentSchema = z.looseObject({
     durationMs: z.number().nonnegative().optional().describe('For video and audio'),
     description: z.string().optional(),
     omitted: z.string().optional().describe('Why the producer did not include its bytes, in an open vocabulary: too-large, not-found, not-allowed, over-budget, policy… Present on a metadata-only attachment, so a reader can tell "left out" from "never recorded"'),
+    scope: EvidenceScopeSchema.optional().describe('What this one attachment (usually a recording) does and does not show. Overrides the scope of its attempt, check, part and layer as a whole'),
     tags: z.array(z.string()).optional().describe('Free labels of this one attachment, such as `demo`: shown as `#demo`, searchable, and normalized by `normalizeTag` (a leading `#` and letter case never matter). Unlike the tags of a check they say nothing about its result'),
     at: MomentSchema.optional(),
     poster: z.string().optional().describe('The `id` of an attachment that stands for this one before it is opened'),
@@ -190,6 +216,7 @@ export const AttemptSchema = z.looseObject({
     durationMs: z.number().nonnegative().optional(),
     startedAtMs: z.number().nonnegative().optional(),
     detail: z.string().optional(),
+    scope: EvidenceScopeSchema.optional().describe('What this try\'s evidence shows, when it differs from the other tries (a retry on another device). Overrides the check\'s scope for this try\'s attachments'),
     steps: z.array(StepSchema).optional(),
     attachments: z.array(AttachmentSchema).optional(),
     annotations: z.array(AnnotationSchema).optional(),
@@ -202,6 +229,7 @@ const evidenceShape = {
     links: z.array(LinkSchema).optional(),
     attachments: z.array(AttachmentSchema).optional(),
     annotations: z.array(AnnotationSchema).optional(),
+    scope: EvidenceScopeSchema.optional().describe('What the evidence below this level does and does not show: where it ran, how real its data and dependencies were, whether audio was captured, and what is asserted. Absent: unknown, never assumed live, physical or end to end'),
     extensions: ExtensionsSchema.optional()
 };
 /**
@@ -329,17 +357,27 @@ function lenientList(value, schema, prepare = (item) => item) {
     });
 }
 const object = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null);
-/** An attachment whose `tags` cannot be read keeps its file: only the tags that are strings are kept. */
+/** A scope that cannot be read is no scope: the evidence is kept and its scope is unknown. */
+function lenientScope(holder) {
+    if (!('scope' in holder))
+        return holder;
+    const { scope, ...rest } = holder;
+    const parsed = EvidenceScopeSchema.safeParse(scope);
+    return parsed.success ? { ...rest, scope: parsed.data } : rest;
+}
+/** An attachment whose `tags` or `scope` cannot be read keeps its file: only the tags that are strings are kept, and an unreadable scope is dropped. */
 function lenientAttachment(item) {
     const attachment = object(item);
-    if (!attachment || !('tags' in attachment))
+    if (!attachment)
         return item;
-    const { tags, ...rest } = attachment;
+    const { tags, ...rest } = lenientScope(attachment);
+    if (!('tags' in attachment))
+        return rest;
     const kept = lenientList(tags, z.string());
     return kept ? { ...rest, tags: kept } : rest;
 }
 function lenientEvidence(holder, nested = []) {
-    const out = { ...holder };
+    const out = lenientScope(holder);
     const set = (key, value) => { if (value === undefined)
         delete out[key];
     else
@@ -468,6 +506,7 @@ export const PublishChecksSchema = z.looseObject({
     links: evidenceShape.links,
     attachments: z.array(AttachmentInputSchema).optional().describe('Attached to the whole layer: a CI log, a coverage report, a trace archive'),
     annotations: evidenceShape.annotations,
+    scope: evidenceShape.scope,
     extensions: evidenceShape.extensions
 });
 const CountsSchema = z.object({

package/dist/server/src/openapi.js

@@ -293,6 +293,7 @@ const BASE_OPERATIONS = [
             { name: 'tag', in: 'query', description: 'Only tests with this tag. Repeatable or comma-separated.', schema: str },
             { name: 'artifactTag', in: 'query', description: 'Only tests with an attachment tagged this (`demo` and `#demo` are the same tag), not counting tags inherited from a check or run: the exact artifact query. `inherited=1` widens it to the tags inherited from the check and run. Repeatable or comma-separated.', schema: str, example: 'demo' },
             { name: 'inherited', in: 'query', description: 'With `artifactTag`: `1` also matches the tags an attachment inherits from its check and run, so a recording without a tag of its own under a run tagged `demo` is found. Without it the query is exact.', schema: { type: 'string', enum: ['1', 'true'] } },
+            { name: 'scope', in: 'query', description: 'Only tests with one playable recording that states every one of these producer-declared qualifications: `surface:<value>`, `device:<value>` (`device:physical` and `device:simulator` stay apart), `data:synthetic` or `data:real`, `dependencies:<value>`, `audio:recorded` or `audio:silent`, `pacing:<value>`. All must hold for the same recording. A recording that did not declare a value never matches it, and `unknown` matches only a recording that declared no scope. Repeatable or comma-separated.', schema: str, example: 'device:physical,audio:recorded' },
             { name: 'run', in: 'query', description: 'Only tests recorded in this run (a `key` from `/api/reports/runs`).', schema: str },
             { name: 'sort', in: 'query', description: 'The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.', schema: { type: 'string', enum: ['spec', 'title', 'recent', 'slowest', 'failures', 'flaky', 'runs'] } },
             { name: 'offset', in: 'query', description: 'Skip this many matching tests.', schema: { type: 'integer', minimum: 0 } },
@@ -392,7 +393,7 @@ const BASE_OPERATIONS = [
     {
         route: 'GET /api/reports/runs/detail', path: '/api/reports/runs/detail', operationId: 'getReportRun', tag: 'Report', role: 'read',
         summary: 'Every test one run recorded',
-        description: 'One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.',
+        description: 'One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer\'s files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.',
         parameters: [
             { name: 'key', in: 'query', required: true, description: 'The run\'s `key` from `/api/reports/runs`, URL-encoded.', schema: str },
             { name: 'format', in: 'query', description: '`markdown` for Markdown instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
@@ -429,7 +430,7 @@ const BASE_OPERATIONS = [
     {
         route: 'GET /api/reports/evidence/detail/:backend/:id', path: '/api/reports/evidence/detail/{backend}/{id}', operationId: 'getCheckDetail', tag: 'Report', role: 'read',
         summary: 'Everything one result carries',
-        description: 'The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run\'s. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.',
+        description: 'The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run\'s, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.',
         parameters: [BACKEND, LAYER_ID, { name: 'check', in: 'query', description: 'The check id.', schema: str }, { name: 'kind', in: 'query', description: 'The kind of the part, when the same id is in several.', schema: str }],
         responses: { '200': json('The detail.', 'CheckDetail'), '401': UNAUTHORIZED, '404': problem('No such layer or check.') }
     },

package/docs/extending.md

@@ -31,6 +31,7 @@ carry any of these. Every one is optional.
 | `attempts[]` | Every try, when the check was retried. |
 | `tags[]` | Free labels to filter by: `smoke`, `payments`. |
 | `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. |
+| `scope{}` | What the evidence does and does not show: surface, device kind, synthetic data, scripted dependencies, audio, pacing, what was asserted and its limits. Unknown when absent. See [Evidence scope](rich-evidence.md#evidence-scope). |
 | `links[]` | Where to read more: the CI run, the issue, the trace client. |
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |
 | `measurements[]` | Numbers, with units and an allowance (already part of the contract). |

package/docs/reference/http-api.md

@@ -497,6 +497,7 @@ Send `format=markdown` (or `Accept: text/markdown`) for the same as a Markdown r
 - `tag` (query): Only tests with this tag. Repeatable or comma-separated.
 - `artifactTag` (query): Only tests with an attachment tagged this (`demo` and `#demo` are the same tag), not counting tags inherited from a check or run: the exact artifact query. `inherited=1` widens it to the tags inherited from the check and run. Repeatable or comma-separated.
 - `inherited` (query): With `artifactTag`: `1` also matches the tags an attachment inherits from its check and run, so a recording without a tag of its own under a run tagged `demo` is found. Without it the query is exact.
+- `scope` (query): Only tests with one playable recording that states every one of these producer-declared qualifications: `surface:<value>`, `device:<value>` (`device:physical` and `device:simulator` stay apart), `data:synthetic` or `data:real`, `dependencies:<value>`, `audio:recorded` or `audio:silent`, `pacing:<value>`. All must hold for the same recording. A recording that did not declare a value never matches it, and `unknown` matches only a recording that declared no scope. Repeatable or comma-separated.
 - `run` (query): Only tests recorded in this run (a `key` from `/api/reports/runs`).
 - `sort` (query): The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.
 - `offset` (query): Skip this many matching tests.
@@ -528,6 +529,7 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 - `tag` (query): Only tests with this tag. Repeatable or comma-separated.
 - `artifactTag` (query): Only tests with an attachment tagged this (`demo` and `#demo` are the same tag), not counting tags inherited from a check or run: the exact artifact query. `inherited=1` widens it to the tags inherited from the check and run. Repeatable or comma-separated.
 - `inherited` (query): With `artifactTag`: `1` also matches the tags an attachment inherits from its check and run, so a recording without a tag of its own under a run tagged `demo` is found. Without it the query is exact.
+- `scope` (query): Only tests with one playable recording that states every one of these producer-declared qualifications: `surface:<value>`, `device:<value>` (`device:physical` and `device:simulator` stay apart), `data:synthetic` or `data:real`, `dependencies:<value>`, `audio:recorded` or `audio:silent`, `pacing:<value>`. All must hold for the same recording. A recording that did not declare a value never matches it, and `unknown` matches only a recording that declared no scope. Repeatable or comma-separated.
 - `run` (query): Only tests recorded in this run (a `key` from `/api/reports/runs`).
 - `sort` (query): The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.
 - `offset` (query): Skip this many matching tests.
@@ -754,7 +756,7 @@ Responses: `200` The matching results and the facets.; `304` Unchanged since the
 
 `GET /api/reports/runs/detail` · role: read
 
-One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.
+One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.
 
 - `key` (query, required): The run's `key` from `/api/reports/runs`, URL-encoded.
 - `format` (query): `markdown` for Markdown instead of JSON.
@@ -766,7 +768,7 @@ Responses: `200` The run and its results.; `304` Unchanged since the `If-None-Ma
 
 `GET /api/projects/{project}/reports/runs/detail` · role: read
 
-One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.
+One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.
 
 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.
 
@@ -876,7 +878,7 @@ Responses: `200` The rows.; `401` No token, or an unknown one. Send `Authorizati
 
 `GET /api/reports/evidence/detail/{backend}/{id}` · role: read
 
-The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
+The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
 
 - `backend` (path, required): A backend id from `/api/server`.
 - `id` (path, required): A layer id: 64 lowercase hex digits.
@@ -890,7 +892,7 @@ Responses: `200` The detail.; `401` No token, or an unknown one. Send `Authoriza
 
 `GET /api/projects/{project}/reports/evidence/detail/{backend}/{id}` · role: read
 
-The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
+The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
 
 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.
 

package/docs/reference/reports.md

@@ -1661,6 +1661,8 @@ export type EvidenceHolder = {
   readonly steps?: readonly Step[];
   readonly attempts?: readonly Attempt[];
   readonly extensions?: Readonly<Record<string, unknown>>;
+  /** What its evidence shows, as its producer declared it (see `EvidenceScope`). */
+  readonly scope?: EvidenceScope;
 };
 ```
 
@@ -1680,7 +1682,17 @@ Several holders (for example a check and its layer) are summed: `attachments` al
 attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
 label the later holder wins. `artifactTags` are the attachments' own normalized tags and are never inherited. `roles` are the attachments' roles (or, without one, what their media type or file
 name implies), sorted and distinct. `videos` lists every attachment whose effective media type is video, with the
-check, retry attempt or step that holds it (see {@link isVideoAttachment}).
+check, retry attempt or step that holds it (see {@link isVideoAttachment}), each with the scope that applies to it.
+
+#### `summarizeEvidenceIn`
+
+```ts
+export function summarizeEvidenceIn(inherited: EvidenceScope | undefined, ...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined
+```
+
+Like {@link summarizeEvidence} for the checks of a part: a video that declares no scope, and sits in a holder that
+declares none, takes the scope `inherited` from its part or layer (the nearest declaration of the two, see
+`effectiveScope`). Without `inherited` it is the same as `summarizeEvidence`.
 
 #### `summarizeLayerEvidence`
 
@@ -1701,6 +1713,16 @@ Whether an attachment is a video, by its effective media type: the producer's `c
 name implies. A role never decides this on its own (`demo` on a PNG is not a video), except that a `video` role
 settles a file whose type nothing says (`application/octet-stream`).
 
+#### `attachmentIdentity`
+
+```ts
+export function attachmentIdentity(item: Pick<Attachment, 'name' | 'sha256' | 'bundleKey' | 'uri' | 'text'>): string | undefined
+```
+
+What identifies an attachment's bytes: its digest, else its bundle key, address or inline text. Attachments with the
+same identity are the same file however many results reference them. Undefined when it names no bytes at all (it can
+never be opened). This is the `recording` of a {@link VideoRef}.
+
 #### `videoCounts`
 
 ```ts
@@ -1730,6 +1752,8 @@ export type CheckDetail = {
   readonly check: Check;
   /** What the run as a whole carries: its logs, its links, its labels. */
   readonly run: EvidenceHolder;
+  /** The scope the check inherits: its part's declaration, else its layer's. Absent when neither declared one, which is unknown, not live or physical. */
+  readonly inheritedScope?: EvidenceScope;
 };
 ```
 
@@ -1738,7 +1762,7 @@ All of one result's evidence, read when someone opens it.
 #### `checkDetailOf`
 
 ```ts
-export function checkDetailOf(layer: { readonly id: string; readonly parts: readonly { readonly kind: string; readonly checks: readonly Check[] }[] } & EvidenceHolder, checkId: string, kind?: string): CheckDetail | null
+export function checkDetailOf(layer: { readonly id: string; readonly parts: readonly { readonly kind: string; readonly checks: readonly Check[]; readonly scope?: EvidenceScope }[] } & EvidenceHolder, checkId: string, kind?: string): CheckDetail | null
 ```
 
 One result's evidence, from a layer: the first check with id `checkId` (in a part of kind `kind`, when given) plus the layer's own evidence. Null when the layer holds no such check.
@@ -1749,7 +1773,28 @@ One result's evidence, from a layer: the first check with id `checkId` (in a par
 export function runEvidence(layer: EvidenceHolder): EvidenceHolder
 ```
 
-What a layer carries as a whole (its tags, labels, links, attachments, annotations and extensions; not its parts' checks). Absent fields stay absent.
+What a layer carries as a whole (its scope, tags, labels, links, attachments, annotations and extensions; not its parts' checks). Absent fields stay absent.
+
+#### `PartEvidence`
+
+```ts
+export type PartEvidence = EvidenceHolder & {
+  readonly kind: string;
+  readonly id: string;
+  readonly title: string;
+};
+```
+
+What one part of a layer (one kind of report) carries as a whole, named by the part.
+
+#### `partsEvidence`
+
+```ts
+export function partsEvidence(layer: { readonly parts: readonly (EvidenceHolder & { readonly kind: string; readonly id: string; readonly title: string })[] }): PartEvidence[]
+```
+
+The parts of a layer that carry evidence of their own (attachments, links, labels…), each with its name. Parts
+that carry none are left out. A part's files belong to the run, not to any one check.
 
 #### `bundleKeysOf`
 
@@ -1844,6 +1889,156 @@ the next pass; `refresh` does not throw for those.
 
 - `args.backend`: The backend id stamped on live layers.
 
+### Evidence scope
+
+Source: `packages/reports/src/evidence-scope.ts`. Import: `@crvouga/atlas/reports/evidence-scope`
+
+Reads what a producer declared a piece of evidence shows (`EvidenceScope`): which declaration applies to an
+attachment, the short badges a reviewer sees before playing a recording, the facts split into declared and
+independently verified, and the filter tokens (`device:physical`, `audio:recorded`) a query narrows by. Pure
+functions, safe in a browser.
+
+The one rule: what is not declared is unknown. A missing scope, or a missing field, never reads as live, physical,
+audible or end to end, and a filter for a value never matches evidence that did not say it. A scope describes
+evidence; it never decides a status, a slot or a winner.
+
+See docs/rich-evidence.md#evidence-scope
+
+#### `SCOPE_DIMENSIONS`
+
+```ts
+export const SCOPE_DIMENSIONS = …
+```
+
+The fields of a scope that say something about the evidence and that `verified` may name, in the order they are shown.
+
+#### `ScopeDimension`
+
+```ts
+export type ScopeDimension = (typeof SCOPE_DIMENSIONS)[number];
+```
+
+One of {@link SCOPE_DIMENSIONS}.
+
+#### `UNKNOWN_SCOPE`
+
+```ts
+export const UNKNOWN_SCOPE = …
+```
+
+The filter token of a recording that declares no scope at all.
+
+#### `effectiveScope`
+
+```ts
+export function effectiveScope(...candidates: readonly (EvidenceScope | undefined)[]): EvidenceScope | undefined
+```
+
+The declaration that applies to something: the nearest one wins as a whole, never field by field, so a recording
+never shows a limitation or a device that was declared for another source. Pass the candidates nearest first
+(attachment, attempt, check, part, layer); absent ones are skipped. Undefined when none declares a scope.
+
+**Example**
+
+```ts
+effectiveScope(attachment.scope, attempt.scope, check.scope, layer.scope);
+```
+
+#### `scopeKey`
+
+```ts
+export function scopeKey(scope: EvidenceScope | undefined): string
+```
+
+A stable string that is equal for equal declarations (key order never matters), to tell one scope from another.
+
+#### `scopeTokens`
+
+```ts
+export function scopeTokens(scope: EvidenceScope | undefined): string[]
+```
+
+The filter tokens one declaration states, normalized (letter case and spaces never matter): `surface:<value>`,
+`device:<value>`, `data:synthetic` or `data:real`, `dependencies:<value>`, `audio:recorded` or `audio:silent`,
+`pacing:<value>`. A field that is not declared adds no token. No scope at all is the single token
+{@link UNKNOWN_SCOPE}, so a filter can ask for the unknown on purpose; a scope that declares nothing readable is
+also unknown.
+
+#### `matchesScope`
+
+```ts
+export function matchesScope(tokens: readonly string[], wanted: readonly string[]): boolean
+```
+
+Whether one recording's tokens satisfy a filter: every wanted token must be among them. Tokens compare normalized.
+An empty filter matches everything. The token {@link UNKNOWN_SCOPE} matches only a recording with no declared
+fields, so asking for `device:physical` never includes a recording that did not say what it ran on.
+
+#### `ScopeBasis`
+
+```ts
+export type ScopeBasis = 'verified' | 'declared' | 'undeclared';
+```
+
+How a fact is known: `verified` (independently checked), `declared` (the producer's word) or `undeclared` (unknown).
+
+#### `ScopeFact`
+
+```ts
+export type ScopeFact = {
+  readonly dimension: ScopeDimension;
+  /** A name for the dimension: `Device`, `Audio`. */
+  readonly label: string;
+  /** The value as words: `Physical device`, `Silent`, `Not declared`. */
+  readonly value: string;
+  readonly basis: ScopeBasis;
+};
+```
+
+One line of what a scope says: the dimension, a sentence for a person, and how well it is known.
+
+#### `ScopeBadge`
+
+```ts
+export type ScopeBadge = {
+  readonly dimension: ScopeDimension | 'unknown';
+  readonly text: string;
+  readonly basis: ScopeBasis;
+};
+```
+
+A short qualification to show beside a recording: `Device: Simulator`, `Scripted dependencies`, `Silent`.
+
+#### `scopeFacts`
+
+```ts
+export function scopeFacts(scope: EvidenceScope | undefined): ScopeFact[]
+```
+
+Every dimension of a scope with its value and how it is known, in a fixed order, including the ones nobody declared
+(`Not declared`, basis `undeclared`). A dimension is `verified` only when the scope's `verified` names it and it has
+a value; everything else a producer wrote is `declared`. With no scope every dimension is undeclared.
+
+#### `scopeBadges`
+
+```ts
+export function scopeBadges(scope: EvidenceScope | undefined): ScopeBadge[]
+```
+
+The concise badges for a scope: one per declared dimension, in a fixed order (`Surface: Browser`, `Device: Simulator`, `Synthetic
+data`, `Scripted dependencies`, `Silent`, `Paced`). With no declared dimension the one badge `Scope unknown`, so
+a reviewer is told nothing was claimed rather than shown nothing.
+
+#### `scopeCaveats`
+
+```ts
+export function scopeCaveats(scope: EvidenceScope | undefined): string[]
+```
+
+What a reviewer must not read into evidence: a sentence per thing that is not shown. It names the assertions the
+result stands on when there are some (so activity visible beyond them is not verified), and every kind of reality
+that was not declared. Empty only for a scope that declares and verifies everything and lists no limitation.
+
 ### Report evidence types
 
 Source: `packages/reports/src/evidence-types.ts`. Import: `@crvouga/atlas/reports/evidence-types`
@@ -1916,6 +2111,8 @@ export type VideoRef = {
   readonly recording?: string;
   /** False when the reference names no bytes at all (no bundle key, address or inline text), so it can never be played. */
   readonly available: boolean;
+  /** 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;
 };
 ```
 
@@ -2419,7 +2616,7 @@ A number a check recorded. Exceeding `limit` is shown and never fails the check
 #### `EvidenceExtras`
 
 ```ts
-export type EvidenceExtras = Partial<Pick<import('../../schema/src/layer').Check, 'tags' | 'labels' | 'links' | 'steps' | 'attachments' | 'annotations' | 'attempts' | 'extensions'>>;
+export type EvidenceExtras = Partial<Pick<import('../../schema/src/layer').Check, 'tags' | 'labels' | 'links' | 'steps' | 'attachments' | 'annotations' | 'attempts' | 'extensions' | 'scope'>>;
 ```
 
 What a check may carry beyond its outcome. All optional and open: see docs/extending.md.
@@ -4333,7 +4530,7 @@ String choices (such as `{ device: 'iphone-15' }`) that make a result its own sl
 #### `LayerExtras`
 
 ```ts
-export type LayerExtras = Partial<Pick<import('../../schema/src/layer').LayerDocument, 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions' | 'recordings'>>;
+export type LayerExtras = Partial<Pick<import('../../schema/src/layer').LayerDocument, 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions' | 'recordings' | 'scope'>>;
 ```
 
 What a layer may carry as a whole. All optional and open: see docs/extending.md.
@@ -4473,7 +4670,8 @@ Routes, relative to where it is mounted:
   runs of this machine. `cursor` is the previous page's; 409 when it no longer matches the listing (refresh).
   Any `retry` value re-lists backends that were unavailable now instead of after the wait.
 - `GET /evidence/rows/:backend/:id` the checks and spec fingerprints of one layer (`LayerRows`).
-- `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer, or one check's detail.
+- `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer (and, as `parts`, what its
+  parts carry as a whole), or one check's detail.
 - `GET /layers/:id/blobs/*` an attachment of an immutable layer by its bundle key, served by `attachmentResponse`.
 - `GET /layers/:id/*` the recorded `frame.css`, `tests/<test>/report.json` and `tests/<test>/files/<frame>` of a layer.
 - `GET /live/:source/frame.css` and `GET /live/:source/tests/:testId/*` the same for a run still writing (uncached).
@@ -6636,7 +6834,7 @@ See docs/server.md#streaming-a-run-as-it-happens
 #### `ReporterIdentity`
 
 ```ts
-export type ReporterIdentity = Pick<PublishChecksInput, 'producer' | 'kind' | 'title' | 'sha' | 'branch' | 'runUrl' | 'run' | 'environment' | 'parameters' | 'freshness' | 'specs' | 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions'>;
+export type ReporterIdentity = Pick<PublishChecksInput, 'producer' | 'kind' | 'title' | 'sha' | 'branch' | 'runUrl' | 'run' | 'environment' | 'parameters' | 'freshness' | 'specs' | 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'scope' | 'extensions'>;
 ```
 
 What every layer of one stream shares: who is reporting, from where. Whatever `publishChecks` takes, except the checks and the time.
@@ -8217,6 +8415,8 @@ export type TestSummary = {
   readonly artifactTags?: readonly string[];
   /** The normalized tags its attachments inherit from their check and run (those of the results that have attachments), apart from `artifactTags`. What an inherited artifact query also matches. */
   readonly inheritedArtifactTags?: readonly string[];
+  /** What each distinct playable recording of its current results declares it shows, as filter tokens (`device:physical`, `audio:silent`; see `scopeTokens`). A recording that declared nothing is `['unknown']`. Absent when it has no playable recording. A query's `scope` must hold for one recording, so evidence from two different devices never combines. */
+  readonly scopeProfiles?: readonly (readonly string[])[];
   readonly labels: Readonly<Record<string, string>>;
   /** What its current results carry: attachments, steps, retries, and the kinds of attachment. */
   readonly evidence: { readonly attachments: number; readonly steps: number; readonly attempts: number; readonly roles: readonly string[] };
@@ -8309,6 +8509,8 @@ export type CatalogFacets = {
   readonly tags: readonly FacetValue[];
   /** The tags of attachments, normalized. Absent in documents of older servers. */
   readonly artifactTags?: readonly FacetValue[];
+  /** The scope tokens of its recordings (`device:simulator`, `audio:recorded`, `unknown`), with how many tests have a recording that states each. Absent in documents of older servers. */
+  readonly scopes?: readonly FacetValue[];
   readonly branches: readonly FacetValue[];
   readonly labels: Readonly<Record<string, readonly FacetValue[]>>;
 };
@@ -8350,6 +8552,8 @@ export type TestQuery = {
   readonly artifactTag?: readonly string[];
   /** With `artifactTag`: also match the tags an attachment inherits from its check and run (a recording without a tag of its own under a run tagged `demo`). Default false: the exact query. */
   readonly inherited?: boolean;
+  /** Only tests with one playable recording that states every one of these (`device:physical`, `audio:recorded`, `data:synthetic`, `dependencies:live`, `surface:browser`, `pacing:paced`; see `scopeTokens`). Evidence that did not declare a value never matches it; `unknown` matches only a recording that declared no scope. */
+  readonly scope?: readonly string[];
   /** Only tests recorded in this run (a key from `runList`). */
   readonly run?: string;
   readonly sort?: TestSort;
@@ -8429,14 +8633,14 @@ export type RunSummary = {
    * and references that cannot be played. Absent when it has none, and in a report that carries no video information.
    */
   readonly videos?: VideoCounts;
+  /**
+   * Files attached to the run itself, in its layers (and their parts), not to any one check: review movies, archives,
+   * summaries. All kinds, videos included. Absent when none, and in a report that carries no such information.
+   */
+  readonly attachments?: number;
   /** The normalized tags of the attachments of its results and layers, sorted and distinct. Absent when none is tagged. */
   readonly artifactTags?: readonly string[];
   /** The tags of its checks and layers, which its attachments inherit (what `inherited=1` also matches), sorted and distinct. Absent when none. */
-  readonly tags?: readonly string[];
-  /** The media types (roles) of its attachments, sorted and distinct; `video` only for a playable recording. Absent when it has no attachment. */
-  readonly types?: readonly string[];
-  /** The `key=value` labels of its results and layers, sorted and distinct. Absent when none. */
-  readonly labels?: readonly string[];
   …
 ```
 
@@ -8494,6 +8698,29 @@ export type RunResult = {
 
 One test's last result within one run.
 
+#### `RunLayer`
+
+```ts
+export type RunLayer = {
+  /** The layer's id: 64 hex digits for an archived layer. */
+  readonly id: string;
+  /** The backend it was read from, for `GET /evidence/detail/{backend}/{id}`. */
+  readonly backend: string;
+  readonly producer: string;
+  readonly environment: string | null;
+  readonly recordedAtMs: number;
+  /** How many checks the layer recorded. A layer of zero checks is evidence only: it is not a passing test. */
+  readonly checks: number;
+  /** Files the layer carries as a whole (not those of its checks). */
+  readonly attachments: number;
+  /** Its videos, when it has any. */
+  readonly videos?: VideoCounts;
+};
+```
+
+One layer of a run, as the run's artifact hub names it: who recorded it, how many checks it holds (zero is possible
+and is not a pass) and the files it carries as a whole. Read the files with `GET /evidence/detail/{backend}/{id}`.
+
 #### `RunDetail`
 
 ```ts
@@ -8502,6 +8729,8 @@ export type RunDetail = {
   readonly version: string;
   readonly run: RunSummary;
   readonly results: readonly RunResult[];
+  /** Every layer of the run, oldest first, so its run-level files can be found even in a layer with no checks. Absent from an older server. */
+  readonly layers?: readonly RunLayer[];
 };
 ```
 
@@ -8607,7 +8836,7 @@ const catalog = testCatalog(catalogModel(layers, { history }));
 - `of(key: string): readonly TestResultEntry[]` — The recorded results of one test (by `TestSummary.key`), newest first. Empty when none.
 - `get runCount(): number { return this.#runs.size; }` — How many runs it knows of.
 - `runs(): RunSummary[]` — Every run, newest first.
-- `run(key: string): { readonly run: RunSummary; readonly results: RunResult[] } | null` — One run and its results (failed first, then by spec and title), or null.
+- `run(key: string): { readonly run: RunSummary; readonly results: RunResult[]; readonly layers: RunLayer[] } | null` — One run and its results (failed first, then by spec and title), or null.
 - `evidenceResults(): readonly { readonly result: ArtifactResult; readonly fields: FilterFields }[]` — Every recorded result that carries an attachment, newest first, with the values a query looks at. Built once per layer added. The domain is left to the caller (`artifactList`), which may know more specs than the layers recorded.
 - `testsIn(key: string): ReadonlySet<string>` — The keys of the tests one run recorded.
 
@@ -8762,7 +8991,7 @@ One run with every result it recorded, or null when no run has that key.
 export function parseTestQuery(params: URLSearchParams): TestQuery
 ```
 
-Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`, `artifactTag`, and `inherited=1`.
+Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`, `artifactTag`, `scope` (every token must hold for one recording), and `inherited=1`.
 
 #### `formatMs`
 

package/docs/reference/schema.md

@@ -776,6 +776,29 @@ export const MomentSchema = …
 
 Where in a check something happened: at a step, and/or this long after the check started.
 
+#### `EvidenceScopeSchema`
+
+```ts
+export const EvidenceScopeSchema = …
+```
+
+What a piece of evidence does and does not show, declared by the producer that made it: where it ran, whether its
+data and dependencies were real, whether audio was captured, how it was paced and which assertions the result
+stands on. Every field is optional and a field that is absent is unknown, never assumed live, physical or end to end.
+
+It is a declaration, not a finding: Atlas shows it as the producer's word, apart from the dimensions the producer
+names in `verified` (facts something independent checked). It describes evidence and never decides a status, a slot
+or a winner. The nearest declaration wins as a whole, never field by field: an attachment's `scope`, else its
+attempt's, else its check's, else its part's, else its layer's.
+
+#### `EvidenceScope`
+
+```ts
+export type EvidenceScope = z.output<typeof EvidenceScopeSchema>;
+```
+
+A producer-declared evidence scope as stored in a layer, parsed from `EvidenceScopeSchema`.
+
 #### `AttachmentSchema`
 
 ```ts