@crvouga/atlas 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog: @crvouga/atlas
 
+## 0.16.0 (2026-10-28)
+
+### Features
+
+- show video availability and filter runs with recordings ([dece195](https://github.com/crvouga/atlas/commit/dece195ef419a3fc6eaedb643544be29ffb341c3))
+
+## 0.15.0 (2026-10-28)
+
+### Features
+
+- tag artifacts and demos with visible, searchable metadata ([833114a](https://github.com/crvouga/atlas/commit/833114ae543fa9a1bfe796b5991611efa02bd098))
+
 ## 0.14.0 (2026-10-28)
 
 ### Features

package/dist/reports/src/artifact-tag-store.d.ts

@@ -0,0 +1,20 @@
+import type { ObjectStore } from './object-store.js';
+import { type ArtifactTagEntry } from './artifact-tags.js';
+/** The prefix of every recorded edit in a store. */
+export declare const ARTIFACT_TAGS_PREFIX = "curation/artifact-tags/";
+/** The edit was not acceptable (`status` is the HTTP status to answer). */
+export declare class ArtifactTagError extends Error {
+    readonly status: 422;
+    constructor(status: 422, message: string);
+}
+/**
+ * Validates an edit (`ArtifactTagEditSchema`), normalizes its tags and records it as a new object in `store`, by
+ * `by` at `atMs`. Throws {@link ArtifactTagError} for a body that is not an edit, a tag that is not a tag (empty, or
+ * over 64 characters) or an edit that changes nothing. Recording the same edit twice records two entries.
+ */
+export declare function recordArtifactTags(store: ObjectStore, input: unknown, by: string, atMs: number): Promise<ArtifactTagEntry>;
+/**
+ * Every recorded edit in `store`, oldest first. An object that cannot be read as an edit is skipped (unknown, never
+ * guessed at). A store with none gives an empty list. Transport errors throw.
+ */
+export declare function readArtifactTagEntries(store: ObjectStore): Promise<ArtifactTagEntry[]>;

package/dist/reports/src/artifact-tag-store.js

@@ -0,0 +1,70 @@
+/**
+ * @module Reviewer tags in a store
+ *
+ * Where a reviewer's tags for attachments are kept: one small immutable object per edit under
+ * `curation/artifact-tags/`, named by time and a random id so editors never overwrite one another, and never changed
+ * or deleted afterwards. The layers they are about are not touched. The list of edits is the audit trail: who changed
+ * which tags of which attachment, and when. `foldArtifactTags` turns it into the tags that stand now.
+ *
+ * @see docs/server.md#tagging-artifacts
+ */
+import { ArtifactTagEntrySchema, ArtifactTagEditSchema } from '../../schema/src/api.js';
+import { readUtf8, writeUtf8 } from './object-io.js';
+import { normalizeTag, normalizeTags } from './artifact-tags.js';
+/** The prefix of every recorded edit in a store. */
+export const ARTIFACT_TAGS_PREFIX = 'curation/artifact-tags/';
+/** The edit was not acceptable (`status` is the HTTP status to answer). */
+export class ArtifactTagError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Validates an edit (`ArtifactTagEditSchema`), normalizes its tags and records it as a new object in `store`, by
+ * `by` at `atMs`. Throws {@link ArtifactTagError} for a body that is not an edit, a tag that is not a tag (empty, or
+ * over 64 characters) or an edit that changes nothing. Recording the same edit twice records two entries.
+ */
+export async function recordArtifactTags(store, input, by, atMs) {
+    const parsed = ArtifactTagEditSchema.safeParse(input);
+    if (!parsed.success)
+        throw new ArtifactTagError(422, `Not a tag edit: ${parsed.error.issues[0]?.path.join('.') || '(body)'}: ${parsed.error.issues[0]?.message ?? 'invalid'}`);
+    const { target, add = [], remove = [] } = parsed.data;
+    if ([...add, ...remove].some(tag => normalizeTag(tag) === null))
+        throw new ArtifactTagError(422, 'A tag is empty or longer than 64 characters.');
+    const added = normalizeTags(add);
+    const removed = normalizeTags(remove);
+    const entryAdd = added.filter(tag => !removed.includes(tag));
+    const entryRemove = removed.filter(tag => !added.includes(tag));
+    if (!entryAdd.length && !entryRemove.length)
+        throw new ArtifactTagError(422, 'Name at least one tag to add or remove.');
+    const id = `${String(atMs).padStart(16, '0')}-${globalThis.crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
+    const entry = {
+        id, by, atMs,
+        target: { layer: target.layer, check: target.check, ...(target.kind === undefined ? {} : { kind: target.kind }), artifact: target.artifact },
+        add: entryAdd, remove: entryRemove
+    };
+    await writeUtf8(store, `${ARTIFACT_TAGS_PREFIX}${id}.json`, JSON.stringify({ schemaVersion: 1, ...entry }), 'application/json');
+    return entry;
+}
+/**
+ * Every recorded edit in `store`, oldest first. An object that cannot be read as an edit is skipped (unknown, never
+ * guessed at). A store with none gives an empty list. Transport errors throw.
+ */
+export async function readArtifactTagEntries(store) {
+    const keys = (await store.listKeys(ARTIFACT_TAGS_PREFIX)).filter(key => key.endsWith('.json'));
+    const read = await Promise.all(keys.map(async (key) => {
+        const text = await readUtf8(store, key);
+        if (text === null)
+            return [];
+        try {
+            const parsed = ArtifactTagEntrySchema.safeParse(JSON.parse(text));
+            return parsed.success ? [parsed.data] : [];
+        }
+        catch {
+            return [];
+        }
+    }));
+    return read.flat().sort((a, b) => a.atMs - b.atMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

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

@@ -0,0 +1,96 @@
+/**
+ * @module Artifact tags
+ *
+ * The tags of one attachment (a recording, a screenshot, a trace): how a tag is normalized so `demo` and `#demo`
+ * are the same tag, which tags an attachment shows (its producer's, its reviewers', and those it inherits from its
+ * check and run), and how a reviewer's edits fold into the tags that stand now. Pure functions, safe in a browser.
+ *
+ * Tags describe evidence; they never decide a status, a slot or a winner. A producer writes `tags` on the attachment
+ * inside an immutable layer. A reviewer's tags live apart, as an append-only list of edits that the server records
+ * with who made each and when (`artifact-tag-store.ts`); the layer is never rewritten.
+ *
+ * @see docs/rich-evidence.md#tagging-artifacts-and-demos
+ */
+import type { Attachment } from '../../schema/src/layer.js';
+/** The longest a normalized tag may be, in characters. */
+export declare const MAX_TAG_LENGTH = 64;
+/**
+ * Normalizes a tag so equal tags compare equal: Unicode NFC, any leading `#` removed, surrounding whitespace
+ * trimmed, letters lower-cased and each run of whitespace inside turned into one `-`. Every other character is kept,
+ * so `Smoke`, `#smoke` and ` smoke ` are `smoke`, and `team/payments` or `release=2` stay as they are. Returns
+ * `null` for a tag that is empty after that (`''`, `'#'`, `'  '`) or longer than {@link MAX_TAG_LENGTH}.
+ *
+ * @example
+ * ```ts
+ * normalizeTag('#Demo'); // 'demo'
+ * normalizeTag('release candidate'); // 'release-candidate'
+ * normalizeTag('#'); // null
+ * ```
+ */
+export declare function normalizeTag(raw: string): string | null;
+/** Normalizes every tag with {@link normalizeTag}, dropping the ones that are not tags and the repeats; the first of each keeps its place. */
+export declare function normalizeTags(raw: Iterable<string> | undefined): string[];
+/** The tag as a person sees it: `#demo`. */
+export declare const displayTag: (tag: string) => string;
+/**
+ * How an edit names an attachment: `id:<id>` when it has an `id`, else `key:<bundleKey>` (its bytes), else
+ * `name:<name>`. It is stable for a layer, which never changes. Two attachments in one check with the same bytes and
+ * no `id` share a reference, and so share reviewer tags; give them an `id` to tag them apart.
+ */
+export declare function artifactRef(attachment: Pick<Attachment, 'id' | 'bundleKey' | 'name'>): string;
+/** Where a reviewer's tags are about: one attachment of one check of one archived layer. */
+export type ArtifactTarget = {
+    readonly layer: string;
+    readonly check: string;
+    readonly kind?: string | undefined;
+    readonly artifact: string;
+};
+/** One recorded edit. Entries are never changed or removed. */
+export type ArtifactTagEntry = {
+    readonly id: string;
+    readonly target: ArtifactTarget;
+    readonly add: readonly string[];
+    readonly remove: readonly string[];
+    readonly by: string;
+    readonly atMs: number;
+};
+/** A string that is equal for equal targets (the part `kind` is optional and then does not matter). */
+export declare const targetKey: (target: ArtifactTarget) => string;
+/** A tag a reviewer added: who added it last, and when. */
+export type ReviewerTag = {
+    readonly tag: string;
+    readonly by: string;
+    readonly atMs: number;
+};
+/**
+ * Folds the recorded edits (in any order) into the reviewer tags that stand now, by target (see {@link targetKey}).
+ * Edits apply oldest first, ties by `id`; a tag added, removed and added again stands, with the time and author of
+ * the last add. A target whose tags were all removed is absent. Entries that are not understood are ignored.
+ */
+export declare function foldArtifactTags(entries: readonly ArtifactTagEntry[]): Map<string, ReviewerTag[]>;
+/** Where a shown tag comes from: the attachment's own producer (`artifact`), a reviewer after the upload (`reviewer`), or the check or run around it (`inherited`). */
+export type TagSource = 'artifact' | 'reviewer' | 'inherited';
+/** One tag an attachment shows, with its source and, for a reviewer's tag, who added it and when. */
+export type ArtifactTag = {
+    readonly tag: string;
+    readonly source: TagSource;
+    readonly by?: string;
+    readonly atMs?: number;
+};
+/**
+ * The tags one attachment shows, normalized and without repeats: its producer's own (`artifact`), then the
+ * reviewers' (`reviewer`), then those of its check and run that it does not have itself (`inherited`). A tag it has
+ * more than once is shown once, by the first source above.
+ */
+export declare function artifactTagsOf(attachment: Pick<Attachment, 'tags'>, options?: {
+    readonly reviewer?: readonly ReviewerTag[];
+    readonly inherited?: Iterable<string>;
+}): ArtifactTag[];
+/**
+ * Does an attachment match a tag (either spelling)? An exact query (`inherited: false`, the default) matches only the
+ * tags the attachment has itself, from its producer or a reviewer; an inherited query also matches the tags it
+ * inherits from its check and run. The two differ for a recording that is untagged under a tagged run.
+ */
+export declare function hasArtifactTag(tags: readonly ArtifactTag[], wanted: string, options?: {
+    readonly inherited?: boolean;
+}): boolean;

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

@@ -0,0 +1,96 @@
+/** The longest a normalized tag may be, in characters. */
+export const MAX_TAG_LENGTH = 64;
+/**
+ * Normalizes a tag so equal tags compare equal: Unicode NFC, any leading `#` removed, surrounding whitespace
+ * trimmed, letters lower-cased and each run of whitespace inside turned into one `-`. Every other character is kept,
+ * so `Smoke`, `#smoke` and ` smoke ` are `smoke`, and `team/payments` or `release=2` stay as they are. Returns
+ * `null` for a tag that is empty after that (`''`, `'#'`, `'  '`) or longer than {@link MAX_TAG_LENGTH}.
+ *
+ * @example
+ * ```ts
+ * normalizeTag('#Demo'); // 'demo'
+ * normalizeTag('release candidate'); // 'release-candidate'
+ * normalizeTag('#'); // null
+ * ```
+ */
+export function normalizeTag(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const tag = raw.normalize('NFC').trim().replace(/^#+/, '').trim().toLowerCase().replace(/\s+/g, '-');
+    return tag.length > 0 && tag.length <= MAX_TAG_LENGTH ? tag : null;
+}
+/** Normalizes every tag with {@link normalizeTag}, dropping the ones that are not tags and the repeats; the first of each keeps its place. */
+export function normalizeTags(raw) {
+    const seen = new Set();
+    for (const value of raw ?? []) {
+        const tag = normalizeTag(value);
+        if (tag !== null)
+            seen.add(tag);
+    }
+    return [...seen];
+}
+/** The tag as a person sees it: `#demo`. */
+export const displayTag = (tag) => `#${tag}`;
+/**
+ * How an edit names an attachment: `id:<id>` when it has an `id`, else `key:<bundleKey>` (its bytes), else
+ * `name:<name>`. It is stable for a layer, which never changes. Two attachments in one check with the same bytes and
+ * no `id` share a reference, and so share reviewer tags; give them an `id` to tag them apart.
+ */
+export function artifactRef(attachment) {
+    if (attachment.id)
+        return `id:${attachment.id}`;
+    if (attachment.bundleKey)
+        return `key:${attachment.bundleKey}`;
+    return `name:${attachment.name}`;
+}
+/** A string that is equal for equal targets (the part `kind` is optional and then does not matter). */
+export const targetKey = (target) => JSON.stringify([target.layer, target.check, target.kind ?? '', target.artifact]);
+/**
+ * Folds the recorded edits (in any order) into the reviewer tags that stand now, by target (see {@link targetKey}).
+ * Edits apply oldest first, ties by `id`; a tag added, removed and added again stands, with the time and author of
+ * the last add. A target whose tags were all removed is absent. Entries that are not understood are ignored.
+ */
+export function foldArtifactTags(entries) {
+    const ordered = [...entries].sort((a, b) => a.atMs - b.atMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const standing = new Map();
+    for (const entry of ordered) {
+        const key = targetKey(entry.target);
+        const tags = standing.get(key) ?? new Map();
+        for (const tag of entry.remove)
+            tags.delete(tag);
+        for (const tag of entry.add)
+            tags.set(tag, { tag, by: entry.by, atMs: entry.atMs });
+        standing.set(key, tags);
+    }
+    const out = new Map();
+    for (const [key, tags] of standing)
+        if (tags.size)
+            out.set(key, [...tags.values()]);
+    return out;
+}
+/**
+ * The tags one attachment shows, normalized and without repeats: its producer's own (`artifact`), then the
+ * reviewers' (`reviewer`), then those of its check and run that it does not have itself (`inherited`). A tag it has
+ * more than once is shown once, by the first source above.
+ */
+export function artifactTagsOf(attachment, options = {}) {
+    const out = new Map();
+    for (const tag of normalizeTags(attachment.tags))
+        out.set(tag, { tag, source: 'artifact' });
+    for (const found of options.reviewer ?? [])
+        if (!out.has(found.tag))
+            out.set(found.tag, { tag: found.tag, source: 'reviewer', by: found.by, atMs: found.atMs });
+    for (const tag of normalizeTags(options.inherited))
+        if (!out.has(tag))
+            out.set(tag, { tag, source: 'inherited' });
+    return [...out.values()];
+}
+/**
+ * Does an attachment match a tag (either spelling)? An exact query (`inherited: false`, the default) matches only the
+ * tags the attachment has itself, from its producer or a reviewer; an inherited query also matches the tags it
+ * inherits from its check and run. The two differ for a recording that is untagged under a tagged run.
+ */
+export function hasArtifactTag(tags, wanted, options = {}) {
+    const tag = normalizeTag(wanted);
+    return tag !== null && tags.some(item => item.tag === tag && (options.inherited === true || item.source !== 'inherited'));
+}

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

@@ -10,7 +10,7 @@
  * @see docs/report-contract.md (evidence)
  */
 import type { Annotation, Attachment, Attempt, Check, Step } from '../../schema/src/layer.js';
-import type { EvidenceSummary } from './evidence-types.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 = {
     readonly tags?: readonly string[];
@@ -33,10 +33,27 @@ export type EvidenceHolder = {
  *
  * Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
  * attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
- * label the later holder wins. `roles` are the attachments' roles (or, without one, what their media type or file
- * name implies), sorted and distinct.
+ * 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}).
  */
 export declare function summarizeEvidence(...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.
+ */
+export declare function summarizeLayerEvidence(...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined;
+/**
+ * Whether an attachment is a video, by its effective media type: the producer's `contentType`, else the one its file
+ * name implies. A role never decides this on its own (`demo` on a PNG is not a video), except that a `video` role
+ * settles a file whose type nothing says (`application/octet-stream`).
+ */
+export declare function isVideoAttachment(attachment: Pick<Attachment, 'name' | 'role' | 'contentType'>): boolean;
+/**
+ * Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so
+ * "no video" and "nothing known about video" look the same on the wire.
+ */
+export declare function videoCounts(videos: readonly VideoRef[] | undefined): VideoCounts | undefined;
 /** A role to show when a producer gave none, from the media type: `image`, `video`, `audio`, `snapshot` (text/html), `text` (text, JSON, XML) or `file`. Roles are an open vocabulary; a producer's own role always wins. */
 export declare function roleOfType(contentType: string | undefined): string;
 /** All of one result's evidence, read when someone opens it. */

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

@@ -1,3 +1,4 @@
+import { normalizeTags } from './artifact-tags.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;
@@ -9,29 +10,49 @@ function count(holder) {
  *
  * Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
  * attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
- * label the later holder wins. `roles` are the attachments' roles (or, without one, what their media type or file
- * name implies), sorted and distinct.
+ * 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}).
  */
 export function summarizeEvidence(...holders) {
+    return summarize(holders, 'check');
+}
+/**
+ * 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');
+}
+function summarize(holders, owner) {
     if (!holders.some(holder => count(holder) > 0))
         return undefined;
     const roles = new Set();
     const tags = new Set();
+    const artifactTags = new Set();
     const labels = {};
+    const videos = [];
     let attachments = 0, steps = 0, annotations = 0, attempts = 0, links = 0;
-    const attachmentsOf = (list) => { for (const item of list ?? []) {
-        attachments += 1;
-        roles.add(item.role ?? roleOfType(item.contentType ?? contentTypeOf(item.name)));
-    } };
+    const attachmentsOf = (list, by, 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);
+            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);
+        attachmentsOf(holder.attachments, owner);
         // Attachments on steps and attempts are part of the check too.
-        for (const step of holder.steps ?? [])
-            attachmentsOf(step.attachments);
+        stepsOf(holder.steps);
         for (const attempt of holder.attempts ?? []) {
-            attachmentsOf(attempt.attachments);
-            for (const step of attempt.steps ?? [])
-                attachmentsOf(step.attachments);
+            attachmentsOf(attempt.attachments, 'attempt', { attempt: attempt.index });
+            stepsOf(attempt.steps, attempt.index);
         }
         steps += holder.steps?.length ?? 0;
         annotations += holder.annotations?.length ?? 0;
@@ -41,7 +62,39 @@ export function summarizeEvidence(...holders) {
             tags.add(tag);
         Object.assign(labels, holder.labels);
     }
-    return { attachments, steps, annotations, attempts, links, tags: [...tags], labels, roles: [...roles].sort() };
+    return { attachments, steps, annotations, attempts, links, tags: [...tags], ...(artifactTags.size ? { artifactTags: [...artifactTags].sort() } : {}), labels, roles: [...roles].sort(), ...(videos.length ? { videos } : {}) };
+}
+/**
+ * Whether an attachment is a video, by its effective media type: the producer's `contentType`, else the one its file
+ * name implies. A role never decides this on its own (`demo` on a PNG is not a video), except that a `video` role
+ * settles a file whose type nothing says (`application/octet-stream`).
+ */
+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) {
+    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 };
+}
+/**
+ * Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so
+ * "no video" and "nothing known about video" look the same on the wire.
+ */
+export function videoCounts(videos) {
+    if (!videos?.length)
+        return undefined;
+    const distinct = new Set();
+    let unavailable = 0;
+    for (const video of videos) {
+        if (video.available && video.recording !== undefined)
+            distinct.add(video.recording);
+        else
+            unavailable += 1;
+    }
+    return { references: videos.length, recordings: distinct.size, unavailable };
 }
 /** A role to show when a producer gave none, from the media type: `image`, `video`, `audio`, `snapshot` (text/html), `text` (text, JSON, XML) or `file`. Roles are an open vocabulary; a producer's own role always wins. */
 export function roleOfType(contentType) {

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

@@ -36,6 +36,35 @@ export type BackendInfo = {
 };
 /** How many results have each status (`passed`, `failed`, `running`, `not-run`). */
 export type StatusCounts = Readonly<Record<EvidenceStatus, number>>;
+/** Who holds a recording: the whole layer (or one of its parts), one check, one retry attempt of a check, or one step. */
+export type VideoOwner = 'layer' | 'check' | 'attempt' | 'step';
+/**
+ * One reference to a video, found by its effective media type (the producer's `contentType`, else the one the file
+ * name implies; a `video` role alone counts only when nothing else says what the file is). A reference is not a
+ * recording: the same bytes referenced from three checks are three references and one recording.
+ */
+export type VideoRef = {
+    /** The attachment's name, for a person. */
+    readonly name: string;
+    readonly owner: VideoOwner;
+    /** The try that holds it, when `owner` is `attempt` or the step is inside one. */
+    readonly attempt?: number;
+    /** The name of the step that holds it, when `owner` is `step`. */
+    readonly step?: 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. */
+    readonly available: boolean;
+};
+/** Video availability as counts: references, distinct playable recordings (deduplicated), and references that cannot be played. */
+export type VideoCounts = {
+    /** Every reference to a video, playable or not. */
+    readonly references: number;
+    /** Distinct playable recordings: identical bytes referenced twice are one. */
+    readonly recordings: number;
+    /** References that name no bytes. A report that predates availability metadata has none of these and none of the others. */
+    readonly unavailable: number;
+};
 /**
  * What a result (or a run) carries beyond its outcome, as counts and short facts: attachments, steps,
  * annotations, retries, tags, labels, links. It is only there when there is something. The evidence itself
@@ -50,9 +79,13 @@ export type EvidenceSummary = {
     readonly attempts: number;
     readonly links: number;
     readonly tags: readonly string[];
+    /** The normalized tags of the attachments themselves (`#demo` is `demo`), sorted and distinct. Absent when no attachment is tagged. Unlike `tags` they are never inherited from a check or run. */
+    readonly artifactTags?: readonly string[];
     readonly labels: Readonly<Record<string, string>>;
     /** The distinct roles of its attachments (or what their media types say), to show what kind of evidence there is. */
     readonly roles: readonly string[];
+    /** Its references to videos, wherever they are held (layer, check, attempt, step). Only there when it has any. */
+    readonly videos?: readonly VideoRef[];
 };
 /** A report layer's origin and totals. Its checks are read separately, once. */
 export type LayerHeader = {

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

@@ -1,4 +1,4 @@
-import { summarizeEvidence } from './evidence-detail.js';
+import { summarizeEvidence, summarizeLayerEvidence } from './evidence-detail.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
@@ -94,7 +94,7 @@ export function layerEvidence(summary, backend) {
         }
     }
     const recording = summary.recording;
-    const layerSummaryEvidence = summarizeEvidence(summary, ...summary.parts);
+    const layerSummaryEvidence = summarizeLayerEvidence(summary, ...summary.parts);
     const layer = {
         ...(summary.freshness ? { freshness: summary.freshness } : {}),
         ...(summary.run ? { run: summary.run } : {}),

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

@@ -82,6 +82,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                         height?: number | undefined;
                         durationMs?: number | undefined;
                         description?: string | undefined;
+                        tags?: string[] | undefined;
                         at?: {
                             [x: string]: import("hono/utils/types").JSONValue;
                             step?: string | undefined;
@@ -125,6 +126,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;
@@ -181,6 +183,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -247,6 +250,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -352,6 +356,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -395,6 +400,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                                     height?: number | undefined;
                                     durationMs?: number | undefined;
                                     description?: string | undefined;
+                                    tags?: string[] | undefined;
                                     at?: {
                                         [x: string]: import("hono/utils/types").JSONValue;
                                         step?: string | undefined;
@@ -451,6 +457,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;
@@ -517,6 +524,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;

package/dist/reports/src/reports-route.d.ts

@@ -120,6 +120,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                         height?: number | undefined;
                         durationMs?: number | undefined;
                         description?: string | undefined;
+                        tags?: string[] | undefined;
                         at?: {
                             [x: string]: import("hono/utils/types").JSONValue;
                             step?: string | undefined;
@@ -163,6 +164,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;
@@ -219,6 +221,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -285,6 +288,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -390,6 +394,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -433,6 +438,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                                     height?: number | undefined;
                                     durationMs?: number | undefined;
                                     description?: string | undefined;
+                                    tags?: string[] | undefined;
                                     at?: {
                                         [x: string]: import("hono/utils/types").JSONValue;
                                         step?: string | undefined;
@@ -489,6 +495,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;
@@ -555,6 +562,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;