@crvouga/atlas 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+- identify local demo executions separately from branch and commit ([543bf9f](https://github.com/crvouga/atlas/commit/543bf9f00bacb3deb5d32d78c3b61437e04497df))
+
 ## 0.13.0 (2026-10-28)
 
 ### Features

package/dist/playwright-reporter/src/index.d.ts

@@ -35,6 +35,17 @@ export type AtlasPlaywrightReporterOptions = {
     readonly branch?: string;
     /** Where to read the CI run. Default the GitHub Actions run (or the CI's own run URL variable). */
     readonly runUrl?: string;
+    /**
+     * Names this execution, for a local or manual run with no CI run URL: every shard and project that gets the same `id`
+     * is one run, and the next invocation gets another. Default: `ATLAS_RUN_ID` (and `ATLAS_RUN_TITLE`) when set. Only
+     * groups and labels runs; it never changes what a check is or which result wins.
+     */
+    readonly run?: {
+        readonly id: string;
+        readonly title?: string;
+        readonly startedAtMs?: number;
+        readonly endedAtMs?: number;
+    };
     /** The spec a test belongs to, relative to the repository. Default: the `.feature` of a playwright-bdd test, else the test file. */
     readonly specPath?: (test: TestCase) => string | undefined;
     /** Paths are relative to this directory. Default the git root above Playwright's `rootDir`, else `rootDir`. */

package/dist/playwright-reporter/src/index.js

@@ -123,15 +123,16 @@ export default class AtlasPlaywrightReporter {
         }
         if (!this.store)
             return;
+        const run = options.run ?? (env.ATLAS_RUN_ID ? { id: env.ATLAS_RUN_ID, ...(env.ATLAS_RUN_TITLE ? { title: env.ATLAS_RUN_TITLE } : {}) } : undefined);
         try {
             const explicitSha = options.sha ?? env.ATLAS_SHA;
             const origin = detectOrigin(env);
             const sha = explicitSha ?? origin.sha;
             const freshness = detectFreshness({ sha, ci: origin.ci && !explicitSha });
-            this.identity = { sha, branch: options.branch ?? env.ATLAS_BRANCH ?? origin.branch, runUrl: options.runUrl ?? origin.runUrl, ...(freshness ? { freshness } : {}) };
+            this.identity = { sha, branch: options.branch ?? env.ATLAS_BRANCH ?? origin.branch, runUrl: options.runUrl ?? origin.runUrl, ...(run ? { run } : {}), ...(freshness ? { freshness } : {}) };
         }
         catch {
-            this.identity = { sha: options.sha ?? env.ATLAS_SHA ?? null, branch: options.branch ?? env.ATLAS_BRANCH ?? null, runUrl: options.runUrl ?? null, freshness: 'unknown' };
+            this.identity = { sha: options.sha ?? env.ATLAS_SHA ?? null, branch: options.branch ?? env.ATLAS_BRANCH ?? null, runUrl: options.runUrl ?? null, ...(run ? { run } : {}), freshness: 'unknown' };
         }
     }
     specPathOf(test) {
@@ -195,6 +196,7 @@ export default class AtlasPlaywrightReporter {
                     sha: this.identity.sha,
                     branch: this.identity.branch,
                     runUrl: this.identity.runUrl,
+                    ...(this.identity.run ? { run: this.identity.run } : {}),
                     ...(this.identity.freshness ? { freshness: this.identity.freshness } : {}),
                     environment,
                     parameters: { ...parameters },

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

@@ -9,6 +9,7 @@
  * @see docs/report-contract.md
  */
 import type { EvidenceMeasurement, EvidenceStatus } from './explorer-types.js';
+import type { LayerRun } from '../../schema/src/layer.js';
 import type { LayerParameters } from './layer-types.js';
 /** Where a recorded test's timeline and captured files are read from. */
 export type RecordingAddress = {
@@ -49,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[];
@@ -77,6 +80,8 @@ export type LayerHeader = {
     readonly parameters: LayerParameters;
     /** `modified`: recorded from a checkout with uncommitted changes; `unknown`: origin not captured; absent: clean. Advisory; never changes a status. */
     readonly freshness?: 'unknown' | 'modified';
+    /** The execution the producer named for it (one local or manual invocation), or absent. Grouping and display only; never part of the slot. */
+    readonly run?: LayerRun;
     /** Where this layer's recorded timelines and captured files are read from, or null when it has none. */
     readonly recording: RecordingAddress | null;
     /** From a spec run that has not been collected into a layer yet. */

package/dist/reports/src/layer-merge.d.ts

@@ -129,7 +129,7 @@ export declare function distinctEvidence(layers: readonly LayerEvidence[]): Laye
 /** Drops each mutable layer whose execution is already archived as an immutable one, and keeps one summary per id. */
 export declare function distinctLayers(layers: readonly LayerSummary[]): LayerSummary[];
 /**
- * A string equal for the mutable and the archived address of one execution: its producer, sha, time and parts.
+ * A string equal for the mutable and the archived address of one execution: its producer, sha, time, parts and, when the producer named one, its execution id.
  * Object key order is ignored at every depth, including check evidence and extensions; array order is preserved.
  * This is an advisory execution identity, not the content digest that addresses an immutable layer in storage.
  */

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

@@ -97,6 +97,7 @@ export function layerEvidence(summary, backend) {
     const layerSummaryEvidence = summarizeEvidence(summary, ...summary.parts);
     const layer = {
         ...(summary.freshness ? { freshness: summary.freshness } : {}),
+        ...(summary.run ? { run: summary.run } : {}),
         id: summary.id,
         backend,
         producer: summary.producer,
@@ -270,12 +271,12 @@ export function distinctLayers(layers) {
     return [...new Map(layers.filter(layer => archived(layer.id) || !kept.has(layerExecutionKey(layer))).map(layer => [layer.id, layer])).values()];
 }
 /**
- * A string equal for the mutable and the archived address of one execution: its producer, sha, time and parts.
+ * A string equal for the mutable and the archived address of one execution: its producer, sha, time, parts and, when the producer named one, its execution id.
  * Object key order is ignored at every depth, including check evidence and extensions; array order is preserved.
  * This is an advisory execution identity, not the content digest that addresses an immutable layer in storage.
  */
 export function layerExecutionKey(layer) {
-    return JSON.stringify([layer.producer, layer.sha, layer.recordedAtMs, orderedValue(layer.parts)]);
+    return JSON.stringify([layer.producer, layer.sha, layer.recordedAtMs, orderedValue(layer.parts), ...(layer.run ? [layer.run.id] : [])]);
 }
 /** Sort JSON objects recursively without changing array order or interpreting extension keys as prototypes. */
 function orderedValue(value) {

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

@@ -8,6 +8,7 @@
  *
  * @see docs/report-contract.md#the-layer-document
  */
+import type { LayerRun } from '../../schema/src/layer.js';
 import type { BundleIndex } from './bundle.js';
 import type { ReportPart, SpecEntry } from './explorer-types.js';
 import type { SourceRecord } from './protocol.js';
@@ -33,6 +34,8 @@ export type LayerSummary = LayerExtras & {
     readonly environment?: string | null;
     /** Provenance: the CI run that produced the layer, or `null`. Never part of the slot. */
     readonly runUrl: string | null;
+    /** The execution (one invocation of a local or manual run) the layer belongs to, when the producer named one. Grouping and display only; never part of the slot. Absent: the run is told by `runUrl`, else `branch@sha`. */
+    readonly run?: LayerRun;
     /** Free choices that make a result its own slot. The `environment` parameter is read as the environment (see `layerPlace`). */
     readonly parameters: LayerParameters;
     /** The specs the layer was recorded against, with fingerprints of their text. */

package/dist/reports/src/publish-checks.js

@@ -103,6 +103,7 @@ export async function publishChecks(store, input, options = {}) {
         sha: args.sha,
         branch: args.branch,
         runUrl: args.runUrl,
+        ...(args.run ? { run: args.run } : {}),
         ...(environment ? { environment } : {}),
         parameters: Object.fromEntries(Object.entries(parameters).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
         specs: args.specs,

package/dist/reports/src/report-cli.d.ts

@@ -13,7 +13,7 @@
  * @see docs/agents.md
  */
 /** The text `atlas report --help` prints: every subcommand, its flags, what each does and the exit codes. Also the source of the command reference in `docs/reference/cli.md`. */
-export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.\n  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
+export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--run-id <id>] [--run-title <t>] [--run-started-at <iso|ms>] [--run-ended-at <iso|ms>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--run-id <id>] [--run-title <t>]\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.\n  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --run-id <id>   name this execution (a local or manual run with no CI run URL; also ATLAS_RUN_ID).\n                            Layers that share an id are one run, however many shards or batches uploaded them;\n                            another invocation at the same commit gets another id. Never part of what a check is\n            --run-title <t> a human name for the run (also ATLAS_RUN_TITLE); --run-started-at and --run-ended-at\n                            record when it ran. Without --run-id a run is its CI run URL, else branch@sha\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
 type Env = Readonly<Record<string, string | undefined>>;
 type Git = (args: readonly string[]) => string | null;
 /** What `reportMain` is given besides arguments: where output goes (`out`), and, for tests and embedding, the environment, working directory, git, clock and standard input (`stdin`, where `stream` reads checks from). Defaults are the real ones. */

package/dist/reports/src/report-cli.js

@@ -38,12 +38,14 @@ export const REPORT_USAGE = `atlas report — layered evidence for any kind of s
   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]
@@ -64,6 +66,11 @@ export const REPORT_USAGE = `atlas report — layered evidence for any kind of s
             --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)
@@ -151,15 +158,32 @@ function linkSpec(spec) {
     const named = /^([^=/:]+)=(.+)$/.exec(spec);
     return named ? { name: named[1], url: named[2] } : { url: spec };
 }
-function parseTime(text) {
+function parseTime(text, flag = '--recorded-at') {
     if (text === undefined)
         return null;
     const numeric = Number(text);
     const parsed = Number.isFinite(numeric) ? numeric : Date.parse(text);
     if (!Number.isFinite(parsed) || parsed < 0)
-        throw new Error(`--recorded-at takes an ISO date or epoch milliseconds (got "${text}")`);
+        throw new Error(`${flag} takes an ISO date or epoch milliseconds (got "${text}")`);
     return parsed;
 }
+/**
+ * The execution the producer named, from `--run-id`, `--run-title`, `--run-started-at`, `--run-ended-at` and then
+ * `ATLAS_RUN_ID` / `ATLAS_RUN_TITLE`, laid over a `run` the checks file gave. `undefined` when nothing names one, so the
+ * documented grouping (CI run URL, else branch@sha) applies. A title or time without an id is refused: it would have nothing to belong to.
+ */
+function executionOf(rest, env, given) {
+    const file = typeof given === 'object' && given !== null && !Array.isArray(given) ? given : {};
+    const id = value(rest, 'run-id') ?? env.ATLAS_RUN_ID ?? (typeof file.id === 'string' ? file.id : undefined);
+    const title = value(rest, 'run-title') ?? env.ATLAS_RUN_TITLE;
+    const startedAtMs = parseTime(value(rest, 'run-started-at'), '--run-started-at');
+    const endedAtMs = parseTime(value(rest, 'run-ended-at'), '--run-ended-at');
+    if (id === undefined && (title !== undefined || startedAtMs !== null || endedAtMs !== null))
+        throw new Error('--run-title, --run-started-at and --run-ended-at go with --run-id <id> (or ATLAS_RUN_ID): a run needs an identity first');
+    if (id === undefined)
+        return undefined;
+    return { ...file, id, ...(title !== undefined ? { title } : {}), ...(startedAtMs !== null ? { startedAtMs } : {}), ...(endedAtMs !== null ? { endedAtMs } : {}) };
+}
 function ingest(argv, base) {
     const read = (file) => readFileSync(path.resolve(base, file), 'utf8');
     const sources = ['ctrf', 'junit', 'manifest', 'checks'].filter(name => value(argv, name) !== undefined);
@@ -258,6 +282,7 @@ export async function reportMain(argv, io = { out: text => process.stdout.write(
         }
         const labels = { ...(ingested.labels ?? {}), ...(extra.labels ?? {}), ...Object.fromEntries(values(rest, 'label').map(pair => keyValue(pair, '--label'))) };
         const links = [...(extra.links ?? []), ...values(rest, 'link').map(linkSpec)];
+        const execution = executionOf(rest, env, extra.run);
         const layer = await publishChecks(target.store, {
             ...extra,
             producer,
@@ -272,6 +297,7 @@ export async function reportMain(argv, io = { out: text => process.stdout.write(
             ...(value(rest, 'title') ?? extra.title ? { title: (value(rest, 'title') ?? extra.title) } : {}),
             sha, branch,
             runUrl: value(rest, 'run-url') ?? extra.runUrl ?? origin.runUrl,
+            ...(execution ? { run: execution } : {}),
             ...(freshness ? { freshness } : {}),
             ...(value(rest, 'environment') ?? extra.environment ? { environment: (value(rest, 'environment') ?? extra.environment) } : {}),
             parameters: { ...(extra.parameters ?? {}), ...parameters }
@@ -329,6 +355,7 @@ export async function reportMain(argv, io = { out: text => process.stdout.write(
         const branch = value(rest, 'branch') ?? origin.branch;
         const freshness = detectFreshness({ sha, ci: origin.ci && !value(rest, 'sha') }, io.git);
         const environment = value(rest, 'environment');
+        const execution = executionOf(rest, env);
         const warnings = [];
         const reporter = createReporter({
             producer,
@@ -336,6 +363,7 @@ export async function reportMain(argv, io = { out: text => process.stdout.write(
             ...(value(rest, 'title') ? { title: value(rest, 'title') } : {}),
             sha, branch,
             runUrl: value(rest, 'run-url') ?? origin.runUrl,
+            ...(execution ? { run: execution } : {}),
             ...(freshness ? { freshness } : {}),
             ...(environment ? { environment } : {}),
             parameters: Object.fromEntries(values(rest, 'param').map(pair => keyValue(pair, '--param')))

package/dist/reports/src/reporter.d.ts

@@ -13,7 +13,7 @@ import { type PublishChecksInput } from '../../schema/src/layer.js';
 import type { ObjectStore } from './object-store.js';
 type Check = PublishChecksInput['checks'][number];
 /** What every layer of one stream shares: who is reporting, from where. Whatever `publishChecks` takes, except the checks and the time. */
-export type ReporterIdentity = Pick<PublishChecksInput, 'producer' | 'kind' | 'title' | 'sha' | 'branch' | 'runUrl' | 'environment' | 'parameters' | 'freshness' | 'specs' | 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions'>;
+export type ReporterIdentity = Pick<PublishChecksInput, 'producer' | 'kind' | 'title' | 'sha' | 'branch' | 'runUrl' | 'run' | 'environment' | 'parameters' | 'freshness' | 'specs' | 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions'>;
 /** How a reporter sends: the `store` (a folder, S3, or `httpStore` for a server), how often (`flushMs`, `batchSize`), how hard it tries (`attempts`, `backoffMs`), what it tells (`onError`, `onPublished`), and the clock and sleep for tests. */
 export type ReporterOptions = {
     /** Where layers go: a directory, S3, or `httpStore` for an Atlas server. */