@crvouga/atlas 1.20.0 → 1.22.0

package/dist/critics/src/uiclip.js

@@ -0,0 +1,167 @@
+/**
+ * @module The UIClip critic (`@crvouga/atlas/critics/uiclip`)
+ *
+ * A model-based critic: UIClip scores how well a screenshot looks, as one number. This module is the adapter around it, and
+ * it needs nothing installed to import: the model runs in an ONNX Runtime session that is loaded only when a run starts
+ * (`loadOnnxRuntime`, which needs the optional `onnxruntime-node` and `sharp` and names the one that is missing), and a test
+ * or another runtime passes its own `UiclipRuntime`. The checkpoint is provisioned only by an explicit `setupUiclip`, which
+ * verifies it against a pinned SHA-256 and refuses a file that does not match; inference never downloads anything and
+ * refuses a checkpoint that does not match. The critic sends images nowhere: it runs on this machine.
+ *
+ * A single global score cannot say what to fix, and on real recordings it ranks ordinary loading overlays as poor, so
+ * a UIClip score is report-only evidence read against the scores of the same state kind (see `relativeVerdict`), never an
+ * absolute gate.
+ *
+ * @see docs/critics.md#the-built-in-uiclip-critic
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { defineCritic } from './contract.js';
+/** The version of this adapter's own logic, recorded in every critique. The checkpoint is part of the identity too (through `model.id`). */
+export const UICLIP_VERSION = '1.0.0';
+/** Thrown when an optional dependency a runtime needs is not installed. The message names it and says how to install it. */
+export class MissingDependencyError extends Error {
+    dependency;
+    /** @param dependency the package that is missing. */
+    constructor(dependency, purpose) {
+        super(`${purpose} needs the optional dependency "${dependency}", which is not installed. Install it in this project (for example: bun add ${dependency}) and run again.`);
+        this.dependency = dependency;
+        this.name = 'MissingDependencyError';
+    }
+}
+/**
+ * Checks a file against a pinned SHA-256. Returns the hash it has. Throws when the file is missing or its hash differs, naming
+ * both hashes, so a corrupted or swapped model is an error and never silently used.
+ */
+export async function verifyCheckpoint(checkpoint) {
+    if (!/^[0-9a-f]{64}$/.test(checkpoint.sha256))
+        throw new Error('The checkpoint is not pinned: give its SHA-256 as 64 lowercase hex digits');
+    try {
+        await stat(checkpoint.path);
+    }
+    catch {
+        throw new Error(`The UIClip checkpoint is missing: ${checkpoint.path}. Run \`atlas critic setup uiclip\`.`);
+    }
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(checkpoint.path))
+        hash.update(chunk);
+    const actual = hash.digest('hex');
+    if (actual !== checkpoint.sha256)
+        throw new Error(`The UIClip checkpoint ${checkpoint.path} does not match its pinned checksum (expected ${checkpoint.sha256}, found ${actual}). Remove it and run \`atlas critic setup uiclip\`, or fix the pin.`);
+    return actual;
+}
+/**
+ * Provisions the checkpoint: uses the file when it is there, else downloads it from `checkpoint.url` (to a temporary file, hashing as
+ * it arrives), and in both cases verifies the pinned SHA-256. A download whose hash differs is deleted and is an error; an
+ * existing file whose hash differs is an error and is left alone. This is the only place anything is downloaded.
+ *
+ * @param checkpoint the pinned checkpoint.
+ * @param options.fetch for tests; default `fetch`.
+ * @param options.signal cancels the download.
+ */
+export async function setupUiclip(checkpoint, options = {}) {
+    const exists = await stat(checkpoint.path).then(() => true, () => false);
+    if (exists)
+        return { path: checkpoint.path, sha256: await verifyCheckpoint(checkpoint), downloaded: false };
+    if (!checkpoint.url)
+        throw new Error(`The UIClip checkpoint is not at ${checkpoint.path} and no download address is configured: put the file there, or set checkpoint.url.`);
+    if (!/^https:\/\//.test(checkpoint.url))
+        throw new Error('The checkpoint must be downloaded over https');
+    const response = await (options.fetch ?? fetch)(checkpoint.url, options.signal ? { signal: options.signal } : {});
+    if (!response.ok || !response.body)
+        throw new Error(`The checkpoint download answered ${response.status}`);
+    await mkdir(path.dirname(checkpoint.path), { recursive: true });
+    const partial = `${checkpoint.path}.part`;
+    const hash = createHash('sha256');
+    const out = createWriteStream(partial);
+    try {
+        const reader = response.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            hash.update(value);
+            if (!out.write(value))
+                await new Promise(resolve => out.once('drain', () => resolve()));
+        }
+        await new Promise((resolve, reject) => { out.once('error', reject); out.end(() => resolve()); });
+    }
+    catch (error) {
+        // The file is opened asynchronously: close it before removing it, or it can reappear.
+        if (!out.closed)
+            await new Promise(resolve => { out.once('close', () => resolve()); out.destroy(); });
+        await rm(partial, { force: true });
+        throw error;
+    }
+    const actual = hash.digest('hex');
+    if (actual !== checkpoint.sha256) {
+        await rm(partial, { force: true });
+        throw new Error(`The downloaded checkpoint does not match its pinned checksum (expected ${checkpoint.sha256}, received ${actual}); it was discarded.`);
+    }
+    await rename(partial, checkpoint.path);
+    return { path: checkpoint.path, sha256: actual, downloaded: true };
+}
+/** CLIP's published normalisation of RGB channels. */
+const MEAN = [0.48145466, 0.4578275, 0.40821073];
+const STD = [0.26862954, 0.26130258, 0.27577711];
+const SIZE = 224;
+/**
+ * Opens an ONNX Runtime session on a verified checkpoint and scores images with it: the image is resized to 224 by 224 and
+ * normalised as CLIP does, and the first output's first value is the score. The checkpoint's hash is verified first and a
+ * mismatch is an error. Needs the optional `onnxruntime-node` and `sharp`; the error names the missing one. Nothing is
+ * downloaded. The graph and score head are those of the checkpoint you pinned; this has not been validated against any particular
+ * checkpoint, so measure it on your own examples (`calibrate`) before reading its scores.
+ */
+export async function loadOnnxRuntime(checkpoint, modules = {}) {
+    const load = modules.importModule ?? ((name) => import(name));
+    const onnx = await load('onnxruntime-node').catch(() => { throw new MissingDependencyError('onnxruntime-node', 'The UIClip critic'); });
+    const sharpModule = await load('sharp').catch(() => { throw new MissingDependencyError('sharp', 'The UIClip critic (to decode images)'); });
+    const sharp = (sharpModule.default ?? sharpModule);
+    await verifyCheckpoint(checkpoint);
+    const session = await onnx.InferenceSession.create(checkpoint.path);
+    return {
+        async score(image) {
+            const rgb = await sharp(image).resize(SIZE, SIZE, { fit: 'cover' }).removeAlpha().raw().toBuffer();
+            const planes = new Float32Array(3 * SIZE * SIZE);
+            for (let pixel = 0; pixel < SIZE * SIZE; pixel++)
+                for (let channel = 0; channel < 3; channel++)
+                    planes[channel * SIZE * SIZE + pixel] = ((rgb[pixel * 3 + channel] / 255) - MEAN[channel]) / STD[channel];
+            const outputs = await session.run({ [session.inputNames[0]]: new onnx.Tensor('float32', planes, [1, 3, SIZE, SIZE]) });
+            const value = outputs[session.outputNames[0]]?.data[0];
+            if (value === undefined || !Number.isFinite(value))
+                throw new Error('The UIClip model gave no finite score');
+            return value;
+        },
+        async close() { await session.release?.(); }
+    };
+}
+/**
+ * The UIClip critic: judges each image with a runtime and reports the score and nothing else (a score is a valid critique; it
+ * has no findings). Deterministic for a deterministic runtime. Its identity includes the checkpoint hash, so a different
+ * checkpoint is judged again. The runtime is created once, on the first image.
+ *
+ * @param options.checkpoint the pinned checkpoint. Its hash is the model id.
+ * @param options.runtime a runtime, or a function that makes one. Default: {@link loadOnnxRuntime} on the checkpoint.
+ * @example
+ * const critic = createUiclipCritic({ checkpoint: { path: '.atlas/uiclip.onnx', sha256 }, runtime: { score: async () => 0.5 } });
+ */
+export function createUiclipCritic(options) {
+    let runtime;
+    const open = () => {
+        runtime ??= Promise.resolve(typeof options.runtime === 'function' ? options.runtime() : options.runtime ?? loadOnnxRuntime(options.checkpoint, options.modules));
+        return runtime;
+    };
+    const critic = defineCritic({
+        name: options.name ?? 'uiclip', version: UICLIP_VERSION, kind: 'model',
+        describe: () => ({ sendsImagesTo: null, model: { id: `uiclip@${options.checkpoint.sha256.slice(0, 16)}`, provider: 'local' }, parameters: { checkpoint: options.checkpoint.sha256 }, needsSetup: true }),
+        setup: async () => { await verifyCheckpoint(options.checkpoint); },
+        async evaluate({ image, signal }) {
+            const score = await (await open()).score(image, signal);
+            return { verdict: { score, scale: 'UIClip similarity, higher is better; read it against the same state kind' } };
+        }
+    });
+    /** Opens the runtime now, so a missing dependency or a bad checkpoint is found before any image is judged. */
+    return { ...critic, async ready() { await open(); } };
+}

