@crvouga/atlas 0.13.0 → 0.14.0

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.
@@ -250,6 +262,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),
@@ -298,6 +311,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 +400,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/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/playwright-reporter.md

@@ -281,6 +281,12 @@ 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`. */
@@ -290,12 +296,6 @@ export type AtlasPlaywrightReporterOptions = {
   /** A larger file is not uploaded; the check says so in an annotation. Default 50 MiB. */
   readonly maxAttachmentBytes?: number;
   /** The most timeline steps recorded per result. Default 500. */
-  readonly maxSteps?: number;
-  /** Record the project's spec files (path, domain, kind, title) in every layer, so a server can group checks by spec without a published spec set. Default true. */
-  readonly specs?: boolean;
-  /** Send what has finished this often, in ms. Default 5000 (every layer repeats the spec list). */
-  readonly flushMs?: number;
-  /** Send at once when this many checks are waiting. Default 50 (their attachments are held in memory until sent). */
   …
 ```
 

package/docs/reference/reports.md

@@ -1454,6 +1454,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. */
@@ -3560,7 +3562,7 @@ Drops each mutable layer whose execution is already archived as an immutable one
 export function layerExecutionKey(layer: LayerSummary): string
 ```
 
-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.
 
@@ -3725,6 +3727,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. */
@@ -5935,7 +5939,7 @@ See docs/server.md#streaming-a-run-as-it-happens
 #### `ReporterIdentity`
 
 ```ts
