@crvouga/atlas 0.14.0 → 0.15.0

package/dist/reports/src/test-catalog.js

@@ -1,3 +1,26 @@
+/**
+ * @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 { displayTag, normalizeTag, normalizeTags } from './artifact-tags.js';
 import { checkSlots } from './evidence-view.js';
 import { combineEvidence, emptyCounts, slotKey, specPath as normalSpecPath } from './layer-merge.js';
 import { RecordedSpecs } from './recorded-specs.js';
@@ -337,15 +360,22 @@ function outcomeOf(result) {
 function summaryOf(slot, history, known) {
     const outcomes = slot.outcomes.map(outcomeOf);
     const tags = new Set();
+    const artifactTags = new Set();
+    const inheritedTags = new Set();
     const labels = {};
     let attachments = 0, steps = 0, attempts = 0;
     const roles = new Set();
-    for (const outcome of outcomes) {
+    for (const [at, outcome] of outcomes.entries()) {
         const evidence = outcome.evidence;
         if (!evidence)
             continue;
+        if (evidence.attachments > 0)
+            for (const tag of normalizeTags([...evidence.tags, ...(slot.outcomes[at]?.layer.evidence?.tags ?? [])]))
+                inheritedTags.add(tag);
         for (const tag of evidence.tags)
             tags.add(tag);
+        for (const tag of evidence.artifactTags ?? [])
+            artifactTags.add(tag);
         Object.assign(labels, evidence.labels);
         attachments += evidence.attachments;
         steps += evidence.steps;
@@ -366,6 +396,8 @@ function summaryOf(slot, history, known) {
         outcomes,
         stats: statsOf(history?.of(slot.key) ?? [], outcomes, tagList, labels),
         tags: tagList,
+        ...(artifactTags.size ? { artifactTags: [...artifactTags].sort() } : {}),
+        ...([...inheritedTags].some(tag => !artifactTags.has(tag)) ? { inheritedArtifactTags: [...inheritedTags].filter(tag => !artifactTags.has(tag)).sort() } : {}),
         labels,
         evidence: { attachments, steps, attempts, roles: [...roles].sort() },
         lastRecordedAtMs: slot.latestAtMs,
@@ -375,7 +407,7 @@ function summaryOf(slot, history, known) {
 /** The lowercase text a search matches a test against: title, id, spec, domain, tags, labels, environments and producers. */
 export function haystackOf(test) {
     return [
-        test.title, test.id, test.specPath ?? '', test.spec?.title ?? '', test.spec?.domain ?? '', ...test.tags,
+        test.title, test.id, test.specPath ?? '', test.spec?.title ?? '', test.spec?.domain ?? '', ...test.tags, ...(test.artifactTags ?? []).map(displayTag),
         ...Object.entries(test.labels).flatMap(([key, value]) => [key, value]), ...test.environments, ...test.producers,
     ].join('\n').toLowerCase();
 }
@@ -481,6 +513,7 @@ export function catalogModel(layers, sources = {}) {
         domains: facet(tests, test => [test.spec?.domain || '(no spec)']),
         specs: [...specGroups].map(([, list]) => { const g = group(list[0].spec.path, list); return { ...list[0].spec, tests: g.tests, counts: g.counts }; }).sort((a, b) => compareText(a.domain, b.domain) || compareText(a.title, b.title)),
         tags: facet(tests, test => test.tags),
+        artifactTags: facet(tests, test => test.artifactTags ?? []),
         branches: facet(tests, test => test.stats.branches),
         labels: Object.fromEntries([...labelKeys].sort().map(key => [key, facet(tests, test => (test.labels[key] === undefined ? [] : [test.labels[key]]))])),
     };