package/dist/reports/src/compose.d.ts

@@ -1,4 +1,5 @@
-import type { BackendInfo, LayerHeader, StatusCounts } from './evidence-types.js';
+import type { BackendInfo, LayerEvidence, LayerHeader, StatusCounts } from './evidence-types.js';
+import type { SpecEntry } from './explorer-types.js';
 import { type CombinedEvidence, type EvidenceResult } from './layer-merge.js';
 import type { ReportOutline } from './layer-types.js';
 import type { ObjectStore } from './object-store.js';
@@ -58,6 +59,27 @@ export declare function countResults(all: readonly EvidenceResult[]): StatusCoun
 };
 /** Counts a combined report's winning results in total and per environment, and lists the specs that have no result at all. */
 export declare function summarize(combined: CombinedEvidence): ReportSummary;
+/** Every layer of some backends, read but not yet composed. */
+export type BackendLayers = {
+    /** Each layer that could be read, with the specs it recorded. A layer several backends hold appears once per backend. */
+    readonly loaded: readonly {
+        readonly evidence: LayerEvidence;
+        readonly specs: readonly SpecEntry[];
+    }[];
+    /** Every backend given, sorted by id, with whether it could be listed. */
+    readonly backends: readonly BackendInfo[];
+    /** What could not be read, sorted and without repeats. */
+    readonly notices: readonly string[];
+};
+/**
+ * Reads every layer of every backend, superseded ones included, without composing them. This is what {@link combineBackends}
+ * starts from; a caller that needs layers a newer layer has replaced (to compare two commits, for example) reads them here.
+ * A backend that cannot be listed, or a layer that cannot be understood, is a notice, never an omission that looks like a pass.
+ * Throws for an invalid or repeated backend `id`, before anything is read.
+ */
+export declare function readBackendLayers(backends: readonly BackendInput[], options?: {
+    readonly concurrency?: number;
+}): Promise<BackendLayers>;
 /**
  * Reads every layer of every backend and lays them over the specs. Layers are the only input:
  * a report is a function of the set of layers, so the order of backends and layers, and how they

package/dist/reports/src/compose.js

@@ -45,25 +45,12 @@ export function summarize(combined) {
     };
 }
 /**
- * Reads every layer of every backend and lays them over the specs. Layers are the only input:
- * a report is a function of the set of layers, so the order of backends and layers, and how they
- * were split across machines, branches and runs, does not change it.
- *
- * A backend that cannot be read, or a layer that cannot be understood, is named in `notices` and
- * leaves everything else usable; a gate must treat any notice as unknown, never as a pass. A layer held by
- * several backends is one layer. Only an invalid backend `id` (not lowercase letters, digits and hyphens, or
- * repeated) throws, before anything is read. Backends are only read from.
- *
- * When `options.outline` is omitted, the specs are the ones the included layers recorded (the newest
- * recording of each spec path wins), with no commit sha.
- *
- * @example
- * const outline = await loadDirectoryOutline('./specs'); // optional: without it the layers' own specs are used
- * const report = await combineBackends([{ id: 'ci', store: directoryStore('./atlas-reports') }], { outline });
- * report.summary.checks.failed; // number of slots whose winner failed
- * report.notices; // non-empty means something could not be read
+ * Reads every layer of every backend, superseded ones included, without composing them. This is what {@link combineBackends}
+ * starts from; a caller that needs layers a newer layer has replaced (to compare two commits, for example) reads them here.
+ * A backend that cannot be listed, or a layer that cannot be understood, is a notice, never an omission that looks like a pass.
+ * Throws for an invalid or repeated backend `id`, before anything is read.
  */
