@crvouga/atlas 1.9.0 → 1.11.0

package/dist/schema/src/api.js

@@ -240,6 +240,156 @@ export const ArtifactTagsSchema = z.looseObject({
     schemaVersion: z.literal(1),
     entries: z.array(ArtifactTagEntrySchema)
 });
+/** 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. */
+export const ReviewSourceSchema = z.looseObject({
+    layer: z.string().regex(/^[0-9a-f]{64}$/).describe('The id of the archived layer that recorded the result'),
+    check: z.string().min(1).max(1024).describe('The check\'s id in that layer'),
+    kind: z.string().min(1).max(256).optional().describe('The kind of the part holding the check, when the same id exists in several parts'),
+    recording: z.string().min(1).max(2048).optional().describe('One recording of the result (`VideoRef.recording`: `sha256:…`, a bundle key or an address). Absent: the result as a whole')
+});
+/** One entry of a request to publish a collection: a source and the curator\'s caption for it. */
+export const ReviewEntryInputSchema = z.looseObject({
+    ...ReviewSourceSchema.shape,
+    caption: z.string().max(500).optional().describe('What the curator wants the reviewer to look at in this entry')
+});
+/** 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). */
+export const ReviewGapInputSchema = z.looseObject({
+    note: z.string().min(1).max(2000).describe('What is missing or unclear'),
+    after: z.number().int().min(0).optional().describe('Place the gap after this many entries (0 or absent: before the first)')
+});
+/**
+ * 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.
+ */
+export const ReviewCollectionRequestSchema = z.looseObject({
+    title: z.string().min(1).max(200),
+    purpose: z.string().max(2000).optional().describe('Why this review exists'),
+    audience: z.string().max(500).optional().describe('Who should review it'),
+    tags: z.array(z.string()).max(20).optional().describe('Tags of the collection, such as `demo` (normalized like artifact tags)'),
+    entries: z.array(ReviewEntryInputSchema).max(500).optional().describe('Ordered. The order is the order of the review; it is never re-sorted by time or status'),
+    gaps: z.array(ReviewGapInputSchema).max(100).optional(),
+    frozenFrom: z.string().max(4000).optional().describe('The live filtered view the entries were frozen from, as its address query (informational; the entries are what count)'),
+    basedOn: z.looseObject({ id: z.string(), revision: z.number().int().min(1) }).optional().describe('Publish a new revision of this collection. `revision` must be its newest, else 409')
+});
+/** What the server recorded about the source of an entry at the moment it was frozen. */
+export const ReviewSnapshotSchema = z.looseObject({
+    title: z.string(),
+    specPath: z.string().nullable(),
+    status: EvidenceStatusSchema.describe('The result\'s recorded status, as that layer recorded it'),
+    recordedAtMs: z.number(),
+    environment: z.string().nullable(),
+    producer: z.string(),
+    branch: z.string().nullable(),
+    sha: z.string().nullable(),
+    run: z.string().describe('The key of the run it belongs to'),
+    runUrl: z.string().nullable(),
+    backend: z.string().nullable().describe('The backend the layer was read from'),
+    testKey: z.string().describe('The test\'s key, as `GET /api/reports/tests` lists it'),
+    attemptStatuses: z.array(EvidenceStatusSchema).optional().describe('The status of each recorded try, in order, when the check was retried. Never collapsed to the last'),
+    videos: z.array(VideoRefSchema).optional().describe('Its references to videos when it was frozen')
+});
+/** One entry of a frozen collection. */
+export const ReviewEntrySchema = z.looseObject({
+    id: z.string().describe('Stable within the collection; notes and reviewed marks refer to it'),
+    source: ReviewSourceSchema,
+    caption: z.string().optional(),
+    snapshot: ReviewSnapshotSchema
+});
+/** A gap item of a collection. */
+export const ReviewGapSchema = z.looseObject({
+    id: z.string(),
+    note: z.string(),
+    after: z.number().int().nonnegative().describe('It sits after this many entries')
+});
+/**
+ * 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.
+ */
+export const ReviewCollectionSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    id: z.string().describe('The collection\'s stable id, in its share URL'),
+    revision: z.number().int().min(1).describe('1 for the first; every change is a new revision'),
+    title: z.string(),
+    purpose: z.string().optional(),
+    audience: z.string().optional(),
+    tags: z.array(z.string()),
+    entries: z.array(ReviewEntrySchema),
+    gaps: z.array(ReviewGapSchema),
+    frozenFrom: z.string().optional(),
+    basedOn: z.looseObject({ id: z.string(), revision: z.number().int().min(1) }).optional(),
+    createdBy: z.string().describe('The name of the token that published it (never the token)'),
+    createdAtMs: z.number().describe('When the server recorded it, epoch milliseconds')
+});
+/** One collection in the list: its newest revision in brief. */
+export const ReviewCollectionSummarySchema = z.looseObject({
+    id: z.string(), revision: z.number().int().min(1), revisions: z.number().int().min(1).describe('How many revisions exist'),
+    title: z.string(), purpose: z.string().optional(), audience: z.string().optional(), tags: z.array(z.string()),
+    entries: z.number().int().nonnegative(), gaps: z.number().int().nonnegative(), createdBy: z.string(), createdAtMs: z.number()
+});
+/** `GET /api/reports/review-collections`: the newest revision of every collection, newest first. */
+export const ReviewCollectionListSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    collections: z.array(ReviewCollectionSummarySchema)
+});
+/** 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. */
+export const ReviewNoteInputSchema = z.looseObject({
+    collection: z.string().describe('The collection id'),
+    revision: z.number().int().min(1),
+    entry: z.string().optional().describe('The entry\'s id; required for `reviewed`, `unreviewed` and a timecode'),
+    kind: z.enum(['note', 'gap', 'reviewed', 'unreviewed']),
+    text: z.string().max(4000).optional().describe('Required for `note` and `gap`'),
+    timecodeMs: z.number().int().min(0).optional().describe('A moment in the entry\'s recording, in milliseconds')
+});
+/** One recorded review note. Entries are never changed or removed: they are the audit trail. */
+export const ReviewNoteSchema = z.looseObject({
+    id: z.string().describe('Unique and time-ordered'),
+    collection: z.string(), revision: z.number().int().min(1),
+    entry: z.string().optional(),
+    kind: z.enum(['note', 'gap', 'reviewed', 'unreviewed']),
+    text: z.string().optional(),
+    timecodeMs: z.number().optional(),
+    by: z.string().describe('The name of the token that made it (never the token)'),
+    atMs: z.number()
+});
+/** 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). */
+export const ReviewAvailabilitySchema = z.looseObject({
+    entry: z.string(),
+    state: z.enum(['available', 'unverified', 'unavailable']),
+    reason: z.string().optional().describe('Why it is not `available`, in words')
+});
+/** `GET /api/reports/review-collections/detail`: one revision, how each source stands now, and the review notes. */
+export const ReviewCollectionDetailSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    collection: ReviewCollectionSchema,
+    revisions: z.array(z.number().int().min(1)).describe('Every revision that exists, oldest first'),
+    availability: z.array(ReviewAvailabilitySchema),
+    reviews: z.array(ReviewNoteSchema).describe('Notes and marks of this revision, oldest first'),
+    reviewed: z.record(z.string(), z.looseObject({ by: z.string(), atMs: z.number() })).describe('Entries whose latest mark is `reviewed`, with who and when')
+});
+/** One file in an export manifest. */
+export const ReviewManifestFileSchema = z.looseObject({
+    name: z.string().describe('The attachment\'s name as recorded'),
+    safeName: z.string().describe('A name safe to write to a file system: letters, digits, dot, dash and underscore'),
+    path: z.string().describe('Where a packer should put it: `files/<entry position>-<safeName>`'),
+    recording: z.string().optional(),
+    sha256: z.string().nullable().describe('The digest of the bytes when the report recorded one, else null: unknown, not verified'),
+    missing: z.boolean().describe('True when the source cannot be read now')
+});
+/** `GET /api/reports/review-collections/export`: a portable index of one revision. It lists sources and files; it contains no bytes. */
+export const ReviewManifestSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    generatedAtMs: z.number(),
+    collection: z.looseObject({ id: z.string(), revision: z.number().int().min(1), title: z.string(), purpose: z.string().optional(), audience: z.string().optional(), tags: z.array(z.string()), createdBy: z.string(), createdAtMs: z.number() }),
+    entries: z.array(z.looseObject({
+        id: z.string(), position: z.number().int().min(1), caption: z.string().optional(), source: ReviewSourceSchema, snapshot: ReviewSnapshotSchema,
+        state: z.enum(['available', 'unverified', 'unavailable']), reason: z.string().optional(), reviewed: z.boolean(),
+        files: z.array(ReviewManifestFileSchema)
+    })),
+    gaps: z.array(ReviewGapSchema),
+    missing: z.array(z.looseObject({ entry: z.string(), reason: z.string() })).describe('Entries whose sources cannot be read now, and every file that is missing'),
+    notes: z.string()
+});
 /** The data of the `hello` event: sent first on `/api/events`. */
 export const HelloEventSchema = z.looseObject({ version: z.string(), ready: z.boolean(), time: z.number(), heartbeatMs: z.number().positive().optional() });
 /** The data of the `report` event: layers arrived. Enough to say who sent what, without asking. */