-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'>;
 ```
 
 What every layer of one stream shares: who is reporting, from where. Whatever `publishChecks` takes, except the checks and the time.
@@ -7685,8 +7689,14 @@ export type TestHistoryDocument = {
 
 ```ts
 export type RunSummary = {
-  /** Stable key: the run URL, or `branch@sha`. */
+  /** Stable key: `run:<id>` for an execution a producer named, else the run URL, else `branch@sha`. */
   readonly key: string;
+  /** The execution id a producer named for it, when it did. Layers that share it are one run, however many uploads they took; another invocation at the same commit has another. */
+  readonly runId?: string;
+  /** The human title the producer gave the execution (the newest layer's). Presentation only: the key, the commit and `freshness` are unaffected. */
+  readonly title?: string;
+  /** `modified` when any of its layers was recorded from a checkout with uncommitted changes, else `unknown` when any origin was not captured; absent when every layer is from a clean commit. Advisory; never changes a status. */
+  readonly freshness?: 'unknown' | 'modified';
   readonly runUrl: string | null;
   readonly branch: string | null;
   readonly sha: string | null;
@@ -7708,7 +7718,8 @@ export type RunSummary = {
 };
 ```
 
-A CI run (or any group of layers sharing a run URL, else a branch and commit): when, where, and how its tests went.
+A run: the layers that name the same execution (`run.id`), else share a CI run URL, else a branch and commit. When,
+where, and how its tests went.
 
 #### `RunList`
 
@@ -7759,10 +7770,11 @@ export type RunDetail = {
 #### `runKey`
 
 ```ts
-export function runKey(layer: Pick<LayerHeader, 'runUrl' | 'branch' | 'sha'>): string
+export function runKey(layer: Pick<LayerHeader, 'runUrl' | 'branch' | 'sha'> & { readonly run?: { readonly id: string } }): string
 ```
 
-The run a layer belongs to: its run URL, else `branch@sha`, else `local`. Layers with the same key are one run.
+The run a layer belongs to: the execution its producer named (`run:<id>`), else its run URL, else `branch@sha`, else
+`local`. Layers with the same key are one run. Only grouping: it is never part of the slot a result fills.
 
 #### `TestHistory`
 

package/docs/reference/schema.md

@@ -258,7 +258,7 @@ export const TestHistorySchema = …
 export const ReportRunSchema = …
 ```
 
-A run: the layers that share a run URL (else a branch and commit), with what they recorded.
+A run: the layers that name the same execution (else share a run URL, else a branch and commit), with what they recorded.
 
 #### `RunListSchema`
 
@@ -643,6 +643,25 @@ Why a layer's origin is advisory: `modified` (recorded from a checkout with unco
 (origin not captured). Absent on a layer from a clean commit. It never changes a status. A closed vocabulary: it
 changes only with a new `schemaVersion`.
 
+#### `LayerRunSchema`
+
+```ts
+export const LayerRunSchema = …
+```
+
+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`.
+
+#### `LayerRun`
+
+```ts
+export type LayerRun = z.output<typeof LayerRunSchema>;
+```
+
+The execution of a layer, parsed from `LayerRunSchema`.
+
 #### `MeasurementSchema`
 
 ```ts

package/docs/report-contract.md

@@ -82,6 +82,7 @@ Zod schema as `LayerDocumentSchema` from `@crvouga/atlas/schema`.
 | `environment` | The client checked, or absent. Normalised to a lowercase slug: `iOS` → `ios`, `Desktop Web` → `desktop-web`, `iphone` → `ios`, `mobile browser` → `mobile-web`. Any other name is kept. Part of the slot. |
 | `parameters` | Other string choices that make a result its own slot, such as `{ "device": "iphone-15" }`. A parameter named `environment` is read as the environment. Part of the slot. |
 | `freshness` | `modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Advisory only; see [Statuses](#statuses-and-the-gate). |
+| `run` | Optional `{ id, title?, startedAtMs?, endedAtMs? }`: the execution a local or manual producer names. Layers with the same `id` in one project are one run in the run list, however many shards or batches uploaded them; a later invocation at the same branch and commit gets another `id`. Without it a run is its `runUrl`, else `branch@sha`, as before. `title` is for people. Grouping and display only: it is **never part of the slot**, never decides a winner or a status, and never hides `sha`, `branch` or `freshness`. A `run` a reader cannot read is treated as absent. |
 | `specs` | The specs the layer was recorded against, with a `fingerprint` of their text, so a reader can warn when a spec changed since. Optional. |
 | `parts[].kind` | An open category (`behavior`, `performance`, `accessibility`, …). A new kind needs no change to any reader. Part of the slot. |
 | `parts[].checks[]` | `id` (required, stable), `title`, `status`, `detail`, `specPath`, `measurements`, `durationMs`. |

package/llms-full.txt

@@ -505,6 +505,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
@@ -2174,6 +2182,7 @@ Zod schema as `LayerDocumentSchema` from `@crvouga/atlas/schema`.
 | `environment` | The client checked, or absent. Normalised to a lowercase slug: `iOS` → `ios`, `Desktop Web` → `desktop-web`, `iphone` → `ios`, `mobile browser` → `mobile-web`. Any other name is kept. Part of the slot. |
 | `parameters` | Other string choices that make a result its own slot, such as `{ "device": "iphone-15" }`. A parameter named `environment` is read as the environment. Part of the slot. |
 | `freshness` | `modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Advisory only; see [Statuses](#statuses-and-the-gate). |
+| `run` | Optional `{ id, title?, startedAtMs?, endedAtMs? }`: the execution a local or manual producer names. Layers with the same `id` in one project are one run in the run list, however many shards or batches uploaded them; a later invocation at the same branch and commit gets another `id`. Without it a run is its `runUrl`, else `branch@sha`, as before. `title` is for people. Grouping and display only: it is **never part of the slot**, never decides a winner or a status, and never hides `sha`, `branch` or `freshness`. A `run` a reader cannot read is treated as absent. |
 | `specs` | The specs the layer was recorded against, with a `fingerprint` of their text, so a reader can warn when a spec changed since. Optional. |
 | `parts[].kind` | An open category (`behavior`, `performance`, `accessibility`, …). A new kind needs no change to any reader. Part of the slot. |
 | `parts[].checks[]` | `id` (required, stable), `title`, `status`, `detail`, `specPath`, `measurements`, `durationMs`. |
@@ -4246,12 +4255,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]
@@ -4272,6 +4283,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",

package/packages/schema/schemas/effective-delta.schema.json

@@ -256,6 +256,36 @@
                   "modified"
                 ]
               },
+              "run": {
+                "description": "The execution the producer named for it (one local or manual invocation). Grouping and display only; never part of the slot",
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 256,
+                    "description": "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": {
+                    "description": "A human name for the run. Presentation only: it is not part of the identity and does not hide the commit or `freshness`",
+                    "type": "string"
+                  },
+                  "startedAtMs": {
+                    "description": "When the execution started, epoch milliseconds",
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "endedAtMs": {
+                    "description": "When the execution ended, epoch milliseconds",
+                    "type": "number",
+                    "minimum": 0
+                  }
+                },
+                "required": [
+                  "id"
+                ],
+                "additionalProperties": {}
+              },
               "recording": {
                 "anyOf": [
                   {},

package/packages/schema/schemas/effective-evidence.schema.json

@@ -256,6 +256,36 @@
                   "modified"
                 ]
               },
+              "run": {
+                "description": "The execution the producer named for it (one local or manual invocation). Grouping and display only; never part of the slot",
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 256,
+                    "description": "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": {
+                    "description": "A human name for the run. Presentation only: it is not part of the identity and does not hide the commit or `freshness`",
+                    "type": "string"
+                  },
+                  "startedAtMs": {
+                    "description": "When the execution started, epoch milliseconds",
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "endedAtMs": {
+                    "description": "When the execution ended, epoch milliseconds",
+                    "type": "number",
+                    "minimum": 0
+                  }
+                },
+                "required": [
+                  "id"
+                ],
+                "additionalProperties": {}
+              },
               "recording": {
                 "anyOf": [
                   {},

package/packages/schema/schemas/evidence-page.schema.json

@@ -75,6 +75,36 @@
               "modified"
             ]
           },
