@crvouga/atlas 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog: @crvouga/atlas
 
+## 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

@@ -33,7 +33,7 @@ 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
+ * 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.
  */
 export declare function summarizeEvidence(...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined;

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,7 +10,7 @@ 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
+ * 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.
  */
 export function summarizeEvidence(...holders) {
@@ -17,10 +18,13 @@ export function summarizeEvidence(...holders) {
         return undefined;
     const roles = new Set();
     const tags = new Set();
+    const artifactTags = new Set();
     const labels = {};
     let attachments = 0, steps = 0, annotations = 0, attempts = 0, links = 0;
     const attachmentsOf = (list) => { 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)));
     } };
     for (const holder of holders) {
@@ -41,7 +45,7 @@ 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() };
 }
 /** 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

@@ -50,6 +50,8 @@ 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[];

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;

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

@@ -1,25 +1,3 @@
-/**
- * @module Test catalog, history and runs
- *
- * What a person or an agent asks of a report once it holds more than a handful of checks: every test with where it ran,
- * how it went over time and how long it takes; the specs, domains, environments and producers they fall under; the CI
- * runs that produced them and which tests each one ran.
- *
- * - `TestHistory` keeps every recorded result of every test (bounded per test) and every run's results, folded in one
- *   layer at a time, in any order, with the same outcome. It never decides a status: the current status of a test is
- *   always the report's winner (`combineEvidence`), and history only describes how it got there.
- * - `testCatalog` turns the report's winners (plus a history, when there is one) into a `TestCatalog`: a summary with
- *   insights (slowest, flaky, failing), facets to filter by, and the tests that match a `TestQuery`.
- * - `testHistory`, `runList` and `runDetail` answer for one test, every run, and one run.
- * - `catalogMarkdown`, `historyMarkdown`, `runsMarkdown` and `runMarkdown` say the same in Markdown, for an agent or a
- *   terminal.
- *
- * A test is a check identity (its spec path and id) regardless of producer, environment and parameters; each of those
- * combinations is one of its results. A result that is not `passed` is never counted as a pass, and a test with no
- * completed result has no pass rate.
- *
- * @see docs/server.md#reading-the-report-as-an-agent
- */
 import type { EvidenceStatus, SpecEntry } from './explorer-types.js';
 import type { EvidenceSummary, LayerEvidence, LayerHeader, LayerRow, StatusCounts } from './evidence-types.js';
 import { RecordedSpecs } from './recorded-specs.js';
@@ -116,6 +94,10 @@ export type TestSummary = {
     readonly outcomes: readonly TestOutcome[];
     readonly stats: TestStats;
     readonly tags: readonly string[];
+    /** The normalized tags of the attachments of its current results (`demo`, shown as `#demo`). Never inherited from a check or run; the `tags` above are. Absent in documents of older servers. */
+    readonly artifactTags?: readonly string[];
+    /** The normalized tags its attachments inherit from their check and run (those of the results that have attachments), apart from `artifactTags`. What an inherited artifact query also matches. */
+    readonly inheritedArtifactTags?: readonly string[];
     readonly labels: Readonly<Record<string, string>>;
     /** What its current results carry: attachments, steps, retries, and the kinds of attachment. */
     readonly evidence: {
@@ -187,6 +169,8 @@ export type CatalogFacets = {
         readonly counts: StatusCounts;
     })[];
     readonly tags: readonly FacetValue[];
+    /** The tags of attachments, normalized. Absent in documents of older servers. */
+    readonly artifactTags?: readonly FacetValue[];
     readonly branches: readonly FacetValue[];
     readonly labels: Readonly<Record<string, readonly FacetValue[]>>;
 };
@@ -206,6 +190,10 @@ export type TestQuery = {
     /** Spec paths (`specs/...`). */
     readonly spec?: readonly string[];
     readonly tag?: readonly string[];
+    /** Only tests with an attachment carrying this tag (`demo` and `#demo` are the same), not counting tags inherited from a check or run: the exact artifact query. `tag` is the inherited one. */
+    readonly artifactTag?: readonly string[];
+    /** With `artifactTag`: also match the tags an attachment inherits from its check and run (a recording without a tag of its own under a run tagged `demo`). Default false: the exact query. */
+    readonly inherited?: boolean;
     /** Only tests recorded in this run (a key from `runList`). */
     readonly run?: string;
     readonly sort?: TestSort;
@@ -396,7 +384,7 @@ export declare function testHistory(model: CatalogModel, key: string): TestHisto
 export declare function runList(history: TestHistory, version: string, limit?: number): RunList;
 /** 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`. */
+/** 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`. */
 export declare function parseTestQuery(params: URLSearchParams): TestQuery;
 /** A duration for a person: `850 ms`, `12.3 s`, `4m 05s`. */
 export declare function formatMs(ms: number | null | undefined): string;