@crvouga/atlas 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog: @crvouga/atlas
 
+## 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
+
+- make focused evidence navigation resilient to slow, missing or large catalogs ([db7932c](https://github.com/crvouga/atlas/commit/db7932cf7d912ebf8cba2ae1867e6eda2352f611))
+
 ## 1.0.0 (2026-10-28)
 
 ### ⚠️ Breaking changes

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.js

@@ -77,7 +77,8 @@ function videoOf(item, owner, where) {
     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 };
 }
 /**
  * Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so

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

@@ -51,6 +51,8 @@ export type VideoRef = {
     readonly attempt?: number;
     /** The name of the step that holds it, when `owner` is `step`. */
     readonly step?: string;
+    /** The normalized tags of this attachment itself (`demo`), so a query can ask for a tagged video rather than a result that has a video and some tagged file. Absent when it has none (and in documents of older servers). */
+    readonly tags?: readonly string[];
     /** What identifies the bytes (digest, bundle key or address); references with the same one are the same recording. Absent when `available` is false. */
     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. */

package/dist/reports/src/test-catalog.d.ts

@@ -1,3 +1,4 @@
+import { type ArtifactFilter, type FilterFields, type FilterName, type QueryFacets } from './artifact-query.js';
 import type { EvidenceStatus, SpecEntry } from './explorer-types.js';
 import type { EvidenceSummary, LayerEvidence, LayerHeader, LayerRow, StatusCounts, VideoCounts, VideoRef } from './evidence-types.js';
 import { RecordedSpecs } from './recorded-specs.js';
@@ -263,12 +264,20 @@ export type RunSummary = {
      * and references that cannot be played. Absent when it has none, and in a report that carries no video information.
      */
     readonly videos?: VideoCounts;
+    /** The normalized tags of the attachments of its results and layers, sorted and distinct. Absent when none is tagged. */
+    readonly artifactTags?: readonly string[];
+    /** The tags of its checks and layers, which its attachments inherit (what `inherited=1` also matches), sorted and distinct. Absent when none. */
+    readonly tags?: readonly string[];
+    /** The media types (roles) of its attachments, sorted and distinct; `video` only for a playable recording. Absent when it has no attachment. */
+    readonly types?: readonly string[];
+    /** The `key=value` labels of its results and layers, sorted and distinct. Absent when none. */
+    readonly labels?: readonly string[];
 };
-/** What `runList` can be asked. */
-export type RunQuery = {
-    /** Only runs that have at least one playable video recording. `total` then counts only those. */
-    readonly video?: boolean;
-};
+/**
+ * What `runList` can be asked: an {@link ArtifactFilter}, of which a run answers every dimension but `domain` and
+ * `spec`. `video` keeps only runs that have at least one playable video recording; `total` then counts only those.
+ */
+export type RunQuery = ArtifactFilter;
 /** `GET /api/reports/runs`: runs, newest first. */
 export type RunList = {
     readonly schemaVersion: typeof TEST_CATALOG_VERSION;
@@ -278,6 +287,10 @@ export type RunList = {
     readonly runs: readonly RunSummary[];
     /** How many of all runs (whatever was asked, before `limit`) have a playable video recording. */
     readonly withVideo?: number;
+    /** The filters of the query that were applied. A viewer that asked for another knows the server ignored it. */
+    readonly filters?: readonly FilterName[];
+    /** The values each filter dimension offers with counts over every run (see `facetsOf`). */
+    readonly facets?: QueryFacets;
 };
 /** One test's last result within one run. */
 export type RunResult = {
@@ -302,6 +315,60 @@ export type RunDetail = {
     readonly run: RunSummary;
     readonly results: readonly RunResult[];
 };
+/**
+ * One recorded result that carries evidence (an attachment: a recording, a screenshot, a trace), with where and when it
+ * was recorded: the unit `artifactList` finds. It is a result in the history, not only the report's current winner, so
+ * a recording tagged `demo` is found with its original run, revision and status even when a later attempt is untagged.
+ */
+export type ArtifactResult = {
+    /** The test's key, as in `TestSummary.key`. */
+    readonly key: string;
+    readonly id: string;
+    readonly title: string;
+    readonly specPath: string | null;
+    /** The domain of its spec, or null when it has none. */
+    readonly domain: string | null;
+    /** When it was recorded, epoch ms. */
+    readonly at: number;
+    readonly status: EvidenceStatus;
+    readonly environment: string | null;
+    readonly producer: string;
+    /** The kind of the part that held it. */
+    readonly kind: string;
+    readonly parameters: Readonly<Record<string, string>>;
+    readonly branch: string | null;
+    readonly sha: string | null;
+    /** The key of its run (see `runKey`). */
+    readonly run: string;
+    readonly runUrl: string | null;
+    /** The id of the layer that recorded it: with `key`, the exact result to open. */
+    readonly layer: string;
+    readonly backend: string;
+    /** Attachments on the result, including those on its steps and attempts. */
+    readonly attachments: number;
+    /** The normalized tags of its attachments. */
+    readonly artifactTags: readonly string[];
+    /** The tags of its check and run, which its attachments inherit. */
+    readonly tags: readonly string[];
+    /** The media types (roles) of its attachments; `video` only for a playable recording. */
+    readonly types: readonly string[];
+    readonly labels: Readonly<Record<string, string>>;
+    readonly videos?: readonly VideoRef[];
+};
+/** `GET /api/reports/artifacts`: the recorded results that carry evidence and match a query, newest first. */
+export type ArtifactList = {
+    readonly schemaVersion: typeof TEST_CATALOG_VERSION;
+    readonly version: string;
+    /** Results that matched, before `offset` and `limit`. */
+    readonly total: number;
+    readonly offset: number;
+    readonly limit: number;
+    readonly results: readonly ArtifactResult[];
+    /** The filters of the query that were applied. */
+    readonly filters: readonly FilterName[];
+    /** The values each dimension offers with disjunctive counts over every result that carries evidence. */
+    readonly facets: QueryFacets;
+};
 /**
  * The run a layer belongs to: the execution its producer named (`run:<id>`), else its run URL, else `branch@sha`, else
  * `local`. Layers with the same key are one run. Only grouping: it is never part of the slot a result fills.
@@ -351,6 +418,14 @@ export declare class TestHistory {
         readonly run: RunSummary;
         readonly results: RunResult[];
     } | null;
+    /**
+     * Every recorded result that carries an attachment, newest first, with the values a query looks at. Built once per
+     * layer added. The domain is left to the caller (`artifactList`), which may know more specs than the layers recorded.
+     */
+    evidenceResults(): readonly {
+        readonly result: ArtifactResult;
+        readonly fields: FilterFields;
+    }[];
     /** The keys of the tests one run recorded. */
     testsIn(key: string): ReadonlySet<string>;
 }
@@ -403,6 +478,25 @@ export declare function hasVideo(run: Pick<RunSummary, 'videos'>): boolean;
  * any recording's bytes. `withVideo` always counts every run that has one.
  */
 export declare function runList(history: TestHistory, version: string, limit?: number, query?: RunQuery): RunList;
+/** What a query looks at in a run: see {@link ArtifactFilter}. A run's outcome is `failed` when any result failed. */
+export declare function fieldsOfRun(run: RunSummary): FilterFields;
+/**
+ * The recorded results that carry evidence and match a query, newest first, across the whole history (`limit` default
+ * 100). `total` and the facet counts apply to every match before `offset` and `limit`. `domainOf` tells the domain of a
+ * spec path when the caller knows more than the layers recorded (a server with a spec set); otherwise it is the
+ * recorded spec's domain, else the folder the path implies.
+ *
+ * @example
+ * ```ts
+ * const list = artifactList(history, 'v1', { artifactTag: ['demo'], type: ['video'], environment: ['ios'] });
+ * list.results.map(r => [r.title, r.run, r.sha, r.status]);
+ * ```
+ */
+export declare function artifactList(history: TestHistory, version: string, query?: ArtifactFilter, page?: {
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly domainOf?: (specPath: string) => string | undefined;
+}): ArtifactList;
 /** One run with every result it recorded, or null when no run has that key. */
 export declare function runDetail(history: TestHistory, version: string, key: string): RunDetail | null;
 /** 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`. */
@@ -415,5 +509,7 @@ export declare function catalogMarkdown(catalog: TestCatalog): string;
 export declare function historyMarkdown(document: TestHistoryDocument): string;
 /** The run list as Markdown. */
 export declare function runsMarkdown(list: RunList): string;
+/** The artifact results as Markdown, for an agent or a terminal. */
+export declare function artifactsMarkdown(list: ArtifactList): string;
 /** One run as Markdown. */
 export declare function runMarkdown(detail: RunDetail): string;