@crvouga/atlas 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

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,12 +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}`);
     const tags = normalizeTags(item.tags);
-    return { name: item.name, owner, ...where, ...(tags.length ? { tags } : {}), ...(recording === undefined ? {} : { recording }), available: recording !== undefined };
+    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
@@ -118,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[];

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

@@ -0,0 +1,129 @@
+/** The fields of a scope that say something about the evidence and that `verified` may name, in the order they are shown. */
+export const SCOPE_DIMENSIONS = ['surface', 'deviceKind', 'syntheticData', 'dependencies', 'audioCaptured', 'pacing'];
+/** The filter token of a recording that declares no scope at all. */
+export 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 function effectiveScope(...candidates) {
+    return candidates.find((candidate) => candidate !== undefined);
+}
+const word = (value) => value.normalize('NFC').trim().toLowerCase().replace(/\s+/g, '-');
+/** A stable string that is equal for equal declarations (key order never matters), to tell one scope from another. */
+export function scopeKey(scope) {
+    if (!scope)
+        return UNKNOWN_SCOPE;
+    const sort = (value) => Array.isArray(value) ? value.map(sort) : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([key, item]) => [key, sort(item)])) : value;
+    return JSON.stringify(sort(scope));
+}
+/**
+ * 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 function scopeTokens(scope) {
+    const tokens = [];
+    if (scope?.surface)
+        tokens.push(`surface:${word(scope.surface)}`);
+    if (scope?.deviceKind)
+        tokens.push(`device:${word(scope.deviceKind)}`);
+    if (scope?.syntheticData !== undefined)
+        tokens.push(scope.syntheticData ? 'data:synthetic' : 'data:real');
+    if (scope?.dependencies)
+        tokens.push(`dependencies:${word(scope.dependencies)}`);
+    if (scope?.audioCaptured !== undefined)
+        tokens.push(scope.audioCaptured ? 'audio:recorded' : 'audio:silent');
+    if (scope?.pacing)
+        tokens.push(`pacing:${word(scope.pacing)}`);
+    return tokens.length ? tokens : [UNKNOWN_SCOPE];
+}
+/**
+ * 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 function matchesScope(tokens, wanted) {
+    const have = new Set(tokens.map(word));
+    return wanted.every(token => have.has(word(token)));
+}
+const title = (value) => { const text = value.replace(/[-_]+/g, ' ').trim(); return text.charAt(0).toUpperCase() + text.slice(1); };
+const LABELS = { surface: 'Surface', deviceKind: 'Device', syntheticData: 'Data', dependencies: 'Dependencies', audioCaptured: 'Audio', pacing: 'Pacing' };
+function valueOf(scope, dimension) {
+    switch (dimension) {
+        case 'surface': return scope.surface ? title(scope.surface) : undefined;
+        case 'deviceKind': return scope.deviceKind ? title(scope.deviceKind) : undefined;
+        case 'syntheticData': return scope.syntheticData === undefined ? undefined : scope.syntheticData ? 'Synthetic' : 'Real';
+        case 'dependencies': return scope.dependencies ? title(scope.dependencies) : undefined;
+        case 'audioCaptured': return scope.audioCaptured === undefined ? undefined : scope.audioCaptured ? 'Recorded' : 'Silent';
+        case 'pacing': return scope.pacing ? title(scope.pacing) : undefined;
+    }
+}
+/**
+ * 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 function scopeFacts(scope) {
+    const verified = new Set(scope?.verified ?? []);
+    return SCOPE_DIMENSIONS.map(dimension => {
+        const value = scope ? valueOf(scope, dimension) : undefined;
+        return { dimension, label: LABELS[dimension], value: value ?? 'Not declared', basis: value === undefined ? 'undeclared' : verified.has(dimension) ? 'verified' : 'declared' };
+    });
+}
+/**
+ * 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 function scopeBadges(scope) {
+    const badges = [];
+    for (const fact of scopeFacts(scope)) {
+        if (fact.basis === 'undeclared')
+            continue;
+        const text = fact.dimension === 'surface' || fact.dimension === 'deviceKind' ? `${fact.label}: ${fact.value}`
+            : fact.dimension === 'syntheticData' ? `${fact.value} data`
+                : fact.dimension === 'dependencies' ? `${fact.value} dependencies`
+                    : fact.dimension === 'audioCaptured' ? (fact.value === 'Silent' ? 'Silent' : 'Audio recorded')
+                        : fact.value;
+        badges.push({ dimension: fact.dimension, text, basis: fact.basis });
+    }
+    return badges.length ? badges : [{ dimension: 'unknown', text: 'Scope unknown', basis: 'undeclared' }];
+}
+/**
+ * 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 function scopeCaveats(scope) {
+    const out = [];
+    if (!scope || scopeTokens(scope)[0] === UNKNOWN_SCOPE)
+        return ['Scope not declared: do not assume this ran live, on a physical device, with real audio or end to end.'];
+    if (scope.asserted?.length)
+        out.push(`Only these were asserted: ${scope.asserted.join('; ')}. Other activity visible in the recording is not verified.`);
+    else
+        out.push('No assertion boundary was declared: activity visible in the recording is not verified behavior.');
+    if (scope.syntheticData === true)
+        out.push('Uses synthetic data: not a statement about production data.');
+    if (scope.dependencies === undefined)
+        out.push('Whether dependencies were scripted or live is not declared.');
+    else if (word(scope.dependencies) !== 'live')
+        out.push(`Dependencies were ${word(scope.dependencies)}, not live.`);
+    if (scope.audioCaptured === undefined)
+        out.push('Whether audio was captured is not declared.');
+    else if (!scope.audioCaptured)
+        out.push('Silent: nothing audible was recorded.');
+    if (scope.deviceKind === undefined)
+        out.push('The kind of device is not declared.');
+    for (const limit of scope.limitations ?? [])
+        out.push(limit);
+    return out;
+}

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

@@ -9,7 +9,7 @@
  * @see docs/report-contract.md
  */
 import type { EvidenceMeasurement, EvidenceStatus } from './explorer-types.js';
-import type { LayerRun } from '../../schema/src/layer.js';
+import type { EvidenceScope, LayerRun } from '../../schema/src/layer.js';
 import type { LayerParameters } from './layer-types.js';
 /** Where a recorded test's timeline and captured files are read from. */
 export type RecordingAddress = {
@@ -57,6 +57,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;
 };
 /** Video availability as counts: references, distinct playable recordings (deduplicated), and references that cannot be played. */
 export type VideoCounts = {

package/dist/reports/src/explorer-types.d.ts

@@ -36,7 +36,7 @@ export type EvidenceMeasurement = {
     readonly limit?: number;
 };
 /** What a check may carry beyond its outcome. All optional and open: see docs/extending.md. */
-export type EvidenceExtras = Partial<Pick<import('../../schema/src/layer.js').Check, 'tags' | 'labels' | 'links' | 'steps' | 'attachments' | 'annotations' | 'attempts' | 'extensions'>>;
+export type EvidenceExtras = Partial<Pick<import('../../schema/src/layer.js').Check, 'tags' | 'labels' | 'links' | 'steps' | 'attachments' | 'annotations' | 'attempts' | 'extensions' | 'scope'>>;
 /** One check of a part, as recorded. */
 export type EvidenceCheck = EvidenceExtras & {
     /** Stable across runs; the newer result replaces the older one only if both used the same id. */

package/dist/reports/src/layer-merge.js

@@ -1,4 +1,5 @@
-import { summarizeEvidence, summarizeLayerEvidence } from './evidence-detail.js';
+import { summarizeEvidenceIn, summarizeLayerEvidence } from './evidence-detail.js';
+import { effectiveScope } from './evidence-scope.js';
 import { layerPlace } from './layer-axes.js';
 /**
  * A short, deterministic fingerprint of a spec's text, shaped `<length>:<hash>:<hash>` (the length in UTF-16 code
@@ -79,7 +80,7 @@ export function layerEvidence(summary, backend) {
     for (const part of summary.parts) {
         for (const check of part.checks) {
             const test = tests.get(check.id);
-            const evidence = summarizeEvidence(check);
+            const evidence = summarizeEvidenceIn(effectiveScope(part.scope, summary.scope), check);
             const item = expectations?.get(check.id);
             rows.push({
                 kind: part.kind,

package/dist/reports/src/layer-types.d.ts

@@ -15,7 +15,7 @@ import type { SourceRecord } from './protocol.js';
 /** String choices (such as `{ device: 'iphone-15' }`) that make a result its own slot. Compared as sorted key/value pairs. */
 export type LayerParameters = Readonly<Record<string, string>>;
 /** What a layer may carry as a whole. All optional and open: see docs/extending.md. */
-export type LayerExtras = Partial<Pick<import('../../schema/src/layer.js').LayerDocument, 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions' | 'recordings'>>;
+export type LayerExtras = Partial<Pick<import('../../schema/src/layer.js').LayerDocument, 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions' | 'recordings' | 'scope'>>;
 /** A layer without its captured files: what composition and the viewer's lists read. */
 export type LayerSummary = LayerExtras & {
     /** `modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Absent for a clean checkout. Advisory; never changes a status. */

