@crvouga/atlas 0.13.0 → 0.15.0

package/packages/server/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Atlas server API",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "summary": "Take in test results from every environment, keep them, and show everyone the combined report, live.",
     "description": "One Atlas node serves multiple projects. Clients select a project using ?project=<slug>, X-Atlas-Project, or /api/projects/<slug>/… . Each project has independent specs, layers, recordings, status, and event streams. Within each project, the newest completed result of every check wins its slot. Unqualified requests address the legacy default project.\n\n**Authentication.** With tokens configured, send `Authorization: Bearer <token>`. Roles: `read` < `publish` < `admin`. Uploading needs a Bearer token; a browser's HTTP Basic sign-in (any user name, the token as the password) is accepted for reading only. A server with no tokens is open and listens on this machine only unless told otherwise.\n\n**Errors** are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem documents (`application/problem+json`) with a `detail` that says what to do. `401` send a token, `403` that token may not, `409` upload what this depends on first or you are changing something immutable, `413` too large, `422` not valid, `503` still starting (retry after `Retry-After`).\n\n**Compatibility.** Within `/api` the API only grows: optional parameters, optional response fields, new events. Ignore what you do not know.\n\nGuides: `/llms.txt`. Source: https://github.com/crvouga/atlas.",
     "license": {
@@ -3058,6 +3058,29 @@
               "type": "string"
             }
           },
+          {
+            "required": false,
+            "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.",
+            "example": "demo",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "required": false,
+            "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"
+              ]
+            }
+          },
           {
             "required": false,
             "name": "run",
@@ -3274,6 +3297,29 @@
               "type": "string"
             }
           },
+          {
+            "required": false,
+            "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.",
+            "example": "demo",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "required": false,
+            "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"
+              ]
+            }
+          },
           {
             "required": false,
             "name": "run",
@@ -3801,6 +3847,298 @@
         }
       }
     },