-export async function combineBackends(backends, options = {}) {
+export async function readBackendLayers(backends, options = {}) {
     const seen = new Set();
     for (const backend of backends) {
         if (!BACKEND_ID.test(backend.id) || seen.has(backend.id))
@@ -96,6 +83,29 @@ export async function combineBackends(backends, options = {}) {
             notices.push(`${backend.label ?? backend.id}: a layer could not be read, so its outcome is unknown (${error instanceof Error ? error.message : String(error)})`);
         }
     });
+    return { loaded, backends: info.sort((a, b) => (a.id < b.id ? -1 : 1)), notices: [...new Set(notices)].sort() };
+}
+/**
+ * Reads every layer of every backend and lays them over the specs. Layers are the only input:
+ * a report is a function of the set of layers, so the order of backends and layers, and how they
+ * were split across machines, branches and runs, does not change it.
+ *
+ * A backend that cannot be read, or a layer that cannot be understood, is named in `notices` and
+ * leaves everything else usable; a gate must treat any notice as unknown, never as a pass. A layer held by
+ * several backends is one layer. Only an invalid backend `id` (not lowercase letters, digits and hyphens, or
+ * repeated) throws, before anything is read. Backends are only read from.
+ *
+ * When `options.outline` is omitted, the specs are the ones the included layers recorded (the newest
+ * recording of each spec path wins), with no commit sha.
+ *
+ * @example
+ * const outline = await loadDirectoryOutline('./specs'); // optional: without it the layers' own specs are used
+ * const report = await combineBackends([{ id: 'ci', store: directoryStore('./atlas-reports') }], { outline });
+ * report.summary.checks.failed; // number of slots whose winner failed
+ * report.notices; // non-empty means something could not be read
+ */
+export async function combineBackends(backends, options = {}) {
+    const { loaded, backends: info, notices } = await readBackendLayers(backends, options.concurrency === undefined ? {} : { concurrency: options.concurrency });
     const include = options.include;
     const kept = include ? loaded.filter(item => include(item.evidence.layer)) : loaded;
     const layers = kept.map(item => item.evidence);
@@ -107,5 +117,5 @@ export async function combineBackends(backends, options = {}) {
     const outline = options.outline ?? { specs: recorded.entries(), sha: null, changedFiles: [] };
     const combined = combineEvidence(outline, layers);
     const headers = distinctHeaders(layers.map(evidence => evidence.layer)).sort((a, b) => b.recordedAtMs - a.recordedAtMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-    return { combined, layers: headers, backends: info.sort((a, b) => (a.id < b.id ? -1 : 1)), notices: [...new Set(notices)].sort(), summary: summarize(combined) };
+    return { combined, layers: headers, backends: info, notices, summary: summarize(combined) };
 }

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

@@ -0,0 +1,111 @@
+/**
+ * @module Reading critiques together
+ *
+ * What a person or a command wants to know after critics have spoken: which states need polish first (`rankCritiques`), do the
+ * critics agree (`critiqueAgreement`), and what did people decide about the opinions (`markStanding`). These are readings of
+ * evidence that is already in the report. They count nothing toward a test total and decide no status, slot or gate: an
+ * opinion is an opinion, and so is a person's mark of it. Everything here is pure, so the viewer and `atlas critic review`
+ * read the same way.
+ *
+ * @see docs/critics.md
+ */
+import type { Critique } from '../../schema/src/critique.js';
+import type { CatalogEntry, EntryCritique, EntryMark } from './ui-catalog-entries.js';
+/** One entry and the critic's newest critique of it. */
+export type RankedEntry<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'> = CatalogEntry> = {
+    readonly entry: E;
+    readonly found: EntryCritique;
+};
+/** The ranking of the entries one critic judged. */
+export type CritiqueRanking<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'> = CatalogEntry> = {
+    /** Entries judged at their current picture with a score, lowest first. */
+    readonly ranked: readonly RankedEntry<E>[];
+    /** How the list was ranked: by standing within the state kind (when every score has one), or by raw score. */
+    readonly rankedBy: 'standing-within-kind' | 'score';
+    /** Entries whose newest critique judged an earlier picture, or that the critic could not judge: listed, never ranked. */
+    readonly unranked: readonly RankedEntry<E>[];
+    /** Entries in scope the critic has not judged at all. */
+    readonly unjudged: number;
+};
+/**
+ * Ranks the entries a critic judged, lowest first, so the likeliest problems are reviewed first. A score is read as
+ * higher-is-better (the convention of the critique format). When every ranked score also carries its standing among the scores
+ * of the same state kind (`verdict.relative.percentile`) that standing ranks them instead, because a loading overlay is not
+ * compared with a full screen. An entry whose picture changed since it was judged, or that the critic could not judge, is not
+ * ranked but is returned; an entry the critic never saw is only counted.
+ *
+ * @param entries the entries in view.
+ * @param critic the critic whose critiques rank them.
+ * @param kind when given, only entries of this state kind.
+ */
+export declare function rankCritiques<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'>>(entries: readonly E[], critic: string | null, kind?: string): CritiqueRanking<E>;
+/** What a critic's opinion amounts to for a reader who wants to know whether it flags the UI: it does, it does not, or it gives no view. */
+export type Stance = 'flags' | 'clear' | 'no-view';
+/** A score at or below this standing within its state kind (the lowest quarter) counts as flagging, when the critic gave no label. */
+export declare const FLAGGING_PERCENTILE = 25;
+/**
+ * Whether a critique flags the UI. A failed critique, or one with nothing to go on, gives no view and is never read as fine.
+ * Otherwise the critic's own label decides (`needs-polish` flags, `ok` clears); with no label, findings flag; with neither, a score
+ * in the lowest quarter of its state kind (`relative.percentile` at most {@link FLAGGING_PERCENTILE}) flags and a higher one clears. A bare
+ * score with no standing gives no view, because a raw score is not absolute.
+ */
+export declare function critiqueStance(critique: Critique): Stance;
+/** How the critics who judged an entry at its current picture stand together. */
+export type AgreementOutcome = 'agree-flag' | 'agree-clear' | 'disagree' | 'unclear';
+/** One critic's view of an entry. */
+export type CriticView = {
+    readonly critic: string;
+    readonly version: string;
+    readonly stance: Stance;
+    readonly score?: number;
+    readonly percentile?: number;
+    readonly label?: string;
+};
+/** An entry judged at its current picture by two or more critics, and whether they agree. */
+export type AgreementRow<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'> = CatalogEntry> = {
+    readonly entry: E;
+    readonly views: readonly CriticView[];
+    readonly outcome: AgreementOutcome;
+};
+/** The agreement of critics over some entries. */
+export type CritiqueAgreement<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'> = CatalogEntry> = {
+    /** Entries judged by two or more critics at their current picture, those every critic flags first, then those they disagree on. */
+    readonly rows: readonly AgreementRow<E>[];
+    /** Entries only one critic has judged at the current picture: there is nothing to compare. */
+    readonly single: number;
+    /** The critics that have judged at least one entry at its current picture. */
+    readonly critics: readonly string[];
+};
+/**
+ * Compares what the critics think of the same pictures. Only critiques of an entry's current picture count, and only each critic's
+ * newest. Critics that give no view ({@link critiqueStance}) are shown but do not make an entry agree or disagree: with fewer than
+ * two views the outcome is `unclear`, never agreement. An agreement is a reading for people; it is not a verdict, a status or a gate.
+ */
+export declare function critiqueAgreement<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'>>(entries: readonly E[], kind?: string): CritiqueAgreement<E>;
+/** What people decided about one opinion (a critic's critique of an entry, or one of its findings). */
+export type MarkStanding = {
+    /** `accepted`: only accepts. `dismissed`: only dismissals. `disputed`: reviewers disagree. `unmarked`: nobody has marked it at the current picture. */
+    readonly state: 'accepted' | 'dismissed' | 'disputed' | 'unmarked';
+    /** Reviewers who accepted it (their name, or the producer when they gave none). */
+    readonly accepted: readonly string[];
+    /** Reviewers who dismissed it. */
+    readonly dismissed: readonly string[];
+    /** Marks made about an earlier picture, which count for nothing now. */
+    readonly earlier: number;
+    /** The notes reviewers left, newest first. */
+    readonly notes: readonly string[];
+};
+/** The decision a mark records: `accept`, `dismiss`, or `null` for a word this reader does not know (shown as written, counted as neither). */
+export declare function markDecision(mark: Pick<EntryMark['mark'], 'decision'>): 'accept' | 'dismiss' | null;
+/**
+ * What reviewers decided about a critic's opinion of an entry. Only marks made about the picture the entry has now count; those
+ * about an earlier picture are tallied apart. Each reviewer's newest mark is the one that is held (the slot rule); a reviewer who
+ * accepted and later dismissed has dismissed. Marks with a decision this reader does not know count as neither.
+ *
+ * @param marks the entry's marks (`CatalogEntry.marks`).
+ * @param target the critic whose opinion is marked; `finding` names one finding, and without it the critique as a whole.
+ */
+export declare function markStanding(marks: readonly EntryMark[], target: {
+    readonly critic: string;
+    readonly finding?: string | undefined;
+}): MarkStanding;

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

