@crvouga/atlas 1.9.0 → 1.11.0

package/docs/reference/http-api.md

@@ -690,6 +690,128 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 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.
 
+### Review collections: curated sets of recordings, newest first
+
+`GET /api/reports/review-collections` · role: read
+
+The newest revision of every review collection, in brief: id, revision and how many exist, title, purpose, audience, tags, how many entries and gaps it has, who published it and when. A collection is curation kept beside the report; it is not a layer, a check or a run, and it has no status. Open one with `/api/reports/review-collections/detail?id=`. Its share URL is the viewer's `?tab=collections&collection=<id>` and needs the same read access as the rest of the report.
+
+- `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 collections.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Review collections: curated sets of recordings, newest first
+
+`GET /api/projects/{project}/reports/review-collections` · role: read
+
+The newest revision of every review collection, in brief: id, revision and how many exist, title, purpose, audience, tags, how many entries and gaps it has, who published it and when. A collection is curation kept beside the report; it is not a layer, a check or a run, and it has no status. Open one with `/api/reports/review-collections/detail?id=`. Its share URL is the viewer's `?tab=collections&collection=<id>` and needs the same read access as the rest of the report.
+
+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 collections.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Publish an immutable review collection (or a new revision of one)
+
+`POST /api/reports/review-collections` · role: publish
+
+Freezes an ordered set of references to recorded results as one named collection, recorded under the name of the publish (or admin) token that sends it. Take each entry's `layer` and `check` (and `kind`) from `GET /api/reports/artifacts`, and optionally one of its recordings (`videos[].recording`). The server resolves every entry to the result the report holds and records what the report says about it (status, time, run, commit, environment, tries, videos): the request does not claim them. An entry it cannot resolve refuses the whole request (`422`, naming the entry). The order is yours and is never re-sorted; failed, rejected and incomplete results stay in it beside a later passing replay.
+
+Entries from different runs are never one execution: each keeps its own layer, run and status. A collection has no status of its own, adds no check and cannot change any result or winner. A revision is immutable. To change a collection, publish a new revision with `basedOn: { id, revision }` naming the newest revision (`409` otherwise); the earlier ones stay readable. Notes and reviewed marks are separate (`/reviews`). A reader-only token, a browser sign-in box and an anonymous reader are refused; nothing is shared publicly by default.
+
+- `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 revision.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `404` `basedOn` names no collection.; `409` `basedOn.revision` is not the newest.; `413` Request too large.; `422` Not a collection, or an entry the report does not hold.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Publish an immutable review collection (or a new revision of one)
+
+`POST /api/projects/{project}/reports/review-collections` · role: publish
+
+Freezes an ordered set of references to recorded results as one named collection, recorded under the name of the publish (or admin) token that sends it. Take each entry's `layer` and `check` (and `kind`) from `GET /api/reports/artifacts`, and optionally one of its recordings (`videos[].recording`). The server resolves every entry to the result the report holds and records what the report says about it (status, time, run, commit, environment, tries, videos): the request does not claim them. An entry it cannot resolve refuses the whole request (`422`, naming the entry). The order is yours and is never re-sorted; failed, rejected and incomplete results stay in it beside a later passing replay.
+
+Entries from different runs are never one execution: each keeps its own layer, run and status. A collection has no status of its own, adds no check and cannot change any result or winner. A revision is immutable. To change a collection, publish a new revision with `basedOn: { id, revision }` naming the newest revision (`409` otherwise); the earlier ones stay readable. Notes and reviewed marks are separate (`/reviews`). A reader-only token, a browser sign-in box and an anonymous reader are refused; nothing is shared publicly by default.
+
+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 revision.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `404` `basedOn` names no collection.; `409` `basedOn.revision` is not the newest.; `413` Request too large.; `422` Not a collection, or an entry the report does not hold.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### One review collection revision with how its sources stand now
+
+`GET /api/reports/review-collections/detail` · role: read
+
+The revision (the newest without `revision`), every revision number, the review notes and reviewed marks of that revision, and for each entry `availability`: `available` (its layer is held and the report lists the result), `unverified` (the layer is held but the report no longer lists the result or recording) or `unavailable` (the layer is gone, for example deleted by garbage collection), with the reason. An entry whose source is not available stays in its place with its frozen snapshot; it is never removed or replaced. Entries keep the status each layer recorded, with their own times, in the order the curator chose. A reviewed mark is curation: it changes no outcome and is not an approval.
+
+- `id` (query, required): A collection id from the list.
+- `revision` (query): A revision number. Default: the newest.
+- `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 revision.; `400` No `id`, or a bad `revision`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No such collection or revision.
+
+### One review collection revision with how its sources stand now
+
+`GET /api/projects/{project}/reports/review-collections/detail` · role: read
+
+The revision (the newest without `revision`), every revision number, the review notes and reviewed marks of that revision, and for each entry `availability`: `available` (its layer is held and the report lists the result), `unverified` (the layer is held but the report no longer lists the result or recording) or `unavailable` (the layer is gone, for example deleted by garbage collection), with the reason. An entry whose source is not available stays in its place with its frozen snapshot; it is never removed or replaced. Entries keep the status each layer recorded, with their own times, in the order the curator chose. A reviewed mark is curation: it changes no outcome and is not an approval.
+
+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.
+- `id` (query, required): A collection id from the list.
+- `revision` (query): A revision number. Default: the newest.
+
+Responses: `200` The revision.; `400` No `id`, or a bad `revision`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No such collection or revision.
+
+### Add a note, a time-coded gap note or a reviewed mark to a collection entry
+
+`POST /api/reports/review-collections/reviews` · role: publish
+
+Records one immutable entry, by the name of the publish (or admin) token and the server's time: a `note` or a `gap` (text required; with `entry` and optionally `timecodeMs`, a moment in that entry's recording), or a `reviewed` / `unreviewed` mark for one entry. It changes no check outcome, no layer, no collection revision and no report winner; a mark is not an acceptance sign-off. The notes of a revision are in its `detail`.
+
+- `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 note.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `404` No such collection or revision.; `413` Request too large.; `422` Not a note: missing text, an unknown entry, or a mark without an entry.
+
+### Add a note, a time-coded gap note or a reviewed mark to a collection entry
+
+`POST /api/projects/{project}/reports/review-collections/reviews` · role: publish
+
+Records one immutable entry, by the name of the publish (or admin) token and the server's time: a `note` or a `gap` (text required; with `entry` and optionally `timecodeMs`, a moment in that entry's recording), or a `reviewed` / `unreviewed` mark for one entry. It changes no check outcome, no layer, no collection revision and no report winner; a mark is not an acceptance sign-off. The notes of a revision are in its `detail`.
+
+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 note.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `404` No such collection or revision.; `413` Request too large.; `422` Not a note: missing text, an unknown entry, or a mark without an entry.
+
+### Portable index (manifest) of one review collection revision
+
+`GET /api/reports/review-collections/export` · role: read
+
+A manifest an archive can be built from: the collection, each entry with its exact source (layer, check, kind, recording), the status and run it was recorded with, how it stands now, whether it is marked reviewed, and the files it references with their name as recorded, a safe name and path (`files/<position>-<safeName>`), and the recorded `sha256` when the report holds one (`null` is unknown, not verified). A source that cannot be read now is listed under `missing` and its files are marked `missing`; nothing is left out silently. The manifest contains no bytes; recordings are fetched from the attachment routes, which keep their own access control. Sent as an attachment.
+
+- `id` (query, required): A collection id.
+- `revision` (query): A revision number. Default: the newest.
+- `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 manifest.; `400` No `id`, or a bad `revision`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No such collection or revision.
+
+### Portable index (manifest) of one review collection revision
+
+`GET /api/projects/{project}/reports/review-collections/export` · role: read
+
+A manifest an archive can be built from: the collection, each entry with its exact source (layer, check, kind, recording), the status and run it was recorded with, how it stands now, whether it is marked reviewed, and the files it references with their name as recorded, a safe name and path (`files/<position>-<safeName>`), and the recorded `sha256` when the report holds one (`null` is unknown, not verified). A source that cannot be read now is listed under `missing` and its files are marked `missing`; nothing is left out silently. The manifest contains no bytes; recordings are fetched from the attachment routes, which keep their own access control. Sent as an attachment.
+
+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.
+- `id` (query, required): A collection id.
+- `revision` (query): A revision number. Default: the newest.
+
+Responses: `200` The manifest.; `400` No `id`, or a bad `revision`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No such collection or revision.
+
 ### The runs that recorded the report
 
 `GET /api/reports/runs` · role: read

package/docs/reference/reports.md

@@ -7784,6 +7784,298 @@ export async function pruneReports(store: ObjectStore): Promise<ReportRetentionP
 
 Same as `planReportRetention`. Despite the name it deletes nothing, and `deleteKeys` is always empty.
 
+### Review collections in a store
+
+Source: `packages/reports/src/review-collection-store.ts`. Import: `@crvouga/atlas/reports/review-collection-store`
+
+Where review collections are kept: one immutable object per revision under `curation/review-collections/<id>/`, and
+one small immutable object per reviewer's note under `curation/review-notes/<id>/`, named by time and a random id so
+editors never overwrite one another. Nothing here is ever changed or deleted by the server, and nothing here touches
+the layers the entries point at: a collection is curation beside the report, not a layer and not a test run.
+
+Publishing refuses; it never alters. A request the server cannot resolve to exact, held results is refused with
+the entry that failed, and what is recorded is what was asked for, plus what the report said about each source.
+
+See docs/server.md#review-collections
+
+#### `ReviewCollectionError`
+
+```ts
+export class ReviewCollectionError extends Error
+```
+
+The request was not acceptable. `status` is the HTTP status to answer: 404 (no such collection), 409 (not the newest revision) or 422.
+
+#### `ResultFinder`
+
+```ts
+export type ResultFinder = (layer: string, check: string, kind: string | undefined) => readonly ArtifactResult[];
+```
+
+Finds the recorded results of a layer's check (all kinds when `kind` is undefined).
+
+#### `reviewRevisions`
+
+```ts
+export async function reviewRevisions(store: ObjectStore, id: string): Promise<number[]>
+```
+
+The revisions that exist for a collection id, oldest first. Empty when there is none. Transport errors throw.
+
+#### `readReviewCollection`
+
+```ts
+export async function readReviewCollection(store: ObjectStore, id: string, revision?: number): Promise<{ readonly collection: ReviewCollection; readonly revisions: number[] } | null>
+```
+
+One revision of a collection (the newest when `revision` is absent), or `null` when there is none or it cannot be read
+as a collection (unknown, never guessed at). Transport errors throw.
+
+#### `recordReviewCollection`
+
+```ts
+export async function recordReviewCollection(store: ObjectStore, input: unknown, by: string, atMs: number, find: ResultFinder): Promise<ReviewCollection>
+```
+
+Validates a request (`ReviewCollectionRequestSchema`) and records it as a new immutable revision, by `by` at `atMs`.
+Without `basedOn` it is a new collection with a new id; with it, revision `basedOn.revision + 1` of that collection,
+and `basedOn.revision` must be the newest (409 otherwise) so two curators never silently overwrite each other.
+
+Every entry is resolved with `find`: it must name a result the report holds (and, when it names a recording, one of
+that result's recordings) or the whole request is refused with 422 naming the entry. The snapshot recorded for an entry
+is what the report says about that result, not what the request claims. Entries are kept in the order given and a
+source may appear once. Throws {@link ReviewCollectionError}; a revision that already exists is never overwritten.
+
+#### `listReviewCollections`
+
+```ts
+export async function listReviewCollections(store: ObjectStore): Promise<{ readonly collection: ReviewCollection; readonly revisions: number }[]>
+```
+
+The newest revision of every collection in `store`, newest first. One that cannot be read as a collection is skipped. Transport errors throw.
+
+#### `recordReviewNote`
+
+```ts
+export async function recordReviewNote(store: ObjectStore, input: unknown, by: string, atMs: number): Promise<ReviewNote>
+```
+
+Validates a note (`ReviewNoteInputSchema`) against the revision it is about and records it as a new object, by `by` at
+`atMs`. `note` and `gap` need text; `reviewed` and `unreviewed` need an entry; an entry must be one of the revision's;
+a timecode needs an entry. Throws {@link ReviewCollectionError} (404 for no such collection or revision). It records
+curation only: no layer, result or collection revision changes.
+
+#### `readReviewNotes`
+
+```ts
+export async function readReviewNotes(store: ObjectStore, id: string): Promise<ReviewNote[]>
+```
+
+Every recorded note of a collection (all revisions), oldest first. One that cannot be read as a note is skipped. Transport errors throw.
+
+### Review collections
+
+Source: `packages/reports/src/review-collection.ts`. Import: `@crvouga/atlas/reports/review-collection`
+
+A review collection is a named, curated, ordered set of references to results that other runs recorded: a few
+recordings from several executions, a note on what each is for, the gaps nobody recorded yet. It is curation, not a
+test run. It has no status of its own, carries no check, never decides a result or a winner, and never claims its
+entries are one execution: each entry keeps the layer, run, revision and status it was recorded with. A revision is
+immutable; changing a collection is publishing a new revision, explicitly. Reviewers' notes and "reviewed" marks live
+apart, as an append-only list with who and when, and are not outcomes.
+
+This module is pure and safe in a browser: how an entry is frozen from the result it points at, how an entry stands
+now (available, unverified, unavailable), how marks fold, and the portable manifest. The store is
+`review-collection-store.ts`.
+
+See docs/server.md#review-collections
+
+#### `ReviewSource`
+
+```ts
+export type ReviewSource = z.infer<typeof ReviewSourceSchema>;
+```
+
+The exact result (and optionally one recording of it) an entry points at.
+
+#### `ReviewSnapshot`
+
+```ts
+export type ReviewSnapshot = z.infer<typeof ReviewSnapshotSchema>;
+```
+
+What was recorded about a source when it was frozen.
+
+#### `ReviewEntry`
+
+```ts
+export type ReviewEntry = z.infer<typeof ReviewEntrySchema>;
+```
+
+One entry of a collection revision.
+
+#### `ReviewCollection`
+
+```ts
+export type ReviewCollection = z.infer<typeof ReviewCollectionSchema>;
+```
+
+One immutable revision of a collection.
+
+#### `ReviewNote`
+
+```ts
+export type ReviewNote = z.infer<typeof ReviewNoteSchema>;
+```
+
+A recorded note, time-coded gap note or reviewed mark.
+
+#### `ReviewAvailability`
+
+```ts
+export type ReviewAvailability = z.infer<typeof ReviewAvailabilitySchema>;
+```
+
+How an entry's source stands now.
+
+#### `ReviewCollectionDetail`
+
+```ts
+export type ReviewCollectionDetail = z.infer<typeof ReviewCollectionDetailSchema>;
+```
+
+`GET /api/reports/review-collections/detail`: one revision, how its sources stand now, and its notes.
+
+#### `ReviewCollectionList`
+
+```ts
+export type ReviewCollectionList = z.infer<typeof ReviewCollectionListSchema>;
+```
+
+`GET /api/reports/review-collections`: the newest revision of every collection.
+
+#### `ReviewManifest`
+
+```ts
+export type ReviewManifest = z.infer<typeof ReviewManifestSchema>;
+```
+
+The portable index of one revision.
+
+#### `REVIEW_COLLECTIONS_PREFIX`
+
+```ts
+export const REVIEW_COLLECTIONS_PREFIX = …
+```
+
+Where the revisions of collections are kept in a store: `<prefix><id>/r<revision, six digits>.json`.
+
+#### `REVIEW_NOTES_PREFIX`
+
+```ts
+export const REVIEW_NOTES_PREFIX = …
+```
+
+Where reviewers' notes are kept: `<prefix><collection id>/<time>-<random>.json`, one object each.
+
+#### `REVIEW_ID`
+
+```ts
+export const REVIEW_ID = …
+```
+
+A collection id as the server mints it and the address carries it. Anything else is not an id (and never reaches a store key).
+
+#### `reviewCollectionKey`
+
+```ts
+export function reviewCollectionKey(id: string, revision: number): string
+```
+
+The store key of one revision of a collection.
+
+#### `sameSource`
+
+```ts
+export function sameSource(a: ReviewSource, b: ReviewSource): boolean
+```
+
+Whether two sources name the same result and recording. `kind` counts only when both have one.
+
+#### `snapshotOf`
+
+```ts
+export function snapshotOf(result: ArtifactResult): ReviewSnapshot
+```
+
+What is recorded about a result when an entry is frozen: its own status, time, run, commit and videos, as the layer
+recorded them. Nothing here is the collection's opinion, and none of it is ever updated: a later run does not change it.
+
+#### `availabilityOf`
+
+```ts
+export function availabilityOf(
+  collection: Pick<ReviewCollection, 'entries'>,
+  layerHeld: (layer: string) => boolean,
+  results: (layer: string, check: string, kind: string | undefined) => readonly ArtifactResult[]
+): ReviewAvailability[]
+```
+
+How the sources of a collection stand now. `layerHeld` says whether a layer is still in a backend; `results` finds the
+results the report holds. A layer that is gone makes its entries `unavailable`; a layer that is held while the report
+no longer lists the result (or the recording) is `unverified`, not available and not gone. Every entry keeps its place
+and its explanation: nothing is removed or replaced.
+
+#### `foldReviewed`
+
+```ts
+export function foldReviewed(notes: readonly ReviewNote[]): Record<string, { readonly by: string; readonly atMs: number }>
+```
+
+Folds the notes into the reviewed marks that stand now: for each entry the newest `reviewed` or `unreviewed` decides
+(ties in time go to the later id). Only entries currently `reviewed` are returned, with who and when. A mark is
+curation: it is not a check outcome and does not mean anyone accepted the behavior.
+
+#### `safeFileName`
+
+```ts
+export function safeFileName(name: string): string
+```
+
+A name that is safe to write to any file system: the last path segment only, letters, digits, dot, dash and
+underscore (everything else becomes `_`), no leading dot, at most 100 characters, never empty.
+
+**Example**
+
+```ts
+safeFileName('../../etc/pass wd.webm'); // 'pass_wd.webm'
+```
+
+#### `digestOf`
+
+```ts
+export function digestOf(recording: string | undefined): string | null
+```
+
+The digest in a recording identity (`sha256:<64 hex>`), or null when the identity is a bundle key or address: the bytes' hash is then not known.
+
+#### `manifestOf`
+
+```ts
+export function manifestOf(
+  collection: ReviewCollection,
+  availability: readonly ReviewAvailability[],
+  reviewed: Readonly<Record<string, unknown>>,
+  generatedAtMs: number
+): ReviewManifest
+```
+
+The portable index of one revision: every entry with where its result came from, how it stands now, whether it was
+marked reviewed, and the files (recordings) it references, each with its recorded digest when there is one and a name
+that is safe to write. A file whose source cannot be read now is listed as `missing`, with the reason under `missing`
+of the manifest, never left out. The manifest has no bytes; it is what a packer needs to build an archive that says
+what it lacks.
+
 ### Run bundles
 
 Source: `packages/reports/src/run-bundle.ts`. Import: `@crvouga/atlas/reports/run-bundle`
@@ -9391,6 +9683,8 @@ export type ArtifactResult = {
   readonly types: readonly string[];
   readonly labels: Readonly<Record<string, string>>;
   readonly videos?: readonly VideoRef[];
+  /** The status of each recorded try in order, when the check was retried. Absent when no try was recorded: a first try is then unknown, never assumed to have passed. */
+  readonly attemptStatuses?: readonly EvidenceStatus[];
 };
 ```
 