+    "/api/reports/artifact-tags": {
+      "get": {
+        "operationId": "getArtifactTags",
+        "tags": [
+          "Report"
+        ],
+        "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`.\n\nRole needed: `read`.",
+        "x-atlas-role": "read",
+        "security": [
+          {
+            "bearer": []
+          },
+          {
+            "basic": []
+          }
+        ],
+        "parameters": [
+          {
+            "required": false,
+            "name": "project",
+            "in": "query",
+            "description": "Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.",
+            "example": "todo-app",
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$",
+              "maxLength": 64
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The edits.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ArtifactTags"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No token, or an unknown one. Send `Authorization: Bearer <token>`.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "editArtifactTags",
+        "tags": [
+          "Report"
+        ],
+        "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>`).\n\nRole needed: `publish`.",
+        "x-atlas-role": "publish",
+        "security": [
+          {
+            "bearer": []
+          }
+        ],
+        "parameters": [
+          {
+            "required": false,
+            "name": "project",
+            "in": "query",
+            "description": "Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.",
+            "example": "todo-app",
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$",
+              "maxLength": 64
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "The attachment and the tags to add and remove. At most 20 of each, 64 KiB.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ArtifactTagEdit"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "The recorded entry.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ArtifactTagEntry"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No token, or an unknown one. Send `Authorization: Bearer <token>`.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "The token is known but its role may not do this.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          },
+          "413": {
+            "description": "Request too large.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/projects/{project}/reports/artifact-tags": {
+      "get": {
+        "operationId": "getArtifactTagsForProject",
+        "tags": [
+          "Report"
+        ],
+        "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`.\n\nScoped 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.\n\nRole needed: `read`.",
+        "x-atlas-role": "read",
+        "security": [
+          {
+            "bearer": []
+          },
+          {
+            "basic": []
+          }
+        ],
+        "parameters": [
+          {
+            "required": true,
+            "name": "project",
+            "in": "path",
+            "description": "Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.",
+            "example": "todo-app",
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$",
+              "maxLength": 64
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The edits.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ArtifactTags"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No token, or an unknown one. Send `Authorization: Bearer <token>`.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "editArtifactTagsForProject",
+        "tags": [
+          "Report"
+        ],
+        "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>`).\n\nScoped 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.\n\nRole needed: `publish`.",
+        "x-atlas-role": "publish",
+        "security": [
+          {
+            "bearer": []
+          }
+        ],
+        "parameters": [
+          {
+            "required": true,
+            "name": "project",
+            "in": "path",
+            "description": "Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.",
+            "example": "todo-app",
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$",
+              "maxLength": 64
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "The attachment and the tags to add and remove. At most 20 of each, 64 KiB.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ArtifactTagEdit"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "The recorded entry.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ArtifactTagEntry"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No token, or an unknown one. Send `Authorization: Bearer <token>`.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "The token is known but its role may not do this.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          },
+          "413": {
+            "description": "Request too large.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/reports/runs": {
       "get": {
         "operationId": "getReportRuns",
@@ -7451,6 +7789,13 @@
                               "type": "string"
                             }
                           },
+                          "artifactTags": {
+                            "description": "Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run",
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
                           "labels": {
                             "type": "object",
                             "propertyNames": {
@@ -7575,6 +7920,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": [
                         {},
@@ -7647,6 +8022,13 @@
                             "type": "string"
                           }
                         },
+                        "artifactTags": {
+                          "description": "Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run",
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
                         "labels": {
                           "type": "object",
                           "propertyNames": {
@@ -7894,6 +8276,13 @@
                               "type": "string"
                             }
                           },
+                          "artifactTags": {
+                            "description": "Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run",
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
                           "labels": {
                             "type": "object",
                             "propertyNames": {
@@ -8018,6 +8407,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": [
                         {},
@@ -8090,6 +8509,13 @@
                             "type": "string"
                           }
                         },
+                        "artifactTags": {
+                          "description": "Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run",
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
                         "labels": {
                           "type": "object",
                           "propertyNames": {
@@ -8742,6 +9168,13 @@
                       "description": {
                         "type": "string"
                       },
+                      "tags": {
+                        "description": "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",
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
                       "at": {
                         "type": "object",
                         "properties": {
@@ -8979,6 +9412,13 @@
                             "description": {
                               "type": "string"
                             },
+                            "tags": {
+                              "description": "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",
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            },
                             "at": {
                               "type": "object",
                               "properties": {
@@ -9253,6 +9693,13 @@
                                   "description": {
                                     "type": "string"
                                   },
+                                  "tags": {
+                                    "description": "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",
+                                    "type": "array",
+                                    "items": {
+                                      "type": "string"
+                                    }
+                                  },
                                   "at": {
                                     "type": "object",
                                     "properties": {
@@ -9463,6 +9910,13 @@
                             "description": {
                               "type": "string"
                             },
+                            "tags": {
+                              "description": "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",
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            },
                             "at": {
                               "type": "object",
                               "properties": {
@@ -9683,6 +10137,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",
@@ -9813,6 +10297,13 @@
                 "description": {
                   "type": "string"
                 },
+                "tags": {
+                  "description": "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",
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
                 "at": {
                   "type": "object",
                   "properties": {
@@ -10171,6 +10662,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": [
                     {},
@@ -10243,6 +10764,13 @@
                         "type": "string"
                       }
                     },
+                    "artifactTags": {
+                      "description": "Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run",
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
                     "labels": {
                       "type": "object",
                       "propertyNames": {
@@ -10470,6 +10998,13 @@
                         "type": "string"
                       }
                     },
+                    "artifactTags": {
+                      "description": "Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run",
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
                     "labels": {
                       "type": "object",
                       "propertyNames": {
@@ -10701,6 +11236,13 @@
                     "description": {
                       "type": "string"
                     },
+                    "tags": {
+                      "description": "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",
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
                     "at": {
                       "type": "object",
                       "properties": {
@@ -10929,6 +11471,13 @@
                           "description": {
                             "type": "string"
                           },
+                          "tags": {
+                            "description": "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",
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
                           "at": {
                             "type": "object",
                             "properties": {
@@ -11194,6 +11743,13 @@
                                 "description": {
                                   "type": "string"
                                 },
+                                "tags": {
+                                  "description": "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",
+                                  "type": "array",
+                                  "items": {
+                                    "type": "string"
+                                  }
+                                },
                                 "at": {
                                   "type": "object",
                                   "properties": {
@@ -11394,6 +11950,13 @@
                           "description": {
                             "type": "string"
                           },
+                          "tags": {
+                            "description": "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",
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
                           "at": {
                             "type": "object",
                             "properties": {
@@ -11564,6 +12127,224 @@
         ],
         "additionalProperties": {}
       },
+      "ArtifactTagEdit": {
+        "type": "object",
+        "properties": {
+          "target": {
+            "type": "object",
+            "properties": {
+              "layer": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$",
+                "description": "The id of the archived layer that holds the check"
+              },
+              "check": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The check's id"
+              },
+              "kind": {
+                "description": "The kind of the part holding the check, when the same id exists in several parts",
+                "type": "string",
+                "minLength": 1
+              },
+              "artifact": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1024,
+                "description": "The attachment: `id:<id>` when it has an id, else `key:<bundleKey>`, else `name:<name>` (see `artifactRef`)"
+              }
+            },
+            "required": [
+              "layer",
+              "check",
+              "artifact"
+            ],
+            "additionalProperties": {}
+          },
+          "add": {
+            "description": "Tags to add. `demo` and `#demo` are the same tag",
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "remove": {
+            "description": "Reviewer tags to remove. Tags the producer wrote are part of the immutable layer and stay",
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "target"
+        ],
+        "additionalProperties": {}
+      },
+      "ArtifactTagEntry": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique and time-ordered"
+          },
+          "target": {
+            "type": "object",
+            "properties": {
+              "layer": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$",
+                "description": "The id of the archived layer that holds the check"
+              },
+              "check": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The check's id"
+              },
+              "kind": {
+                "description": "The kind of the part holding the check, when the same id exists in several parts",
+                "type": "string",
+                "minLength": 1
+              },
+              "artifact": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1024,
+                "description": "The attachment: `id:<id>` when it has an id, else `key:<bundleKey>`, else `name:<name>` (see `artifactRef`)"
+              }
+            },
+            "required": [
+              "layer",
+              "check",
+              "artifact"
+            ],
+            "additionalProperties": {}
+          },
+          "add": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Normalized tags added"
+          },
+          "remove": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Normalized tags removed"
+          },
+          "by": {
+            "type": "string",
+            "description": "The name of the token that made the edit (never the token)"
+          },
+          "atMs": {
+            "type": "number",
+            "description": "When the server recorded it, epoch milliseconds"
+          }
+        },
+        "required": [
+          "id",
+          "target",
+          "add",
+          "remove",
+          "by",
+          "atMs"
+        ],
+        "additionalProperties": {}
+      },
+      "ArtifactTags": {
+        "type": "object",
+        "properties": {
+          "schemaVersion": {
+            "type": "number",
+            "const": 1
+          },
+          "entries": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "Unique and time-ordered"
+                },
+                "target": {
+                  "type": "object",
+                  "properties": {
+                    "layer": {
+                      "type": "string",
+                      "pattern": "^[0-9a-f]{64}$",
+                      "description": "The id of the archived layer that holds the check"
+                    },
+                    "check": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "The check's id"
+                    },
+                    "kind": {
+                      "description": "The kind of the part holding the check, when the same id exists in several parts",
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "artifact": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 1024,
+                      "description": "The attachment: `id:<id>` when it has an id, else `key:<bundleKey>`, else `name:<name>` (see `artifactRef`)"
+                    }
+                  },
+                  "required": [
+                    "layer",
+                    "check",
+                    "artifact"
+                  ],
+                  "additionalProperties": {}
+                },
+                "add": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Normalized tags added"
+                },
+                "remove": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Normalized tags removed"
+                },
+                "by": {
+                  "type": "string",
+                  "description": "The name of the token that made the edit (never the token)"
+                },
+                "atMs": {
+                  "type": "number",
+                  "description": "When the server recorded it, epoch milliseconds"
+                }
+              },
+              "required": [
+                "id",
+                "target",
+                "add",
+                "remove",
+                "by",
+                "atMs"
+              ],
+              "additionalProperties": {}
+            }
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "entries"
+        ],
+        "additionalProperties": {}
+      },
       "TestCatalog": {
         "type": "object",
         "properties": {
@@ -12154,6 +12935,27 @@
                   "additionalProperties": {}
                 }
               },
+              "artifactTags": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "value": {
+                      "type": "string"
+                    },
+                    "count": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "value",
+                    "count"
+                  ],
+                  "additionalProperties": {}
+                }
+              },
               "branches": {
                 "type": "array",
                 "items": {
@@ -12420,6 +13222,13 @@
                               "type": "string"
                             }
                           },
+                          "artifactTags": {
+                            "description": "Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run",
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
                           "labels": {
                             "type": "object",
                             "propertyNames": {
@@ -12614,6 +13423,20 @@
                     "type": "string"
                   }
                 },
+                "artifactTags": {
+                  "description": "Normalized tags of the attachments of its current results, such as `demo` (shown `#demo`). Not inherited from a check or run, unlike `tags`",
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "inheritedArtifactTags": {
+                  "description": "Normalized tags its attachments inherit from their check and run, apart from `artifactTags`: what `?artifactTag=…&inherited=1` also matches",
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
                 "labels": {
                   "type": "object",
                   "propertyNames": {
@@ -13292,6 +14115,13 @@
                             "type": "string"
                           }
                         },
+                        "artifactTags": {
+                          "description": "Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run",
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
                         "labels": {
                           "type": "object",
                           "propertyNames": {
@@ -13486,6 +14316,20 @@
                   "type": "string"
                 }
               },
+              "artifactTags": {
+                "description": "Normalized tags of the attachments of its current results, such as `demo` (shown `#demo`). Not inherited from a check or run, unlike `tags`",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "inheritedArtifactTags": {
+                "description": "Normalized tags its attachments inherit from their check and run, apart from `artifactTags`: what `?artifactTag=…&inherited=1` also matches",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
               "labels": {
                 "type": "object",
                 "propertyNames": {
@@ -13668,6 +14512,13 @@
                         "type": "string"
                       }
                     },
+                    "artifactTags": {
+                      "description": "Normalized tags of the attachments themselves, sorted and distinct. Absent when no attachment is tagged; never inherited from a check or run",
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
                     "labels": {
                       "type": "object",
                       "propertyNames": {
@@ -13747,7 +14598,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": [
@@ -13901,7 +14768,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": [