+          "run": {
+            "description": "The execution the producer named for it (one local or manual invocation). Grouping and display only; never part of the slot",
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 256,
+                "description": "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": {
+                "description": "A human name for the run. Presentation only: it is not part of the identity and does not hide the commit or `freshness`",
+                "type": "string"
+              },
+              "startedAtMs": {
+                "description": "When the execution started, epoch milliseconds",
+                "type": "number",
+                "minimum": 0
+              },
+              "endedAtMs": {
+                "description": "When the execution ended, epoch milliseconds",
+                "type": "number",
+                "minimum": 0
+              }
+            },
+            "required": [
+              "id"
+            ],
+            "additionalProperties": {}
+          },
           "recording": {
             "anyOf": [
               {},

package/packages/schema/schemas/layer.schema.json

@@ -70,6 +70,36 @@
         "modified"
       ]
     },
+    "run": {
+      "description": "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",
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "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": {
+          "description": "A human name for the run. Presentation only: it is not part of the identity and does not hide the commit or `freshness`",
+          "type": "string"
+        },
+        "startedAtMs": {
+          "description": "When the execution started, epoch milliseconds",
+          "type": "number",
+          "minimum": 0
+        },
+        "endedAtMs": {
+          "description": "When the execution ended, epoch milliseconds",
+          "type": "number",
+          "minimum": 0
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "additionalProperties": {}
+    },
     "specs": {
       "default": [],
       "type": "array",

package/packages/schema/schemas/publish-checks.schema.json

@@ -1110,6 +1110,36 @@
         "modified"
       ]
     },
+    "run": {
+      "description": "Name the execution these checks belong to, so repeated local runs at one commit stay separate runs and shards of one execution stay together",
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "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": {
+          "description": "A human name for the run. Presentation only: it is not part of the identity and does not hide the commit or `freshness`",
+          "type": "string"
+        },
+        "startedAtMs": {
+          "description": "When the execution started, epoch milliseconds",
+          "type": "number",
+          "minimum": 0
+        },
+        "endedAtMs": {
+          "description": "When the execution ended, epoch milliseconds",
+          "type": "number",
+          "minimum": 0
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "additionalProperties": {}
+    },
     "specs": {
       "default": [],
       "type": "array",

package/packages/schema/schemas/report-run.schema.json

@@ -15,7 +15,23 @@
       "properties": {
         "key": {
           "type": "string",
-          "description": "The run URL, or `branch@sha`. Pass it to `/api/reports/runs/detail?key=` or `/api/reports/tests?run=`"
+          "description": "`run:<id>` for an execution a producer named, else the run URL, else `branch@sha`. Pass it to `/api/reports/runs/detail?key=` or `/api/reports/tests?run=`"
+        },
+        "runId": {
+          "description": "The execution id the producer named, when it did. Layers that share it are one run however many uploads they took",
+          "type": "string"
+        },
+        "title": {
+          "description": "The human title of the execution (the newest layer's). Presentation only: the key, commit and `freshness` are unaffected",
+          "type": "string"
+        },
+        "freshness": {
+          "description": "`modified` when any layer of the run was recorded from a checkout with uncommitted changes; `unknown` when an origin was not captured; absent when all are clean. Shown beside the commit, never replaced by the title",
+          "type": "string",
+          "enum": [
+            "unknown",
+            "modified"
+          ]
         },
         "runUrl": {
           "type": [

package/packages/schema/schemas/report-runs.schema.json

@@ -22,7 +22,23 @@
         "properties": {
           "key": {
             "type": "string",
-            "description": "The run URL, or `branch@sha`. Pass it to `/api/reports/runs/detail?key=` or `/api/reports/tests?run=`"
+            "description": "`run:<id>` for an execution a producer named, else the run URL, else `branch@sha`. Pass it to `/api/reports/runs/detail?key=` or `/api/reports/tests?run=`"
+          },
+          "runId": {
+            "description": "The execution id the producer named, when it did. Layers that share it are one run however many uploads they took",
+            "type": "string"
+          },
+          "title": {
+            "description": "The human title of the execution (the newest layer's). Presentation only: the key, commit and `freshness` are unaffected",
+            "type": "string"
+          },
+          "freshness": {
+            "description": "`modified` when any layer of the run was recorded from a checkout with uncommitted changes; `unknown` when an origin was not captured; absent when all are clean. Shown beside the commit, never replaced by the title",
+            "type": "string",
+            "enum": [
+              "unknown",
+              "modified"
+            ]
           },
           "runUrl": {
             "type": [