@crvouga/atlas 1.2.0 → 1.3.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 } },

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.

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`
 
@@ -1730,6 +1742,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 +1752,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 +1763,7 @@ 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.
 
 #### `bundleKeysOf`
 
@@ -1844,6 +1858,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 +2080,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 +2585,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 +4499,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.
@@ -6636,7 +6802,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 +8383,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 +8477,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 +8520,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;
@@ -8762,7 +8934,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

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). |
+| `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. |
 | `specPath` | check | The spec a check belongs to (a `.feature`, a test file), relative to the repository. Checks are grouped by it. |
 | `specs[]` (`path`, `domain`, `kind`, `title`) | layer | Names each spec and its group (`domain`), so a server can group checks by spec with a title even when no [spec set](integrating.md#tell-atlas-which-spec-a-check-belongs-to) has been published. |
@@ -62,6 +63,52 @@ attachments with that tag, and says how many match. Tags describe evidence; they
 - **Older layers.** A layer without attachment tags reads exactly as before. Tags on an attachment that cannot be read
   (not a list of strings) are dropped, and the attachment, check and layer stay.
 
+## Evidence scope
+
+A green result and a video do not say whether the speech was real, the replies scripted, the audio recorded, the device
+physical or a vendor substituted. Declare it where the evidence is, in an optional `scope`, and the viewer shows it as
+short badges above the recording (before it is played), with the exact declaration on demand:
+
+```ts
+{
+  name: 'checkout.webm', role: 'video',
+  scope: {
+    surface: 'browser',               // where the product ran: browser, native-app, api…
+    deviceKind: 'simulator',          // simulator, emulator, physical, virtual-machine, desktop…
+    syntheticData: true,              // made-up data (false: real, absent: unknown)
+    dependencies: 'scripted',         // scripted, live or mixed
+    audioCaptured: false,             // false: silent, absent: unknown
+    pacing: 'paced',                  // paced, real-time
+    asserted: ['the receipt is shown'],           // what the result stands on
+    limitations: ['Replies are scripted'],
+    declaredBy: 'checkout e2e suite',
+    verified: ['deviceKind'],         // fields something independent checked
+    verifiedBy: 'device farm session log',
+    provenance: [{ url: 'https://farm.example/session/1', name: 'Device session' }]
+  }
+}
+```
+
+Every field is optional, and every value except the booleans is an open string.
+
+- **Unknown is not live.** A recording with no scope, or a scope that does not say a thing, shows `Scope unknown` or
+  `Not declared`. It is never assumed live, physical, audible or end to end.
+- **Declared is not verified.** Atlas shows `scope` as the producer's word. Only the fields named in `verified` are
+  marked verified (with `verifiedBy`), and `provenance` links where to check them. Atlas does not check any of it.
+- **Only what was asserted.** `asserted` lists the boundaries the result stands on. The viewer says that other activity
+  visible in the clip is not verified behavior; with no `asserted` it says that no boundary was declared.
+- **The nearest declaration, whole.** A recording takes the `scope` of the attachment, else its attempt, its check, its
+  part, its layer, in that order. It is never merged field by field, so a retry on a physical phone does not borrow
+  the limitations declared for the simulator try, and the badges change with the exact recording opened.
+- **Filtering.** `GET /api/reports/tests?scope=device:physical,audio:recorded` (and the explorer's *Recording scope*
+  filter) lists tests with one playable recording that states every token: `surface:<v>`, `device:<v>`,
+  `data:synthetic` or `data:real`, `dependencies:<v>`, `audio:recorded` or `audio:silent`, `pacing:<v>`. A simulator
+  and a physical phone are separate values. Evidence that did not declare a value is never included, and `unknown`
+  asks for recordings that declared nothing. Each test lists its recordings' tokens as `scopeProfiles`, the facets as
+  `scopes`, and the search box finds the words in them.
+- **It decides nothing.** A scope never changes a status, a slot or a winner. A scope an older Atlas cannot read is
+  dropped, and the attachment, check and layer stay.
+
 ## Finding runs and artifacts
 
 The viewer's **Runs** and **Artifacts** tabs and the API answer one query, so a link means the same thing everywhere.

package/llms-full.txt

@@ -1014,6 +1014,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). |
+| `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. |
 | `specPath` | check | The spec a check belongs to (a `.feature`, a test file), relative to the repository. Checks are grouped by it. |
 | `specs[]` (`path`, `domain`, `kind`, `title`) | layer | Names each spec and its group (`domain`), so a server can group checks by spec with a title even when no [spec set](integrating.md#tell-atlas-which-spec-a-check-belongs-to) has been published. |
@@ -1049,6 +1050,52 @@ attachments with that tag, and says how many match. Tags describe evidence; they
 - **Older layers.** A layer without attachment tags reads exactly as before. Tags on an attachment that cannot be read
   (not a list of strings) are dropped, and the attachment, check and layer stay.
 
+## Evidence scope
+
+A green result and a video do not say whether the speech was real, the replies scripted, the audio recorded, the device
+physical or a vendor substituted. Declare it where the evidence is, in an optional `scope`, and the viewer shows it as
+short badges above the recording (before it is played), with the exact declaration on demand:
+
+```ts
+{
+  name: 'checkout.webm', role: 'video',
+  scope: {
+    surface: 'browser',               // where the product ran: browser, native-app, api…
+    deviceKind: 'simulator',          // simulator, emulator, physical, virtual-machine, desktop…
+    syntheticData: true,              // made-up data (false: real, absent: unknown)
+    dependencies: 'scripted',         // scripted, live or mixed
+    audioCaptured: false,             // false: silent, absent: unknown
+    pacing: 'paced',                  // paced, real-time
+    asserted: ['the receipt is shown'],           // what the result stands on
+    limitations: ['Replies are scripted'],
+    declaredBy: 'checkout e2e suite',
+    verified: ['deviceKind'],         // fields something independent checked
+    verifiedBy: 'device farm session log',
+    provenance: [{ url: 'https://farm.example/session/1', name: 'Device session' }]
+  }
+}
+```
+
+Every field is optional, and every value except the booleans is an open string.
+
+- **Unknown is not live.** A recording with no scope, or a scope that does not say a thing, shows `Scope unknown` or
+  `Not declared`. It is never assumed live, physical, audible or end to end.
+- **Declared is not verified.** Atlas shows `scope` as the producer's word. Only the fields named in `verified` are
+  marked verified (with `verifiedBy`), and `provenance` links where to check them. Atlas does not check any of it.
+- **Only what was asserted.** `asserted` lists the boundaries the result stands on. The viewer says that other activity
+  visible in the clip is not verified behavior; with no `asserted` it says that no boundary was declared.
+- **The nearest declaration, whole.** A recording takes the `scope` of the attachment, else its attempt, its check, its
+  part, its layer, in that order. It is never merged field by field, so a retry on a physical phone does not borrow
+  the limitations declared for the simulator try, and the badges change with the exact recording opened.
+- **Filtering.** `GET /api/reports/tests?scope=device:physical,audio:recorded` (and the explorer's *Recording scope*
+  filter) lists tests with one playable recording that states every token: `surface:<v>`, `device:<v>`,
+  `data:synthetic` or `data:real`, `dependencies:<v>`, `audio:recorded` or `audio:silent`, `pacing:<v>`. A simulator
+  and a physical phone are separate values. Evidence that did not declare a value is never included, and `unknown`
+  asks for recordings that declared nothing. Each test lists its recordings' tokens as `scopeProfiles`, the facets as
+  `scopes`, and the search box finds the words in them.
+- **It decides nothing.** A scope never changes a status, a slot or a winner. A scope an older Atlas cannot read is
+  dropped, and the attachment, check and layer stay.
+
 ## Finding runs and artifacts
 
 The viewer's **Runs** and **Artifacts** tabs and the API answer one query, so a link means the same thing everywhere.
@@ -2757,6 +2804,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). |
@@ -4923,6 +4971,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.
@@ -4954,6 +5003,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.

package/package.json

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