@@ -0,0 +1,123 @@
+const byKey = (a, b) => (a.entry.key < b.entry.key ? -1 : a.entry.key > b.entry.key ? 1 : 0);
+/**
+ * Ranks the entries a critic judged, lowest first, so the likeliest problems are reviewed first. A score is read as
+ * higher-is-better (the convention of the critique format). When every ranked score also carries its standing among the scores
+ * of the same state kind (`verdict.relative.percentile`) that standing ranks them instead, because a loading overlay is not
+ * compared with a full screen. An entry whose picture changed since it was judged, or that the critic could not judge, is not
+ * ranked but is returned; an entry the critic never saw is only counted.
+ *
+ * @param entries the entries in view.
+ * @param critic the critic whose critiques rank them.
+ * @param kind when given, only entries of this state kind.
+ */
+export function rankCritiques(entries, critic, kind) {
+    const ranked = [], unranked = [];
+    let unjudged = 0;
+    for (const entry of entries) {
+        if (kind && entry.state !== kind)
+            continue;
+        const found = critic ? entry.critiques.filter(item => item.critique.critic.name === critic) : [];
+        // The newest critique that judged the current picture decides; failing that, the newest of any.
+        const current = found.find(item => item.currency === 'current');
+        const pick = current ?? found[0];
+        if (!pick) {
+            unjudged += 1;
+            continue;
+        }
+        if (current && current.critique.verdict?.score !== undefined && !current.critique.failure)
+            ranked.push({ entry, found: current });
+        else
+            unranked.push({ entry, found: pick });
+    }
+    const standing = (item) => item.found.critique.verdict?.relative?.percentile;
+    const byStanding = ranked.length > 0 && ranked.every(item => standing(item) !== undefined);
+    const key = (item) => (byStanding ? standing(item) : item.found.critique.verdict.score);
+    ranked.sort((a, b) => key(a) - key(b) || byKey(a, b));
+    unranked.sort(byKey);
+    return { ranked, rankedBy: byStanding ? 'standing-within-kind' : 'score', unranked, unjudged };
+}
+/** A score at or below this standing within its state kind (the lowest quarter) counts as flagging, when the critic gave no label. */
+export const FLAGGING_PERCENTILE = 25;
+/**
+ * Whether a critique flags the UI. A failed critique, or one with nothing to go on, gives no view and is never read as fine.
+ * Otherwise the critic's own label decides (`needs-polish` flags, `ok` clears); with no label, findings flag; with neither, a score
+ * in the lowest quarter of its state kind (`relative.percentile` at most {@link FLAGGING_PERCENTILE}) flags and a higher one clears. A bare
+ * score with no standing gives no view, because a raw score is not absolute.
+ */
+export function critiqueStance(critique) {
+    if (critique.failure)
+        return 'no-view';
+    const label = critique.verdict?.label;
+    if (label === 'needs-polish')
+        return 'flags';
+    if (label === 'ok')
+        return 'clear';
+    if ((critique.findings ?? []).length > 0)
+        return 'flags';
+    const percentile = critique.verdict?.relative?.percentile;
+    if (percentile !== undefined)
+        return percentile <= FLAGGING_PERCENTILE ? 'flags' : 'clear';
+    return 'no-view';
+}
+const ORDER = { 'agree-flag': 0, disagree: 1, unclear: 2, 'agree-clear': 3 };
+/**
+ * Compares what the critics think of the same pictures. Only critiques of an entry's current picture count, and only each critic's
+ * newest. Critics that give no view ({@link critiqueStance}) are shown but do not make an entry agree or disagree: with fewer than
+ * two views the outcome is `unclear`, never agreement. An agreement is a reading for people; it is not a verdict, a status or a gate.
+ */
+export function critiqueAgreement(entries, kind) {
+    const rows = [];
+    const critics = new Set();
+    let single = 0;
+    for (const entry of entries) {
+        if (kind && entry.state !== kind)
+            continue;
+        const newest = new Map();
+        for (const found of entry.critiques)
+            if (found.currency === 'current' && !newest.has(found.critique.critic.name))
+                newest.set(found.critique.critic.name, found);
+        for (const name of newest.keys())
+            critics.add(name);
+        if (newest.size < 2) {
+            if (newest.size === 1)
+                single += 1;
+            continue;
+        }
+        const views = [...newest.values()].map(({ critique }) => ({
+            critic: critique.critic.name, version: critique.critic.version, stance: critiqueStance(critique),
+            ...(critique.verdict?.score === undefined ? {} : { score: critique.verdict.score }),
+            ...(critique.verdict?.relative?.percentile === undefined ? {} : { percentile: critique.verdict.relative.percentile }),
+            ...(critique.verdict?.label ? { label: critique.verdict.label } : {})
+        })).sort((a, b) => (a.critic < b.critic ? -1 : 1));
+        const decided = views.filter(view => view.stance !== 'no-view');
+        const outcome = decided.length < 2 ? 'unclear' : decided.every(view => view.stance === 'flags') ? 'agree-flag' : decided.every(view => view.stance === 'clear') ? 'agree-clear' : 'disagree';
+        rows.push({ entry, views, outcome });
+    }
+    rows.sort((a, b) => ORDER[a.outcome] - ORDER[b.outcome] || byKey(a, b));
+    return { rows, single, critics: [...critics].sort() };
+}
+/** The decision a mark records: `accept`, `dismiss`, or `null` for a word this reader does not know (shown as written, counted as neither). */
+export function markDecision(mark) {
+    return mark.decision === 'accept' || mark.decision === 'dismiss' ? mark.decision : null;
+}
+/**
+ * What reviewers decided about a critic's opinion of an entry. Only marks made about the picture the entry has now count; those
+ * about an earlier picture are tallied apart. Each reviewer's newest mark is the one that is held (the slot rule); a reviewer who
+ * accepted and later dismissed has dismissed. Marks with a decision this reader does not know count as neither.
+ *
+ * @param marks the entry's marks (`CatalogEntry.marks`).
+ * @param target the critic whose opinion is marked; `finding` names one finding, and without it the critique as a whole.
+ */
+export function markStanding(marks, target) {
+    const mine = marks.filter(item => item.mark.critic.name === target.critic && (target.finding === undefined ? item.mark.finding === undefined : item.mark.finding === target.finding));
+    const current = mine.filter(item => item.currency === 'current');
+    const who = (item) => item.mark.reviewer ?? item.producer;
+    const accepted = [...new Set(current.filter(item => markDecision(item.mark) === 'accept').map(who))].sort();
+    const dismissed = [...new Set(current.filter(item => markDecision(item.mark) === 'dismiss').map(who))].sort();
+    return {
+        state: accepted.length && dismissed.length ? 'disputed' : accepted.length ? 'accepted' : dismissed.length ? 'dismissed' : 'unmarked',
+        accepted, dismissed,
+        earlier: mine.length - current.length,
+        notes: current.filter(item => item.mark.note).sort((a, b) => b.recordedAtMs - a.recordedAtMs).map(item => item.mark.note)
+    };
+}

