@crvouga/atlas 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog: @crvouga/atlas
 
+## 1.3.0 (2026-10-28)
+
+### Features
+
+- expose readable evidence scope for synthetic, scripted, simulator and physical runs ([fae5d02](https://github.com/crvouga/atlas/commit/fae5d02c7bdaecdfdf4ec113b23f6b11f9e3e012))
+
+## 1.2.0 (2026-10-28)
+
+### Features
+
+- filter runs and artifacts by tags, labels and media type ([ae89175](https://github.com/crvouga/atlas/commit/ae8917551ab82e469e3b35244bf9d570986be76d))
+
 ## 1.1.0 (2026-10-28)
 
 ### Features

package/dist/reports/src/artifact-query.d.ts

@@ -0,0 +1,123 @@
+/** A value of a dimension and how many records have it. */
+export type QueryFacetValue = {
+    readonly value: string;
+    readonly count: number;
+};
+/** The dimensions a query narrows by, with their address parameters. */
+export declare const QUERY_DIMENSIONS: readonly ["artifactTag", "type", "label", "environment", "producer", "branch", "sha", "outcome", "domain", "spec"];
+/** One of {@link QUERY_DIMENSIONS}. */
+export type QueryDimension = (typeof QUERY_DIMENSIONS)[number];
+/** What a query asks for. Every field is optional; nothing asked is everything. See the module comment for the semantics. */
+export type ArtifactFilter = {
+    /** Words (all of them) found in the title, test id, spec, domain, branch, labels, tags, environment or producer; or, for a run, its title. */
+    readonly q?: string;
+    /** Artifact tags (`demo` and `#demo` are the same). */
+    readonly artifactTag?: readonly string[];
+    /** Also match the tags an artifact inherits from its check and run. Default false: the exact artifact query. */
+    readonly inherited?: boolean;
+    /** Media types as roles: `video`, `image`, `audio`, `snapshot`, `text`, `file`, or a producer's own role. `video` means a playable recording. */
+    readonly type?: readonly string[];
+    /** `key=value`, or `key` for any value. */
+    readonly label?: readonly string[];
+    /** Environments or devices (`ios`, `desktop-web`). */
+    readonly environment?: readonly string[];
+    readonly producer?: readonly string[];
+    readonly branch?: readonly string[];
+    /** Revisions: a full commit id, or a prefix of at least seven characters. */
+    readonly sha?: readonly string[];
+    /** Statuses (`passed`, `failed`, `running`, `not-run`). A run's outcome is `failed` when any result failed, else `running`, else `passed`, else `not-run`. */
+    readonly outcome?: readonly string[];
+    /** The feature domain of a result's spec. Not applicable to runs. */
+    readonly domain?: readonly string[];
+    /** Spec paths. Not applicable to runs. */
+    readonly spec?: readonly string[];
+    /** Only records at or after this time (epoch ms): a result's recording time, a run's end. */
+    readonly since?: number;
+    /** Only records at or before this time (epoch ms). */
+    readonly until?: number;
+    /** Only records with a playable video recording (the same as `type: ['video']`). */
+    readonly video?: boolean;
+};
+/** The filters a query used, as they are named in the address and in `filters` of a response. */
+export type FilterName = QueryDimension | 'q' | 'inherited' | 'since' | 'until' | 'video';
+/** The values of a record a query looks at: made by {@link fieldsOfRun} or by the artifact search. */
+export type FilterFields = {
+    /** Lower-cased text a search matches. */
+    readonly text: string;
+    /** The normalized tags of its artifacts. */
+    readonly artifactTags: readonly string[];
+    /** The tags its artifacts inherit from checks and runs, and its own. */
+    readonly tags: readonly string[];
+    /** Distinct media types; `video` only when a recording can be played. */
+    readonly types: readonly string[];
+    /** Artifacts by type and their own tags. Where the report does not say which artifact carries which tag, every artifact of the record is given the record's artifact tags. */
+    readonly media: readonly {
+        readonly type: string;
+        readonly tags: readonly string[];
+    }[];
+    /** `key=value`, sorted and distinct. */
+    readonly labels: readonly string[];
+    readonly environments: readonly string[];
+    readonly producers: readonly string[];
+    readonly branches: readonly string[];
+    readonly shas: readonly string[];
+    readonly outcomes: readonly string[];
+    /** Absent when the dimension does not apply (runs have no domain). */
+    readonly domains?: readonly string[];
+    readonly specs?: readonly string[];
+    readonly at: number;
+};
+/** The facets of a query: for each dimension, its values with disjunctive counts (see the module comment). */
+export type QueryFacets = {
+    readonly artifactTags: readonly QueryFacetValue[];
+    readonly types: readonly QueryFacetValue[];
+    /** Values are `key=value`. */
+    readonly labels: readonly QueryFacetValue[];
+    readonly environments: readonly QueryFacetValue[];
+    readonly producers: readonly QueryFacetValue[];
+    readonly branches: readonly QueryFacetValue[];
+    readonly outcomes: readonly QueryFacetValue[];
+    readonly domains?: readonly QueryFacetValue[];
+};
+/**
+ * Splits a comma-separated list from an address: `a,b` is two values; `\,` is a comma and `\\` a backslash inside a
+ * value. Values are trimmed and empty ones dropped.
+ *
+ * @example
+ * ```ts
+ * splitList('demo,release\\,2'); // ['demo', 'release,2']
+ * ```
+ */
+export declare function splitList(raw: string): string[];
+/** Joins values into one address parameter that {@link splitList} reads back; `undefined` when there are none. */
+export declare function joinList(list: readonly string[]): string | undefined;
+/** A time from an address: epoch milliseconds, or a date or date-time Date can read (a date alone is UTC). `undefined` when unreadable. */
+export declare function parseTime(raw: string | null | undefined): number | undefined;
+/**
+ * Reads a query from URL search parameters: `q`, `video`, `inherited`, `since`, `until` and the repeatable or
+ * comma-separated {@link QUERY_DIMENSIONS}. Unreadable values are left out, never an error.
+ */
+export declare function parseArtifactFilter(params: URLSearchParams): ArtifactFilter;
+/** A query as URL search parameters, the form {@link parseArtifactFilter} reads back. */
+export declare function filterParams(filter: ArtifactFilter): URLSearchParams;
+/** Which filters a query uses, by the names an address gives them. */
+export declare function usedFilters(filter: ArtifactFilter): FilterName[];
+/** Whether a query narrows anything. */
+export declare function isFiltered(filter: ArtifactFilter): boolean;
+/** Every filter in `filter` that may be applied to a record with these fields, as the runs query applies them (no domain or spec). */
+export declare function forRuns(filter: ArtifactFilter): ArtifactFilter;
+/**
+ * Whether a record satisfies a query. `skip` leaves one dimension out: what {@link facetsOf} uses to count the values of
+ * that dimension, and nothing else should need.
+ */
+export declare function matchesFilter(fields: FilterFields, filter: ArtifactFilter, skip?: QueryDimension): boolean;
+/**
+ * The facets of a query over every record: for each dimension, the values the records have and how many records
+ * would match if that value were chosen in its dimension (see the module comment). A value chosen in the query is
+ * listed even when nothing has it, with a count of 0, so it can be removed.
+ */
+export declare function facetsOf(records: readonly FilterFields[], filter: ArtifactFilter): QueryFacets;
+/** The outcome of a run from its results by status: `failed`, else `running`, else `passed`, else `not-run`. */
+export declare function outcomeOfCounts(counts: Readonly<Record<string, number>>): string;
+/** The `key=value` labels of a record, sorted and distinct. */
+export declare function labelList(labels: Readonly<Record<string, string>> | undefined): string[];

package/dist/reports/src/artifact-query.js

@@ -0,0 +1,234 @@
+/**
+ * @module Run and artifact queries
+ *
+ * One shareable query for the runs of a project and for the recorded results that carry evidence (recordings,
+ * screenshots, traces): by artifact tag, label, media type, feature (domain, spec), environment or device, producer,
+ * branch, revision, outcome and time. The same rules answer `GET /api/reports/runs`, `GET /api/reports/artifacts`
+ * and the viewer's Runs and Artifacts views, so a link means the same thing everywhere.
+ *
+ * The semantics are fixed, not inferred:
+ *
+ * - Across dimensions the filters combine with AND: `artifactTag=demo&type=video&environment=ios` is a demo
+ *   recording on ios.
+ * - Within a dimension the values combine with OR: `environment=ios,android` is either.
+ * - When both `artifactTag` and `type` are asked for, one artifact must be both (a `demo`-tagged video, not a demo-tagged
+ *   screenshot beside an untagged video) wherever the report says which videos carry which tags; otherwise a result with
+ *   an artifact of that type and an artifact with that tag matches.
+ * - Facet counts are disjunctive: the count beside a value is how many records the list would hold if that value were
+ *   the only choice in its dimension, with every other dimension's filter applied. With a value already chosen, the
+ *   other values show what choosing them in addition would add, and the chosen one's count is the list's.
+ * - A filter never changes a status. Evidence that is not recorded is unknown, never a match.
+ *
+ * Lists in the address are comma-separated; a comma or backslash inside a value is written `\,` or `\\`
+ * ({@link splitList}, {@link joinList}), so a label such as `note=a,b` survives.
+ *
+ * @see docs/server.md#reading-the-report-as-an-agent
+ */
+import { normalizeTag } from './artifact-tags.js';
+/** The dimensions a query narrows by, with their address parameters. */
+export const QUERY_DIMENSIONS = ['artifactTag', 'type', 'label', 'environment', 'producer', 'branch', 'sha', 'outcome', 'domain', 'spec'];
+/**
+ * Splits a comma-separated list from an address: `a,b` is two values; `\,` is a comma and `\\` a backslash inside a
+ * value. Values are trimmed and empty ones dropped.
+ *
+ * @example
+ * ```ts
+ * splitList('demo,release\\,2'); // ['demo', 'release,2']
+ * ```
+ */
+export function splitList(raw) {
+    const out = [];
+    let current = '';
+    for (let at = 0; at < raw.length; at += 1) {
+        const char = raw[at];
+        const next = raw[at + 1];
+        if (char === '\\' && (next === ',' || next === '\\')) {
+            current += next;
+            at += 1;
+        }
+        else if (char === ',') {
+            out.push(current);
+            current = '';
+        }
+        else
+            current += char;
+    }
+    out.push(current);
+    return out.map(value => value.trim()).filter(Boolean);
+}
+/** Joins values into one address parameter that {@link splitList} reads back; `undefined` when there are none. */
+export function joinList(list) {
+    return list.length ? list.map(value => value.replace(/\\/g, '\\\\').replace(/,/g, '\\,')).join(',') : undefined;
+}
+/** A time from an address: epoch milliseconds, or a date or date-time Date can read (a date alone is UTC). `undefined` when unreadable. */
+export function parseTime(raw) {
+    if (!raw)
+        return undefined;
+    const value = /^\d+$/.test(raw.trim()) ? Number(raw) : Date.parse(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Reads a query from URL search parameters: `q`, `video`, `inherited`, `since`, `until` and the repeatable or
+ * comma-separated {@link QUERY_DIMENSIONS}. Unreadable values are left out, never an error.
+ */
+export function parseArtifactFilter(params) {
+    const many = (name) => params.getAll(name).flatMap(splitList);
+    const filter = {};
+    const q = params.get('q')?.trim();
+    if (q)
+        filter.q = q;
+    for (const name of QUERY_DIMENSIONS) {
+        const values = many(name);
+        if (values.length)
+            filter[name] = values;
+    }
+    const truthy = (name) => ['1', 'true'].includes(params.get(name) ?? '');
+    if (truthy('inherited'))
+        filter.inherited = true;
+    if (truthy('video'))
+        filter.video = true;
+    const since = parseTime(params.get('since'));
+    if (since !== undefined)
+        filter.since = since;
+    const until = parseTime(params.get('until'));
+    if (until !== undefined)
+        filter.until = until;
+    return filter;
+}
+/** A query as URL search parameters, the form {@link parseArtifactFilter} reads back. */
+export function filterParams(filter) {
+    const params = new URLSearchParams();
+    if (filter.q)
+        params.set('q', filter.q);
+    for (const name of QUERY_DIMENSIONS) {
+        const joined = joinList(filter[name] ?? []);
+        if (joined)
+            params.set(name, joined);
+    }
+    if (filter.inherited)
+        params.set('inherited', '1');
+    if (filter.since !== undefined)
+        params.set('since', String(filter.since));
+    if (filter.until !== undefined)
+        params.set('until', String(filter.until));
+    if (filter.video)
+        params.set('video', 'true');
+    return params;
+}
+/** Which filters a query uses, by the names an address gives them. */
+export function usedFilters(filter) {
+    const used = [];
+    if (filter.q)
+        used.push('q');
+    for (const name of QUERY_DIMENSIONS)
+        if (filter[name]?.length)
+            used.push(name);
+    if (filter.inherited)
+        used.push('inherited');
+    if (filter.since !== undefined)
+        used.push('since');
+    if (filter.until !== undefined)
+        used.push('until');
+    if (filter.video)
+        used.push('video');
+    return used;
+}
+/** Whether a query narrows anything. */
+export function isFiltered(filter) {
+    return usedFilters(filter).some(name => name !== 'inherited');
+}
+/** Every filter in `filter` that may be applied to a record with these fields, as the runs query applies them (no domain or spec). */
+export function forRuns(filter) {
+    const { domain: _domain, spec: _spec, ...rest } = filter;
+    return rest;
+}
+function hasTag(tags, wanted) {
+    return wanted.some(tag => { const normal = normalizeTag(tag); return normal !== null && tags.includes(normal); });
+}
+function labelMatches(labels, wanted) {
+    return wanted.includes('=') ? labels.includes(wanted) : labels.some(label => label.startsWith(`${wanted}=`));
+}
+/**
+ * Whether a record satisfies a query. `skip` leaves one dimension out: what {@link facetsOf} uses to count the values of
+ * that dimension, and nothing else should need.
+ */
+export function matchesFilter(fields, filter, skip) {
+    if (filter.q) {
+        for (const term of filter.q.toLowerCase().split(/\s+/).filter(Boolean))
+            if (!fields.text.includes(term))
+                return false;
+    }
+    const tags = skip === 'artifactTag' ? [] : filter.artifactTag ?? [];
+    const types = skip === 'type' ? [] : [...(filter.type ?? []), ...(filter.video ? ['video'] : [])];
+    if (tags.length && types.length) {
+        if (!fields.media.some(item => types.includes(item.type) && (hasTag(item.tags, tags) || (filter.inherited === true && hasTag(fields.tags, tags)))))
+            return false;
+    }
+    else {
+        if (tags.length && !hasTag(fields.artifactTags, tags) && !(filter.inherited === true && hasTag(fields.tags, tags)))
+            return false;
+        if (types.length && !types.some(type => fields.types.includes(type)))
+            return false;
+    }
+    if (skip !== 'label' && filter.label?.length && !filter.label.some(wanted => labelMatches(fields.labels, wanted)))
+        return false;
+    if (skip !== 'environment' && filter.environment?.length && !filter.environment.some(value => fields.environments.includes(value)))
+        return false;
+    if (skip !== 'producer' && filter.producer?.length && !filter.producer.some(value => fields.producers.includes(value)))
+        return false;
+    if (skip !== 'branch' && filter.branch?.length && !filter.branch.some(value => fields.branches.includes(value)))
+        return false;
+    if (skip !== 'sha' && filter.sha?.length && !filter.sha.some(value => value.length >= 7 && fields.shas.some(sha => sha.startsWith(value.toLowerCase()))))
+        return false;
+    if (skip !== 'outcome' && filter.outcome?.length && !filter.outcome.some(value => fields.outcomes.includes(value)))
+        return false;
+    if (skip !== 'domain' && filter.domain?.length && fields.domains && !filter.domain.some(value => fields.domains.includes(value)))
+        return false;
+    if (skip !== 'spec' && filter.spec?.length && fields.specs && !filter.spec.some(value => fields.specs.includes(value)))
+        return false;
+    if (filter.since !== undefined && fields.at < filter.since)
+        return false;
+    if (filter.until !== undefined && fields.at > filter.until)
+        return false;
+    return true;
+}
+/** Distinct values counted, most first and then alphabetically. */
+function tally(values) {
+    const counts = new Map();
+    for (const list of values)
+        for (const value of new Set(list))
+            counts.set(value, (counts.get(value) ?? 0) + 1);
+    return [...counts].map(([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count || (a.value < b.value ? -1 : a.value > b.value ? 1 : 0));
+}
+/**
+ * The facets of a query over every record: for each dimension, the values the records have and how many records
+ * would match if that value were chosen in its dimension (see the module comment). A value chosen in the query is
+ * listed even when nothing has it, with a count of 0, so it can be removed.
+ */
+export function facetsOf(records, filter) {
+    const scope = (skip) => records.filter(record => matchesFilter(record, filter, skip));
+    const withChosen = (found, chosen) => [
+        ...found, ...(chosen ?? []).filter(value => !found.some(entry => entry.value === value)).map(value => ({ value, count: 0 }))
+    ];
+    const dimension = (skip, pick, chosen) => withChosen(tally(scope(skip).map(pick)), chosen);
+    const normalTags = (filter.artifactTag ?? []).map(tag => normalizeTag(tag)).filter((tag) => tag !== null);
+    const domains = records.some(record => record.domains);
+    return {
+        artifactTags: dimension('artifactTag', fields => fields.artifactTags, normalTags),
+        types: dimension('type', fields => fields.types, filter.type),
+        labels: dimension('label', fields => fields.labels, (filter.label ?? []).filter(value => value.includes('='))),
+        environments: dimension('environment', fields => fields.environments, filter.environment),
+        producers: dimension('producer', fields => fields.producers, filter.producer),
+        branches: dimension('branch', fields => fields.branches, filter.branch),
+        outcomes: dimension('outcome', fields => fields.outcomes, filter.outcome),
+        ...(domains ? { domains: dimension('domain', fields => fields.domains ?? [], filter.domain) } : {})
+    };
+}
+/** The outcome of a run from its results by status: `failed`, else `running`, else `passed`, else `not-run`. */
+export function outcomeOfCounts(counts) {
+    return (counts.failed ?? 0) > 0 ? 'failed' : (counts.running ?? 0) > 0 ? 'running' : (counts.passed ?? 0) > 0 ? 'passed' : 'not-run';
+}
+/** The `key=value` labels of a record, sorted and distinct. */
+export function labelList(labels) {
+    return Object.entries(labels ?? {}).map(([key, value]) => `${key}=${value}`).sort();
+}

package/dist/reports/src/evidence-detail.d.ts

@@ -9,7 +9,7 @@
  * @see docs/extending.md
  * @see docs/report-contract.md (evidence)
  */
-import type { Annotation, Attachment, Attempt, Check, Step } from '../../schema/src/layer.js';
+import type { Annotation, Attachment, Attempt, Check, EvidenceScope, Step } from '../../schema/src/layer.js';
 import type { EvidenceSummary, VideoCounts, VideoRef } from './evidence-types.js';
 /** Anything that may carry evidence: a layer, a part or a check. */
 export type EvidenceHolder = {
@@ -25,6 +25,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;
 };
 /**
  * What a result carries beyond its outcome, as counts and short facts. It rides in every row of the
@@ -35,9 +37,15 @@ export type EvidenceHolder = {
  * 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.
  */
 export declare function summarizeEvidence(...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`.
+ */
+export declare function summarizeEvidenceIn(inherited: EvidenceScope | undefined, ...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined;
 /**
  * Like {@link summarizeEvidence} for a layer and its parts: the same summary, but a video attached to the layer or a
  * part is owned by the `layer`, not by a check.
@@ -66,6 +74,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;
 };
 /** 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. */
 export declare function checkDetailOf(layer: {
@@ -73,9 +83,10 @@ export declare function checkDetailOf(layer: {
     readonly parts: readonly {
         readonly kind: string;
         readonly checks: readonly Check[];
+        readonly scope?: EvidenceScope;
     }[];
 } & EvidenceHolder, checkId: string, kind?: string): CheckDetail | null;
-/** 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. */
 export declare function runEvidence(layer: EvidenceHolder): EvidenceHolder;
 /** Every distinct bundle key (`bundleKey`) that the attachments of a holder, its steps and its attempts point to, so a layer's files can be copied. Attachments held by `uri` or inline `text` have none. */
 export declare function bundleKeysOf(holder: EvidenceHolder): string[];

package/dist/reports/src/evidence-detail.js

@@ -1,4 +1,5 @@
 import { normalizeTags } from './artifact-tags.js';
+import { effectiveScope } from './evidence-scope.js';
 import { contentTypeOf } from './media-types.js';
 function count(holder) {
     return (holder.attachments?.length ?? 0) + (holder.steps?.length ?? 0) + (holder.annotations?.length ?? 0) + (holder.attempts?.length ?? 0) + (holder.tags?.length ?? 0) + (holder.links?.length ?? 0) + Object.keys(holder.labels ?? {}).length + Object.keys(holder.extensions ?? {}).length;
@@ -12,19 +13,28 @@ function count(holder) {
  * 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.
  */
 export function summarizeEvidence(...holders) {
     return summarize(holders, 'check');
 }
+/**
+ * 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`.
+ */
+export function summarizeEvidenceIn(inherited, ...holders) {
+    return summarize(holders, 'check', inherited);
+}
 /**
  * Like {@link summarizeEvidence} for a layer and its parts: the same summary, but a video attached to the layer or a
  * part is owned by the `layer`, not by a check.
  */
 export function summarizeLayerEvidence(...holders) {
-    return summarize(holders, 'layer');
+    // The first holder is the layer: its scope reaches the parts after it, which may declare their own.
+    return summarize(holders, 'layer', undefined, true);
 }
-function summarize(holders, owner) {
+function summarize(holders, owner, inherited, firstIsParent = false) {
     if (!holders.some(holder => count(holder) > 0))
         return undefined;
     const roles = new Set();
@@ -33,26 +43,28 @@ function summarize(holders, owner) {
     const labels = {};
     const videos = [];
     let attachments = 0, steps = 0, annotations = 0, attempts = 0, links = 0;
-    const attachmentsOf = (list, by, where = {}) => {
+    const attachmentsOf = (list, by, scopes, where = {}) => {
         for (const item of list ?? []) {
             attachments += 1;
             for (const tag of normalizeTags(item.tags))
                 artifactTags.add(tag);
             roles.add(item.role ?? roleOfType(item.contentType ?? contentTypeOf(item.name)));
-            const video = videoOf(item, by, where);
+            const video = videoOf(item, by, where, effectiveScope(item.scope, ...scopes));
             if (video)
                 videos.push(video);
         }
     };
-    const stepsOf = (list, attempt) => { for (const step of list ?? [])
-        attachmentsOf(step.attachments, 'step', { ...(attempt === undefined ? {} : { attempt }), step: step.name }); };
-    for (const holder of holders) {
-        attachmentsOf(holder.attachments, owner);
+    const stepsOf = (list, scopes, attempt) => { for (const step of list ?? [])
+        attachmentsOf(step.attachments, 'step', scopes, { ...(attempt === undefined ? {} : { attempt }), step: step.name }); };
+    for (const [index, holder] of holders.entries()) {
+        const around = [holder.scope, inherited, ...(firstIsParent && index > 0 ? [holders[0]?.scope] : [])];
+        attachmentsOf(holder.attachments, owner, around);
         // Attachments on steps and attempts are part of the check too.
-        stepsOf(holder.steps);
+        stepsOf(holder.steps, around);
         for (const attempt of holder.attempts ?? []) {
-            attachmentsOf(attempt.attachments, 'attempt', { attempt: attempt.index });
-            stepsOf(attempt.steps, attempt.index);
+            const tried = [attempt.scope, ...around];
+            attachmentsOf(attempt.attachments, 'attempt', tried, { attempt: attempt.index });
+            stepsOf(attempt.steps, tried, attempt.index);
         }
         steps += holder.steps?.length ?? 0;
         annotations += holder.annotations?.length ?? 0;
@@ -73,11 +85,12 @@ export function isVideoAttachment(attachment) {
     const type = (attachment.contentType ?? contentTypeOf(attachment.name)).toLowerCase();
     return type.startsWith('video/') || (attachment.role === 'video' && type.startsWith('application/octet-stream'));
 }
-function videoOf(item, owner, where) {
+function videoOf(item, owner, where, scope) {
     if (!isVideoAttachment(item))
         return undefined;
     const recording = item.sha256 ? `sha256:${item.sha256}` : item.bundleKey ?? item.uri ?? (item.text === undefined ? undefined : `inline:${item.name}`);
-    return { name: item.name, owner, ...where, ...(recording === undefined ? {} : { recording }), available: recording !== undefined };
+    const tags = normalizeTags(item.tags);
+    return { name: item.name, owner, ...where, ...(tags.length ? { tags } : {}), ...(recording === undefined ? {} : { recording }), available: recording !== undefined, ...(scope ? { scope } : {}) };
 }
 /**
  * Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so
@@ -117,15 +130,17 @@ export function checkDetailOf(layer, checkId, kind) {
         if (kind !== undefined && part.kind !== kind)
             continue;
         const check = part.checks.find(item => item.id === checkId);
-        if (check)
-            return { layer: layer.id, kind: part.kind, check, run: runEvidence(layer) };
+        if (check) {
+            const inheritedScope = effectiveScope(part.scope, layer.scope);
+            return { layer: layer.id, kind: part.kind, check, run: runEvidence(layer), ...(inheritedScope ? { inheritedScope } : {}) };
+        }
     }
     return null;
 }
-/** 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. */
 export function runEvidence(layer) {
-    const { tags, labels, links, attachments, annotations, extensions } = layer;
-    return { ...(tags ? { tags } : {}), ...(labels ? { labels } : {}), ...(links ? { links } : {}), ...(attachments ? { attachments } : {}), ...(annotations ? { annotations } : {}), ...(extensions ? { extensions } : {}) };
+    const { tags, labels, links, attachments, annotations, extensions, scope } = layer;
+    return { ...(scope ? { scope } : {}), ...(tags ? { tags } : {}), ...(labels ? { labels } : {}), ...(links ? { links } : {}), ...(attachments ? { attachments } : {}), ...(annotations ? { annotations } : {}), ...(extensions ? { extensions } : {}) };
 }
 /** Every distinct bundle key (`bundleKey`) that the attachments of a holder, its steps and its attempts point to, so a layer's files can be copied. Attachments held by `uri` or inline `text` have none. */
 export function bundleKeysOf(holder) {

package/dist/reports/src/evidence-scope.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module 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
+ */
+import type { EvidenceScope } from '../../schema/src/layer.js';
+/** The fields of a scope that say something about the evidence and that `verified` may name, in the order they are shown. */
+export declare const SCOPE_DIMENSIONS: readonly ["surface", "deviceKind", "syntheticData", "dependencies", "audioCaptured", "pacing"];
+/** One of {@link SCOPE_DIMENSIONS}. */
+export type ScopeDimension = (typeof SCOPE_DIMENSIONS)[number];
+/** The filter token of a recording that declares no scope at all. */
+export declare const UNKNOWN_SCOPE = "unknown";
+/**
+ * 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);
+ * ```
+ */
+export declare function effectiveScope(...candidates: readonly (EvidenceScope | undefined)[]): EvidenceScope | undefined;
+/** A stable string that is equal for equal declarations (key order never matters), to tell one scope from another. */
+export declare function scopeKey(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.
+ */
+export declare function scopeTokens(scope: EvidenceScope | undefined): string[];
+/**
+ * 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.
+ */
+export declare function matchesScope(tokens: readonly string[], wanted: readonly string[]): boolean;
+/** How a fact is known: `verified` (independently checked), `declared` (the producer's word) or `undeclared` (unknown). */
+export type ScopeBasis = 'verified' | 'declared' | 'undeclared';
+/** One line of what a scope says: the dimension, a sentence for a person, and how well it is known. */
+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;
+};
+/** A short qualification to show beside a recording: `Device: Simulator`, `Scripted dependencies`, `Silent`. */
+export type ScopeBadge = {
+    readonly dimension: ScopeDimension | 'unknown';
+    readonly text: string;
+    readonly basis: ScopeBasis;
+};
+/**
+ * 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.
+ */
+export declare function scopeFacts(scope: EvidenceScope | undefined): ScopeFact[];
+/**
+ * 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.
+ */
+export declare function scopeBadges(scope: EvidenceScope | undefined): ScopeBadge[];
+/**
+ * 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.
+ */
+export declare function scopeCaveats(scope: EvidenceScope | undefined): string[];