@@ -490,7 +640,8 @@ export const ArtifactResultSchema = z.looseObject({
     tags: z.array(z.string()).describe('Tags of its check and run, which its attachments inherit'),
     types: z.array(z.string()).describe('Media types (roles) of its attachments; `video` only for a playable recording'),
     labels: z.record(z.string(), z.string()),
-    videos: z.array(VideoRefSchema).optional()
+    videos: z.array(VideoRefSchema).optional(),
+    attemptStatuses: z.array(EvidenceStatusSchema).optional().describe('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')
 });
 /** `GET /api/reports/artifacts`: recorded results that carry evidence, newest first, with the facets of the query. */
 export const ArtifactListSchema = z.looseObject({

package/dist/server/src/app.js

@@ -42,6 +42,7 @@ import { Refusal } from './validate.js';
 import { createAuth } from './auth.js';
 import { EventHub } from './events.js';
 import { projectServer } from './projects.js';
+import { mountReviewCollections } from './review-collections.js';
 import { readLimited, storeApi } from './store-api.js';
 const gzipAsync = promisify(gzip);
 const brotliAsync = promisify(brotliCompress);
@@ -258,7 +259,7 @@ function createProjectApplication(options) {
             name: 'atlas', version: options.version ?? null, role: identity?.role ?? 'read', open: auth.open,
             write: options.write, ready: index.ready, viewers: events.count, time: now(),
             backends: snapshot.backends.map(({ id, label, available }) => ({ id, label, available, write: id === options.write })),
-            ...(({ backends: _unused, ...rest }) => rest)(index.stats()), capabilities: { events: true, ingest: true, store: true, checks: true, status: true, effective: true, live: true, tests: true, artifactTags: true, artifactSearch: true }
+            ...(({ backends: _unused, ...rest }) => rest)(index.stats()), capabilities: { events: true, ingest: true, store: true, checks: true, status: true, effective: true, live: true, tests: true, artifactTags: true, artifactSearch: true, reviewCollections: true }
         });
     });
     app.get('/api/live', async (c) => c.json({ runs: await live.list() }, 200, { 'cache-control': 'no-store' }));
