@crvouga/atlas 1.12.0 → 1.14.0

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

@@ -55,6 +55,7 @@ export declare const ServerInfoSchema: z.ZodObject<{
     version: z.ZodNullable<z.ZodString>;
     role: z.ZodEnum<{
         read: "read";
+        critic: "critic";
         publish: "publish";
         admin: "admin";
     }>;
@@ -324,6 +325,26 @@ export declare const LayerRowSchema: z.ZodObject<{
             }, z.core.$loose>>;
         }, z.core.$loose>>>;
     }, z.core.$loose>>;
+    state: z.ZodOptional<z.ZodObject<{
+        route: z.ZodOptional<z.ZodString>;
+        fixture: z.ZodOptional<z.ZodString>;
+        cohort: z.ZodOptional<z.ZodString>;
+        area: z.ZodOptional<z.ZodString>;
+        flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        inventory: z.ZodOptional<z.ZodBoolean>;
+        screenshot: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            bundleKey: z.ZodOptional<z.ZodString>;
+            uri: z.ZodOptional<z.ZodString>;
+            contentType: z.ZodOptional<z.ZodString>;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            bytes: z.ZodOptional<z.ZodNumber>;
+            sha256: z.ZodOptional<z.ZodString>;
+            omitted: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
     recording: z.ZodOptional<z.ZodObject<{
         state: z.ZodString;
         reason: z.ZodOptional<z.ZodString>;
@@ -409,6 +430,26 @@ export declare const LayerRowsSchema: z.ZodObject<{
                 }, z.core.$loose>>;
             }, z.core.$loose>>>;
         }, z.core.$loose>>;
+        state: z.ZodOptional<z.ZodObject<{
+            route: z.ZodOptional<z.ZodString>;
+            fixture: z.ZodOptional<z.ZodString>;
+            cohort: z.ZodOptional<z.ZodString>;
+            area: z.ZodOptional<z.ZodString>;
+            flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            inventory: z.ZodOptional<z.ZodBoolean>;
+            screenshot: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                bundleKey: z.ZodOptional<z.ZodString>;
+                uri: z.ZodOptional<z.ZodString>;
+                contentType: z.ZodOptional<z.ZodString>;
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                bytes: z.ZodOptional<z.ZodNumber>;
+                sha256: z.ZodOptional<z.ZodString>;
+                omitted: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
         recording: z.ZodOptional<z.ZodObject<{
             state: z.ZodString;
             reason: z.ZodOptional<z.ZodString>;
@@ -496,6 +537,26 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
                 }, z.core.$loose>>;
             }, z.core.$loose>>>;
         }, z.core.$loose>>;
+        state: z.ZodOptional<z.ZodObject<{
+            route: z.ZodOptional<z.ZodString>;
+            fixture: z.ZodOptional<z.ZodString>;
+            cohort: z.ZodOptional<z.ZodString>;
+            area: z.ZodOptional<z.ZodString>;
+            flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            inventory: z.ZodOptional<z.ZodBoolean>;
+            screenshot: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                bundleKey: z.ZodOptional<z.ZodString>;
+                uri: z.ZodOptional<z.ZodString>;
+                contentType: z.ZodOptional<z.ZodString>;
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                bytes: z.ZodOptional<z.ZodNumber>;
+                sha256: z.ZodOptional<z.ZodString>;
+                omitted: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
         recording: z.ZodOptional<z.ZodObject<{
             state: z.ZodString;
             reason: z.ZodOptional<z.ZodString>;
@@ -673,6 +734,26 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                     }, z.core.$loose>>;
                 }, z.core.$loose>>>;
             }, z.core.$loose>>;