package/dist/reports/src/publish-checks.js

@@ -123,6 +123,7 @@ export async function publishChecks(store, input, options = {}) {
         ...(args.links?.length ? { links: args.links } : {}),
         ...(layerEvidence.attachments?.length ? { attachments: layerEvidence.attachments } : {}),
         ...(args.annotations?.length ? { annotations: args.annotations } : {}),
+        ...(args.scope ? { scope: args.scope } : {}),
         ...(args.extensions && Object.keys(args.extensions).length ? { extensions: args.extensions } : {})
     };
     const bundle = entries.size ? await writeBundle(store, (async function* () { for (const entry of [...entries.values()].sort((a, b) => (a.key < b.key ? -1 : 1)))

package/dist/reports/src/reporter.d.ts

@@ -13,7 +13,7 @@ import { type PublishChecksInput } from '../../schema/src/layer.js';
 import type { ObjectStore } from './object-store.js';
 type Check = PublishChecksInput['checks'][number];
 /** What every layer of one stream shares: who is reporting, from where. Whatever `publishChecks` takes, except the checks and the time. */
-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'>;
 /** How a reporter sends: the `store` (a folder, S3, or `httpStore` for a server), how often (`flushMs`, `batchSize`), how hard it tries (`attempts`, `backoffMs`), what it tells (`onError`, `onPublished`), and the clock and sleep for tests. */
 export type ReporterOptions = {
     /** Where layers go: a directory, S3, or `httpStore` for an Atlas server. */