package/dist/reports/src/critique-row.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @module Critiques in report rows
+ *
+ * A check of a part of kind `critique` carries an automated reviewer's opinion in `extensions["atlas.critique"]`
+ * (see `@crvouga/atlas/critics`). This module reads that extension into the optional `critique` field of a report row,
+ * so a viewer can list critiques without a second request, exactly as `state` carries a UI state. It decides nothing:
+ * the row's `status` says only whether the critic ran, a critique is never counted, and an extension this reader cannot
+ * read (a missing subject, a score that is not a number, a version it does not know) leaves the row as it was, an
+ * unknown opinion and never a pass.
+ *
+ * @see docs/critics.md
+ */
+import { type Critique, type CritiqueMark } from '../../schema/src/critique.js';
+import type { Check } from '../../schema/src/layer.js';
+/**
+ * The critique a check of a part of `kind` carries, or `undefined` for any other kind and for an extension that cannot be
+ * read. Unknown fields and values inside a readable critique are kept.
+ */
+export declare function critiqueOf(kind: string, check: Pick<Check, 'extensions'>): Critique | undefined;
+/**
+ * The mark a check of a part of `kind` carries (a reviewer's accept or dismiss of a critic's opinion, `atlas.critique-mark`), or
+ * `undefined` for any other kind and for an extension that cannot be read. Like a critique it is evidence: it decides nothing.
+ */
+export declare function critiqueMarkOf(kind: string, check: Pick<Check, 'extensions'>): CritiqueMark | undefined;

