@crvouga/atlas 0.13.0 → 0.15.0

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

@@ -60,6 +60,20 @@ export type CheckStatus = z.infer<typeof CheckStatusSchema>;
  * changes only with a new `schemaVersion`.
  */
 export declare const FRESHNESS: readonly ["unknown", "modified"];
+/**
+ * The execution a layer belongs to, named by the producer: one invocation of a local or manual run, which several
+ * layers (shards, batches, producers) may share. Presentation and history grouping only: it never takes part in the
+ * slot a result fills, in which result wins, or in a status. Absent, a run is told by its CI run URL, else `branch@sha`.
+ * Within one project, layers that carry the same `id` are one run; a later invocation gets another `id`.
+ */
+export declare const LayerRunSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    startedAtMs: z.ZodOptional<z.ZodNumber>;
+    endedAtMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+/** The execution of a layer, parsed from `LayerRunSchema`. */
+export type LayerRun = z.output<typeof LayerRunSchema>;
 /**
  * A number a check measured, such as a latency or a size, with its unit and an optional allowance. A measurement over
  * its `limit` is reported and never changes the check's status.
@@ -107,6 +121,7 @@ export declare const AttachmentSchema: 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>;
@@ -167,6 +182,7 @@ export declare const StepSchema: 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>;
@@ -234,6 +250,7 @@ export declare const AttemptSchema: 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>;
@@ -278,6 +295,7 @@ export declare const AttemptSchema: 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>;
@@ -341,6 +359,7 @@ export declare const CheckSchema: 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>;
@@ -405,6 +424,7 @@ export declare const CheckSchema: 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>;
@@ -449,6 +469,7 @@ export declare const CheckSchema: 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>;
@@ -500,6 +521,7 @@ export declare const CheckSchema: 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>;
@@ -586,6 +608,7 @@ export declare const ReportPartSchema: 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>;
@@ -649,6 +672,7 @@ export declare const ReportPartSchema: 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>;
@@ -713,6 +737,7 @@ export declare const ReportPartSchema: 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>;
@@ -757,6 +782,7 @@ export declare const ReportPartSchema: 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>;
@@ -808,6 +834,7 @@ export declare const ReportPartSchema: 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>;
@@ -896,6 +923,7 @@ export declare const LayerSourceSchema: 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>;
@@ -960,6 +988,7 @@ export declare const LayerSourceSchema: 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>;
@@ -1004,6 +1033,7 @@ export declare const LayerSourceSchema: 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>;
@@ -1055,6 +1085,7 @@ export declare const LayerSourceSchema: 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>;
@@ -1169,6 +1200,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1211,6 +1243,12 @@ export declare const LayerDocumentSchema: z.ZodObject<{
         unknown: "unknown";
         modified: "modified";
     }>>;
+    run: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        startedAtMs: z.ZodOptional<z.ZodNumber>;
+        endedAtMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
     specs: z.ZodDefault<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         domain: z.ZodString;
@@ -1240,6 +1278,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1303,6 +1342,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1367,6 +1407,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1411,6 +1452,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1462,6 +1504,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1549,6 +1592,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1613,6 +1657,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1657,6 +1702,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1708,6 +1754,7 @@ export declare const LayerDocumentSchema: 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>;
@@ -1835,6 +1882,7 @@ export declare const AttachmentInputSchema: 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>;
@@ -1915,6 +1963,7 @@ export declare const PublishChecksSchema: 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>;
@@ -1970,6 +2019,7 @@ export declare const PublishChecksSchema: 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>;
@@ -2058,6 +2108,7 @@ export declare const PublishChecksSchema: 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>;
@@ -2084,6 +2135,7 @@ export declare const PublishChecksSchema: 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>;
@@ -2109,6 +2161,12 @@ export declare const PublishChecksSchema: z.ZodObject<{
         unknown: "unknown";
         modified: "modified";
     }>>;
+    run: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        startedAtMs: z.ZodOptional<z.ZodNumber>;
+        endedAtMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
     specs: z.ZodDefault<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         domain: z.ZodString;
@@ -2137,6 +2195,7 @@ export declare const PublishChecksSchema: 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>;

package/dist/schema/src/layer.js

@@ -50,6 +50,18 @@ export const CheckStatusSchema = z.enum(CHECK_STATUSES);
  * changes only with a new `schemaVersion`.
  */
 export const FRESHNESS = ['unknown', 'modified'];
