@crvouga/atlas 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog: @crvouga/atlas
 
-## 1.10.0 (2026-10-29)
+## 1.12.0 (2026-10-29)
+
+### Features
+
+- seek recordings from scenario steps and share a moment ([6071cd9](https://github.com/crvouga/atlas/commit/6071cd90e8ece66deb384b037a25ee51381283ed))
+
+## 1.11.0 (2026-10-28)
+
+### Features
+
+- publish immutable review collections with videos, notes and gaps ([00ef474](https://github.com/crvouga/atlas/commit/00ef4741cecd70be1dc06ae3d7f690717e25cd6d))
+- search recorded speech and screen text with timestamped evidence matches ([a5874d8](https://github.com/crvouga/atlas/commit/a5874d87d4cfe0fdfa7996b5e06fc613940a1211))
+- show whether recorded evidence applies to the selected behavior and release ([550435d](https://github.com/crvouga/atlas/commit/550435dff15524866912076d69889749a6a9dae3))
+
+## 1.10.0 (2026-10-28)
 
 ### Features
 

package/dist/reports/src/review-collection-store.d.ts

@@ -0,0 +1,47 @@
+import type { ObjectStore } from './object-store.js';
+import { type ReviewCollection, type ReviewNote } from './review-collection.js';
+import type { ArtifactResult } from './test-catalog.js';
+/** The request was not acceptable. `status` is the HTTP status to answer: 404 (no such collection), 409 (not the newest revision) or 422. */
+export declare class ReviewCollectionError extends Error {
+    readonly status: 404 | 409 | 422;
+    constructor(status: 404 | 409 | 422, message: string);
+}
+/** Finds the recorded results of a layer's check (all kinds when `kind` is undefined). */
+export type ResultFinder = (layer: string, check: string, kind: string | undefined) => readonly ArtifactResult[];
+/**
+ * The revisions that exist for a collection id, oldest first. Empty when there is none. Transport errors throw.
+ */
+export declare function reviewRevisions(store: ObjectStore, id: string): Promise<number[]>;
+/**
+ * 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.
+ */
+export declare function readReviewCollection(store: ObjectStore, id: string, revision?: number): Promise<{
+    readonly collection: ReviewCollection;
+    readonly revisions: number[];
+} | null>;
+/**
+ * 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.
+ */
+export declare function recordReviewCollection(store: ObjectStore, input: unknown, by: string, atMs: number, find: ResultFinder): Promise<ReviewCollection>;
+/** The newest revision of every collection in `store`, newest first. One that cannot be read as a collection is skipped. Transport errors throw. */
+export declare function listReviewCollections(store: ObjectStore): Promise<{
+    readonly collection: ReviewCollection;
+    readonly revisions: number;
+}[]>;
+/**
+ * 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.
+ */
+export declare function recordReviewNote(store: ObjectStore, input: unknown, by: string, atMs: number): 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. */
+export declare function readReviewNotes(store: ObjectStore, id: string): Promise<ReviewNote[]>;

package/dist/reports/src/review-collection-store.js

@@ -0,0 +1,214 @@
+/**
+ * @module Review collections in a 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
+ */
+import { ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewNoteInputSchema, ReviewNoteSchema } from '../../schema/src/api.js';
+import { normalizeTag, normalizeTags } from './artifact-tags.js';
+import { readUtf8, writeUtf8 } from './object-io.js';
+import { REVIEW_COLLECTIONS_PREFIX, REVIEW_ID, REVIEW_NOTES_PREFIX, reviewCollectionKey, sameSource, snapshotOf } from './review-collection.js';
+/** The request was not acceptable. `status` is the HTTP status to answer: 404 (no such collection), 409 (not the newest revision) or 422. */
+export class ReviewCollectionError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const KEY = /^curation\/review-collections\/([a-z0-9][a-z0-9-]{7,39})\/r(\d{6})\.json$/;
+const first = (error) => `${error.issues[0]?.path.join('.') || '(body)'}: ${error.issues[0]?.message ?? 'invalid'}`;
+/** A fresh collection id: `rc-` and 16 random hex digits. */
+function newId() {
+    return `rc-${globalThis.crypto.randomUUID().replace(/-/g, '').slice(0, 16)}`;
+}
+/**
+ * The revisions that exist for a collection id, oldest first. Empty when there is none. Transport errors throw.
+ */
+export async function reviewRevisions(store, id) {
+    if (!REVIEW_ID.test(id))
+        return [];
+    const keys = await store.listKeys(`${REVIEW_COLLECTIONS_PREFIX}${id}/`);
+    return keys.flatMap((key) => {
+        const match = KEY.exec(key);
+        return match ? [Number(match[2])] : [];
+    }).sort((a, b) => a - b);
+}
+/**
+ * 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.
+ */
+export async function readReviewCollection(store, id, revision) {
+    const revisions = await reviewRevisions(store, id);
+    const wanted = revision ?? revisions.at(-1);
+    if (wanted === undefined || !revisions.includes(wanted))
+        return null;
+    const text = await readUtf8(store, reviewCollectionKey(id, wanted));
+    if (text === null)
+        return null;
+    try {
+        const parsed = ReviewCollectionSchema.safeParse(JSON.parse(text));
+        return parsed.success ? { collection: parsed.data, revisions } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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.
+ */
+export async function recordReviewCollection(store, input, by, atMs, find) {
+    const parsed = ReviewCollectionRequestSchema.safeParse(input);
+    if (!parsed.success)
+        throw new ReviewCollectionError(422, `Not a review collection: ${first(parsed.error)}`);
+    const request = parsed.data;
+    const given = request.entries ?? [];
+    const gapsGiven = request.gaps ?? [];
+    if (given.length === 0 && gapsGiven.length === 0)
+        throw new ReviewCollectionError(422, 'Name at least one entry or one gap.');
+    const tagInputs = request.tags ?? [];
+    if (tagInputs.some((tag) => normalizeTag(tag) === null))
+        throw new ReviewCollectionError(422, 'A tag is empty or longer than 64 characters.');
+    if (gapsGiven.some((gap) => (gap.after ?? 0) > given.length))
+        throw new ReviewCollectionError(422, 'A gap is placed after more entries than the collection has.');
+    let id;
+    let revision = 1;
+    if (request.basedOn) {
+        id = request.basedOn.id;
+        const existing = await reviewRevisions(store, id);
+        if (existing.length === 0)
+            throw new ReviewCollectionError(404, 'No collection has that id.');
+        const newest = existing.at(-1);
+        if (request.basedOn.revision !== newest)
+            throw new ReviewCollectionError(409, `Revision ${request.basedOn.revision} is not the newest: revision ${newest} exists. Base the new revision on that one.`);
+        revision = newest + 1;
+    }
+    else {
+        id = newId();
+    }
+    const entries = [];
+    for (const [index, item] of given.entries()) {
+        const label = `Entry ${index + 1}`;
+        const found = find(item.layer, item.check, item.kind);
+        if (found.length === 0)
+            throw new ReviewCollectionError(422, `${label}: the report holds no result "${item.check}" in layer ${item.layer.slice(0, 12)}. Take the layer and check from GET /api/reports/artifacts.`);
+        if (found.length > 1)
+            throw new ReviewCollectionError(422, `${label}: the check "${item.check}" exists in several parts of that layer (${found.map((result) => result.kind).join(', ')}). Name the kind.`);
+        const result = found[0];
+        if (item.recording !== undefined && !result.videos?.some((video) => video.available && video.recording === item.recording)) {
+            throw new ReviewCollectionError(422, `${label}: that result has no such recording.`);
+        }
+        const source = { layer: item.layer, check: item.check, kind: result.kind, ...(item.recording === undefined ? {} : { recording: item.recording }) };
+        if (entries.some((entry) => sameSource(entry.source, source)))
+            throw new ReviewCollectionError(422, `${label}: the same source is already in the collection.`);
+        entries.push({ id: `e${index + 1}`, source, ...(item.caption ? { caption: item.caption } : {}), snapshot: snapshotOf(result) });
+    }
+    const collection = {
+        schemaVersion: 1, id, revision, title: request.title.trim(),
+        ...(request.purpose?.trim() ? { purpose: request.purpose.trim() } : {}),
+        ...(request.audience?.trim() ? { audience: request.audience.trim() } : {}),
+        tags: normalizeTags(tagInputs), entries,
+        gaps: gapsGiven.map((gap, index) => ({ id: `g${index + 1}`, note: gap.note.trim(), after: gap.after ?? 0 })),
+        ...(request.frozenFrom ? { frozenFrom: request.frozenFrom } : {}),
+        ...(request.basedOn ? { basedOn: { id: request.basedOn.id, revision: request.basedOn.revision } } : {}),
+        createdBy: by, createdAtMs: atMs
+    };
+    if (!collection.title)
+        throw new ReviewCollectionError(422, 'The title is empty.');
+    const key = reviewCollectionKey(id, revision);
+    // A revision is never overwritten. (A store has no conditional write: two simultaneous requests for the same
+    // revision can still race, which is why a new revision must name the newest one it is based on.)
+    if (await store.head(key))
+        throw new ReviewCollectionError(409, `Revision ${revision} already exists.`);
+    await writeUtf8(store, key, JSON.stringify(collection), 'application/json');
+    return collection;
+}
+/** The newest revision of every collection in `store`, newest first. One that cannot be read as a collection is skipped. Transport errors throw. */
+export async function listReviewCollections(store) {
+    const keys = await store.listKeys(REVIEW_COLLECTIONS_PREFIX);
+    const byId = new Map();
+    for (const key of keys) {
+        const match = KEY.exec(key);
+        if (match)
+            byId.set(match[1], [...(byId.get(match[1]) ?? []), Number(match[2])]);
+    }
+    const read = await Promise.all([...byId].map(async ([id, revisions]) => {
+        const newest = Math.max(...revisions);
+        const text = await readUtf8(store, reviewCollectionKey(id, newest));
+        if (text === null)
+            return [];
+        try {
+            const parsed = ReviewCollectionSchema.safeParse(JSON.parse(text));
+            return parsed.success ? [{ collection: parsed.data, revisions: revisions.length }] : [];
+        }
+        catch {
+            return [];
+        }
+    }));
+    return read.flat().sort((a, b) => b.collection.createdAtMs - a.collection.createdAtMs || (a.collection.id < b.collection.id ? -1 : 1));
+}
+/**
+ * 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.
+ */
+export async function recordReviewNote(store, input, by, atMs) {
+    const parsed = ReviewNoteInputSchema.safeParse(input);
+    if (!parsed.success)
+        throw new ReviewCollectionError(422, `Not a review note: ${first(parsed.error)}`);
+    const { collection: id, revision, entry, kind, text, timecodeMs } = parsed.data;
+    if (!REVIEW_ID.test(id))
+        throw new ReviewCollectionError(404, 'No collection has that id.');
+    const found = await readReviewCollection(store, id, revision);
+    if (!found)
+        throw new ReviewCollectionError(404, 'No such collection revision.');
+    if (entry !== undefined && !found.collection.entries.some((item) => item.id === entry))
+        throw new ReviewCollectionError(422, `Entry "${entry}" is not in revision ${revision}.`);
+    if ((kind === 'reviewed' || kind === 'unreviewed') && entry === undefined)
+        throw new ReviewCollectionError(422, `A "${kind}" mark names the entry.`);
+    if ((kind === 'note' || kind === 'gap') && !text?.trim())
+        throw new ReviewCollectionError(422, `A ${kind} needs text.`);
+    if (timecodeMs !== undefined && entry === undefined)
+        throw new ReviewCollectionError(422, 'A timecode names the entry whose recording it is a moment of.');
+    const noteId = `${String(atMs).padStart(16, '0')}-${globalThis.crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
+    const note = {
+        id: noteId, collection: id, revision, ...(entry === undefined ? {} : { entry }), kind,
+        ...(text?.trim() ? { text: text.trim() } : {}), ...(timecodeMs === undefined ? {} : { timecodeMs }), by, atMs
+    };
+    await writeUtf8(store, `${REVIEW_NOTES_PREFIX}${id}/${noteId}.json`, JSON.stringify({ schemaVersion: 1, ...note }), 'application/json');
+    return note;
+}
+/** Every recorded note of a collection (all revisions), oldest first. One that cannot be read as a note is skipped. Transport errors throw. */
+export async function readReviewNotes(store, id) {
+    if (!REVIEW_ID.test(id))
+        return [];
+    const keys = (await store.listKeys(`${REVIEW_NOTES_PREFIX}${id}/`)).filter((key) => key.endsWith('.json'));
+    const read = await Promise.all(keys.map(async (key) => {
+        const text = await readUtf8(store, key);
+        if (text === null)
+            return [];
+        try {
+            const parsed = ReviewNoteSchema.safeParse(JSON.parse(text));
+            return parsed.success ? [parsed.data] : [];
+        }
+        catch {
+            return [];
+        }
+    }));
+    return read.flat().sort((a, b) => a.atMs - b.atMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

package/dist/reports/src/review-collection.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @module Review collections
+ *
+ * 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
+ */
+import type { z } from 'zod/v4';
+import type { ReviewAvailabilitySchema, ReviewCollectionDetailSchema, ReviewCollectionListSchema, ReviewCollectionSchema, ReviewEntrySchema, ReviewManifestSchema, ReviewNoteSchema, ReviewSnapshotSchema, ReviewSourceSchema } from '../../schema/src/api.js';
+import type { ArtifactResult } from './test-catalog.js';
+/** The exact result (and optionally one recording of it) an entry points at. */
+export type ReviewSource = z.infer<typeof ReviewSourceSchema>;
+/** What was recorded about a source when it was frozen. */
+export type ReviewSnapshot = z.infer<typeof ReviewSnapshotSchema>;
+/** One entry of a collection revision. */
+export type ReviewEntry = z.infer<typeof ReviewEntrySchema>;
+/** One immutable revision of a collection. */
+export type ReviewCollection = z.infer<typeof ReviewCollectionSchema>;
+/** A recorded note, time-coded gap note or reviewed mark. */
+export type ReviewNote = z.infer<typeof ReviewNoteSchema>;
+/** How an entry's source stands now. */
+export type ReviewAvailability = z.infer<typeof ReviewAvailabilitySchema>;
+/** `GET /api/reports/review-collections/detail`: one revision, how its sources stand now, and its notes. */
+export type ReviewCollectionDetail = z.infer<typeof ReviewCollectionDetailSchema>;
+/** `GET /api/reports/review-collections`: the newest revision of every collection. */
+export type ReviewCollectionList = z.infer<typeof ReviewCollectionListSchema>;
+/** The portable index of one revision. */
+export type ReviewManifest = z.infer<typeof ReviewManifestSchema>;
+/** Where the revisions of collections are kept in a store: `<prefix><id>/r<revision, six digits>.json`. */
+export declare const REVIEW_COLLECTIONS_PREFIX = "curation/review-collections/";
+/** Where reviewers' notes are kept: `<prefix><collection id>/<time>-<random>.json`, one object each. */
+export declare const REVIEW_NOTES_PREFIX = "curation/review-notes/";
+/** 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). */
+export declare const REVIEW_ID: RegExp;
+/** The store key of one revision of a collection. */
+export declare function reviewCollectionKey(id: string, revision: number): string;
+/** Whether two sources name the same result and recording. `kind` counts only when both have one. */
+export declare function sameSource(a: ReviewSource, b: ReviewSource): boolean;
+/**
+ * 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.
+ */
+export declare function snapshotOf(result: ArtifactResult): ReviewSnapshot;
+/**
+ * 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.
+ */
+export declare function availabilityOf(collection: Pick<ReviewCollection, 'entries'>, layerHeld: (layer: string) => boolean, results: (layer: string, check: string, kind: string | undefined) => readonly ArtifactResult[]): ReviewAvailability[];
+/**
+ * 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.
+ */
+export declare function foldReviewed(notes: readonly ReviewNote[]): Record<string, {
+    readonly by: string;
+    readonly atMs: number;
+}>;
+/**
+ * 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'
+ * ```
+ */
+export declare function safeFileName(name: string): string;
+/** 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. */
+export declare function digestOf(recording: string | undefined): string | null;
+/**
+ * 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.
+ */
+export declare function manifestOf(collection: ReviewCollection, availability: readonly ReviewAvailability[], reviewed: Readonly<Record<string, unknown>>, generatedAtMs: number): ReviewManifest;

package/dist/reports/src/review-collection.js

@@ -0,0 +1,144 @@
+/** Where the revisions of collections are kept in a store: `<prefix><id>/r<revision, six digits>.json`. */
+export const REVIEW_COLLECTIONS_PREFIX = 'curation/review-collections/';
+/** Where reviewers' notes are kept: `<prefix><collection id>/<time>-<random>.json`, one object each. */
+export const REVIEW_NOTES_PREFIX = 'curation/review-notes/';
+/** 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). */
+export const REVIEW_ID = /^[a-z0-9][a-z0-9-]{7,39}$/;
+/** The store key of one revision of a collection. */
+export function reviewCollectionKey(id, revision) {
+    return `${REVIEW_COLLECTIONS_PREFIX}${id}/r${String(revision).padStart(6, '0')}.json`;
+}
+/** Whether two sources name the same result and recording. `kind` counts only when both have one. */
+export function sameSource(a, b) {
+    return a.layer === b.layer && a.check === b.check && (a.kind ?? '') === (b.kind ?? '') && (a.recording ?? '') === (b.recording ?? '');
+}
+/**
+ * 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.
+ */
+export function snapshotOf(result) {
+    return {
+        title: result.title,
+        specPath: result.specPath,
+        status: result.status,
+        recordedAtMs: result.at,
+        environment: result.environment,
+        producer: result.producer,
+        branch: result.branch,
+        sha: result.sha,
+        run: result.run,
+        runUrl: result.runUrl,
+        backend: result.backend,
+        testKey: result.key,
+        ...(result.attemptStatuses ? { attemptStatuses: [...result.attemptStatuses] } : {}),
+        ...(result.videos ? { videos: structuredClone(result.videos) } : {})
+    };
+}
+/**
+ * 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.
+ */
+export function availabilityOf(collection, layerHeld, results) {
+    return collection.entries.map((entry) => {
+        const { source } = entry;
+        if (!layerHeld(source.layer)) {
+            return { entry: entry.id, state: 'unavailable', reason: `The layer ${source.layer.slice(0, 12)} that recorded this is no longer in any backend (it may have been deleted by garbage collection). The entry is kept as it was frozen.` };
+        }
+        const found = results(source.layer, source.check, source.kind);
+        if (found.length === 0) {
+            return { entry: entry.id, state: 'unverified', reason: 'The layer is held, but the report no longer lists this result (it is outside the history the report keeps), so it cannot be checked now.' };
+        }
+        if (source.recording !== undefined && !found.some((result) => result.videos?.some((video) => video.available && video.recording === source.recording))) {
+            return { entry: entry.id, state: 'unverified', reason: 'The result is listed, but the recording this entry points at is not among its recordings any more.' };
+        }
+        return { entry: entry.id, state: 'available' };
+    });
+}
+/**
+ * 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.
+ */
+export function foldReviewed(notes) {
+    const latest = new Map();
+    const ordered = [...notes].sort((a, b) => a.atMs - b.atMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    for (const note of ordered)
+        if (note.entry !== undefined && (note.kind === 'reviewed' || note.kind === 'unreviewed'))
+            latest.set(note.entry, note);
+    const out = {};
+    for (const [entry, note] of latest)
+        if (note.kind === 'reviewed')
+            out[entry] = { by: note.by, atMs: note.atMs };
+    return out;
+}
+/**
+ * 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'
+ * ```
+ */
+export function safeFileName(name) {
+    const last = name.normalize('NFC').split(/[\\/]/).filter(Boolean).at(-1) ?? '';
+    const cleaned = last.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '').slice(0, 100);
+    return cleaned.length > 0 ? cleaned : 'file';
+}
+/** 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. */
+export function digestOf(recording) {
+    const match = recording === undefined ? null : /^sha256:([0-9a-f]{64})$/.exec(recording);
+    return match ? match[1] : null;
+}
+/**
+ * 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.
+ */
+export function manifestOf(collection, availability, reviewed, generatedAtMs) {
+    const states = new Map(availability.map((item) => [item.entry, item]));
+    const missing = [];
+    const entries = collection.entries.map((entry, index) => {
+        const position = index + 1;
+        const state = states.get(entry.id) ?? { entry: entry.id, state: 'unverified', reason: 'Not checked.' };
+        const wanted = (entry.snapshot.videos ?? []).filter((video) => entry.source.recording === undefined || video.recording === entry.source.recording);
+        const seen = new Set();
+        const files = wanted.flatMap((video) => {
+            const identity = video.recording ?? `unavailable:${video.name}`;
+            if (seen.has(identity))
+                return [];
+            seen.add(identity);
+            const safeName = safeFileName(video.name);
+            const gone = state.state === 'unavailable' || !video.available;
+            return [{
+                    name: video.name, safeName, path: `files/${String(position).padStart(3, '0')}-${safeName}`,
+                    ...(video.recording === undefined ? {} : { recording: video.recording }),
+                    sha256: digestOf(video.recording), missing: gone
+                }];
+        });
+        if (state.state === 'unavailable')
+            missing.push({ entry: entry.id, reason: state.reason ?? 'The source is gone.' });
+        else
+            for (const file of files)
+                if (file.missing)
+                    missing.push({ entry: entry.id, reason: `${file.name}: the recording names no bytes.` });
+        return {
+            id: entry.id, position, ...(entry.caption === undefined ? {} : { caption: entry.caption }), source: entry.source, snapshot: entry.snapshot,
+            state: state.state, ...(state.reason === undefined ? {} : { reason: state.reason }), reviewed: entry.id in reviewed, files
+        };
+    });
+    return {
+        schemaVersion: 1, generatedAtMs,
+        collection: {
+            id: collection.id, revision: collection.revision, title: collection.title,
+            ...(collection.purpose === undefined ? {} : { purpose: collection.purpose }), ...(collection.audience === undefined ? {} : { audience: collection.audience }),
+            tags: collection.tags, createdBy: collection.createdBy, createdAtMs: collection.createdAtMs
+        },
+        entries, gaps: collection.gaps, missing,
+        notes: 'A review collection is curation. Its entries come from the results named in each source, possibly from several runs; they are not one execution. Statuses are those the layers recorded. A reviewed mark is not an outcome and not an approval. This manifest lists files and holds no bytes; a file with a null digest has no recorded hash and is unverified.'
+    };
+}

package/dist/reports/src/test-catalog.d.ts

@@ -390,6 +390,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[];
 };
 /** `GET /api/reports/artifacts`: the recorded results that carry evidence and match a query, newest first. */
 export type ArtifactList = {

package/dist/reports/src/test-catalog.js

@@ -288,7 +288,7 @@ export class TestHistory {
                 const result = {
                     key: i.slot, id: i.id, title: i.title, specPath: i.specPath, domain: null, at: o.at, status: held.s, environment: o.environment, producer: o.producer, kind: held.k,
                     parameters: o.parameters, branch: o.branch, sha: o.sha, run: o.run, runUrl: o.runUrl, layer: o.layer, backend: o.backend, attachments: e.attachments,
-                    artifactTags, tags: [...e.tags], types, labels: e.labels, ...(e.videos ? { videos: e.videos } : {}),
+                    artifactTags, tags: [...e.tags], types, labels: e.labels, ...(e.videos ? { videos: e.videos } : {}), ...(e.attemptStatuses ? { attemptStatuses: e.attemptStatuses } : {}),
                 };
                 const media = [
                     ...types.filter(type => type !== 'video').map(type => ({ type, tags: artifactTags })),