@crvouga/atlas 1.12.0 → 1.13.0

package/dist/schema/src/critique.js

@@ -0,0 +1,96 @@
+/**
+ * @module The `atlas.critique` evidence schema
+ *
+ * What an automated reviewer (a critic) says about one captured UI. It is not a new layer format: a critique is a
+ * check inside a part of kind `critique`, and the opinion rides in the check's `extensions["atlas.critique"]`, so by the
+ * rules of docs/extending.md it can never decide a result. The check's `status` says only whether the critic ran
+ * (`passed` a verdict was produced, `failed` the critic could not produce one, `running`, `not-run`).
+ *
+ * Everything except `schema`, `subject` and `critic` is optional, so a single score (a model-based critic) and rich
+ * findings (an LLM critic) are one shape. Every object is open, and `kind`, `category`, `severity`, `label` and `reason`
+ * are open strings: a value nobody has heard of is kept and shown generically, never rejected. A reader that cannot read
+ * the whole extension drops it and keeps the check and its status (`readCritique` in `@crvouga/atlas/critics`).
+ *
+ * @see docs/critics.md
+ * @see docs/extending.md
+ */
+import { z } from 'zod/v4';
+/** The key under which a critique is stored in a check's `extensions`. */
+export const CRITIQUE_EXTENSION = 'atlas.critique';
+/** The version of the `atlas.critique` extension a reader of this release understands. A critique of another version is unknown, not wrong. */
+export const CRITIQUE_SCHEMA_VERSION = 1;
+/** The `kind` of the report part that holds critiques. Parts of this kind are opinions: never counted, never part of the gate. */
+export const CRITIQUE_PART_KIND = 'critique';
+/** The prefix of the `producer` of a layer of critiques: `critic.<critic name>`. */
+export const CRITIC_PRODUCER_PREFIX = 'critic.';
+/** The region of the image a finding is about, in the stated unit (`px` of the stored image, or `normalized` 0..1). */
+export const CritiqueRegionSchema = z.looseObject({
+    unit: z.string().min(1).describe('`px` (pixels of the stored image) or `normalized` (0..1 of its width and height). Open vocabulary'),
+    x: z.number(),
+    y: z.number(),
+    w: z.number().nonnegative(),
+    h: z.number().nonnegative()
+});
+/** One thing a critic found: where, what kind, how bad, why, and what to do. Nothing is required. */
+export const CritiqueFindingSchema = z.looseObject({
+    id: z.string().min(1).optional().describe('Stable within the critique, so a reviewer can mark this finding valid or not'),
+    category: z.string().min(1).optional().describe('Open vocabulary: `spacing`, `contrast`, `alignment`, `overflow`, `hierarchy`…'),
+    severity: z.string().min(1).optional().describe('Open vocabulary, conventionally `info`, `minor`, `major`'),
+    confidence: z.number().min(0).max(1).optional(),
+    region: CritiqueRegionSchema.optional(),
+    rationale: z.string().optional(),
+    suggestion: z.string().optional()
+});
+/**
+ * How a score reads in context. A raw score is not absolute: a loading overlay is compared with other loading overlays,
+ * not with full screens, and a change against the same entry's previous image is more telling than the level.
+ */
+export const CritiqueRelativeSchema = z.looseObject({
+    stateKind: z.string().min(1).describe('The kind of UI state the score is relative to: `screen`, `overlay`, `loading`, `error`, `empty`…'),
+    percentile: z.number().min(0).max(100).optional().describe('Where the score falls among the project\'s scores of the same state kind, 0..100, higher is better'),
+    sampleSize: z.number().int().nonnegative().optional().describe('How many scores of that state kind the percentile is over'),
+    previousScore: z.number().optional().describe('The same entry\'s score for its previous image, from the same critic'),
+    delta: z.number().optional().describe('`score` minus `previousScore`')
+});
+/** The judgement: a score and how to read it, a label, a confidence. A critic that cannot score may give only a label. */
+export const CritiqueVerdictSchema = z.looseObject({
+    score: z.number().optional().describe('A finite number. `scale` says what it means'),
+    scale: z.string().optional().describe('For example `0..1, higher is better`'),
+    label: z.string().optional().describe('Open vocabulary, conventionally `ok` or `needs-polish`'),
+    confidence: z.number().min(0).max(1).optional(),
+    relative: CritiqueRelativeSchema.optional()
+});
+/** Why a critic produced no verdict: a reason code in an open vocabulary (`error`, `timeout`, `rate-limited`, `invalid-output`) and a message that holds no credential. */
+export const CritiqueFailureSchema = z.looseObject({
+    reason: z.string().min(1),
+    message: z.string().optional()
+});
+/**
+ * The `atlas.critique` extension, version 1: the image judged (`subject`), who judged (`critic`, `model`,
+ * `parameters`), the opinion (`verdict`, `findings`) or why there is none (`failure`), and what it cost (`usage`).
+ * The prompt is recorded only as a hash (`parameters.rubric`). Emitted as `critique.schema.json`.
+ */
+export const CritiqueSchema = z.looseObject({
+    schema: z.number().int().positive().describe('The version of this extension. 1'),
+    subject: z.looseObject({
+        entryKey: z.string().min(1).describe('The catalog entry that was judged'),
+        imageSha256: z.string().min(1).describe('The hash of the exact image bytes that were judged. When the entry\'s image changes, this critique judged an earlier image'),
+        state: z.string().min(1).optional().describe('The kind of UI state: `screen`, `overlay`, `loading`, `error`, `empty`…')
+    }),
+    critic: z.looseObject({
+        name: z.string().min(1),
+        version: z.string().min(1).describe('Of the critic\'s own logic. A newer version replaces an older one'),
+        kind: z.string().min(1).optional().describe('Open vocabulary: `model`, `llm`, `ml`, `heuristic`…')
+    }),
+    model: z.looseObject({ id: z.string().min(1), provider: z.string().optional() }).optional(),
+    parameters: z.record(z.string(), z.unknown()).optional().describe('Everything else that explains the result: temperature, seed, the SHA-256 of the rubric'),
+    verdict: CritiqueVerdictSchema.optional(),
+    findings: z.array(CritiqueFindingSchema).optional(),
+    failure: CritiqueFailureSchema.optional(),
+    usage: z.looseObject({
+        inputTokens: z.number().nonnegative().optional(),
+        outputTokens: z.number().nonnegative().optional(),
+        latencyMs: z.number().nonnegative().optional(),
+        costUsd: z.number().nonnegative().optional()
+    }).optional()
+});