+/**
+ * The execution a layer belongs to, named by the producer: one invocation of a local or manual run, which several
+ * layers (shards, batches, producers) may share. Presentation and history grouping only: it never takes part in the
+ * slot a result fills, in which result wins, or in a status. Absent, a run is told by its CI run URL, else `branch@sha`.
+ * Within one project, layers that carry the same `id` are one run; a later invocation gets another `id`.
+ */
+export const LayerRunSchema = z.looseObject({
+    id: z.string().min(1).max(256).describe('The execution\'s identity within a project, chosen by the producer: a UUID, a timestamped name. Layers with the same id are one run; it never changes after it is recorded'),
+    title: z.string().optional().describe('A human name for the run. Presentation only: it is not part of the identity and does not hide the commit or `freshness`'),
+    startedAtMs: z.number().nonnegative().optional().describe('When the execution started, epoch milliseconds'),
+    endedAtMs: z.number().nonnegative().optional().describe('When the execution ended, epoch milliseconds')
+});
 /**
  * A number a check measured, such as a latency or a size, with its unit and an optional allowance. A measurement over
  * its `limit` is reported and never changes the check's status.
@@ -97,6 +109,7 @@ export const AttachmentSchema = z.looseObject({
     height: z.number().nonnegative().optional(),
     durationMs: z.number().nonnegative().optional().describe('For video and audio'),
     description: z.string().optional(),
+    tags: z.array(z.string()).optional().describe('Free labels of this one attachment, such as `demo`: shown as `#demo`, searchable, and normalized by `normalizeTag` (a leading `#` and letter case never matter). Unlike the tags of a check they say nothing about its result'),
     at: MomentSchema.optional(),
     poster: z.string().optional().describe('The `id` of an attachment that stands for this one before it is opened'),
     captions: z.array(z.string()).optional().describe('The `id`s of attachments (WebVTT, SRT) that caption this one'),
@@ -250,6 +263,7 @@ export const LayerDocumentSchema = z.looseObject({
     environment: z.string().nullable().optional().describe('The client that was checked: desktop-web, mobile-web, ios, android, or any other lowercase name'),
     parameters: z.record(z.string(), z.string()).default({}).describe('Other choices that make a result its own slot, such as a device size'),
     freshness: z.enum(FRESHNESS).optional().describe('`modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured'),
+    run: LayerRunSchema.optional().describe('The execution this layer belongs to, when the producer names one (a local or manual run without a CI run URL). Grouping and display only; it never partitions a report or decides a result'),
     specs: z.array(SpecEntrySchema).default([]),
     parts: z.array(ReportPartSchema),
     source: LayerSourceSchema.nullable().default(null),
@@ -272,6 +286,15 @@ function lenientList(value, schema, prepare = (item) => item) {
     });
 }
 const object = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null);
+/** An attachment whose `tags` cannot be read keeps its file: only the tags that are strings are kept. */
+function lenientAttachment(item) {
+    const attachment = object(item);
+    if (!attachment || !('tags' in attachment))
+        return item;
+    const { tags, ...rest } = attachment;
+    const kept = lenientList(tags, z.string());
+    return kept ? { ...rest, tags: kept } : rest;
+}
 function lenientEvidence(holder, nested = []) {
     const out = { ...holder };
     const set = (key, value) => { if (value === undefined)
@@ -283,7 +306,7 @@ function lenientEvidence(holder, nested = []) {
     if ('links' in out)
         set('links', lenientList(out.links, LinkSchema));
     if ('attachments' in out)
-        set('attachments', lenientList(out.attachments, AttachmentSchema));
+        set('attachments', lenientList(out.attachments, AttachmentSchema, lenientAttachment));
     if ('annotations' in out)
         set('annotations', lenientList(out.annotations, AnnotationSchema));
     if ('labels' in out)
@@ -298,6 +321,9 @@ function lenientEvidence(holder, nested = []) {
 }
 function lenientLayer(raw) {
     const layer = lenientEvidence(raw);
+    // The execution only groups and labels: one that cannot be read leaves the layer to the documented grouping, never refuses it.
+    if ('run' in layer && !LayerRunSchema.safeParse(layer.run).success)
+        delete layer.run;
     if (Array.isArray(layer.parts)) {
         layer.parts = layer.parts.map((part) => {
             const found = object(part);
@@ -384,6 +410,7 @@ export const PublishChecksSchema = z.looseObject({
     environment: z.string().nullable().optional(),
     parameters: z.record(z.string(), z.string()).default({}),
     freshness: z.enum(FRESHNESS).optional(),
+    run: LayerRunSchema.optional().describe('Name the execution these checks belong to, so repeated local runs at one commit stay separate runs and shards of one execution stay together'),
     specs: z.array(SpecEntrySchema).default([]),
     tags: evidenceShape.tags,
     labels: evidenceShape.labels,

package/dist/server/src/app.js

@@ -20,6 +20,7 @@ import { combineBackends, summarize } from '../../reports/src/compose.js';
 import { combineEvidence } from '../../reports/src/layer-merge.js';
 import { layerCatalogKey } from '../../reports/src/layer-store.js';
 import { createLayersApp } from '../../reports/src/layers-route.js';
+import { readArtifactTagEntries, recordArtifactTags, ArtifactTagError } from '../../reports/src/artifact-tag-store.js';
 import { publishChecks } from '../../reports/src/publish-checks.js';
 import { reportStatus } from '../../reports/src/report-status.js';
 import { ReportIndex } from '../../reports/src/report-index.js';
@@ -254,7 +255,7 @@ function createProjectApplication(options) {
             name: 'atlas', version: options.version ?? null, role: identity?.role ?? 'read', open: auth.open,
             write: options.write, ready: index.ready, viewers: events.count, time: now(),
             backends: snapshot.backends.map(({ id, label, available }) => ({ id, label, available, write: id === options.write })),
-            ...(({ backends: _unused, ...rest }) => rest)(index.stats()), capabilities: { events: true, ingest: true, store: true, checks: true, status: true, effective: true, live: true, tests: true }
+            ...(({ backends: _unused, ...rest }) => rest)(index.stats()), capabilities: { events: true, ingest: true, store: true, checks: true, status: true, effective: true, live: true, tests: true, artifactTags: true }
         });
     });
     app.get('/api/live', async (c) => c.json({ runs: await live.list() }, 200, { 'cache-control': 'no-store' }));
@@ -440,6 +441,36 @@ function createProjectApplication(options) {
             return problemResponse(404, 'No run has that key.');
         return answer(c, found.version, () => document, () => runMarkdown(document), `run|${key}|${wantsMarkdown(c)}`);
     });
+    // Reviewer tags for attachments: an audit trail of edits kept beside the layers, which they never change. Read
+    // with a read token; an edit needs a publish token in a Bearer header, and is recorded under that token's name.
+    const tagStore = options.liveStore ?? writeBackend.store;
+    // Edits are ordered by time, so two in one millisecond are told apart by moving the later one on.
+    let lastTagAt = 0;
+    const artifactTags = cached(() => readArtifactTagEntries(tagStore), 5_000);
+    app.get('/api/reports/artifact-tags', async (c) => c.json({ schemaVersion: 1, entries: await artifactTags() }, 200, { 'cache-control': 'no-store' }));
+    app.post('/api/reports/artifact-tags', async (c) => {
+        const verdict = auth.check(c.req.raw, 'publish');
+        if (!verdict.ok)
+            return unauthorized(verdict);
+        try {
+            const bytes = await readLimited(c.req.raw, Math.min(limits.json, 64 * 1024));
+            let input;
+            try {
+                input = JSON.parse(new TextDecoder().decode(bytes));
+            }
+            catch {
+                return problemResponse(422, 'The body is not JSON.');
+            }
+            const entry = await recordArtifactTags(tagStore, input, verdict.identity.name, lastTagAt = Math.max(now(), lastTagAt + 1));
+            await artifactTags.invalidate();
+            return c.json(entry, 201, { 'cache-control': 'no-store' });
+        }
+        catch (error) {
+            if (error instanceof ArtifactTagError || error instanceof Refusal)
+                return problemResponse(error.status, error.message);
+            throw error;
+        }
+    });
     app.route('/api/reports', layers);
     // Upload: the store protocol, and a simple JSON way in for anything that can make a request.
     app.route('/api/store', storeApi({

package/dist/server/src/openapi.d.ts

@@ -1,5 +1,5 @@
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
-export declare const API_VERSION = "1.4.0";
+export declare const API_VERSION = "1.5.0";
 /** Who may call an operation: `none` (anyone), or the least role that may (`read` < `publish` < `admin`). */
 export type Role = 'none' | 'read' | 'publish' | 'admin';
 type JsonSchema = Record<string, unknown>;

package/dist/server/src/openapi.js

@@ -14,10 +14,10 @@
  */
 import { z } from 'zod/v4';
 import { ProjectsSchema } from '../../schema/src/project.js';
-import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, RunListSchema, RunDetailSchema } from '../../schema/src/api.js';
+import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, RunListSchema, RunDetailSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema } from '../../schema/src/api.js';
 import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
-export const API_VERSION = '1.4.0';
+export const API_VERSION = '1.5.0';
 /** The JSON Schema of a Zod schema, as OpenAPI 3.1 embeds it. `output` for what the server sends, `input` for what it accepts. */
 function schemaOf(schema, io = 'output') {
     const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { target: 'draft-2020-12', unrepresentable: 'any', io });
@@ -35,6 +35,7 @@ const COMPONENTS = {
     PublishChecks: [PublishChecksSchema.partial({ recordedAtMs: true }), 'input'], ChecksResult: [ChecksResultSchema, 'output'],
     StoreListing: [StoreListingSchema, 'output'], StoreWriteResult: [StoreWriteResultSchema, 'output'],
     Outline: [OutlineSchema, 'output'], EvidencePage: [EvidencePageSchema, 'output'], LayerRows: [LayerRowsSchema, 'output'], CheckDetail: [CheckDetailSchema, 'output'],
+    ArtifactTagEdit: [ArtifactTagEditSchema, 'input'], ArtifactTagEntry: [ArtifactTagEntrySchema, 'output'], ArtifactTags: [ArtifactTagsSchema, 'output'],
     TestCatalog: [TestCatalogSchema, 'output'], CatalogHealth: [CatalogHealthSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], RunList: [RunListSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
     SpecIndex: [SpecIndexSchema, 'output'], ReportSources: [ReportSourcesSchema, 'output'], RunsIndex: [RunsIndexSchema, 'output'],
     RunEvent: [LiveRunSchema, 'output'], HelloEvent: [HelloEventSchema, 'output'], ReportEvent: [ReportEventSchema, 'output'], AtlasChangeEvent: [AtlasChangeSchema, 'output'], PingEvent: [PingEventSchema, 'output']
@@ -271,6 +272,8 @@ const BASE_OPERATIONS = [
             { name: 'domain', in: 'query', description: 'Only tests whose spec is in this domain (`(no spec)` for none). Repeatable or comma-separated.', schema: str },
             { name: 'spec', in: 'query', description: 'Only tests of this spec path. Repeatable or comma-separated.', schema: str, example: 'specs/checkout/pay.feature' },
             { name: 'tag', in: 'query', description: 'Only tests with this tag. Repeatable or comma-separated.', schema: str },
+            { name: 'artifactTag', in: 'query', description: 'Only tests with an attachment tagged this (`demo` and `#demo` are the same tag), not counting tags inherited from a check or run: the exact artifact query. `inherited=1` widens it to the tags inherited from the check and run. Repeatable or comma-separated.', schema: str, example: 'demo' },
+            { name: 'inherited', in: 'query', description: 'With `artifactTag`: `1` also matches the tags an attachment inherits from its check and run, so a recording without a tag of its own under a run tagged `demo` is found. Without it the query is exact.', schema: { type: 'string', enum: ['1', 'true'] } },
             { name: 'run', in: 'query', description: 'Only tests recorded in this run (a `key` from `/api/reports/runs`).', schema: str },
             { name: 'sort', in: 'query', description: 'The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.', schema: { type: 'string', enum: ['spec', 'title', 'recent', 'slowest', 'failures', 'flaky', 'runs'] } },
             { name: 'offset', in: 'query', description: 'Skip this many matching tests.', schema: { type: 'integer', minimum: 0 } },
@@ -305,6 +308,19 @@ const BASE_OPERATIONS = [
         ],
         responses: { '200': json('The test and its history.', 'TestHistory'), '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '400': problem('No `key`.'), '401': UNAUTHORIZED, '404': problem('No test in the report has that key.'), '503': NOT_READY }
     },
+    {
+        route: 'GET /api/reports/artifact-tags', path: '/api/reports/artifact-tags', operationId: 'getArtifactTags', tag: 'Report', role: 'read',
+        summary: 'Reviewer tags of attachments: every recorded edit',
+        description: 'The audit trail of tags that reviewers added to and removed from attachments after upload, oldest first. Each entry says which attachment (`target`), which normalized tags were added and removed, the name of the token that made the edit (`by`, never the token) and when (`atMs`). The layers themselves are never rewritten, so a producer\'s own `tags` on an attachment stay as uploaded; fold the entries (oldest first, the last edit of a tag wins) to get the reviewer tags that stand now. Tags are normalized: `#Demo` and `demo` are `demo`.',
+        responses: { '200': json('The edits.', 'ArtifactTags'), '401': UNAUTHORIZED }
+    },
+    {
+        route: 'POST /api/reports/artifact-tags', path: '/api/reports/artifact-tags', operationId: 'editArtifactTags', tag: 'Report', role: 'publish',
+        summary: 'Tag or untag one attachment after upload',
+        description: 'Records one edit of the reviewer tags of one attachment, by the name of the publish (or admin) token that sends it. It adds an immutable entry to the audit trail and changes nothing else: not the layer, not the movie, not any result. The tags it removes are reviewer tags only; a producer\'s tags are part of the layer and stay. A reader-only token, a browser sign-in box and an anonymous reader are refused. Name the attachment as `artifactRef` does (`id:<id>`, else `key:<bundleKey>`, else `name:<name>`).',
+        body: { description: 'The attachment and the tags to add and remove. At most 20 of each, 64 KiB.', contentType: 'application/json', required: true, schema: ref('ArtifactTagEdit') },
+        responses: { '201': json('The recorded entry.', 'ArtifactTagEntry'), '401': UNAUTHORIZED, '403': FORBIDDEN, '413': problem('Request too large.'), '422': problem('Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.') }
+    },
     {
         route: 'GET /api/reports/runs', path: '/api/reports/runs', operationId: 'getReportRuns', tag: 'Report', role: 'read',
         summary: 'The runs that recorded the report',

package/docs/extending.md

@@ -35,6 +35,9 @@ carry any of these. Every one is optional.
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |
 | `measurements[]` | Numbers, with units and an allowance (already part of the contract). |
 
+An attachment may carry its own `tags[]` (`demo`): shown as `#demo` and searchable; see
+[Tagging artifacts and demos](rich-evidence.md#tagging-artifacts-and-demos).
+
 On a **layer** the same fields describe the whole run: its CI log, a coverage report, an archive of traces, the
 build number, a link to the pipeline.
 

package/docs/integrating.md

@@ -95,6 +95,14 @@ first commit, they are `null`: that is provenance missing, not an error, and nev
 result wins. `--param key=value` (repeatable) adds a parameter that makes a result its own slot, such
 as `--param device=iphone-15`.
 
+Without a CI run URL, layers recorded at one branch and commit group into one run, so repeating a local demo
+looks like one execution. To keep invocations apart, name each one: `--run-id <id>` (or `ATLAS_RUN_ID`), with
+`--run-title <title>` (or `ATLAS_RUN_TITLE`) for a human name and `--run-started-at` / `--run-ended-at` for when
+it ran. Every shard or batch of one invocation passes the same id and is one run; the next invocation passes a new
+one. A run recorded from a checkout with uncommitted changes keeps saying so beside its commit. The id only
+groups: it is not part of which result a check fills or which wins, and a producer that never passes it keeps
+the CI-run-URL, then `branch@sha`, grouping.
+
 The time the checks ran comes from the report (CTRF `summary.stop`, a JUnit `timestamp`, a manifest's
 `finishedAt`), or failing that from the report file's modification time, in milliseconds. Publish in
 the same job that wrote the report and that is the time it ran. If you copy the report first, pass

package/docs/reference/cli.md

@@ -86,12 +86,14 @@ atlas report — layered evidence for any kind of spec
   atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]
                        ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )
                        [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]
+                       [--run-id <id>] [--run-title <t>] [--run-started-at <iso|ms>] [--run-ended-at <iso|ms>]
                        [--spec <path> | --specs <dir>] [--upload-run]
                        [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]
                        [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...
                        [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]
   atlas report stream  [--store <dir|s3://…|https://atlas.example.com>] --producer <name> [--environment <name>]
                        [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...
+                       [--run-id <id>] [--run-title <t>]
                        [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)
   atlas report status  [--store <dir|s3://…|id=url>]... [--backends <module>]
                        [--specs <dir>] [--format text|json|markdown]
@@ -112,6 +114,11 @@ atlas report — layered evidence for any kind of spec
             --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or
                             file name the report gives; also publishes the specs themselves, so the
                             node can show them without a checkout
+            --run-id <id>   name this execution (a local or manual run with no CI run URL; also ATLAS_RUN_ID).
+                            Layers that share an id are one run, however many shards or batches uploaded them;
+                            another invocation at the same commit gets another id. Never part of what a check is
+            --run-title <t> a human name for the run (also ATLAS_RUN_TITLE); --run-started-at and --run-ended-at
+                            record when it ran. Without --run-id a run is its CI run URL, else branch@sha
             --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer
             --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive
                               (screenshots, videos and traces of a single test go in its CTRF or checks file)

package/docs/reference/http-api.md

@@ -467,6 +467,8 @@ Send `format=markdown` (or `Accept: text/markdown`) for the same as a Markdown r
 - `domain` (query): Only tests whose spec is in this domain (`(no spec)` for none). Repeatable or comma-separated.
 - `spec` (query): Only tests of this spec path. Repeatable or comma-separated.
 - `tag` (query): Only tests with this tag. Repeatable or comma-separated.
+- `artifactTag` (query): Only tests with an attachment tagged this (`demo` and `#demo` are the same tag), not counting tags inherited from a check or run: the exact artifact query. `inherited=1` widens it to the tags inherited from the check and run. Repeatable or comma-separated.
+- `inherited` (query): With `artifactTag`: `1` also matches the tags an attachment inherits from its check and run, so a recording without a tag of its own under a run tagged `demo` is found. Without it the query is exact.
 - `run` (query): Only tests recorded in this run (a `key` from `/api/reports/runs`).
 - `sort` (query): The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.
 - `offset` (query): Skip this many matching tests.
@@ -496,6 +498,8 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 - `domain` (query): Only tests whose spec is in this domain (`(no spec)` for none). Repeatable or comma-separated.
 - `spec` (query): Only tests of this spec path. Repeatable or comma-separated.
 - `tag` (query): Only tests with this tag. Repeatable or comma-separated.
+- `artifactTag` (query): Only tests with an attachment tagged this (`demo` and `#demo` are the same tag), not counting tags inherited from a check or run: the exact artifact query. `inherited=1` widens it to the tags inherited from the check and run. Repeatable or comma-separated.
+- `inherited` (query): With `artifactTag`: `1` also matches the tags an attachment inherits from its check and run, so a recording without a tag of its own under a run tagged `demo` is found. Without it the query is exact.
 - `run` (query): Only tests recorded in this run (a `key` from `/api/reports/runs`).
 - `sort` (query): The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.
 - `offset` (query): Skip this many matching tests.
@@ -564,6 +568,50 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `200` The test and its history.; `304` Unchanged since the `If-None-Match` ETag.; `400` No `key`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No test in the report has that key.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
 
+### Reviewer tags of attachments: every recorded edit
+
+`GET /api/reports/artifact-tags` · role: read
+
+The audit trail of tags that reviewers added to and removed from attachments after upload, oldest first. Each entry says which attachment (`target`), which normalized tags were added and removed, the name of the token that made the edit (`by`, never the token) and when (`atMs`). The layers themselves are never rewritten, so a producer's own `tags` on an attachment stay as uploaded; fold the entries (oldest first, the last edit of a tag wins) to get the reviewer tags that stand now. Tags are normalized: `#Demo` and `demo` are `demo`.
+
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The edits.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Reviewer tags of attachments: every recorded edit
+
+`GET /api/projects/{project}/reports/artifact-tags` · role: read
+
+The audit trail of tags that reviewers added to and removed from attachments after upload, oldest first. Each entry says which attachment (`target`), which normalized tags were added and removed, the name of the token that made the edit (`by`, never the token) and when (`atMs`). The layers themselves are never rewritten, so a producer's own `tags` on an attachment stay as uploaded; fold the entries (oldest first, the last edit of a tag wins) to get the reviewer tags that stand now. Tags are normalized: `#Demo` and `demo` are `demo`.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The edits.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Tag or untag one attachment after upload
+
+`POST /api/reports/artifact-tags` · role: publish
+
+Records one edit of the reviewer tags of one attachment, by the name of the publish (or admin) token that sends it. It adds an immutable entry to the audit trail and changes nothing else: not the layer, not the movie, not any result. The tags it removes are reviewer tags only; a producer's tags are part of the layer and stay. A reader-only token, a browser sign-in box and an anonymous reader are refused. Name the attachment as `artifactRef` does (`id:<id>`, else `key:<bundleKey>`, else `name:<name>`).
+
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `201` The recorded entry.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `413` Request too large.; `422` Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.
+
+### Tag or untag one attachment after upload
+
+`POST /api/projects/{project}/reports/artifact-tags` · role: publish
+
+Records one edit of the reviewer tags of one attachment, by the name of the publish (or admin) token that sends it. It adds an immutable entry to the audit trail and changes nothing else: not the layer, not the movie, not any result. The tags it removes are reviewer tags only; a producer's tags are part of the layer and stay. A reader-only token, a browser sign-in box and an anonymous reader are refused. Name the attachment as `artifactRef` does (`id:<id>`, else `key:<bundleKey>`, else `name:<name>`).
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `201` The recorded entry.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `413` Request too large.; `422` Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.
+
 ### The runs that recorded the report
 
 `GET /api/reports/runs` · role: read