package/docs/reference/schema.md

@@ -233,6 +233,137 @@ export const ArtifactTagsSchema = …
 
 `GET /api/reports/artifact-tags`: every recorded edit, oldest first. Fold them with `foldArtifactTags`.
 
+#### `ReviewSourceSchema`
+
+```ts
+export const ReviewSourceSchema = …
+```
+
+A source a review collection points at: one recorded result of one archived layer, and optionally one of its recordings. Exact and immutable: a layer never changes.
+
+#### `ReviewEntryInputSchema`
+
+```ts
+export const ReviewEntryInputSchema = …
+```
+
+One entry of a request to publish a collection: a source and the curator\'s caption for it.
+
+#### `ReviewGapInputSchema`
+
+```ts
+export const ReviewGapInputSchema = …
+```
+
+A gap the curator names: something the review should show and no recording does. It sits after the first `after` entries (0 or absent: before the first).
+
+#### `ReviewCollectionRequestSchema`
+
+```ts
+export const ReviewCollectionRequestSchema = …
+```
+
+The body of `POST /api/reports/review-collections`: a new collection, or, with `basedOn`, an explicit new revision of
+one. At least one entry or gap. The server records which sources the entries are now; it never alters the request.
+
+#### `ReviewSnapshotSchema`
+
+```ts
+export const ReviewSnapshotSchema = …
+```
+
+What the server recorded about the source of an entry at the moment it was frozen.
+
+#### `ReviewEntrySchema`
+
+```ts
+export const ReviewEntrySchema = …
+```
+
+One entry of a frozen collection.
+
+#### `ReviewGapSchema`
+
+```ts
+export const ReviewGapSchema = …
+```
+
+A gap item of a collection.
+
+#### `ReviewCollectionSchema`
+
+```ts
+export const ReviewCollectionSchema = …
+```
+
+One revision of a review collection, as stored: immutable. It is curation, not a test run: it has no status of its own,
+carries no check, and its entries are references to results that other runs recorded. Entries from different
+runs are never one execution.
+
+#### `ReviewCollectionSummarySchema`
+
+```ts
+export const ReviewCollectionSummarySchema = …
+```
+
+One collection in the list: its newest revision in brief.
+
+#### `ReviewCollectionListSchema`
+
+```ts
+export const ReviewCollectionListSchema = …
+```
+
+`GET /api/reports/review-collections`: the newest revision of every collection, newest first.
+
+#### `ReviewNoteInputSchema`
+
+```ts
+export const ReviewNoteInputSchema = …
+```
+
+The body of `POST /api/reports/review-collections/reviews`: a note, a time-coded gap note, or a reviewed marker on one entry. Curation only: it changes no outcome.
+
+#### `ReviewNoteSchema`
+
+```ts
+export const ReviewNoteSchema = …
+```
+
+One recorded review note. Entries are never changed or removed: they are the audit trail.
+
+#### `ReviewAvailabilitySchema`
+
+```ts
+export const ReviewAvailabilitySchema = …
+```
+
+How an entry\'s source stands now: `available` (the layer and the result are in the report), `unverified` (the layer is held but the result is outside the report\'s history window) or `unavailable` (the layer is gone).
+
+#### `ReviewCollectionDetailSchema`
+
+```ts
+export const ReviewCollectionDetailSchema = …
+```
+
+`GET /api/reports/review-collections/detail`: one revision, how each source stands now, and the review notes.
+
+#### `ReviewManifestFileSchema`
+
+```ts
+export const ReviewManifestFileSchema = …
+```
+
+One file in an export manifest.
+
+#### `ReviewManifestSchema`
+
+```ts
+export const ReviewManifestSchema = …
+```
+
+`GET /api/reports/review-collections/export`: a portable index of one revision. It lists sources and files; it contains no bytes.
+
 #### `HelloEventSchema`
 
 ```ts

package/docs/reference/server.md

@@ -625,6 +625,50 @@ export function projectServer(options: AtlasServerOptions, create: (options: Atl
 
 Wrap the single-project protocol in project selection. Auth, upload validation and composition stay identical.
 
+### Review collection routes
+
+Source: `packages/server/src/review-collections.ts`
+
+`/api/reports/review-collections`: publish an immutable, named, ordered collection of references to recorded results
+(with notes and gaps), read it back with how every source stands now, add reviewers' notes and "reviewed" marks, and
+export a portable manifest. A collection is curation kept beside the report under `curation/`: it is never a layer, a
+check or a run, changes no status, slot or winner, and never alters what is uploaded. Reading needs a reader (the
+same as the rest of the report, so nothing becomes public by sharing a link); publishing and noting need a Bearer
+token with the `publish` role, recorded under that token's name. Recordings are still served only by the attachment
+routes, under their own access control.
+
+See docs/server.md#review-collections
+
+#### `ReviewCollectionDeps`
+
+```ts
+export type ReviewCollectionDeps = {
+  /** Where collections and notes are kept: the write backend's store. */
+  readonly store: ObjectStore;
+  /** Every backend's store, to tell whether a layer is still held anywhere. */
+  readonly stores: readonly ObjectStore[];
+  readonly auth: Auth;
+  readonly index: ReportIndex;
+  readonly now: () => number;
+  /** The largest request body, in bytes. */
+  readonly maxBytes: number;
+  readonly unauthorized: (verdict: Extract<ReturnType<Auth['check']>, { ok: false }>) => Response;
+};
+```
+
+What the review collection routes need from the server around them.
+
+#### `mountReviewCollections`
+
+```ts
+export function mountReviewCollections(app: Hono, deps: ReviewCollectionDeps): void
+```
+
+Registers the review collection routes on `app`:
+`GET /api/reports/review-collections`, `POST /api/reports/review-collections`,
+`GET /api/reports/review-collections/detail`, `POST /api/reports/review-collections/reviews` and
+`GET /api/reports/review-collections/export`.
+
 ### settings-page.ts
 
 Source: `packages/server/src/settings-page.ts`

package/docs/rich-evidence.md

@@ -183,6 +183,44 @@ curl "$ATLAS_SERVER_URL/api/reports/artifacts?artifactTag=demo&type=video&domain
   **live query**: opening it asks again and shows what matches the newest report. It is not a snapshot; an immutable
   review collection is a separate feature. *Copy link* gives the address, which holds the whole query.
 
+## Words in recordings
+
+A reviewer who remembers a phrase that was spoken or shown in a video can search for it on the **Artifacts** tab
+(**Search inside recordings**, the `inside` address parameter). Atlas never transcribes video or reads a screen: it
+searches text you attach, and nothing is read from a recording until words are typed. Attach it beside the video, at the
+same level (the check, or the retry attempt that recorded the video):
+
+```ts
+attachments: [
+  { id: 'video', name: 'checkout.webm', contentType: 'video/webm', data: video },
+  // Spoken words: WebVTT, SubRip, JSON segments or plain text.
+  { name: 'checkout.vtt', role: 'transcript', contentType: 'text/vtt', data: transcript,
+    extensions: { 'atlas.text': { recording: 'video', generated: true, generator: 'my-speech-tool' } } },
+  // Text shown on screen, with its own timing.
+  { name: 'screen.json', role: 'ocr', contentType: 'application/json', data: JSON.stringify({ segments: [{ start: 2, end: 4, text: 'Order total', confidence: 0.9 }] }) }
+]
+```
+
+- **Which attachment is text.** One with `extensions["atlas.text"]`, a `role` of `transcript`, `ocr`, `screen-text`,
+  `captions` or `subtitles`, or a WebVTT or SubRip type. `extensions["atlas.text"].kind` (`speech`, `screen`, `caption`)
+  says what it is; otherwise the role does. It belongs to the video that lists its `id` in `captions`, or that
+  `extensions["atlas.text"].recording` names by `id`, else to the only video at the same level.
+- **Segments.** WebVTT and SubRip cues; JSON as `{ "segments": [...] }` (or `cues`, `results`, `lines`, or a bare list) of
+  `{ text, start, end }` in seconds or `{ text, startMs, endMs }`, with an optional `confidence` between 0 and 1. A
+  segment whose time is missing or invalid is still searched and is shown with no time; the viewer offers the recording
+  and says seeking is unavailable, and never guesses a moment.
+- **Honesty about the text.** `generated: true` (with `generator`) marks text a tool produced; results show it with its
+  confidence and say it may contain errors. A result always shows the indexed words, never a reworded quotation. A
+  match finds a moment; it is not a new assertion, and the result's own outcome and the retry attempt stay beside it.
+- **States are different things.** Searched with no match; not indexed (no text was supplied); unsupported (the video is
+  silent by its `scope.audioCaptured: false`, or the text is in a form that is not read, or sits at a `uri`); failed
+  (`extensions["atlas.text"].state: "failed"` with a `reason`, a file left out with `omitted`, or text that did not
+  parse). The ones not searched are listed apart and never counted as "no match".
+- **Access.** The text is read through the same report API, and so the same access rules, that play the recording. A file
+  the viewer may not read is not indexed and appears in no snippet or count. The index exists only in the open page: there
+  is no stored or cross-project index. Sending evidence to a transcription or OCR service is the producer's explicit
+  decision and happens outside Atlas.
+
 ## Labels describe, parameters split
 
 A result's **slot** is its producer, check id, part kind, spec, environment and **parameters**. The newest completed