@@ -543,6 +544,8 @@ function createProjectApplication(options) {
             throw error;
         }
     });
+    // Review collections: immutable, curated references to recorded results, with reviewers' notes kept apart.
+    mountReviewCollections(app, { store: tagStore, stores, auth, index, now, maxBytes: limits.json, unauthorized });
     app.route('/api/reports', layers);
     // Upload: the store protocol, and a simple JSON way in for anything that can make a request.
     app.route('/api/store', storeApi({

package/dist/server/src/openapi.js

@@ -14,7 +14,7 @@
  */
 import { z } from 'zod/v4';
 import { ProjectsSchema } from '../../schema/src/project.js';
-import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema } from '../../schema/src/api.js';
+import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema, ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewCollectionListSchema, ReviewCollectionDetailSchema, ReviewNoteInputSchema, ReviewNoteSchema, ReviewManifestSchema } from '../../schema/src/api.js';
 import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, GcPolicySchema, GcSnapshotSchema, GcRunResultSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
 export const API_VERSION = '1.5.0';
@@ -37,6 +37,7 @@ const COMPONENTS = {
     StoreListing: [StoreListingSchema, 'output'], StoreWriteResult: [StoreWriteResultSchema, 'output'],
     Outline: [OutlineSchema, 'output'], EvidencePage: [EvidencePageSchema, 'output'], LayerRows: [LayerRowsSchema, 'output'], CheckDetail: [CheckDetailSchema, 'output'],
     ArtifactTagEdit: [ArtifactTagEditSchema, 'input'], ArtifactTagEntry: [ArtifactTagEntrySchema, 'output'], ArtifactTags: [ArtifactTagsSchema, 'output'],
+    ReviewCollectionRequest: [ReviewCollectionRequestSchema, 'input'], ReviewCollection: [ReviewCollectionSchema, 'output'], ReviewCollectionList: [ReviewCollectionListSchema, 'output'], ReviewCollectionDetail: [ReviewCollectionDetailSchema, 'output'], ReviewNoteInput: [ReviewNoteInputSchema, 'input'], ReviewNote: [ReviewNoteSchema, 'output'], ReviewManifest: [ReviewManifestSchema, 'output'],
     TestCatalog: [TestCatalogSchema, 'output'], CatalogHealth: [CatalogHealthSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], TestReliability: [TestReliabilitySchema, 'output'], RunList: [RunListSchema, 'output'], ArtifactList: [ArtifactListSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
     SpecIndex: [SpecIndexSchema, 'output'], ReportSources: [ReportSourcesSchema, 'output'], RunsIndex: [RunsIndexSchema, 'output'],
     RunEvent: [LiveRunSchema, 'output'], HelloEvent: [HelloEventSchema, 'output'], ReportEvent: [ReportEventSchema, 'output'], AtlasChangeEvent: [AtlasChangeSchema, 'output'], PingEvent: [PingEventSchema, 'output']
@@ -364,6 +365,50 @@ const BASE_OPERATIONS = [
         body: { description: 'The attachment and the tags to add and remove. At most 20 of each, 64 KiB.', contentType: 'application/json', required: true, schema: ref('ArtifactTagEdit') },
         responses: { '201': json('The recorded entry.', 'ArtifactTagEntry'), '401': UNAUTHORIZED, '403': FORBIDDEN, '413': problem('Request too large.'), '422': problem('Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.') }
     },
+    {
+        route: 'GET /api/reports/review-collections', path: '/api/reports/review-collections', operationId: 'listReviewCollections', tag: 'Report', role: 'read',
+        summary: 'Review collections: curated sets of recordings, newest first',
+        description: '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.',
+        responses: { '200': json('The collections.', 'ReviewCollectionList'), '401': UNAUTHORIZED }
+    },
+    {
+        route: 'POST /api/reports/review-collections', path: '/api/reports/review-collections', operationId: 'publishReviewCollection', tag: 'Report', role: 'publish',
+        summary: 'Publish an immutable review collection (or a new revision of one)',
+        description: [
+            '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.'
+        ].join('\n'),
+        body: { description: 'The title, optional purpose, audience and tags, the ordered entries, optional gaps, and `basedOn` for a new revision. At most 500 entries and 100 gaps.', contentType: 'application/json', required: true, schema: ref('ReviewCollectionRequest') },
+        responses: { '201': json('The recorded revision.', 'ReviewCollection'), '401': UNAUTHORIZED, '403': FORBIDDEN, '404': problem('`basedOn` names no collection.'), '409': problem('`basedOn.revision` is not the newest.'), '413': problem('Request too large.'), '422': problem('Not a collection, or an entry the report does not hold.'), '503': NOT_READY }
+    },
+    {
+        route: 'GET /api/reports/review-collections/detail', path: '/api/reports/review-collections/detail', operationId: 'getReviewCollection', tag: 'Report', role: 'read',
+        summary: 'One review collection revision with how its sources stand now',
+        description: '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.',
+        parameters: [
+            { name: 'id', in: 'query', required: true, description: 'A collection id from the list.', schema: str, example: 'rc-0123456789abcdef' },
+            { name: 'revision', in: 'query', description: 'A revision number. Default: the newest.', schema: { type: 'integer', minimum: 1 } }
+        ],
+        responses: { '200': json('The revision.', 'ReviewCollectionDetail'), '400': problem('No `id`, or a bad `revision`.'), '401': UNAUTHORIZED, '404': problem('No such collection or revision.') }
+    },
+    {
+        route: 'POST /api/reports/review-collections/reviews', path: '/api/reports/review-collections/reviews', operationId: 'addReviewNote', tag: 'Report', role: 'publish',
+        summary: 'Add a note, a time-coded gap note or a reviewed mark to a collection entry',
+        description: '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`.',
+        body: { description: 'The collection and revision, optionally the entry, the kind and its text.', contentType: 'application/json', required: true, schema: ref('ReviewNoteInput') },
+        responses: { '201': json('The recorded note.', 'ReviewNote'), '401': UNAUTHORIZED, '403': FORBIDDEN, '404': problem('No such collection or revision.'), '413': problem('Request too large.'), '422': problem('Not a note: missing text, an unknown entry, or a mark without an entry.') }
+    },
+    {
+        route: 'GET /api/reports/review-collections/export', path: '/api/reports/review-collections/export', operationId: 'exportReviewCollection', tag: 'Report', role: 'read',
+        summary: 'Portable index (manifest) of one review collection revision',
+        description: '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.',
+        parameters: [
+            { name: 'id', in: 'query', required: true, description: 'A collection id.', schema: str },
+            { name: 'revision', in: 'query', description: 'A revision number. Default: the newest.', schema: { type: 'integer', minimum: 1 } }
+        ],
+        responses: { '200': json('The manifest.', 'ReviewManifest'), '400': problem('No `id`, or a bad `revision`.'), '401': UNAUTHORIZED, '404': problem('No such collection or revision.') }
+    },
     {
         route: 'GET /api/reports/runs', path: '/api/reports/runs', operationId: 'getReportRuns', tag: 'Report', role: 'read',
         summary: 'The runs that recorded the report',

package/dist/server/src/review-collections.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @module Review collection routes
+ *
+ * `/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
+ */
+import type { Hono } from 'hono';
+import type { ObjectStore } from '../../reports/src/object-store.js';
+import type { ReportIndex } from '../../reports/src/report-index.js';
+import type { Auth } from './auth.js';
+/** What the review collection routes need from the server around them. */
+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;
+};
+/**
+ * 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`.
+ */
+export declare function mountReviewCollections(app: Hono, deps: ReviewCollectionDeps): void;

package/dist/server/src/review-collections.js

@@ -0,0 +1,179 @@
+import { eachLimited } from '../../reports/src/completion-order.js';
+import { layerKey } from '../../reports/src/layer-store.js';
+import { availabilityOf, foldReviewed, manifestOf } from '../../reports/src/review-collection.js';
+import { listReviewCollections, readReviewCollection, readReviewNotes, recordReviewCollection, recordReviewNote, ReviewCollectionError } from '../../reports/src/review-collection-store.js';
+import { problemResponse } from './problem.js';
+import { readLimited } from './store-api.js';
+import { Refusal } from './validate.js';
+const NO_STORE = { 'cache-control': 'no-store' };
+const HELD_MS = 30_000;
+const LIST_MS = 5_000;
+/**
+ * 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`.
+ */
+export function mountReviewCollections(app, deps) {
+    const { store, stores, auth, index, now } = deps;
+    // One publisher at a time in this process, so the check that a revision is free and the write of it are one step.
+    let queue = Promise.resolve();
+    const exclusive = (work) => {
+        const run = queue.then(work, work);
+        queue = run.catch(() => undefined);
+        return run;
+    };
+    let lastAt = 0;
+    const stamp = () => (lastAt = Math.max(now(), lastAt + 1));
+    // The report's recorded results by layer and check, rebuilt only when the history changes.
+    let located = null;
+    const find = (layer, check, kind) => {
+        if (!located || located.rev !== index.history.rev) {
+            const map = new Map();
+            for (const { result } of index.history.evidenceResults()) {
+                const key = `${result.layer}\u0000${result.id}`;
+                const list = map.get(key);
+                if (list)
+                    list.push(result);
+                else
+                    map.set(key, [result]);
+            }
+            located = { rev: index.history.rev, map };
+        }
+        const all = located.map.get(`${layer}\u0000${check}`) ?? [];
+        return kind === undefined ? all : all.filter(result => result.kind === kind);
+    };
+    const held = new Map();
+    const holdsLayers = async (layers) => {
+        const out = new Set();
+        const ask = layers.filter(layer => {
+            const known = held.get(layer);
+            if (known && now() - known.at < HELD_MS) {
+                if (known.value)
+                    out.add(layer);
+                return false;
+            }
+            return true;
+        });
+        await eachLimited(ask, 8, async (layer) => {
+            let value = false;
+            for (const each of stores) {
+                if (await each.head(layerKey(layer)).catch(() => false)) {
+                    value = true;
+                    break;
+                }
+            }
+            if (held.size >= 4096)
+                held.delete(held.keys().next().value);
+            held.set(layer, { at: now(), value });
+            if (value)
+                out.add(layer);
+        });
+        return out;
+    };
+    let listing = null;
+    const list = async () => {
+        if (!listing || now() - listing.at > LIST_MS)
+            listing = { at: now(), value: await listReviewCollections(store) };
+        return listing.value;
+    };
+    const problem = (error) => {
+        if (error instanceof ReviewCollectionError || error instanceof Refusal)
+            return problemResponse(error.status, error.message);
+        return null;
+    };
+    const standing = async (id, revision) => {
+        const found = await readReviewCollection(store, id, revision);
+        if (!found)
+            return null;
+        const notes = (await readReviewNotes(store, id)).filter(note => note.revision === found.collection.revision);
+        const present = await holdsLayers([...new Set(found.collection.entries.map(entry => entry.source.layer))]);
+        const availability = availabilityOf(found.collection, layer => present.has(layer), find);
+        return { ...found, notes, availability, reviewed: foldReviewed(notes) };
+    };
+    const wanted = (c) => {
+        const id = c.req.query('id');
+        if (!id)
+            return problemResponse(400, 'Name the collection with ?id=, an id from GET /api/reports/review-collections.');
+        const raw = c.req.query('revision');
+        if (raw !== undefined && !/^[1-9]\d{0,5}$/.test(raw))
+            return problemResponse(400, '?revision= is a whole number of 1 or more.');
+        return { id, revision: raw === undefined ? undefined : Number(raw) };
+    };
+    app.get('/api/reports/review-collections', async (c) => {
+        const collections = (await list()).map(({ collection, revisions }) => ({
+            id: collection.id, revision: collection.revision, revisions, title: collection.title,
+            ...(collection.purpose === undefined ? {} : { purpose: collection.purpose }), ...(collection.audience === undefined ? {} : { audience: collection.audience }),
+            tags: collection.tags, entries: collection.entries.length, gaps: collection.gaps.length, createdBy: collection.createdBy, createdAtMs: collection.createdAtMs
+        }));
+        return c.json({ schemaVersion: 1, collections }, 200, NO_STORE);
+    });
+    app.post('/api/reports/review-collections', async (c) => {
+        const verdict = auth.check(c.req.raw, 'publish');
+        if (!verdict.ok)
+            return deps.unauthorized(verdict);
+        try {
+            const bytes = await readLimited(c.req.raw, Math.min(deps.maxBytes, 2 * 1024 * 1024));
+            let input;
+            try {
+                input = JSON.parse(new TextDecoder().decode(bytes));
+            }
+            catch {
+                return problemResponse(422, 'The body is not JSON.');
+            }
+            if (!index.ready)
+                return problemResponse(503, 'Atlas is still reading its backends; try again in a moment.', { 'retry-after': '1' });
+            const collection = await exclusive(() => recordReviewCollection(store, input, verdict.identity.name, stamp(), find));
+            listing = null;
+            return c.json(collection, 201, NO_STORE);
+        }
+        catch (error) {
+            const answered = problem(error);
+            if (answered)
+                return answered;
+            throw error;
+        }
+    });
+    app.get('/api/reports/review-collections/detail', async (c) => {
+        const asked = wanted(c);
+        if (asked instanceof Response)
+            return asked;
+        const found = await standing(asked.id, asked.revision);
+        if (!found)
+            return problemResponse(404, 'No such collection or revision.');
+        return c.json({ schemaVersion: 1, collection: found.collection, revisions: found.revisions, availability: found.availability, reviews: found.notes, reviewed: found.reviewed }, 200, NO_STORE);
+    });
+    app.post('/api/reports/review-collections/reviews', async (c) => {
+        const verdict = auth.check(c.req.raw, 'publish');
+        if (!verdict.ok)
+            return deps.unauthorized(verdict);
+        try {
+            const bytes = await readLimited(c.req.raw, Math.min(deps.maxBytes, 64 * 1024));
+            let input;
+            try {
+                input = JSON.parse(new TextDecoder().decode(bytes));
+            }
+            catch {
+                return problemResponse(422, 'The body is not JSON.');
+            }
+            const note = await recordReviewNote(store, input, verdict.identity.name, stamp());
+            return c.json(note, 201, NO_STORE);
+        }
+        catch (error) {
+            const answered = problem(error);
+            if (answered)
+                return answered;
+            throw error;
+        }
+    });
+    app.get('/api/reports/review-collections/export', async (c) => {
+        const asked = wanted(c);
+        if (asked instanceof Response)
+            return asked;
+        const found = await standing(asked.id, asked.revision);
+        if (!found)
+            return problemResponse(404, 'No such collection or revision.');
+        const manifest = manifestOf(found.collection, found.availability, found.reviewed, now());
+        return c.json(manifest, 200, { ...NO_STORE, 'content-disposition': `attachment; filename="review-${found.collection.id}-r${found.collection.revision}.json"` });
+    });
+}

package/docs/extending.md

@@ -30,7 +30,7 @@ carry any of these. Every one is optional.
 | `annotations[]` | Notes about the result: a warning, a deprecation, an accessibility finding, a coverage figure. |
 | `attempts[]` | Every try, when the check was retried. |
 | `tags[]` | Free labels to filter by: `smoke`, `payments`. |
-| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. |
+| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). |
 | `scope{}` | What the evidence does and does not show: surface, device kind, synthetic data, scripted dependencies, audio, pacing, what was asserted and its limits. Unknown when absent. See [Evidence scope](rich-evidence.md#evidence-scope). |
 | `links[]` | Where to read more: the CI run, the issue, the trace client. |
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |