@crvouga/atlas 0.14.0 → 0.15.0

package/docs/reference/reports.md

@@ -4,6 +4,209 @@ Layered evidence for any kind of spec: publishing layers, stores (folder, S3, an
 
 > Generated from the doc comments of `packages/reports/src` by `bun run docs`. Do not edit: change the comment next to the code.
 
+### Reviewer tags in a store
+
+Source: `packages/reports/src/artifact-tag-store.ts`. Import: `@crvouga/atlas/reports/artifact-tag-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
+
+#### `ARTIFACT_TAGS_PREFIX`
+
+```ts
+export const ARTIFACT_TAGS_PREFIX = …
+```
+
+The prefix of every recorded edit in a store.
+
+#### `ArtifactTagError`
+
+```ts
+export class ArtifactTagError extends Error
+```
+
+The edit was not acceptable (`status` is the HTTP status to answer).
+
+#### `recordArtifactTags`
+
+```ts
+export async function recordArtifactTags(store: ObjectStore, input: unknown, by: string, atMs: number): Promise<ArtifactTagEntry>
+```
+
+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.
+
+#### `readArtifactTagEntries`
+
+```ts
+export async function readArtifactTagEntries(store: ObjectStore): 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.
+
+### Artifact tags
+
+Source: `packages/reports/src/artifact-tags.ts`. Import: `@crvouga/atlas/reports/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
+
+#### `MAX_TAG_LENGTH`
+
+```ts
+export const MAX_TAG_LENGTH = …
+```
+
+The longest a normalized tag may be, in characters.
+
+#### `normalizeTag`
+
+```ts
+export function normalizeTag(raw: string): string | null
+```
+
+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
+```
+
+#### `normalizeTags`
+
+```ts
+export function normalizeTags(raw: Iterable<string> | undefined): string[]
+```
+
+Normalizes every tag with {@link normalizeTag}, dropping the ones that are not tags and the repeats; the first of each keeps its place.
+
+#### `displayTag`
+
+```ts
+export const displayTag = …
+```
+
+The tag as a person sees it: `#demo`.
+
+#### `artifactRef`
+
+```ts
+export function artifactRef(attachment: Pick<Attachment, 'id' | 'bundleKey' | 'name'>): 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.
+
+#### `ArtifactTarget`
+
+```ts
+export type ArtifactTarget = {
+  readonly layer: string;
+  readonly check: string;
+  readonly kind?: string | undefined;
+  readonly artifact: string;
+};
+```
+
+Where a reviewer's tags are about: one attachment of one check of one archived layer.
+
+#### `ArtifactTagEntry`
+
+```ts
+export type ArtifactTagEntry = {
+  readonly id: string;
+  readonly target: ArtifactTarget;
+  readonly add: readonly string[];
+  readonly remove: readonly string[];
+  readonly by: string;
+  readonly atMs: number;
+};
+```
+
+One recorded edit. Entries are never changed or removed.
+
+#### `targetKey`
+
+```ts
+export const targetKey = …
+```
+
+A string that is equal for equal targets (the part `kind` is optional and then does not matter).
+
+#### `ReviewerTag`
+
+```ts
+export type ReviewerTag = { readonly tag: string; readonly by: string; readonly atMs: number };
+```
+
+A tag a reviewer added: who added it last, and when.
+
+#### `foldArtifactTags`
+
+```ts
+export function foldArtifactTags(entries: readonly ArtifactTagEntry[]): Map<string, ReviewerTag[]>
+```
+
+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.
+
+#### `TagSource`
+
+```ts
+export type TagSource = 'artifact' | 'reviewer' | 'inherited';
+```
+
+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`).
+
+#### `ArtifactTag`
+
+```ts
+export type ArtifactTag = { readonly tag: string; readonly source: TagSource; readonly by?: string; readonly atMs?: number };
+```
+
+One tag an attachment shows, with its source and, for a reviewer's tag, who added it and when.
+
+#### `artifactTagsOf`
+
+```ts
+export function artifactTagsOf(attachment: Pick<Attachment, 'tags'>, options: { readonly reviewer?: readonly ReviewerTag[]; readonly inherited?: Iterable<string> } = {}): ArtifactTag[]
+```
+
+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.
+
+#### `hasArtifactTag`
+
+```ts
+export function hasArtifactTag(tags: readonly ArtifactTag[], wanted: string, options: { readonly inherited?: boolean } = {}): boolean
+```
+
+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.
+
 ### Reading the files attachments name
 
 Source: `packages/reports/src/attachment-files.ts`. Import: `@crvouga/atlas/reports/attachment-files`
@@ -1222,7 +1425,7 @@ read when someone asks for it. Undefined when there is none.
 
 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.
 
 #### `roleOfType`
@@ -1418,6 +1621,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[];
@@ -7514,6 +7719,10 @@ export type TestSummary = {
   readonly outcomes: readonly TestOutcome[];
   readonly stats: TestStats;
   readonly tags: readonly string[];
+  /** The normalized tags of the attachments of its current results (`demo`, shown as `#demo`). Never inherited from a check or run; the `tags` above are. Absent in documents of older servers. */
+  readonly artifactTags?: readonly string[];
+  /** The normalized tags its attachments inherit from their check and run (those of the results that have attachments), apart from `artifactTags`. What an inherited artifact query also matches. */
+  readonly inheritedArtifactTags?: readonly string[];
   readonly labels: Readonly<Record<string, string>>;
   /** What its current results carry: attachments, steps, retries, and the kinds of attachment. */
   readonly evidence: { readonly attachments: number; readonly steps: number; readonly attempts: number; readonly roles: readonly string[] };
@@ -7604,6 +7813,8 @@ export type CatalogFacets = {
   readonly domains: readonly FacetValue[];
   readonly specs: readonly (CatalogSpec & { readonly tests: number; readonly counts: StatusCounts })[];
   readonly tags: readonly FacetValue[];
+  /** The tags of attachments, normalized. Absent in documents of older servers. */
+  readonly artifactTags?: readonly FacetValue[];
   readonly branches: readonly FacetValue[];
   readonly labels: Readonly<Record<string, readonly FacetValue[]>>;
 };
@@ -7641,6 +7852,10 @@ export type TestQuery = {
   /** Spec paths (`specs/...`). */
   readonly spec?: readonly string[];
   readonly tag?: readonly string[];
+  /** Only tests with an attachment carrying this tag (`demo` and `#demo` are the same), not counting tags inherited from a check or run: the exact artifact query. `tag` is the inherited one. */
+  readonly artifactTag?: readonly string[];
+  /** With `artifactTag`: also match the tags an attachment inherits from its check and run (a recording without a tag of its own under a run tagged `demo`). Default false: the exact query. */
+  readonly inherited?: boolean;
   /** Only tests recorded in this run (a key from `runList`). */
   readonly run?: string;
   readonly sort?: TestSort;
@@ -7921,7 +8136,7 @@ One run with every result it recorded, or null when no run has that key.
 export function parseTestQuery(params: URLSearchParams): TestQuery
 ```
 
-Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`.
+Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`, `artifactTag`, and `inherited=1`.
 
 #### `formatMs`
 

package/docs/reference/schema.md

@@ -185,6 +185,38 @@ export const ChecksResultSchema = …
 
 `POST /api/checks` answered: the layer that was written.
 
+#### `ArtifactTargetSchema`
+
+```ts
+export const ArtifactTargetSchema = …
+```
+
+Which attachment a reviewer's tags belong to: one attachment of one check of one archived layer.
+
+#### `ArtifactTagEditSchema`
+
+```ts
+export const ArtifactTagEditSchema = …
+```
+
+The body of `POST /api/reports/artifact-tags`: tags to add to and to remove from one attachment. At least one tag overall.
+
+#### `ArtifactTagEntrySchema`
+
+```ts
+export const ArtifactTagEntrySchema = …
+```
+
+One recorded edit of an attachment's reviewer tags. Entries are never changed or removed: they are the audit trail.
+
+#### `ArtifactTagsSchema`
+
+```ts
+export const ArtifactTagsSchema = …
+```
+
+`GET /api/reports/artifact-tags`: every recorded edit, oldest first. Fold them with `foldArtifactTags`.
+
 #### `HelloEventSchema`
 
 ```ts

package/docs/rich-evidence.md

@@ -26,6 +26,7 @@ decided exactly as before ([the report contract](report-contract.md)). Evidence
 | `steps` (`parentId`, `offsetMs`, `durationMs`, `status`, `kind`) | check, attempt | Draws the check's timeline: nested steps, when each started, how long it took, which one failed. |
 | `attempts` | check | Every try of a retried check, with its own status, detail, steps and attachments. A check that passed after failing is flaky. |
 | `tags`, `labels` | check, layer | Filters and groups (`smoke`, `flaky`, an owner, a browser). |
+| `tags` | attachment | Marks one recording or screenshot, for example `demo`: shown as a `#demo` chip, and searchable. See [Tagging artifacts and demos](#tagging-artifacts-and-demos). |
 | `annotations`, `links` | check, step, attempt, layer | Notes, warnings and issue links next to the result. |
 | `specPath` | check | The spec a check belongs to (a `.feature`, a test file), relative to the repository. Checks are grouped by it. |
 | `specs[]` (`path`, `domain`, `kind`, `title`) | layer | Names each spec and its group (`domain`), so a server can group checks by spec with a title even when no [spec set](integrating.md#tell-atlas-which-spec-a-check-belongs-to) has been published. |
@@ -34,6 +35,33 @@ decided exactly as before ([the report contract](report-contract.md)). Evidence
 Send `sha`, `branch` and `runUrl` on every layer too. They never change a result, but they tie results to a commit
 and to the CI run that produced them.
 
+## Tagging artifacts and demos
+
+To mark one recording as a demo, tag the attachment itself. A tag on a check says something about the result; a tag on
+an attachment says something about that file, and no Gherkin tag, label, environment or producer name is needed:
+
+```ts
+{ name: 'checkout.webm', role: 'video', tags: ['demo'], labels: { audience: 'business' } }
+```
+
+The viewer shows it as a `#demo` chip on the artifact card. Selecting the chip filters the result's evidence to the
+attachments with that tag, and says how many match. Tags describe evidence; they never change a status or a slot.
+
+- **One spelling.** A tag is normalized before it is compared or stored: a leading `#` is dropped, letters are
+  lower-cased, each run of whitespace becomes `-`, and surrounding space is trimmed, so `demo`, `#demo` and `#Demo ` are
+  `demo`. Empty tags and tags over 64 characters are not tags and are ignored (or refused, when a reviewer enters them).
+  Everything else is a valid tag (`team/payments`, `release=2`), and repeats are shown once.
+- **Inherited.** An attachment is also searchable by the tags of its check and its run. The viewer says `inherited` on
+  such a chip, and a switch decides whether the filter counts them: a recording without a tag of its own under a run
+  tagged `demo` is found by the inherited query and not by the exact one. In the API,
+  `GET /api/reports/tests?artifactTag=demo` is exact and adding `&inherited=1` includes inherited tags.
+- **Reviewers.** After upload, a person with a publish token can add tags to an attachment (the viewer's *Add tag*
+  button) and remove the ones a reviewer added. Those tags are not written into the layer, which is immutable: the
+  server keeps them as an audit trail (who, when, which tags) and the viewer shows them as `added by <name>`, apart
+  from the producer's tags. See [Tagging artifacts](server.md#tagging-artifacts). A producer's own tags stay as uploaded.
+- **Older layers.** A layer without attachment tags reads exactly as before. Tags on an attachment that cannot be read
+  (not a list of strings) are dropped, and the attachment, check and layer stay.
+
 ## Labels describe, parameters split
 
 A result's **slot** is its producer, check id, part kind, spec, environment and **parameters**. The newest completed

package/docs/server.md

@@ -216,6 +216,26 @@ against a server unchanged. A client uploads **in dependency order**: blobs, the
 entry that makes it visible. The server checks each step and says no to a catalog entry whose manifest is not
 there (`409`), so nothing half-uploaded is ever shown.
 
+## Tagging artifacts
+
+A reviewer can mark a recording `#demo` after it was uploaded without uploading it again. The layer is immutable, so the
+tag is kept beside it: each edit is one small object under `curation/artifact-tags/` in the write backend (or the live
+store of a relay), named by time, never changed or removed. It records the attachment (layer, check, and the attachment's
+`id`, else its bytes' key, else its name), the normalized tags added and removed, the name of the token that made the
+edit, and the server's time. Nothing about the layer, its results or the report's winners changes.
+
+- `GET /api/reports/artifact-tags` (read) returns every edit, oldest first. Fold them to get the tags that stand now: the
+  last edit of a tag wins.
+- `POST /api/reports/artifact-tags` (publish, `Authorization: Bearer`) records an edit. A read token, an anonymous reader
+  and the browser's sign-in box are refused (`403`/`401`) like any upload, so a read-only visitor can see the tags and
+  not change them. The viewer asks for a token when a reviewer adds a tag and keeps it only in that tab.
+- Producer tags (`tags` on the attachment) and reviewer tags are kept apart everywhere: the viewer says who added a
+  reviewer tag and when, and a reviewer can remove only reviewer tags. `capabilities.artifactTags` on `/api/server` says
+  a server has this.
+
+See [Tagging artifacts and demos](rich-evidence.md#tagging-artifacts-and-demos) for the tag rules. Reviewer tags are
+shown in the viewer's evidence; the tests API (`artifactTag`) searches the producers' tags.
+
 ## Streaming
 
 `GET /api/events` is a server-sent-events stream:
@@ -330,6 +350,10 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `GET /api/projects/{project}/reports/tests/health` | read | Why specs, domains and counts disagree. |
 | `GET /api/reports/tests/history` | read | One test and every result recorded for it. |
 | `GET /api/projects/{project}/reports/tests/history` | read | One test and every result recorded for it. |
+| `GET /api/reports/artifact-tags` | read | Reviewer tags of attachments: every recorded edit. |
+| `GET /api/projects/{project}/reports/artifact-tags` | read | Reviewer tags of attachments: every recorded edit. |
+| `POST /api/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
+| `POST /api/projects/{project}/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
 | `GET /api/reports/runs` | read | The runs that recorded the report. |
 | `GET /api/projects/{project}/reports/runs` | read | The runs that recorded the report. |
 | `GET /api/reports/runs/detail` | read | Every test one run recorded. |

package/llms-full.txt

@@ -1013,6 +1013,7 @@ decided exactly as before ([the report contract](report-contract.md)). Evidence
 | `steps` (`parentId`, `offsetMs`, `durationMs`, `status`, `kind`) | check, attempt | Draws the check's timeline: nested steps, when each started, how long it took, which one failed. |
 | `attempts` | check | Every try of a retried check, with its own status, detail, steps and attachments. A check that passed after failing is flaky. |
 | `tags`, `labels` | check, layer | Filters and groups (`smoke`, `flaky`, an owner, a browser). |
+| `tags` | attachment | Marks one recording or screenshot, for example `demo`: shown as a `#demo` chip, and searchable. See [Tagging artifacts and demos](#tagging-artifacts-and-demos). |
 | `annotations`, `links` | check, step, attempt, layer | Notes, warnings and issue links next to the result. |
 | `specPath` | check | The spec a check belongs to (a `.feature`, a test file), relative to the repository. Checks are grouped by it. |
 | `specs[]` (`path`, `domain`, `kind`, `title`) | layer | Names each spec and its group (`domain`), so a server can group checks by spec with a title even when no [spec set](integrating.md#tell-atlas-which-spec-a-check-belongs-to) has been published. |
@@ -1021,6 +1022,33 @@ decided exactly as before ([the report contract](report-contract.md)). Evidence
 Send `sha`, `branch` and `runUrl` on every layer too. They never change a result, but they tie results to a commit
 and to the CI run that produced them.
 
+## Tagging artifacts and demos
+
+To mark one recording as a demo, tag the attachment itself. A tag on a check says something about the result; a tag on
+an attachment says something about that file, and no Gherkin tag, label, environment or producer name is needed:
+
+```ts
+{ name: 'checkout.webm', role: 'video', tags: ['demo'], labels: { audience: 'business' } }
+```
+
+The viewer shows it as a `#demo` chip on the artifact card. Selecting the chip filters the result's evidence to the
+attachments with that tag, and says how many match. Tags describe evidence; they never change a status or a slot.
+
+- **One spelling.** A tag is normalized before it is compared or stored: a leading `#` is dropped, letters are
+  lower-cased, each run of whitespace becomes `-`, and surrounding space is trimmed, so `demo`, `#demo` and `#Demo ` are
+  `demo`. Empty tags and tags over 64 characters are not tags and are ignored (or refused, when a reviewer enters them).
+  Everything else is a valid tag (`team/payments`, `release=2`), and repeats are shown once.
+- **Inherited.** An attachment is also searchable by the tags of its check and its run. The viewer says `inherited` on
+  such a chip, and a switch decides whether the filter counts them: a recording without a tag of its own under a run
+  tagged `demo` is found by the inherited query and not by the exact one. In the API,
+  `GET /api/reports/tests?artifactTag=demo` is exact and adding `&inherited=1` includes inherited tags.
+- **Reviewers.** After upload, a person with a publish token can add tags to an attachment (the viewer's *Add tag*
+  button) and remove the ones a reviewer added. Those tags are not written into the layer, which is immutable: the
+  server keeps them as an audit trail (who, when, which tags) and the viewer shows them as `added by <name>`, apart
+  from the producer's tags. See [Tagging artifacts](server.md#tagging-artifacts). A producer's own tags stay as uploaded.
+- **Older layers.** A layer without attachment tags reads exactly as before. Tags on an attachment that cannot be read
+  (not a list of strings) are dropped, and the attachment, check and layer stay.
+
 ## Labels describe, parameters split
 
 A result's **slot** is its producer, check id, part kind, spec, environment and **parameters**. The newest completed
@@ -1404,6 +1432,26 @@ against a server unchanged. A client uploads **in dependency order**: blobs, the
 entry that makes it visible. The server checks each step and says no to a catalog entry whose manifest is not
 there (`409`), so nothing half-uploaded is ever shown.
 
+## Tagging artifacts
+
+A reviewer can mark a recording `#demo` after it was uploaded without uploading it again. The layer is immutable, so the
+tag is kept beside it: each edit is one small object under `curation/artifact-tags/` in the write backend (or the live
+store of a relay), named by time, never changed or removed. It records the attachment (layer, check, and the attachment's
+`id`, else its bytes' key, else its name), the normalized tags added and removed, the name of the token that made the
+edit, and the server's time. Nothing about the layer, its results or the report's winners changes.
+
+- `GET /api/reports/artifact-tags` (read) returns every edit, oldest first. Fold them to get the tags that stand now: the
+  last edit of a tag wins.
+- `POST /api/reports/artifact-tags` (publish, `Authorization: Bearer`) records an edit. A read token, an anonymous reader
+  and the browser's sign-in box are refused (`403`/`401`) like any upload, so a read-only visitor can see the tags and
+  not change them. The viewer asks for a token when a reviewer adds a tag and keeps it only in that tab.
+- Producer tags (`tags` on the attachment) and reviewer tags are kept apart everywhere: the viewer says who added a
+  reviewer tag and when, and a reviewer can remove only reviewer tags. `capabilities.artifactTags` on `/api/server` says
+  a server has this.
+
+See [Tagging artifacts and demos](rich-evidence.md#tagging-artifacts-and-demos) for the tag rules. Reviewer tags are
+shown in the viewer's evidence; the tests API (`artifactTag`) searches the producers' tags.
+
 ## Streaming
 
 `GET /api/events` is a server-sent-events stream:
@@ -1518,6 +1566,10 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `GET /api/projects/{project}/reports/tests/health` | read | Why specs, domains and counts disagree. |
 | `GET /api/reports/tests/history` | read | One test and every result recorded for it. |
 | `GET /api/projects/{project}/reports/tests/history` | read | One test and every result recorded for it. |
+| `GET /api/reports/artifact-tags` | read | Reviewer tags of attachments: every recorded edit. |
+| `GET /api/projects/{project}/reports/artifact-tags` | read | Reviewer tags of attachments: every recorded edit. |
+| `POST /api/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
+| `POST /api/projects/{project}/reports/artifact-tags` | publish | Tag or untag one attachment after upload. |
 | `GET /api/reports/runs` | read | The runs that recorded the report. |
 | `GET /api/projects/{project}/reports/runs` | read | The runs that recorded the report. |
 | `GET /api/reports/runs/detail` | read | Every test one run recorded. |
@@ -2542,6 +2594,9 @@ carry any of these. Every one is optional.
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |
 | `measurements[]` | Numbers, with units and an allowance (already part of the contract). |
 
+An attachment may carry its own `tags[]` (`demo`): shown as `#demo` and searchable; see
+[Tagging artifacts and demos](rich-evidence.md#tagging-artifacts-and-demos).
+
 On a **layer** the same fields describe the whole run: its CI log, a coverage report, an archive of traces, the
 build number, a link to the pipeline.
 
@@ -4794,6 +4849,8 @@ Send `format=markdown` (or `Accept: text/markdown`) for the same as a Markdown r
 - `domain` (query): Only tests whose spec is in this domain (`(no spec)` for none). Repeatable or comma-separated.
 - `spec` (query): Only tests of this spec path. Repeatable or comma-separated.
 - `tag` (query): Only tests with this tag. Repeatable or comma-separated.
+- `artifactTag` (query): Only tests with an attachment tagged this (`demo` and `#demo` are the same tag), not counting tags inherited from a check or run: the exact artifact query. `inherited=1` widens it to the tags inherited from the check and run. Repeatable or comma-separated.
+- `inherited` (query): With `artifactTag`: `1` also matches the tags an attachment inherits from its check and run, so a recording without a tag of its own under a run tagged `demo` is found. Without it the query is exact.
 - `run` (query): Only tests recorded in this run (a `key` from `/api/reports/runs`).
 - `sort` (query): The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.
 - `offset` (query): Skip this many matching tests.
@@ -4823,6 +4880,8 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 - `domain` (query): Only tests whose spec is in this domain (`(no spec)` for none). Repeatable or comma-separated.
 - `spec` (query): Only tests of this spec path. Repeatable or comma-separated.
 - `tag` (query): Only tests with this tag. Repeatable or comma-separated.
+- `artifactTag` (query): Only tests with an attachment tagged this (`demo` and `#demo` are the same tag), not counting tags inherited from a check or run: the exact artifact query. `inherited=1` widens it to the tags inherited from the check and run. Repeatable or comma-separated.
+- `inherited` (query): With `artifactTag`: `1` also matches the tags an attachment inherits from its check and run, so a recording without a tag of its own under a run tagged `demo` is found. Without it the query is exact.
 - `run` (query): Only tests recorded in this run (a `key` from `/api/reports/runs`).
 - `sort` (query): The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.
 - `offset` (query): Skip this many matching tests.
@@ -4891,6 +4950,50 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `200` The test and its history.; `304` Unchanged since the `If-None-Match` ETag.; `400` No `key`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No test in the report has that key.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
 
+### Reviewer tags of attachments: every recorded edit
+
+`GET /api/reports/artifact-tags` · role: read
+
+The audit trail of tags that reviewers added to and removed from attachments after upload, oldest first. Each entry says which attachment (`target`), which normalized tags were added and removed, the name of the token that made the edit (`by`, never the token) and when (`atMs`). The layers themselves are never rewritten, so a producer's own `tags` on an attachment stay as uploaded; fold the entries (oldest first, the last edit of a tag wins) to get the reviewer tags that stand now. Tags are normalized: `#Demo` and `demo` are `demo`.
+
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The edits.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Reviewer tags of attachments: every recorded edit
+
+`GET /api/projects/{project}/reports/artifact-tags` · role: read
+
+The audit trail of tags that reviewers added to and removed from attachments after upload, oldest first. Each entry says which attachment (`target`), which normalized tags were added and removed, the name of the token that made the edit (`by`, never the token) and when (`atMs`). The layers themselves are never rewritten, so a producer's own `tags` on an attachment stay as uploaded; fold the entries (oldest first, the last edit of a tag wins) to get the reviewer tags that stand now. Tags are normalized: `#Demo` and `demo` are `demo`.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The edits.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Tag or untag one attachment after upload
+
+`POST /api/reports/artifact-tags` · role: publish
+
+Records one edit of the reviewer tags of one attachment, by the name of the publish (or admin) token that sends it. It adds an immutable entry to the audit trail and changes nothing else: not the layer, not the movie, not any result. The tags it removes are reviewer tags only; a producer's tags are part of the layer and stay. A reader-only token, a browser sign-in box and an anonymous reader are refused. Name the attachment as `artifactRef` does (`id:<id>`, else `key:<bundleKey>`, else `name:<name>`).
+
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `201` The recorded entry.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `413` Request too large.; `422` Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.
+
+### Tag or untag one attachment after upload
+
+`POST /api/projects/{project}/reports/artifact-tags` · role: publish
+
+Records one edit of the reviewer tags of one attachment, by the name of the publish (or admin) token that sends it. It adds an immutable entry to the audit trail and changes nothing else: not the layer, not the movie, not any result. The tags it removes are reviewer tags only; a producer's tags are part of the layer and stay. A reader-only token, a browser sign-in box and an anonymous reader are refused. Name the attachment as `artifactRef` does (`id:<id>`, else `key:<bundleKey>`, else `name:<name>`).
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `201` The recorded entry.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `413` Request too large.; `422` Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.
+
 ### The runs that recorded the report
 
 `GET /api/reports/runs` · role: read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "0.14.0",
+  "version": "0.15.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/check-detail.schema.json

@@ -169,6 +169,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": {
@@ -397,6 +404,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": {
@@ -662,6 +676,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": {
@@ -862,6 +883,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": {

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

@@ -132,6 +132,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": {
@@ -358,6 +365,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": {