package/dist/schema/src/index.d.ts

@@ -2,7 +2,7 @@
  * @module Schema package entry point (`@crvouga/atlas/schema`)
  *
  * Re-exports every Zod schema, constant and inferred type of the Atlas contract: the layer format and report status
- * (`layer`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
+ * (`layer`), the `atlas.critique` evidence of automated UI reviewers (`critique`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
  * report sources the viewer reads (`runs-index`, `report-sources`) and the server configuration (`server-config`).
  * The JSON Schemas shipped in `schemas/` are generated from these by `bun run schemas`.
  *
@@ -14,6 +14,7 @@ export * from './runs-index.js';
 export * from './spec.js';
 export * from './report-sources.js';
 export * from './layer.js';
+export * from './critique.js';
 export * from './server-config.js';
 export * from './user-state.js';
 export * from './api.js';

package/dist/schema/src/index.js

@@ -2,7 +2,7 @@
  * @module Schema package entry point (`@crvouga/atlas/schema`)
  *
  * Re-exports every Zod schema, constant and inferred type of the Atlas contract: the layer format and report status
- * (`layer`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
+ * (`layer`), the `atlas.critique` evidence of automated UI reviewers (`critique`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
  * report sources the viewer reads (`runs-index`, `report-sources`) and the server configuration (`server-config`).
  * The JSON Schemas shipped in `schemas/` are generated from these by `bun run schemas`.
  *
@@ -14,6 +14,7 @@ export * from './runs-index.js';
 export * from './spec.js';
 export * from './report-sources.js';
 export * from './layer.js';
+export * from './critique.js';
 export * from './server-config.js';
 export * from './user-state.js';
 export * from './api.js';

package/dist/schema/src/server-config.d.ts

@@ -11,9 +11,13 @@
  * @see docs/server.md
  */
 import { z } from 'zod/v4';
-/** What a bearer token may do: `read` (look), `publish` (also upload) or `admin` (also remove scratch objects). */
+/**
+ * What a bearer token may do: `read` (look), `critic` (also publish critiques, and nothing else), `publish` (also upload
+ * anything) or `admin` (also remove scratch objects).
+ */
 export declare const ServerRoleSchema: z.ZodEnum<{
     read: "read";
+    critic: "critic";
     publish: "publish";
     admin: "admin";
 }>;
@@ -27,6 +31,7 @@ export declare const ServerTokenSchema: z.ZodObject<{
     name: z.ZodString;
     role: z.ZodEnum<{
         read: "read";
+        critic: "critic";
         publish: "publish";
         admin: "admin";
     }>;
@@ -45,6 +50,7 @@ export declare const ServerConfigSchema: z.ZodObject<{
             name: z.ZodString;
             role: z.ZodEnum<{
                 read: "read";
+                critic: "critic";
                 publish: "publish";
                 admin: "admin";
             }>;

package/dist/schema/src/server-config.js

@@ -11,8 +11,11 @@
  * @see docs/server.md
  */
 import { z } from 'zod/v4';
-/** What a bearer token may do: `read` (look), `publish` (also upload) or `admin` (also remove scratch objects). */
-export const ServerRoleSchema = z.enum(['read', 'publish', 'admin']);
+/**
+ * What a bearer token may do: `read` (look), `critic` (also publish critiques, and nothing else), `publish` (also upload
+ * anything) or `admin` (also remove scratch objects).
+ */
+export const ServerRoleSchema = z.enum(['read', 'critic', 'publish', 'admin']);
 /**
  * A bearer token: a name for logs, a role, and the token itself or the name of the environment variable that holds it
  * (exactly one of the two).
@@ -20,7 +23,7 @@ export const ServerRoleSchema = z.enum(['read', 'publish', 'admin']);
 export const ServerTokenSchema = z
     .strictObject({
     name: z.string().min(1).describe('Shown in logs, never the token itself'),
-    role: ServerRoleSchema.describe('`read` may look. `publish` may also upload. `admin` may also remove scratch objects'),
+    role: ServerRoleSchema.describe('`read` may look. `critic` may also publish critiques (layers of producer `critic.*` whose parts are all of kind `critique`). `publish` may also upload. `admin` may also remove scratch objects'),
     token: z.string().min(12).optional().describe('The token. Prefer `tokenEnv`, so the file holds no secret'),
     tokenEnv: z.string().optional().describe('The name of the environment variable that holds the token')
 })

package/dist/server/src/auth.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module Authentication and roles
  *
- * Who is asking, and may they. Tokens have a role (`read` < `publish` < `admin`) and are compared in constant time. Reading
+ * Who is asking, and may they. Tokens have a role (`read` < `critic` < `publish` < `admin`) and are compared in constant time. Reading
  * accepts a Bearer token or the browser's sign-in box (any user name, the token as the password); changing anything needs
  * the Bearer header, because a browser sends the sign-in box's credentials to any page that asks, which would let another
  * site upload with them. A server with no tokens is open, and refuses to listen beyond this machine unless told it may.

package/dist/server/src/auth.js

@@ -1,13 +1,13 @@
 /**
  * @module Authentication and roles
  *
- * Who is asking, and may they. Tokens have a role (`read` < `publish` < `admin`) and are compared in constant time. Reading
+ * Who is asking, and may they. Tokens have a role (`read` < `critic` < `publish` < `admin`) and are compared in constant time. Reading
  * accepts a Bearer token or the browser's sign-in box (any user name, the token as the password); changing anything needs
  * the Bearer header, because a browser sends the sign-in box's credentials to any page that asks, which would let another
  * site upload with them. A server with no tokens is open, and refuses to listen beyond this machine unless told it may.
  */
 import { timingSafeEqual } from 'node:crypto';
-const RANK = { read: 1, publish: 2, admin: 3 };
+const RANK = { read: 1, critic: 2, publish: 3, admin: 4 };
 function same(a, b) {
     const left = Buffer.from(a), right = Buffer.from(b);
     return left.length === right.length && timingSafeEqual(left, right);

package/dist/server/src/config.js

@@ -60,7 +60,7 @@ export const SERVER_SETTINGS = [
     { summary: 'How often (seconds) the backends are looked at for layers written by something else', key: 'refreshSeconds', flag: '--refresh <seconds>', env: ['ATLAS_REFRESH_SECONDS'], default: '`10`', example: { value: '30', read: c => c.refreshSeconds, expected: 30 } },
     { summary: 'Let anyone look, not upload', key: 'auth.anonymousRead', flag: '--anonymous-read', env: ['ATLAS_ANONYMOUS_READ'], default: 'no', example: { value: '1', read: c => c.anonymousRead, expected: true } },
     { summary: 'Listen publicly with no tokens (something in front signs people in)', key: 'auth.insecure', flag: '--insecure', env: ['ATLAS_INSECURE'], default: 'no', example: { value: '1', read: c => c.insecure, expected: true } },
-    { summary: 'The admin token (also `ATLAS_PUBLISH_TOKEN` and `ATLAS_READ_TOKEN` for the other roles, or `auth.tokens` in the file)', key: 'auth.tokens', flag: null, env: ['ATLAS_TOKEN'], default: 'none: the server is open and listens on this machine only', example: { value: 'admin-token-123456', read: c => c.tokens.map(token => token.role), expected: ['admin'] } },
+    { summary: 'The admin token (also `ATLAS_PUBLISH_TOKEN`, `ATLAS_CRITIC_TOKEN` and `ATLAS_READ_TOKEN` for the other roles, or `auth.tokens` in the file)', key: 'auth.tokens', flag: null, env: ['ATLAS_TOKEN'], default: 'none: the server is open and listens on this machine only', example: { value: 'admin-token-123456', read: c => c.tokens.map(token => token.role), expected: ['admin'] } },
     { summary: 'The configuration file', key: '(the file itself)', flag: '--config <file>', env: ['ATLAS_CONFIG'], default: '`./atlas.server.json` when it exists', example: { value: 'custom.json', read: c => path.basename(c.configFile ?? ''), expected: 'custom.json' } },
     { summary: 'Largest uploaded object in MiB', key: 'limits.maxObjectMiB', flag: null, env: ['ATLAS_MAX_OBJECT_MIB'], default: '`256`', example: { value: '64', read: c => c.limits.maxObjectMiB, expected: 64 } },
     { summary: 'Largest JSON upload in MiB', key: 'limits.maxJsonMiB', flag: null, env: ['ATLAS_MAX_JSON_MIB'], default: '`32`', example: { value: '8', read: c => c.limits.maxJsonMiB, expected: 8 } },
@@ -172,7 +172,7 @@ export function loadServerConfig(argv, env, cwd, read = file => readFileSync(fil
             throw new ConfigError(`Token "${item.name}" reads ${item.tokenEnv} and it is not set`);
         tokens.push({ name: item.name, role: item.role, token });
     }
-    for (const [variable, role, name] of [['ATLAS_TOKEN', 'admin', 'admin'], ['ATLAS_PUBLISH_TOKEN', 'publish', 'publish'], ['ATLAS_READ_TOKEN', 'read', 'read']]) {
+    for (const [variable, role, name] of [['ATLAS_TOKEN', 'admin', 'admin'], ['ATLAS_PUBLISH_TOKEN', 'publish', 'publish'], ['ATLAS_CRITIC_TOKEN', 'critic', 'critic'], ['ATLAS_READ_TOKEN', 'read', 'read']]) {
         if (env[variable])
             tokens.push({ name, role, token: env[variable].trim() });
     }

package/dist/server/src/openapi.d.ts

@@ -1,7 +1,7 @@
 /** 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 declare const API_VERSION = "1.5.0";
-/** Who may call an operation: `none` (anyone), or the least role that may (`read` < `publish` < `admin`). */
-export type Role = 'none' | 'read' | 'publish' | 'admin';
+export declare const API_VERSION = "1.6.0";
+/** Who may call an operation: `none` (anyone), or the least role that may (`read` < `critic` < `publish` < `admin`). */
+export type Role = 'none' | 'read' | 'critic' | 'publish' | 'admin';
 type JsonSchema = Record<string, unknown>;
 type Param = {
     readonly name: string;

package/dist/server/src/openapi.js

@@ -17,7 +17,7 @@ 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, 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';
+export const API_VERSION = '1.6.0';
 /** The JSON Schema of a Zod schema, as OpenAPI 3.1 embeds it. `output` for what the server sends, `input` for what it accepts. */
 function schemaOf(schema, io = 'output') {
     const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { target: 'draft-2020-12', unrepresentable: 'any', io });
@@ -246,7 +246,7 @@ const BASE_OPERATIONS = [
         responses: { '200': { description: 'It exists.' }, '401': UNAUTHORIZED, '404': problem('No such object.') }
     },
     {
-        route: 'PUT /api/store/*', path: '/api/store/{key}', operationId: 'putObject', tag: 'Store protocol', role: 'publish',
+        route: 'PUT /api/store/*', path: '/api/store/{key}', operationId: 'putObject', tag: 'Store protocol', role: 'critic',
         summary: 'Upload an object',
         description: [
             'The write half of the `ObjectStore` interface. The server checks what it can from the bytes in hand and says no to what would corrupt the report for everyone:',
@@ -257,7 +257,9 @@ const BASE_OPERATIONS = [
             '- a **run manifest** must have passed its privacy scan;',
             '- keys are immutable: the same bytes again are `200` (a retry), other bytes under the same key are `409`.',
             '',
-            'Upload in dependency order: blobs, then the manifest, then the catalog entry. `atlas report publish`, `atlas report stream` and `httpStore` do. Needs a `Bearer` token of role `publish` or `admin`; a browser\'s sign-in box is refused.'
+            'Upload in dependency order: blobs, then the manifest, then the catalog entry. `atlas report publish`, `atlas report stream` and `httpStore` do. Needs a `Bearer` token of role `publish` or `admin`; a browser\'s sign-in box is refused.',
+            '',
+            'A token of role `critic` may upload only what a critic publishes: blobs, and layers (and their catalog entries) whose `producer` is `critic.<name>` and whose parts are all of kind `critique`. Anything else is `403` with the rule it broke, and nothing is stored.'
         ].join('\n'),
         parameters: [KEY, { name: 'content-type', in: 'header', description: 'Stored with the object and returned when it is read.', schema: str }],
         body: { description: 'The object\'s bytes.', contentType: 'application/octet-stream', schema: { type: 'string', format: 'binary' }, required: true },
@@ -590,6 +592,7 @@ export const NOT_OPERATIONS = new Map([
 const SECURITY = {
     none: [],
     read: [{ bearer: [] }, { basic: [] }],
+    critic: [{ bearer: [] }],
     publish: [{ bearer: [] }],
     admin: [{ bearer: [] }]
 };
@@ -623,7 +626,7 @@ export function openApiDocument(options = {}) {
             description: [
                 'One Atlas node serves multiple projects. Clients select a project using ?project=<slug>, X-Atlas-Project, or /api/projects/<slug>/… . Each project has independent specs, layers, recordings, status, and event streams. Within each project, the newest completed result of every check wins its slot. Unqualified requests address the legacy default project.',
                 '',
-                '**Authentication.** With tokens configured, send `Authorization: Bearer <token>`. Roles: `read` < `publish` < `admin`. Uploading needs a Bearer token; a browser\'s HTTP Basic sign-in (any user name, the token as the password) is accepted for reading only. A server with no tokens is open and listens on this machine only unless told otherwise.',
+                '**Authentication.** With tokens configured, send `Authorization: Bearer <token>`. Roles: `read` < `critic` < `publish` < `admin`. A `critic` token may read, and publish critiques (layers of automated reviewers) and nothing else. Uploading needs a Bearer token; a browser\'s HTTP Basic sign-in (any user name, the token as the password) is accepted for reading only. A server with no tokens is open and listens on this machine only unless told otherwise.',
                 '',
                 '**Errors** are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem documents (`application/problem+json`) with a `detail` that says what to do. `401` send a token, `403` that token may not, `409` upload what this depends on first or you are changing something immutable, `413` too large, `422` not valid, `503` still starting (retry after `Retry-After`).',
                 '',

package/dist/server/src/store-api.js

@@ -12,6 +12,7 @@ import { Hono } from 'hono';
 import { isPaged } from '../../reports/src/object-store.js';
 import { readBytes } from '../../reports/src/object-io.js';
 import { UNTRUSTED_HEADERS } from '../../reports/src/attachment-response.js';
+import { criticScopeViolation } from '../../critics/src/scope.js';
 import { classify, isCatalog, Refusal, sameBytes, validateUpload, validKey } from './validate.js';
 /** Read a request body, refusing as soon as it is over the limit rather than after holding it all. */
 export async function readLimited(request, limit) {
@@ -55,6 +56,40 @@ const decode = (c, prefix) => {
         return null;
     }
 };
+const decoder = new TextDecoder();
+/**
+ * What a critic-role token may upload: blobs, and layers (and the catalog entries that make them visible) whose producer
+ * is `critic.<name>` and whose parts are all of kind `critique`. Anything else, including a key that is not a layer at
+ * all, is refused with `403` and the rule it broke, before anything is stored. Blobs are checked against their name by
+ * the upload validation, so on their own they are harmless.
+ */
+async function assertCriticMayStore(name, bytes, store) {
+    const known = classify(name);
+    if (known?.kind === 'blob')
+        return;
+    if (known?.kind !== 'layer' && known?.kind !== 'layer-catalog')
+        throw new Refusal(403, `A critic token may upload only critiques, not "${name}". Use a publish token for anything else.`);
+    let text;
+    if (known.kind === 'layer')
+        text = decoder.decode(bytes);
+    else {
+        const stored = await store.get(`layers/manifests/${known.id}.json`);
+        // A catalog entry for a layer that is not there is refused by the upload validation, as for everyone.
+        if (!stored)
+            return;
+        text = decoder.decode(await readBytes(stored.body));
+    }
+    let layer;
+    try {
+        layer = JSON.parse(text);
+    }
+    catch {
+        return;
+    }
+    const violation = criticScopeViolation(layer ?? {});
+    if (violation)
+        throw new Refusal(403, violation);
+}
 /**
  * The store protocol: the seven operations of an object store over HTTP, for what the server keeps. A client
  * that publishes to it uses the same code that publishes to a folder or a bucket. It differs from a bucket in
@@ -134,7 +169,8 @@ export function storeApi(options) {
         return new Response(stored.body, { headers });
     });
     app.put('/*', async (c) => {
-        const verdict = auth.check(c.req.raw, 'publish');
+        // A critic may upload too, but only what a critic publishes (see `assertCriticMayStore`).
+        const verdict = auth.check(c.req.raw, 'critic');
         if (!verdict.ok)
             return refuse(c, verdict.status, verdict.message);
         const name = key(c);
@@ -143,6 +179,8 @@ export function storeApi(options) {
         try {
             const bytes = await readLimited(c.req.raw, options.maxObjectBytes);
             return await exclusive(name, async () => {
+                if (verdict.identity.role === 'critic')
+                    await assertCriticMayStore(name, bytes, store);
                 const kind = await validateUpload(name, bytes, store, layer => { recent.set(layer.id, layer); if (recent.size > 8)
                     recent.delete(recent.keys().next().value); });
                 // A blob's name is the digest of what is in it, which was just checked: one that is there is this one, however it was compressed.

package/docs/agents.md

@@ -103,6 +103,7 @@ The complete public export map is generated from the package manifest (wildcards
 @crvouga/atlas/vitest
 @crvouga/atlas/schema
 @crvouga/atlas/server
+@crvouga/atlas/critics
 @crvouga/atlas/reports/*
 @crvouga/atlas/schemas/*
 @crvouga/atlas/openapi.json

package/docs/critics.md

@@ -0,0 +1,190 @@
+# Critics: automated reviewers that mark which UIs need polish
+
+A **critic** looks at one captured UI (an image and what is known about it) and says how polished it is, and ideally
+where and why it is not. A critic may be a pretrained model that gives a score, a vision-capable language model that
+follows a rubric, or a classic measure such as a contrast ratio. All three are the same thing to Atlas, through one small
+contract, so people review the likeliest problems first.
+
+**Critics are producers that publish layers.** Atlas supplies the contract, the runner, the evidence format and the
+credential. It never executes a model on the server and never holds a provider key. A critique is not a test result and
+is not human review: it never changes whether a report passes.
+
+- [What is available](#what-is-available)
+- [The critic contract](#the-critic-contract)
+- [A critique is a layer](#a-critique-is-a-layer)
+- [Running critics](#running-critics)
+- [State-aware judging, calibration and modes](#state-aware-judging-calibration-and-modes)
+- [Authentication and authorization](#authentication-and-authorization)
+- [Credentials](#credentials)
+- [What is not here yet](#what-is-not-here-yet)
+
+## What is available
+
+Import `@crvouga/atlas/critics`. It needs no model, no provider SDK and no network; a critic brings its own.
+
+| You want | Use |
+| --- | --- |
+| Define a critic | `defineCritic` (the contract below) |
+| Judge many images with caching, retries, rate limits, timeouts and budgets | `runCritic` |
+| Store the opinions | `critiqueLayer`, `publishCritiques` (a layer of parts of kind `critique`) |
+| Read them back | `readCritique`, `critiquesOfLayer`, `critiqueCurrency` |
+| Read a score in context, measure a threshold, decide an exit code | `relativeVerdict`, `calibrate`, `gateDecision` |
+| Keep keys out of configuration and logs | `parseCredentialRef`, `resolveCredential`, `assertNoLiteralCredentials`, `createRedactor` |
+| Let a token publish critiques and nothing else | the `critic` role (below) |
+
+The JSON Schema of the evidence is [`critique.schema.json`](../packages/schema/schemas/critique.schema.json). The
+function-level reference is generated from the code: [critics](reference/critics.md).
+
+## The critic contract
+
+```ts
+import { defineCritic } from '@crvouga/atlas/critics';
+
+export default defineCritic({
+  name: 'contrast', version: '1.0.0', kind: 'heuristic',   // kind is an open string: model, llm, ml, heuristic…
+  describe: () => ({ sendsImagesTo: null, needsSetup: false }),
+  evaluate: async ({ image, imageSha256, entry, signal }) => ({
+    verdict: { score: measureContrast(image), scale: '0..1, higher is better' }
+  })
+});
+```
+
+A critic only judges one image. `describe()` says where images are sent (`sendsImagesTo`, `null` when they never leave
+the machine), the model, and the fixed parameters (temperature, the SHA-256 of the rubric): together with the critic's
+`name` and `version` and the image hash they are the identity of a judgement. `evaluate` returns a `verdict` (a score
+and how to read it), `findings`, or both, and may throw: throw a `RateLimitedError` (with the provider's `Retry-After` in
+milliseconds), an `InvalidOutputError`, or any `CriticError` with your own reason code. The runner records the failure
+and the next run retries it. A failure never becomes a score.
+
+## A critique is a layer
+
+A critique is a check inside a part of kind `critique`, in a layer whose `producer` is `critic.<name>`. The check's
+`status` says only whether the critic ran: `passed` a verdict was produced, `failed` the critic could not produce one.
+The opinion is evidence, by the rules of [extending.md](extending.md#the-rules-that-keep-it-compatible-forever), so it
+can never decide a result. It lives in `extensions["atlas.critique"]` and is repeated as standard evidence, so a viewer
+that has never heard of critics still shows it: the score is a measurement named `polish`, and each finding is an
+annotation of type `critique`.
+
+```json
+{
+  "producer": "critic.vision-llm",
+  "kind": "critique",
+  "checks": [{
+    "id": "critique/checkout/payment-sheet",
+    "status": "passed",
+    "measurements": [{ "name": "polish", "value": 0.62, "unit": "score" }],
+    "annotations": [{ "type": "critique", "level": "warning", "message": "spacing: Label touches both edges of the button. (suggestion: Increase horizontal padding.)" }],
+    "extensions": { "atlas.critique": {
+      "schema": 1,
+      "subject": { "entryKey": "checkout/payment-sheet", "imageSha256": "…", "state": "overlay" },
+      "critic": { "name": "vision-llm", "kind": "llm", "version": "1.0.0" },
+      "model": { "id": "…", "provider": "…" },
+      "parameters": { "temperature": 0, "rubric": "<sha256 of the rubric>" },
+      "verdict": { "score": 0.62, "scale": "0..1, higher is better", "label": "needs-polish", "confidence": 0.7 },
+      "findings": [{ "id": "f1", "category": "spacing", "severity": "minor", "region": { "unit": "px", "x": 24, "y": 612, "w": 342, "h": 48 }, "rationale": "Label touches both edges of the button.", "suggestion": "Increase horizontal padding." }]
+    } }
+  }]
+}
+```
+
+- A single score (a model-based critic) is a valid critique: everything except `schema`, `subject` and `critic` is optional.
+- `kind`, `category`, `severity`, `label` and failure `reason` are open strings, and every object is open. A value or field
+  nobody has heard of is kept and shown generically, never rejected.
+- A reader that cannot read the whole extension (a missing `subject`, a score that is not a number, a `schema` version it
+  does not know) drops the extension and keeps the check and its status. An unreadable opinion is unknown.
+- **Anchored to pixels.** `subject.imageSha256` is the hash of the image that was judged. When an entry's image changes,
+  `critiqueCurrency` says the old critique judged an earlier image: it is shown, never hidden, and the entry counts as not
+  yet judged.
+- **Slots.** The producer is the critic's name; the critic and model versions are labels. A newer version of a critic
+  replaces an older one's critique of the same entry. Put the version in `parameters` of `critiqueLayer` to compare
+  versions side by side instead.
+- **The prompt is recorded as a hash** (`parameters.rubric`), not as text.
+- **Failures are data.** A crash, a timeout, a rate limit that never cleared and an unparseable answer are `failed`
+  critiques with `failure.reason` (`error`, `timeout`, `rate-limited`, `invalid-output`, `image-mismatch`…) and a message.
+
+**Critiques never change the gate.** Parts of kind `critique` are left out of every count and of `atlas report status`,
+even when they are the only thing recorded (a report of opinions alone has no test results, so the gate says so). A low
+score does not fail it, and neither does a critic that crashed. A project that wants a score to fail something opts in
+with `gateDecision` in `gate` mode, which is computed by the reader from critique data and never changes a check's
+status, a slot or a winner.
+
+## Running critics
+
+`runCritic` owns everything around the judgement; a critic only judges one image.
+
+- **Caching.** An entry is skipped, without fetching its image, when a critique with a verdict already exists for the same
+  critic, version, model, parameters and image hash (`existing`, read with `critiquesOfLayer`). Identical images across
+  runs are judged once; only a changed image is judged again. A failed critique is not a cache hit. `force` judges again.
+  Layers are content-addressed, so publishing the same outcomes twice is harmless.
+- **Concurrency, timeout, rate limits.** A bounded number of calls in flight. A call over `timeoutMs` is aborted and
+  recorded as `timeout`; the run goes on. A rate-limit answer waits at least `Retry-After`, with exponential backoff and
+  jitter, for a bounded number of attempts, and then is recorded as `rate-limited`.
+- **Budgets.** `budget: { maxImages, maxTokens, maxCostUsd }`. When one is reached the run stops cleanly and returns what
+  it finished with `stoppedBy: 'budget'`. Cost and tokens come from the `usage` a critic reports.
+- **Dry run.** `dryRun` loads and sends nothing and returns what would be judged and skipped, and where images would go
+  (`sendsImagesTo`).
+- **Reproducibility.** Results come back in the order of the entries, so the same inputs publish the same layer; a
+  deterministic critic gives identical scores on every run. Atlas records what explains a result (critic, version,
+  model, rubric hash, parameters) and does not promise that a language model answers the same twice. A re-run adds a
+  newer layer instead of changing an old one.
+- **Images may leave the machine.** `describe().sendsImagesTo` is the thing to show a person before a run that sends
+  images to a third party, and to require explicit confirmation for.
+
+```ts
+import { critiquesOfLayer, publishCritiques, runCritic } from '@crvouga/atlas/critics';
+
+const result = await runCritic({
+  critic, entries, loadImage: (entry) => fetchImage(entry),
+  existing: layers.flatMap((layer) => critiquesOfLayer(layer).map((found) => found.critique)),
+  budget: { maxImages: 200 }, secrets: [providerKey]
+});
+await publishCritiques(store, { critic, outcomes: result.outcomes, recordedAtMs: Date.now() });
+```
+
+## State-aware judging, calibration and modes
+
+A raw score is not absolute: a loading overlay is not a full screen.
+
+- `relativeVerdict` reads a score against the project's scores of the **same state kind** (a percentile within the kind)
+  and against the same entry's previous image (`delta`), and goes into `verdict.relative`.
+- `calibrate` measures a critic against labelled examples **per state kind**: sample sizes, precision, recall, the
+  threshold chosen, and `inSample`, which is true unless held-out examples were given. In-sample figures flatter a critic
+  and are labelled as such.
+- `gateDecision` turns scores into an exit code. Modes: `report` (default: shown, always exit 0), `warn` (a warning for each
+  score below its threshold, exit 0), `gate` (exit 1 when a threshold is crossed). `gate` is **refused** (exit 2, with the
+  reasons) unless every state kind present has a calibration of this critic and version with a threshold, at least 10 bad
+  and 10 good examples, and held-out figures. An explicit threshold never waives that evidence.
+
+## Authentication and authorization
+
+Run critics against a server that has tokens: a server with no tokens is open and every caller is an administrator, a
+critic included.
+
+A token of role `critic` (`ATLAS_CRITIC_TOKEN`, or `role: "critic"` under `auth.tokens`) may do what `read` may, and
+publish critiques, and nothing else. Through the store protocol (`PUT /api/store/…`) it may upload blobs and layers, and
+the catalog entries that make them visible, whose `producer` is `critic.<name>` and whose parts are all of kind
+`critique`. Anything else is `403` naming the rule it broke, and the layer is not stored. It cannot post test results,
+start live runs, change settings or remove anything. `publish` and `admin` tokens may publish critiques too. As for every
+token: send it as `Authorization: Bearer`, never in a URL, never over plain `http` beyond this machine.
+
+## Credentials
+
+Developers bring their own models and AI accounts. Configuration names a credential by **reference**
+(`env:SOME_API_KEY`, `file:/run/secrets/key`) and never contains one, so it can be committed;
+`assertNoLiteralCredentials` refuses a configuration with a literal key and says where, never what. Credentials are read at
+run time (`resolveCredential`) and every message the runner records goes through a redactor (`secrets` in `runCritic`,
+`createRedactor`) that removes them, in their URL-encoded and base64 forms too, and anything shaped like a provider key,
+token or JWT. A credential never reaches a layer, a progress event or an error message.
+
+## What is not here yet
+
+This release delivers the contract, the evidence format, the runner, state-aware judging and calibration, credential
+handling and the scoped `critic` role. Still to come, tracked in [issue 50](https://github.com/crvouga/atlas/issues/50):
+
+- the **catalog read surface** for critics (cursor pagination, `since`, realtime events, images by hash), which builds on
+  the UI catalog of [issue 43](https://github.com/crvouga/atlas/issues/43);
+- the **`atlas critic` command** (`list`, `setup`, `doctor`, `run`, `watch`, `review`, `calibrate`), its interactive mode
+  and its `--format json` documents;
+- the **built-in UIClip critic** and the **LLM critic** with provider adapters;
+- the **viewer**: a ranked "needs polish" list, finding overlays and agreement across critics. Until then critiques are
+  stored, composed and kept out of test counts, and the viewer lists only test results.

package/docs/extending.md

@@ -249,6 +249,7 @@ Annotation `type`: `note`, `warning`, `deprecation`, `issue`, `accessibility`, `
 | A kind of file Atlas has never seen | Attach it with its media type and a `role`. It is stored and offered for download today. |
 | Structured data of your own | Put it in `extensions` under a name you own. It is kept, and shown as raw data. |
 | A new annotation type, role or step kind | Use it. Open vocabularies need no registration. |
+| An automated reviewer's opinion of a captured UI | A [critique](critics.md): a part of kind `critique` with the `atlas.critique` extension. It is never counted and never gates. |
 | Something that should be shown well | Ask for a renderer (below). |
 | A field every tool should have | Open an issue. It is added as an optional field, and the rules above guarantee nothing breaks. |