package/dist/reports/src/critique-row.js

@@ -0,0 +1,39 @@
+/**
+ * @module Critiques in report rows
+ *
+ * A check of a part of kind `critique` carries an automated reviewer's opinion in `extensions["atlas.critique"]`
+ * (see `@crvouga/atlas/critics`). This module reads that extension into the optional `critique` field of a report row,
+ * so a viewer can list critiques without a second request, exactly as `state` carries a UI state. It decides nothing:
+ * the row's `status` says only whether the critic ran, a critique is never counted, and an extension this reader cannot
+ * read (a missing subject, a score that is not a number, a version it does not know) leaves the row as it was, an
+ * unknown opinion and never a pass.
+ *
+ * @see docs/critics.md
+ */
+import { CRITIQUE_EXTENSION, CRITIQUE_MARK_EXTENSION, CRITIQUE_MARK_SCHEMA_VERSION, CRITIQUE_PART_KIND, CRITIQUE_SCHEMA_VERSION, CritiqueMarkSchema, CritiqueSchema } from '../../schema/src/critique.js';
+/**
+ * The critique a check of a part of `kind` carries, or `undefined` for any other kind and for an extension that cannot be
+ * read. Unknown fields and values inside a readable critique are kept.
+ */
+export function critiqueOf(kind, check) {
+    if (kind !== CRITIQUE_PART_KIND)
+        return undefined;
+    const raw = check.extensions?.[CRITIQUE_EXTENSION];
+    if (raw === undefined)
+        return undefined;
+    const parsed = CritiqueSchema.safeParse(raw);
+    return parsed.success && parsed.data.schema === CRITIQUE_SCHEMA_VERSION ? parsed.data : undefined;
+}
+/**
+ * The mark a check of a part of `kind` carries (a reviewer's accept or dismiss of a critic's opinion, `atlas.critique-mark`), or
+ * `undefined` for any other kind and for an extension that cannot be read. Like a critique it is evidence: it decides nothing.
+ */
+export function critiqueMarkOf(kind, check) {
+    if (kind !== CRITIQUE_PART_KIND)
+        return undefined;
+    const raw = check.extensions?.[CRITIQUE_MARK_EXTENSION];
+    if (raw === undefined)
+        return undefined;
+    const parsed = CritiqueMarkSchema.safeParse(raw);
+    return parsed.success && parsed.data.schema === CRITIQUE_MARK_SCHEMA_VERSION ? parsed.data : undefined;
+}