@@ -515,6 +548,8 @@ export function matchesQuery(model, test, query, inRun) {
         return false;
     if (query.tag?.length && !query.tag.some(tag => test.tags.includes(tag)))
         return false;
+    if (query.artifactTag?.length && !query.artifactTag.some(tag => { const wanted = normalizeTag(tag); return wanted !== null && ((test.artifactTags?.includes(wanted) ?? false) || (query.inherited === true && (test.inheritedArtifactTags?.includes(wanted) ?? false))); }))
+        return false;
     if (inRun && !inRun.has(test.key))
         return false;
     return true;
@@ -546,7 +581,7 @@ export function runDetail(history, version, key) {
     const found = history.run(key);
     return found ? { schemaVersion: TEST_CATALOG_VERSION, version, ...found } : 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 function parseTestQuery(params) {
     const many = (name) => params.getAll(name).flatMap(value => value.split(',')).map(value => value.trim()).filter(Boolean);
     const number = (name) => { const value = params.get(name); return value !== null && /^\d+$/.test(value) ? Number(value) : undefined; };
@@ -555,11 +590,13 @@ export function parseTestQuery(params) {
     const q = params.get('q');
     if (q)
         query.q = q;
-    for (const name of ['status', 'environment', 'producer', 'domain', 'spec', 'tag']) {
+    for (const name of ['status', 'environment', 'producer', 'domain', 'spec', 'tag', 'artifactTag']) {
         const values = many(name);
         if (values.length)
             query[name] = values;
     }
+    if (['1', 'true'].includes(params.get('inherited') ?? ''))
+        query.inherited = true;
     const run = params.get('run');
     if (run)
         query.run = run;
@@ -633,6 +670,7 @@ export function historyMarkdown(document) {
         `- Results: ${test.stats.results} recorded, ${test.stats.passed} passed, ${test.stats.failed} failed${test.stats.passRate === null ? '' : `, pass rate ${Math.round(test.stats.passRate * 100)}%`}, in ${test.stats.runs} runs`,
         `- Duration: ${d ? `avg ${formatMs(d.avgMs)}, p50 ${formatMs(d.p50Ms)}, p95 ${formatMs(d.p95Ms)}, min ${formatMs(d.minMs)}, max ${formatMs(d.maxMs)}, last ${formatMs(d.lastMs)}` : 'not measured'}`,
         ...(test.tags.length ? [`- Tags: ${test.tags.join(', ')}`] : []),
+        ...(test.artifactTags?.length ? [`- Artifact tags: ${test.artifactTags.map(displayTag).join(', ')}`] : []),
         ...(Object.keys(test.labels).length ? [`- Labels: ${Object.entries(test.labels).map(([k, v]) => `${k}=${v}`).join(', ')}`] : []),
         `- Evidence: ${test.evidence.attachments} attachments${test.evidence.roles.length ? ` (${test.evidence.roles.join(', ')})` : ''}, ${test.evidence.steps} steps`,
         '',

package/dist/schema/src/api.d.ts

@@ -88,6 +88,7 @@ export declare const EvidenceSummarySchema: z.ZodObject<{
     attempts: z.ZodNumber;
     links: z.ZodNumber;
     tags: z.ZodArray<z.ZodString>;
+    artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     labels: z.ZodRecord<z.ZodString, z.ZodString>;
     roles: z.ZodArray<z.ZodString>;
 }, z.core.$loose>;
@@ -129,6 +130,7 @@ export declare const LayerHeaderSchema: z.ZodObject<{
         attempts: z.ZodNumber;
         links: z.ZodNumber;
         tags: z.ZodArray<z.ZodString>;
+        artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         labels: z.ZodRecord<z.ZodString, z.ZodString>;
         roles: z.ZodArray<z.ZodString>;
     }, z.core.$loose>>;
@@ -162,6 +164,7 @@ export declare const LayerRowSchema: z.ZodObject<{
         attempts: z.ZodNumber;
         links: z.ZodNumber;
         tags: z.ZodArray<z.ZodString>;
+        artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         labels: z.ZodRecord<z.ZodString, z.ZodString>;
         roles: z.ZodArray<z.ZodString>;
     }, z.core.$loose>>;
@@ -197,6 +200,7 @@ export declare const LayerRowsSchema: z.ZodObject<{
             attempts: z.ZodNumber;
             links: z.ZodNumber;
             tags: z.ZodArray<z.ZodString>;
+            artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
         }, z.core.$loose>>;
@@ -234,6 +238,7 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
             attempts: z.ZodNumber;
             links: z.ZodNumber;
             tags: z.ZodArray<z.ZodString>;
+            artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
         }, z.core.$loose>>;
@@ -276,6 +281,7 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
             attempts: z.ZodNumber;
             links: z.ZodNumber;
             tags: z.ZodArray<z.ZodString>;
+            artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
         }, z.core.$loose>>;
@@ -318,6 +324,7 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                 attempts: z.ZodNumber;
                 links: z.ZodNumber;
                 tags: z.ZodArray<z.ZodString>;
+                artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
             }, z.core.$loose>>;
@@ -360,6 +367,7 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                 attempts: z.ZodNumber;
                 links: z.ZodNumber;
                 tags: z.ZodArray<z.ZodString>;
+                artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
             }, z.core.$loose>>;
@@ -423,6 +431,7 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                 attempts: z.ZodNumber;
                 links: z.ZodNumber;
                 tags: z.ZodArray<z.ZodString>;
+                artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
             }, z.core.$loose>>;
@@ -465,6 +474,7 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                 attempts: z.ZodNumber;
                 links: z.ZodNumber;
                 tags: z.ZodArray<z.ZodString>;
+                artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
             }, z.core.$loose>>;