+            state: z.ZodOptional<z.ZodObject<{
+                route: z.ZodOptional<z.ZodString>;
+                fixture: z.ZodOptional<z.ZodString>;
+                cohort: z.ZodOptional<z.ZodString>;
+                area: z.ZodOptional<z.ZodString>;
+                flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                inventory: z.ZodOptional<z.ZodBoolean>;
+                screenshot: z.ZodOptional<z.ZodObject<{
+                    name: z.ZodString;
+                    bundleKey: z.ZodOptional<z.ZodString>;
+                    uri: z.ZodOptional<z.ZodString>;
+                    contentType: z.ZodOptional<z.ZodString>;
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    bytes: z.ZodOptional<z.ZodNumber>;
+                    sha256: z.ZodOptional<z.ZodString>;
+                    omitted: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+            }, z.core.$loose>>;
             recording: z.ZodOptional<z.ZodObject<{
                 state: z.ZodString;
                 reason: z.ZodOptional<z.ZodString>;
@@ -871,6 +952,26 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                     }, z.core.$loose>>;
                 }, z.core.$loose>>>;
             }, z.core.$loose>>;
+            state: z.ZodOptional<z.ZodObject<{
+                route: z.ZodOptional<z.ZodString>;
+                fixture: z.ZodOptional<z.ZodString>;
+                cohort: z.ZodOptional<z.ZodString>;
+                area: z.ZodOptional<z.ZodString>;
+                flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                inventory: z.ZodOptional<z.ZodBoolean>;
+                screenshot: z.ZodOptional<z.ZodObject<{
+                    name: z.ZodString;
+                    bundleKey: z.ZodOptional<z.ZodString>;
+                    uri: z.ZodOptional<z.ZodString>;
+                    contentType: z.ZodOptional<z.ZodString>;
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    bytes: z.ZodOptional<z.ZodNumber>;
+                    sha256: z.ZodOptional<z.ZodString>;
+                    omitted: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+            }, z.core.$loose>>;
             recording: z.ZodOptional<z.ZodObject<{
                 state: z.ZodString;
                 reason: z.ZodOptional<z.ZodString>;
@@ -3539,3 +3640,253 @@ export declare const RunDetailSchema: z.ZodObject<{
         }, z.core.$loose>>;
     }, z.core.$loose>>>;
 }, z.core.$loose>;
+/** A state's profile: the client and the choices it was captured under. */
+export declare const UiProfileSchema: z.ZodObject<{
+    key: z.ZodString;
+    environment: z.ZodNullable<z.ZodString>;
+    parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+    label: z.ZodString;
+}, z.core.$loose>;
+/** The picture of a capture. */
+export declare const UiImageSchema: z.ZodObject<{
+    name: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    bytes: z.ZodOptional<z.ZodNumber>;
+    sha256: z.ZodOptional<z.ZodString>;
+    bundleKey: z.ZodOptional<z.ZodString>;
+    uri: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    omitted: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** One state in one profile. */
+export declare const UiCellSchema: z.ZodObject<{
+    profile: z.ZodObject<{
+        key: z.ZodString;
+        environment: z.ZodNullable<z.ZodString>;
+        parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+        label: z.ZodString;
+    }, z.core.$loose>;
+    coverage: z.ZodEnum<{
+        failed: "failed";
+        skipped: "skipped";
+        missing: "missing";
+        captured: "captured";
+        capturing: "capturing";
+    }>;
+    expected: z.ZodEnum<{
+        unknown: "unknown";
+        declared: "declared";
+        undeclared: "undeclared";
+    }>;
+    capture: z.ZodNullable<z.ZodObject<{
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            running: "running";
+            "not-run": "not-run";
+        }>;
+        detail: z.ZodString;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+        image: z.ZodNullable<z.ZodObject<{
+            name: z.ZodString;
+            contentType: z.ZodOptional<z.ZodString>;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            bytes: z.ZodOptional<z.ZodNumber>;
+            sha256: z.ZodOptional<z.ZodString>;
+            bundleKey: z.ZodOptional<z.ZodString>;
+            uri: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            omitted: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        labels: z.ZodRecord<z.ZodString, z.ZodString>;
+        origin: z.ZodObject<{
+            layer: z.ZodString;
+            backend: z.ZodString;
+            producer: z.ZodString;
+            recordedAtMs: z.ZodNumber;
+            sha: z.ZodNullable<z.ZodString>;
+            branch: z.ZodNullable<z.ZodString>;
+            runUrl: z.ZodNullable<z.ZodString>;
+            freshness: z.ZodOptional<z.ZodEnum<{
+                unknown: "unknown";
+                modified: "modified";
+            }>>;
+        }, z.core.$loose>;
+        alternatives: z.ZodNumber;
+    }, z.core.$loose>>;
+    planned: z.ZodNullable<z.ZodObject<{
+        layer: z.ZodString;
+        backend: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/**
+ * `GET /api/reports/ui-catalog`: the UI catalog, computed from the winning results of the `ui-state` and `ui-plan` parts
+ * of every layer. States are in id order and cells in profile order, so the same layers always give the same document.
+ */
+export declare const UiCatalogSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    version: z.ZodOptional<z.ZodString>;
+    summary: z.ZodObject<{
+        states: z.ZodNumber;
+        profiles: z.ZodNumber;
+        cells: z.ZodNumber;
+        coverage: z.ZodObject<{
+            captured: z.ZodNumber;
+            failed: z.ZodNumber;
+            capturing: z.ZodNumber;
+            skipped: z.ZodNumber;
+            missing: z.ZodNumber;
+        }, z.core.$loose>;
+        undeclared: z.ZodNumber;
+        planned: z.ZodBoolean;
+        surfaces: z.ZodNumber;
+        uncoveredSurfaces: z.ZodNumber;
+    }, z.core.$loose>;
+    profiles: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        environment: z.ZodNullable<z.ZodString>;
+        parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+        label: z.ZodString;
+    }, z.core.$loose>>;
+    states: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        route: z.ZodNullable<z.ZodString>;
+        fixture: z.ZodNullable<z.ZodString>;
+        cohort: z.ZodNullable<z.ZodString>;
+        area: z.ZodNullable<z.ZodString>;
+        flags: z.ZodArray<z.ZodString>;
+        covers: z.ZodArray<z.ZodString>;
+        producers: z.ZodArray<z.ZodString>;
+        cells: z.ZodArray<z.ZodObject<{
+            profile: z.ZodObject<{
+                key: z.ZodString;
+                environment: z.ZodNullable<z.ZodString>;
+                parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+                label: z.ZodString;
+            }, z.core.$loose>;
+            coverage: z.ZodEnum<{
+                failed: "failed";
+                skipped: "skipped";
+                missing: "missing";
+                captured: "captured";
+                capturing: "capturing";
+            }>;
+            expected: z.ZodEnum<{
+                unknown: "unknown";
+                declared: "declared";
+                undeclared: "undeclared";
+            }>;
+            capture: z.ZodNullable<z.ZodObject<{
+                status: z.ZodEnum<{
+                    passed: "passed";
+                    failed: "failed";
+                    running: "running";
+                    "not-run": "not-run";
+                }>;
+                detail: z.ZodString;
+                durationMs: z.ZodNullable<z.ZodNumber>;
+                image: z.ZodNullable<z.ZodObject<{
+                    name: z.ZodString;
+                    contentType: z.ZodOptional<z.ZodString>;
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    bytes: z.ZodOptional<z.ZodNumber>;
+                    sha256: z.ZodOptional<z.ZodString>;
+                    bundleKey: z.ZodOptional<z.ZodString>;
+                    uri: z.ZodOptional<z.ZodString>;
+                    path: z.ZodOptional<z.ZodString>;
+                    omitted: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+                labels: z.ZodRecord<z.ZodString, z.ZodString>;
+                origin: z.ZodObject<{
+                    layer: z.ZodString;
+                    backend: z.ZodString;
+                    producer: z.ZodString;
+                    recordedAtMs: z.ZodNumber;
+                    sha: z.ZodNullable<z.ZodString>;
+                    branch: z.ZodNullable<z.ZodString>;
+                    runUrl: z.ZodNullable<z.ZodString>;
+                    freshness: z.ZodOptional<z.ZodEnum<{
+                        unknown: "unknown";
+                        modified: "modified";
+                    }>>;
+                }, z.core.$loose>;
+                alternatives: z.ZodNumber;
+            }, z.core.$loose>>;
+            planned: z.ZodNullable<z.ZodObject<{
+                layer: z.ZodString;
+                backend: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    surfaces: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        inventoried: z.ZodBoolean;
+        states: z.ZodNumber;
+        captured: z.ZodNumber;
+        status: z.ZodEnum<{
+            covered: "covered";
+            uncaptured: "uncaptured";
+            uncovered: "uncovered";
+        }>;
+    }, z.core.$loose>>;
+    facets: z.ZodObject<{
+        profiles: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        coverage: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        areas: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        routes: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        cohorts: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        flags: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        surfaces: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        producers: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    sources: z.ZodObject<{
+        layers: z.ZodNumber;
+        backends: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            live: z.ZodBoolean;
+            available: z.ZodBoolean;
+        }, z.core.$loose>>;
+        notices: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    total: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;

package/dist/schema/src/api.js

@@ -44,7 +44,7 @@ export const ReadySchema = z.looseObject({
 export const ServerInfoSchema = z.looseObject({
     name: z.literal('atlas'),
     version: z.string().nullable().describe('The @crvouga/atlas version the server runs, or null when it does not know'),
-    role: z.enum(['read', 'publish', 'admin']).describe('What the token of this request may do. A server with no tokens treats everyone as admin'),
+    role: z.enum(['read', 'critic', 'publish', 'admin']).describe('What the token of this request may do. A server with no tokens treats everyone as admin'),
     open: z.boolean().describe('True when the server has no tokens at all'),
     write: z.string().describe('The id of the backend uploads go to'),
     ready: z.boolean(),
@@ -130,6 +130,16 @@ export const LayerRowSchema = z.looseObject({
     variant: z.record(z.string(), z.string()),
     durationMs: z.number().nullable(),
     evidence: EvidenceSummarySchema.optional(),
+    state: z.looseObject({
+        route: z.string().optional(), fixture: z.string().optional(), cohort: z.string().optional(), area: z.string().optional(),
+        flags: z.array(z.string()).optional(), covers: z.array(z.string()).optional(),
+        inventory: z.boolean().optional().describe('A `ui-plan` entry that names a surface of the product\'s inventory, not a state'),
+        screenshot: z.looseObject({
+            name: z.string(), bundleKey: z.string().optional(), uri: z.string().optional(), contentType: z.string().optional(),
+            width: z.number().optional(), height: z.number().optional(), bytes: z.number().optional(), sha256: z.string().optional(),
+            omitted: z.string().optional().describe('Why the producer left the bytes out')
+        }).optional().describe('The check\'s picture: its `screenshot` attachment, else its first image')
+    }).optional().describe('Only for a check of a `ui-state` or `ui-plan` part: its picture and the facts its producer declared under the `atlas.ui-state` extension. See the UI catalog guide. Never decides a result'),
     recording: z.looseObject({ state: z.string(), reason: z.string().optional() }).optional().describe('What became of the check\'s expected recording: uploaded, referenced, skipped, unresolved or not-applicable. Independent of `status`')
 });
 /** A layer with its checks: the rows of one layer, read apart from its header. */
@@ -671,3 +681,64 @@ export const RunDetailSchema = z.looseObject({
         videos: VideoCountsSchema.optional()
     })).optional().describe('Every layer of the run, oldest first. Absent from an older server')
 });
+/** A state's profile: the client and the choices it was captured under. */
+export const UiProfileSchema = z.looseObject({
+    key: z.string().describe('Identifies the profile across layers: the environment and the sorted parameters'),
+    environment: z.string().nullable(), parameters: z.record(z.string(), z.string()),
+    label: z.string().describe('For a person: the client and each parameter\'s value')
+});
+/** The picture of a capture. */
+export const UiImageSchema = z.looseObject({
+    name: z.string(), contentType: z.string().optional(), width: z.number().optional(), height: z.number().optional(), bytes: z.number().optional(), sha256: z.string().optional(),
+    bundleKey: z.string().optional(), uri: z.string().optional().describe('An http(s) address, when the picture lives elsewhere'),
+    path: z.string().optional().describe('Where the stored bytes are, relative to the reports API root (`/api/reports` on a server): `/layers/<layer>/blobs/attachments/<sha256>`'),
+    omitted: z.string().optional().describe('Why the producer left the bytes out. A picture that is left out is not a picture that was never taken')
+});
+/** One state in one profile. */
+export const UiCellSchema = z.looseObject({
+    profile: UiProfileSchema,
+    coverage: z.enum(['captured', 'failed', 'capturing', 'skipped', 'missing']).describe('`captured` only when the winning capture passed. Every other value means there is no picture to trust'),
+    expected: z.enum(['declared', 'undeclared', 'unknown']).describe('`declared`: a plan expects it. `undeclared`: plans exist and none names it. `unknown`: no plan was published, so nothing is known to be unexpected'),
+    capture: z.looseObject({
+        status: EvidenceStatusSchema, detail: z.string(), durationMs: z.number().nullable(), image: UiImageSchema.nullable(),
+        labels: z.record(z.string(), z.string()).describe('What describes the capture without splitting it: a `shard`, a `browser`'),
+        origin: z.looseObject({
+            layer: z.string(), backend: z.string(), producer: z.string(), recordedAtMs: z.number(), sha: z.string().nullable(), branch: z.string().nullable(), runUrl: z.string().nullable(),
+            freshness: z.enum(['unknown', 'modified']).optional()
+        }),
+        alternatives: z.number().int().nonnegative().describe('Other captures of this cell from other producers; the winner is the one the report contract picks')
+    }).nullable(),
+    planned: z.looseObject({ layer: z.string(), backend: z.string() }).nullable().describe('The plan layer that expects this cell')
+});
+const UiFacetSchema = z.array(z.looseObject({ value: z.string(), count: z.number().int().nonnegative(), label: z.string().optional() }));
+/**
+ * `GET /api/reports/ui-catalog`: the UI catalog, computed from the winning results of the `ui-state` and `ui-plan` parts
+ * of every layer. States are in id order and cells in profile order, so the same layers always give the same document.
+ */
+export const UiCatalogSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    version: z.string().optional().describe('The report version this was computed from; equal exactly when the report is'),
+    summary: z.looseObject({
+        states: z.number().int().nonnegative(), profiles: z.number().int().nonnegative(), cells: z.number().int().nonnegative(),
+        coverage: z.looseObject({ captured: z.number(), failed: z.number(), capturing: z.number(), skipped: z.number(), missing: z.number() }),
+        undeclared: z.number().int().nonnegative().describe('Cells captured or failed that no plan expects. Zero when no plan was published'),
+        planned: z.boolean().describe('Whether any plan was published. Without one `missing` is always zero: what should exist is unknown'),
+        surfaces: z.number().int().nonnegative(), uncoveredSurfaces: z.number().int().nonnegative()
+    }),
+    profiles: z.array(UiProfileSchema),
+    states: z.array(z.looseObject({
+        id: z.string(), title: z.string(),
+        route: z.string().nullable(), fixture: z.string().nullable(), cohort: z.string().nullable(), area: z.string().nullable(),
+        flags: z.array(z.string()), covers: z.array(z.string()).describe('The surfaces it covers'), producers: z.array(z.string()),
+        cells: z.array(UiCellSchema)
+    })),
+    surfaces: z.array(z.looseObject({
+        id: z.string(), inventoried: z.boolean().describe('A `ui-plan` inventory entry names it: the product is known to have it'),
+        states: z.number().int().nonnegative(), captured: z.number().int().nonnegative(),
+        status: z.enum(['covered', 'uncaptured', 'uncovered'])
+    })),
+    facets: z.looseObject({ profiles: UiFacetSchema, coverage: UiFacetSchema, areas: UiFacetSchema, routes: UiFacetSchema, cohorts: UiFacetSchema, flags: UiFacetSchema, surfaces: UiFacetSchema, producers: UiFacetSchema }),
+    sources: z.looseObject({ layers: z.number().int().nonnegative(), backends: z.array(BackendInfoSchema), notices: z.array(z.string()) }).describe('What was read. A backend that is unavailable, or a layer that could not be read, is named here; what depended on it is not shown as captured'),
+    total: z.number().int().nonnegative().optional().describe('States that matched, before `offset` and `limit`'),
+    offset: z.number().int().nonnegative().optional(), limit: z.number().int().nonnegative().optional()
+});

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

@@ -0,0 +1,144 @@
+/**
+ * @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 declare 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 declare 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 declare const CRITIQUE_PART_KIND = "critique";
+/** The prefix of the `producer` of a layer of critiques: `critic.<critic name>`. */
+export declare 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 declare const CritiqueRegionSchema: z.ZodObject<{
+    unit: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    w: z.ZodNumber;
+    h: z.ZodNumber;
+}, z.core.$loose>;
+/** One thing a critic found: where, what kind, how bad, why, and what to do. Nothing is required. */
+export declare const CritiqueFindingSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    region: z.ZodOptional<z.ZodObject<{
+        unit: z.ZodString;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, z.core.$loose>>;
+    rationale: z.ZodOptional<z.ZodString>;
+    suggestion: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * 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 declare const CritiqueRelativeSchema: z.ZodObject<{
+    stateKind: z.ZodString;
+    percentile: z.ZodOptional<z.ZodNumber>;
+    sampleSize: z.ZodOptional<z.ZodNumber>;
+    previousScore: z.ZodOptional<z.ZodNumber>;
+    delta: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+/** The judgement: a score and how to read it, a label, a confidence. A critic that cannot score may give only a label. */
+export declare const CritiqueVerdictSchema: z.ZodObject<{
+    score: z.ZodOptional<z.ZodNumber>;
+    scale: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    relative: z.ZodOptional<z.ZodObject<{
+        stateKind: z.ZodString;
+        percentile: z.ZodOptional<z.ZodNumber>;
+        sampleSize: z.ZodOptional<z.ZodNumber>;
+        previousScore: z.ZodOptional<z.ZodNumber>;
+        delta: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** 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 declare const CritiqueFailureSchema: z.ZodObject<{
+    reason: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * 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 declare const CritiqueSchema: z.ZodObject<{
+    schema: z.ZodNumber;
+    subject: z.ZodObject<{
+        entryKey: z.ZodString;
+        imageSha256: z.ZodString;
+        state: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    critic: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        kind: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    model: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        provider: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    verdict: z.ZodOptional<z.ZodObject<{
+        score: z.ZodOptional<z.ZodNumber>;
+        scale: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+        relative: z.ZodOptional<z.ZodObject<{
+            stateKind: z.ZodString;
+            percentile: z.ZodOptional<z.ZodNumber>;
+            sampleSize: z.ZodOptional<z.ZodNumber>;
+            previousScore: z.ZodOptional<z.ZodNumber>;
+            delta: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        severity: z.ZodOptional<z.ZodString>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+        region: z.ZodOptional<z.ZodObject<{
+            unit: z.ZodString;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            w: z.ZodNumber;
+            h: z.ZodNumber;
+        }, z.core.$loose>>;
+        rationale: z.ZodOptional<z.ZodString>;
+        suggestion: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    failure: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        latencyMs: z.ZodOptional<z.ZodNumber>;
+        costUsd: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** A critique as stored in a check's `extensions["atlas.critique"]`. */
+export type Critique = z.output<typeof CritiqueSchema>;
+/** One finding of a critique. */
+export type CritiqueFinding = z.output<typeof CritiqueFindingSchema>;