package/dist/reports/src/evidence-types.d.ts

@@ -11,6 +11,7 @@
 import type { EvidenceMeasurement, EvidenceStatus } from './explorer-types.js';
 import type { EvidenceScope, LayerRun } from '../../schema/src/layer.js';
 import type { LayerParameters } from './layer-types.js';
+import type { Critique, CritiqueMark } from '../../schema/src/critique.js';
 import type { UiStateFact } from './ui-state.js';
 /** Where a recorded test's timeline and captured files are read from. */
 export type RecordingAddress = {
@@ -179,6 +180,10 @@ export type LayerRow = {
     readonly evidence?: EvidenceSummary;
     /** For a check of a `ui-state` or `ui-plan` part: its picture and declared facts, so a catalog is listed without another request (see `ui-state.ts`). Absent for every other kind. */
     readonly state?: UiStateFact;
+    /** For a check of a `critique` part whose `atlas.critique` extension can be read: the opinion of an automated reviewer (see `critique-row.ts`). An opinion, never a result: it does not decide `status`, a slot or the gate. Absent for every other kind, and for an extension that cannot be read. */
+    readonly critique?: Critique;
+    /** For a check of a `critique` part whose `atlas.critique-mark` extension can be read: a person's accept or dismiss of a critic's opinion (see `critique-row.ts`). Evidence, never a result: it does not decide `status`, a slot or the gate. Absent for every other kind, and for an extension that cannot be read. */
+    readonly critiqueMark?: CritiqueMark;
     /** What became of this check's expected recording: `uploaded`, `referenced`, `skipped`, `unresolved` or `not-applicable`, with a reason when it is not uploaded. Absent when the check declared no expectation. Independent of `status`. */
     readonly recording?: {
         readonly state: string;

package/dist/reports/src/layer-merge.js

@@ -1,6 +1,7 @@
 import { summarizeStoredEvidence, summarizeStoredLayerEvidence } from './evidence-detail.js';
 import { effectiveScope } from './evidence-scope.js';
 import { layerPlace } from './layer-axes.js';
+import { critiqueMarkOf, critiqueOf } from './critique-row.js';
 import { UI_PLAN_KIND, uiStateOf } from './ui-state.js';
 /**
  * A short, deterministic fingerprint of a spec's text, shaped `<length>:<hash>:<hash>` (the length in UTF-16 code
@@ -100,6 +101,8 @@ export function layerEvidence(summary, backend) {
             const evidence = summarizeStoredEvidence(effectiveScope(part.scope, summary.scope), unstored, check);
             const item = expectations?.get(check.id);
             const state = uiStateOf(part.kind, check);
+            const critique = critiqueOf(part.kind, check);
+            const critiqueMark = critiqueMarkOf(part.kind, check);
             rows.push({
                 kind: part.kind,
                 id: check.id,
@@ -113,6 +116,8 @@ export function layerEvidence(summary, backend) {
                 durationMs: test?.durationMs ?? check.durationMs ?? null,
                 ...(evidence ? { evidence } : {}),
                 ...(state ? { state } : {}),
+                ...(critique ? { critique } : {}),
+                ...(critiqueMark ? { critiqueMark } : {}),
                 ...(item ? { recording: { state: item.state, ...(item.reason ? { reason: item.reason } : {}) } } : {}),
             });
         }