@@ -531,6 +541,7 @@ export declare const EvidencePageSchema: z.ZodObject<{
             attempts: z.ZodNumber;
             links: z.ZodNumber;
             tags: z.ZodArray<z.ZodString>;
+            artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
         }, z.core.$loose>>;
@@ -573,6 +584,7 @@ export declare const CheckDetailSchema: z.ZodObject<{
                 height: z.ZodOptional<z.ZodNumber>;
                 durationMs: z.ZodOptional<z.ZodNumber>;
                 description: z.ZodOptional<z.ZodString>;
+                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 at: z.ZodOptional<z.ZodObject<{
                     step: z.ZodOptional<z.ZodString>;
                     offsetMs: z.ZodOptional<z.ZodNumber>;
@@ -637,6 +649,7 @@ export declare const CheckDetailSchema: z.ZodObject<{
                     height: z.ZodOptional<z.ZodNumber>;
                     durationMs: z.ZodOptional<z.ZodNumber>;
                     description: z.ZodOptional<z.ZodString>;
+                    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     at: z.ZodOptional<z.ZodObject<{
                         step: z.ZodOptional<z.ZodString>;
                         offsetMs: z.ZodOptional<z.ZodNumber>;
@@ -681,6 +694,7 @@ export declare const CheckDetailSchema: z.ZodObject<{
                 height: z.ZodOptional<z.ZodNumber>;
                 durationMs: z.ZodOptional<z.ZodNumber>;
                 description: z.ZodOptional<z.ZodString>;
+                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 at: z.ZodOptional<z.ZodObject<{
                     step: z.ZodOptional<z.ZodString>;
                     offsetMs: z.ZodOptional<z.ZodNumber>;
@@ -732,6 +746,7 @@ export declare const CheckDetailSchema: z.ZodObject<{
             height: z.ZodOptional<z.ZodNumber>;
             durationMs: z.ZodOptional<z.ZodNumber>;
             description: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             at: z.ZodOptional<z.ZodObject<{
                 step: z.ZodOptional<z.ZodString>;
                 offsetMs: z.ZodOptional<z.ZodNumber>;
@@ -799,6 +814,55 @@ export declare const ChecksResultSchema: z.ZodObject<{
     id: z.ZodString;
     checks: z.ZodNumber;
 }, z.core.$loose>;
+/** Which attachment a reviewer's tags belong to: one attachment of one check of one archived layer. */
+export declare const ArtifactTargetSchema: z.ZodObject<{
+    layer: z.ZodString;
+    check: z.ZodString;
+    kind: z.ZodOptional<z.ZodString>;
+    artifact: z.ZodString;
+}, z.core.$loose>;
+/** The body of `POST /api/reports/artifact-tags`: tags to add to and to remove from one attachment. At least one tag overall. */
+export declare const ArtifactTagEditSchema: z.ZodObject<{
+    target: z.ZodObject<{
+        layer: z.ZodString;
+        check: z.ZodString;
+        kind: z.ZodOptional<z.ZodString>;
+        artifact: z.ZodString;
+    }, z.core.$loose>;
+    add: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    remove: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+/** One recorded edit of an attachment's reviewer tags. Entries are never changed or removed: they are the audit trail. */
+export declare const ArtifactTagEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    target: z.ZodObject<{
+        layer: z.ZodString;
+        check: z.ZodString;
+        kind: z.ZodOptional<z.ZodString>;
+        artifact: z.ZodString;
+    }, z.core.$loose>;
+    add: z.ZodArray<z.ZodString>;
+    remove: z.ZodArray<z.ZodString>;
+    by: z.ZodString;
+    atMs: z.ZodNumber;
+}, z.core.$loose>;
+/** `GET /api/reports/artifact-tags`: every recorded edit, oldest first. Fold them with `foldArtifactTags`. */
+export declare const ArtifactTagsSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        target: z.ZodObject<{
+            layer: z.ZodString;
+            check: z.ZodString;
+            kind: z.ZodOptional<z.ZodString>;
+            artifact: z.ZodString;
+        }, z.core.$loose>;
+        add: z.ZodArray<z.ZodString>;
+        remove: z.ZodArray<z.ZodString>;
+        by: z.ZodString;
+        atMs: z.ZodNumber;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
 /** The data of the `hello` event: sent first on `/api/events`. */
 export declare const HelloEventSchema: z.ZodObject<{
     version: z.ZodString;
@@ -856,6 +920,7 @@ export declare const TestResultEntrySchema: z.ZodObject<{
         attempts: z.ZodNumber;
         links: z.ZodNumber;
         tags: z.ZodArray<z.ZodString>;
+        artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         labels: z.ZodRecord<z.ZodString, z.ZodString>;
         roles: z.ZodArray<z.ZodString>;
     }, z.core.$loose>>;
@@ -907,6 +972,7 @@ export declare const TestSummarySchema: z.ZodObject<{
             attempts: z.ZodNumber;
             links: z.ZodNumber;
             tags: z.ZodArray<z.ZodString>;
+            artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
         }, z.core.$loose>>;
@@ -937,6 +1003,8 @@ export declare const TestSummarySchema: z.ZodObject<{
         branches: z.ZodArray<z.ZodString>;
     }, z.core.$loose>;
     tags: z.ZodArray<z.ZodString>;
+    artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    inheritedArtifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     labels: z.ZodRecord<z.ZodString, z.ZodString>;
     evidence: z.ZodObject<{
         attachments: z.ZodNumber;
@@ -1084,6 +1152,10 @@ export declare const TestCatalogSchema: z.ZodObject<{
             value: z.ZodString;
             count: z.ZodNumber;
         }, z.core.$loose>>;
+        artifactTags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>>;
         branches: z.ZodArray<z.ZodObject<{
             value: z.ZodString;
             count: z.ZodNumber;
@@ -1142,6 +1214,7 @@ export declare const TestCatalogSchema: z.ZodObject<{
                 attempts: z.ZodNumber;
                 links: z.ZodNumber;
                 tags: z.ZodArray<z.ZodString>;
+                artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
             }, z.core.$loose>>;
@@ -1172,6 +1245,8 @@ export declare const TestCatalogSchema: z.ZodObject<{
             branches: z.ZodArray<z.ZodString>;
         }, z.core.$loose>;
         tags: z.ZodArray<z.ZodString>;
+        artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        inheritedArtifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         labels: z.ZodRecord<z.ZodString, z.ZodString>;
         evidence: z.ZodObject<{
             attachments: z.ZodNumber;
@@ -1312,6 +1387,7 @@ export declare const TestHistorySchema: z.ZodObject<{
                 attempts: z.ZodNumber;
                 links: z.ZodNumber;
                 tags: z.ZodArray<z.ZodString>;
+                artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 labels: z.ZodRecord<z.ZodString, z.ZodString>;
                 roles: z.ZodArray<z.ZodString>;
             }, z.core.$loose>>;
@@ -1342,6 +1418,8 @@ export declare const TestHistorySchema: z.ZodObject<{
             branches: z.ZodArray<z.ZodString>;
         }, z.core.$loose>;
         tags: z.ZodArray<z.ZodString>;
+        artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        inheritedArtifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         labels: z.ZodRecord<z.ZodString, z.ZodString>;
         evidence: z.ZodObject<{
             attachments: z.ZodNumber;
@@ -1379,6 +1457,7 @@ export declare const TestHistorySchema: z.ZodObject<{
             attempts: z.ZodNumber;
             links: z.ZodNumber;
             tags: z.ZodArray<z.ZodString>;
+            artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             labels: z.ZodRecord<z.ZodString, z.ZodString>;
             roles: z.ZodArray<z.ZodString>;
         }, z.core.$loose>>;

package/dist/schema/src/api.js

@@ -70,6 +70,7 @@ export const EvidenceSummarySchema = z.looseObject({
     attempts: z.number().int().nonnegative(),
     links: z.number().int().nonnegative(),
     tags: z.array(z.string()),
+    artifactTags: z.array(z.string()).optional().describe('Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run'),
     labels: z.record(z.string(), z.string()),
     roles: z.array(z.string())
 });
@@ -186,6 +187,33 @@ export const ChecksResultSchema = z.looseObject({
     id: z.string().describe('The layer id'),
     checks: z.number().int().nonnegative()
 });
+/** Which attachment a reviewer's tags belong to: one attachment of one check of one archived layer. */
+export const ArtifactTargetSchema = z.looseObject({
+    layer: z.string().regex(/^[0-9a-f]{64}$/).describe('The id of the archived layer that holds the check'),
+    check: z.string().min(1).describe('The check\'s id'),
+    kind: z.string().min(1).optional().describe('The kind of the part holding the check, when the same id exists in several parts'),
+    artifact: z.string().min(1).max(1024).describe('The attachment: `id:<id>` when it has an id, else `key:<bundleKey>`, else `name:<name>` (see `artifactRef`)')
+});
+/** The body of `POST /api/reports/artifact-tags`: tags to add to and to remove from one attachment. At least one tag overall. */
+export const ArtifactTagEditSchema = z.looseObject({
+    target: ArtifactTargetSchema,
+    add: z.array(z.string()).max(20).optional().describe('Tags to add. `demo` and `#demo` are the same tag'),
+    remove: z.array(z.string()).max(20).optional().describe('Reviewer tags to remove. Tags the producer wrote are part of the immutable layer and stay')
+});
+/** One recorded edit of an attachment's reviewer tags. Entries are never changed or removed: they are the audit trail. */
+export const ArtifactTagEntrySchema = z.looseObject({
+    id: z.string().describe('Unique and time-ordered'),
+    target: ArtifactTargetSchema,
+    add: z.array(z.string()).describe('Normalized tags added'),
+    remove: z.array(z.string()).describe('Normalized tags removed'),
+    by: z.string().describe('The name of the token that made the edit (never the token)'),
+    atMs: z.number().describe('When the server recorded it, epoch milliseconds')
+});
+/** `GET /api/reports/artifact-tags`: every recorded edit, oldest first. Fold them with `foldArtifactTags`. */
+export const ArtifactTagsSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    entries: z.array(ArtifactTagEntrySchema)
+});
 /** The data of the `hello` event: sent first on `/api/events`. */
 export const HelloEventSchema = z.looseObject({ version: z.string(), ready: z.boolean(), time: z.number(), heartbeatMs: z.number().positive().optional() });
 /** The data of the `report` event: layers arrived. Enough to say who sent what, without asking. */
@@ -243,6 +271,8 @@ export const TestSummarySchema = z.looseObject({
         runs: z.number().int().nonnegative(), branches: z.array(z.string())
     }),
     tags: z.array(z.string()),
+    artifactTags: z.array(z.string()).optional().describe('Normalized tags of the attachments of its current results, such as `demo` (shown `#demo`). Not inherited from a check or run, unlike `tags`'),
+    inheritedArtifactTags: z.array(z.string()).optional().describe('Normalized tags its attachments inherit from their check and run, apart from `artifactTags`: what `?artifactTag=…&inherited=1` also matches'),
     labels: z.record(z.string(), z.string()),
     evidence: z.looseObject({ attachments: z.number().int().nonnegative(), steps: z.number().int().nonnegative(), attempts: z.number().int().nonnegative(), roles: z.array(z.string()) }),
     lastRecordedAtMs: z.number(),
@@ -269,7 +299,7 @@ export const TestCatalogSchema = z.looseObject({
     facets: z.looseObject({
         statuses: z.array(FacetValueSchema), environments: z.array(FacetValueSchema), producers: z.array(FacetValueSchema), domains: z.array(FacetValueSchema),
         specs: z.array(CatalogSpecSchema.extend({ tests: z.number().int().nonnegative(), counts: StatusCountsSchema })),
-        tags: z.array(FacetValueSchema), branches: z.array(FacetValueSchema), labels: z.record(z.string(), z.array(FacetValueSchema))
+        tags: z.array(FacetValueSchema), artifactTags: z.array(FacetValueSchema).optional(), branches: z.array(FacetValueSchema), labels: z.record(z.string(), z.array(FacetValueSchema))
     }),
     total: z.number().int().nonnegative().describe('Tests the query matched, before offset and limit'),
     offset: z.number().int().nonnegative(),