@crvouga/atlas 1.19.0 → 1.21.0

package/dist/schema/src/cli-results.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module Command results (`--format json`)
  *
- * What `atlas report publish`, `stream`, `merge`, `doctor` and `verify-recordings` print on standard output with `--format json` (alias
+ * What `atlas report publish`, `stream`, `merge`, `doctor` and `verify-recordings`, and `atlas ui-catalog plan`, `publish`, `status`, `diff` and `export`, print on standard output with `--format json` (alias
  * `--json`), and what any `atlas` command prints on standard error for a command that was wrong: one JSON document,
  * so an agent or a script never has to parse prose. (`status` and `policy` already print documents:
  * `ReportStatusSchema`, and an IAM policy.) Each is also published as a JSON Schema.
@@ -289,6 +289,153 @@ export declare const InitPlanSchema: z.ZodObject<{
     nextSteps: z.ZodArray<z.ZodString>;
     warnings: z.ZodArray<z.ZodString>;
 }, z.core.$loose>;
+/** What `atlas ui-catalog plan --format json` and `atlas ui-catalog publish --format json` print: the one layer that was written. */
+export declare const UiCatalogPublishResultSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    store: z.ZodString;
+    layer: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            "ui-state": "ui-state";
+            "ui-plan": "ui-plan";
+        }>;
+        producer: z.ZodString;
+        environment: z.ZodNullable<z.ZodString>;
+        parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+        states: z.ZodNumber;
+        captured: z.ZodNumber;
+        failed: z.ZodNumber;
+        pictures: z.ZodNumber;
+        pictureBytes: z.ZodNumber;
+        shard: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+/** One thing that keeps a UI catalog from being complete and good. */
+export declare const UiCatalogProblemSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        failed: "failed";
+        missing: "missing";
+        unavailable: "unavailable";
+        capturing: "capturing";
+        unreadable: "unreadable";
+        empty: "empty";
+    }>;
+    state: z.ZodOptional<z.ZodString>;
+    profile: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** What `atlas ui-catalog status --format json` prints. */
+export declare const UiCatalogStatusSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    summary: z.ZodObject<{
+        states: z.ZodNumber;
+        profiles: z.ZodNumber;
+        cells: z.ZodNumber;
+        coverage: z.ZodRecord<z.ZodEnum<{
+            failed: "failed";
+            skipped: "skipped";
+            missing: "missing";
+            captured: "captured";
+            capturing: "capturing";
+        }>, z.ZodNumber>;
+        undeclared: z.ZodNumber;
+        planned: z.ZodBoolean;
+        surfaces: z.ZodNumber;
+        uncoveredSurfaces: z.ZodNumber;
+    }, z.core.$loose>;
+    profiles: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$loose>>;
+    problems: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            failed: "failed";
+            missing: "missing";
+            unavailable: "unavailable";
+            capturing: "capturing";
+            unreadable: "unreadable";
+            empty: "empty";
+        }>;
+        state: z.ZodOptional<z.ZodString>;
+        profile: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    sources: z.ZodObject<{
+        layers: z.ZodNumber;
+        backends: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            available: z.ZodBoolean;
+        }, z.core.$loose>>;
+        notices: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+/** What `atlas ui-catalog diff --format json` prints. */
+export declare const UiCatalogDiffResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    from: z.ZodObject<{
+        sha: z.ZodString;
+        states: z.ZodNumber;
+        layers: z.ZodNumber;
+    }, z.core.$loose>;
+    to: z.ZodObject<{
+        sha: z.ZodString;
+        states: z.ZodNumber;
+        layers: z.ZodNumber;
+    }, z.core.$loose>;
+    summary: z.ZodObject<{
+        coverage: z.ZodNumber;
+        picture: z.ZodNumber;
+        unverified: z.ZodNumber;
+        added: z.ZodNumber;
+        removed: z.ZodNumber;
+        unchanged: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$loose>;
+    changes: z.ZodArray<z.ZodObject<{
+        state: z.ZodString;
+        title: z.ZodString;
+        profile: z.ZodString;
+        change: z.ZodEnum<{
+            coverage: "coverage";
+            removed: "removed";
+            unverified: "unverified";
+            added: "added";
+            picture: "picture";
+        }>;
+        from: z.ZodNullable<z.ZodEnum<{
+            failed: "failed";
+            skipped: "skipped";
+            missing: "missing";
+            captured: "captured";
+            capturing: "capturing";
+        }>>;
+        to: z.ZodNullable<z.ZodEnum<{
+            failed: "failed";
+            skipped: "skipped";
+            missing: "missing";
+            captured: "captured";
+            capturing: "capturing";
+        }>>;
+    }, z.core.$loose>>;
+    notices: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+/** What `atlas ui-catalog export --format json` prints. */
+export declare const UiCatalogExportResultSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    out: z.ZodString;
+    bytes: z.ZodNumber;
+    states: z.ZodNumber;
+    cells: z.ZodNumber;
+    pictures: z.ZodObject<{
+        embedded: z.ZodNumber;
+        embeddedBytes: z.ZodNumber;
+        left: z.ZodNumber;
+    }, z.core.$loose>;
+    manifest: z.ZodNullable<z.ZodString>;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
 /**
  * JSON command contracts, shared by schema publication, agent documentation and executable command checks.
  * A new result needs an entry here and a runtime scenario in the documentation contract tests.
@@ -582,6 +729,176 @@ export declare const CLI_RESULTS: {
             notices: z.ZodArray<z.ZodString>;
         }, z.core.$loose>;
     };
+    readonly uiCatalogPlan: {
+        readonly command: "atlas ui-catalog plan";
+        readonly schemaName: "ui-catalog-publish-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+            store: z.ZodString;
+            layer: z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    "ui-state": "ui-state";
+                    "ui-plan": "ui-plan";
+                }>;
+                producer: z.ZodString;
+                environment: z.ZodNullable<z.ZodString>;
+                parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+                states: z.ZodNumber;
+                captured: z.ZodNumber;
+                failed: z.ZodNumber;
+                pictures: z.ZodNumber;
+                pictureBytes: z.ZodNumber;
+                shard: z.ZodNullable<z.ZodString>;
+            }, z.core.$loose>;
+            warnings: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    };
+    readonly uiCatalogPublish: {
+        readonly command: "atlas ui-catalog publish";
+        readonly schemaName: "ui-catalog-publish-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+            store: z.ZodString;
+            layer: z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    "ui-state": "ui-state";
+                    "ui-plan": "ui-plan";
+                }>;
+                producer: z.ZodString;
+                environment: z.ZodNullable<z.ZodString>;
+                parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+                states: z.ZodNumber;
+                captured: z.ZodNumber;
+                failed: z.ZodNumber;
+                pictures: z.ZodNumber;
+                pictureBytes: z.ZodNumber;
+                shard: z.ZodNullable<z.ZodString>;
+            }, z.core.$loose>;
+            warnings: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    };
+    readonly uiCatalogStatus: {
+        readonly command: "atlas ui-catalog status";
+        readonly schemaName: "ui-catalog-status";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodBoolean;
+            summary: z.ZodObject<{
+                states: z.ZodNumber;
+                profiles: z.ZodNumber;
+                cells: z.ZodNumber;
+                coverage: z.ZodRecord<z.ZodEnum<{
+                    failed: "failed";
+                    skipped: "skipped";
+                    missing: "missing";
+                    captured: "captured";
+                    capturing: "capturing";
+                }>, z.ZodNumber>;
+                undeclared: z.ZodNumber;
+                planned: z.ZodBoolean;
+                surfaces: z.ZodNumber;
+                uncoveredSurfaces: z.ZodNumber;
+            }, z.core.$loose>;
+            profiles: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$loose>>;
+            problems: z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    failed: "failed";
+                    missing: "missing";
+                    unavailable: "unavailable";
+                    capturing: "capturing";
+                    unreadable: "unreadable";
+                    empty: "empty";
+                }>;
+                state: z.ZodOptional<z.ZodString>;
+                profile: z.ZodOptional<z.ZodString>;
+                detail: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            sources: z.ZodObject<{
+                layers: z.ZodNumber;
+                backends: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    label: z.ZodString;
+                    available: z.ZodBoolean;
+                }, z.core.$loose>>;
+                notices: z.ZodArray<z.ZodString>;
+            }, z.core.$loose>;
+        }, z.core.$loose>;
+    };
+    readonly uiCatalogDiff: {
+        readonly command: "atlas ui-catalog diff";
+        readonly schemaName: "ui-catalog-diff-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodBoolean;
+            from: z.ZodObject<{
+                sha: z.ZodString;
+                states: z.ZodNumber;
+                layers: z.ZodNumber;
+            }, z.core.$loose>;
+            to: z.ZodObject<{
+                sha: z.ZodString;
+                states: z.ZodNumber;
+                layers: z.ZodNumber;
+            }, z.core.$loose>;
+            summary: z.ZodObject<{
+                coverage: z.ZodNumber;
+                picture: z.ZodNumber;
+                unverified: z.ZodNumber;
+                added: z.ZodNumber;
+                removed: z.ZodNumber;
+                unchanged: z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$loose>;
+            changes: z.ZodArray<z.ZodObject<{
+                state: z.ZodString;
+                title: z.ZodString;
+                profile: z.ZodString;
+                change: z.ZodEnum<{
+                    coverage: "coverage";
+                    removed: "removed";
+                    unverified: "unverified";
+                    added: "added";
+                    picture: "picture";
+                }>;
+                from: z.ZodNullable<z.ZodEnum<{
+                    failed: "failed";
+                    skipped: "skipped";
+                    missing: "missing";
+                    captured: "captured";
+                    capturing: "capturing";
+                }>>;
+                to: z.ZodNullable<z.ZodEnum<{
+                    failed: "failed";
+                    skipped: "skipped";
+                    missing: "missing";
+                    captured: "captured";
+                    capturing: "capturing";
+                }>>;
+            }, z.core.$loose>>;
+            notices: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    };
+    readonly uiCatalogExport: {
+        readonly command: "atlas ui-catalog export";
+        readonly schemaName: "ui-catalog-export-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+            out: z.ZodString;
+            bytes: z.ZodNumber;
+            states: z.ZodNumber;
+            cells: z.ZodNumber;
+            pictures: z.ZodObject<{
+                embedded: z.ZodNumber;
+                embeddedBytes: z.ZodNumber;
+                left: z.ZodNumber;
+            }, z.core.$loose>;
+            manifest: z.ZodNullable<z.ZodString>;
+            warnings: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    };
     readonly error: {
         readonly command: "a command that was wrong (standard error)";
         readonly schemaName: "command-error";

package/dist/schema/src/cli-results.js

@@ -1,7 +1,7 @@
 /**
  * @module Command results (`--format json`)
  *
- * What `atlas report publish`, `stream`, `merge`, `doctor` and `verify-recordings` print on standard output with `--format json` (alias
+ * What `atlas report publish`, `stream`, `merge`, `doctor` and `verify-recordings`, and `atlas ui-catalog plan`, `publish`, `status`, `diff` and `export`, print on standard output with `--format json` (alias
  * `--json`), and what any `atlas` command prints on standard error for a command that was wrong: one JSON document,
  * so an agent or a script never has to parse prose. (`status` and `policy` already print documents:
  * `ReportStatusSchema`, and an IAM policy.) Each is also published as a JSON Schema.
@@ -154,6 +154,89 @@ export const InitPlanSchema = z.looseObject({
     nextSteps: z.array(z.string()).describe('What to do next, in order, as plain instructions an agent can follow'),
     warnings: z.array(z.string())
 });
+/** The coverage of one state in one profile, as the UI catalog words it. */
+const UiCoverageSchema = z.enum(['captured', 'failed', 'capturing', 'skipped', 'missing']);
+/** What `atlas ui-catalog plan --format json` and `atlas ui-catalog publish --format json` print: the one layer that was written. */
+export const UiCatalogPublishResultSchema = z.looseObject({
+    ok: z.literal(true).describe('True: the layer was written. A state whose picture could not be read is published as `failed` and named in `warnings`; it does not fail the command'),
+    store: z.string().describe('Where it was written: a folder, `s3://…` or a server URL'),
+    layer: z.looseObject({
+        id: z.string().describe('The layer id: 64 hex digits, the SHA-256 of its content. Publishing the same input again gives the same id'),
+        kind: z.enum(['ui-state', 'ui-plan']).describe('`ui-state`: captures (`publish`). `ui-plan`: the expected set (`plan`)'),
+        producer: z.string(),
+        environment: z.string().nullable(),
+        parameters: z.record(z.string(), z.string()).describe('The rest of the profile, such as `{ "viewport": "390x844" }`'),
+        states: z.number().int().nonnegative().describe('States in the layer'),
+        captured: z.number().int().nonnegative().describe('For `publish`: states that were captured (`passed`). Zero for a plan'),
+        failed: z.number().int().nonnegative().describe('For `publish`: states recorded as failed, including those whose picture could not be read'),
+        pictures: z.number().int().nonnegative().describe('Pictures stored in the layer'),
+        pictureBytes: z.number().int().nonnegative(),
+        shard: z.string().nullable().describe('The `--shard` label, which describes the layer and never splits its slot')
+    }),
+    warnings: z.array(z.string()).describe('What was skipped and why, such as a picture file that could not be read. Never fatal')
+});
+/** One thing that keeps a UI catalog from being complete and good. */
+export const UiCatalogProblemSchema = z.looseObject({
+    kind: z.enum(['failed', 'missing', 'capturing', 'unavailable', 'unreadable', 'empty']).describe('`failed`: a capture was attempted and failed. `missing`: a plan expects it and nothing was captured. `capturing`: still being taken, so not known. `unavailable`: a backend could not be read. `unreadable`: a layer could not be read. `empty`: the catalog holds no state at all'),
+    state: z.string().optional().describe('The state id, for `failed`, `missing` and `capturing`'),
+    profile: z.string().optional().describe('The profile label, for `failed`, `missing` and `capturing`'),
+    detail: z.string().optional().describe('Why, when the producer said')
+});
+/** What `atlas ui-catalog status --format json` prints. */
+export const UiCatalogStatusSchema = z.looseObject({
+    ok: z.boolean().describe('True only when the catalog holds a state and has no problem: nothing failed, nothing expected is missing, nothing is still being captured, and every backend and layer was read (otherwise the exit code is 1). Skipped cells are counted, not problems'),
+    summary: z.looseObject({
+        states: z.number().int().nonnegative(),
+        profiles: z.number().int().nonnegative(),
+        cells: z.number().int().nonnegative().describe('States counted once per profile'),
+        coverage: z.record(UiCoverageSchema, z.number().int().nonnegative()).describe('Cells by coverage'),
+        undeclared: z.number().int().nonnegative().describe('Captured cells no plan expects; zero when no plan exists'),
+        planned: z.boolean().describe('Whether any plan was published. Without one, `missing` is always zero because what should exist is unknown'),
+        surfaces: z.number().int().nonnegative(),
+        uncoveredSurfaces: z.number().int().nonnegative()
+    }),
+    profiles: z.array(z.looseObject({ key: z.string(), label: z.string() })),
+    problems: z.array(UiCatalogProblemSchema),
+    sources: z.looseObject({ layers: z.number().int().nonnegative(), backends: z.array(z.looseObject({ id: z.string(), label: z.string(), available: z.boolean() })), notices: z.array(z.string()) })
+});
+/** One side of `atlas ui-catalog diff`. */
+const UiCatalogCommitSchema = z.looseObject({ sha: z.string(), states: z.number().int().nonnegative(), layers: z.number().int().nonnegative() });
+/** What `atlas ui-catalog diff --format json` prints. */
+export const UiCatalogDiffResultSchema = z.looseObject({
+    ok: z.boolean().describe('False when a layer or backend could not be read (the comparison may be wrong), or, with `--fail-on-change`, when anything differs. Otherwise true: a difference is not a failure by itself'),
+    from: UiCatalogCommitSchema,
+    to: UiCatalogCommitSchema,
+    summary: z.looseObject({
+        coverage: z.number().int().nonnegative().describe('Pairs that stand differently (captured against failed, for example)'),
+        picture: z.number().int().nonnegative().describe('Both captured, and the stored bytes differ. Not a measure of how many pixels'),
+        unverified: z.number().int().nonnegative().describe('Both captured, but a side has no content hash, so whether the picture changed is unknown'),
+        added: z.number().int().nonnegative().describe('Only `to` has it'),
+        removed: z.number().int().nonnegative().describe('Only `from` has it. Not a regression: the other side may not have run it'),
+        unchanged: z.number().int().nonnegative(),
+        total: z.number().int().nonnegative()
+    }),
+    changes: z.array(z.looseObject({
+        state: z.string(), title: z.string(), profile: z.string(),
+        change: z.enum(['coverage', 'picture', 'unverified', 'added', 'removed']),
+        from: UiCoverageSchema.nullable(), to: UiCoverageSchema.nullable()
+    })).describe('Every pair that is not unchanged'),
+    notices: z.array(z.string()).describe('What could not be read. Any makes `ok` false: an unreadable layer is unknown, never unchanged')
+});
+/** What `atlas ui-catalog export --format json` prints. */
+export const UiCatalogExportResultSchema = z.looseObject({
+    ok: z.literal(true),
+    out: z.string().describe('The HTML file that was written'),
+    bytes: z.number().int().nonnegative().describe('Its size'),
+    states: z.number().int().nonnegative(),
+    cells: z.number().int().nonnegative(),
+    pictures: z.looseObject({
+        embedded: z.number().int().nonnegative(),
+        embeddedBytes: z.number().int().nonnegative(),
+        left: z.number().int().nonnegative().describe('Pictures not embedded (over the size limit, not stored, not an image, or `--images none`); each is listed on the page with the reason')
+    }),
+    manifest: z.string().nullable().describe('The JSON manifest written beside it with `--manifest`, or null'),
+    warnings: z.array(z.string()).describe('Backends and layers that could not be read, and pictures left out. The page says so too')
+});
 /**
  * JSON command contracts, shared by schema publication, agent documentation and executable command checks.
  * A new result needs an entry here and a runtime scenario in the documentation contract tests.
@@ -166,5 +249,10 @@ export const CLI_RESULTS = {
     doctor: { command: 'atlas report doctor', schemaName: 'doctor-result', schema: DoctorResultSchema },
     status: { command: 'atlas report status', schemaName: 'report-status', schema: ReportStatusSchema },
     verifyRecordings: { command: 'atlas report verify-recordings', schemaName: 'verify-recordings-result', schema: VerifyRecordingsResultSchema },
+    uiCatalogPlan: { command: 'atlas ui-catalog plan', schemaName: 'ui-catalog-publish-result', schema: UiCatalogPublishResultSchema },
+    uiCatalogPublish: { command: 'atlas ui-catalog publish', schemaName: 'ui-catalog-publish-result', schema: UiCatalogPublishResultSchema },
+    uiCatalogStatus: { command: 'atlas ui-catalog status', schemaName: 'ui-catalog-status', schema: UiCatalogStatusSchema },
+    uiCatalogDiff: { command: 'atlas ui-catalog diff', schemaName: 'ui-catalog-diff-result', schema: UiCatalogDiffResultSchema },
+    uiCatalogExport: { command: 'atlas ui-catalog export', schemaName: 'ui-catalog-export-result', schema: UiCatalogExportResultSchema },
     error: { command: 'a command that was wrong (standard error)', schemaName: 'command-error', schema: CommandErrorSchema }
 };

package/dist/server/src/app.js

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

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

@@ -1,5 +1,5 @@
 /** 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.6.0";
+export declare const API_VERSION = "1.7.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>;

package/dist/server/src/openapi.js

@@ -14,10 +14,10 @@
  */
 import { z } from 'zod/v4';
 import { ProjectsSchema } from '../../schema/src/project.js';
-import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, UiCatalogSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema, ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewCollectionListSchema, ReviewCollectionDetailSchema, ReviewNoteInputSchema, ReviewNoteSchema, ReviewManifestSchema } from '../../schema/src/api.js';
+import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, UiCatalogSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema, ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewCollectionListSchema, ReviewCollectionDetailSchema, ReviewNoteInputSchema, ReviewNoteSchema, ReviewManifestSchema, RecordingVerificationSchema, RecordingVerifyRequestSchema } 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.6.0';
+export const API_VERSION = '1.7.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 });
@@ -38,6 +38,7 @@ const COMPONENTS = {
     Outline: [OutlineSchema, 'output'], EvidencePage: [EvidencePageSchema, 'output'], LayerRows: [LayerRowsSchema, 'output'], CheckDetail: [CheckDetailSchema, 'output'],
     ArtifactTagEdit: [ArtifactTagEditSchema, 'input'], ArtifactTagEntry: [ArtifactTagEntrySchema, 'output'], ArtifactTags: [ArtifactTagsSchema, 'output'],
     ReviewCollectionRequest: [ReviewCollectionRequestSchema, 'input'], ReviewCollection: [ReviewCollectionSchema, 'output'], ReviewCollectionList: [ReviewCollectionListSchema, 'output'], ReviewCollectionDetail: [ReviewCollectionDetailSchema, 'output'], ReviewNoteInput: [ReviewNoteInputSchema, 'input'], ReviewNote: [ReviewNoteSchema, 'output'], ReviewManifest: [ReviewManifestSchema, 'output'],
+    RecordingVerification: [RecordingVerificationSchema, 'output'], RecordingVerifyRequest: [RecordingVerifyRequestSchema, 'input'],
     TestCatalog: [TestCatalogSchema, 'output'], CatalogHealth: [CatalogHealthSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], TestReliability: [TestReliabilitySchema, 'output'], RunList: [RunListSchema, 'output'], ArtifactList: [ArtifactListSchema, 'output'], UiCatalog: [UiCatalogSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
     SpecIndex: [SpecIndexSchema, 'output'], ReportSources: [ReportSourcesSchema, 'output'], RunsIndex: [RunsIndexSchema, 'output'],
     RunEvent: [LiveRunSchema, 'output'], HelloEvent: [HelloEventSchema, 'output'], ReportEvent: [ReportEventSchema, 'output'], AtlasChangeEvent: [AtlasChangeSchema, 'output'], PingEvent: [PingEventSchema, 'output']
@@ -367,6 +368,27 @@ const BASE_OPERATIONS = [
         body: { description: 'The attachment and the tags to add and remove. At most 20 of each, 64 KiB.', contentType: 'application/json', required: true, schema: ref('ArtifactTagEdit') },
         responses: { '201': json('The recorded entry.', 'ArtifactTagEntry'), '401': UNAUTHORIZED, '403': FORBIDDEN, '413': problem('Request too large.'), '422': problem('Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.') }
     },
+    {
+        route: 'GET /api/reports/recordings/verification', path: '/api/reports/recordings/verification', operationId: 'getRecordingVerification', tag: 'Report', role: 'read',
+        summary: 'Which stored recordings the server last read back, and which were gone or damaged',
+        description: [
+            'The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run\'s recordings as stored-then-unavailable beside its test results.',
+            '',
+            'This route never reads a blob: it returns what a publish token\'s `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server\'s memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).'
+        ].join('\n'),
+        parameters: [
+            { name: 'run', in: 'query', description: 'Only layers of this run (a key from `GET /api/reports/runs`).', schema: str },
+            { name: 'layer', in: 'query', description: 'Only layers whose id starts with this prefix. Repeatable or comma-separated.', schema: str }
+        ],
+        responses: { '200': json('The held read-backs.', 'RecordingVerification'), '401': UNAUTHORIZED }
+    },
+    {
+        route: 'POST /api/reports/recordings/verification', path: '/api/reports/recordings/verification', operationId: 'verifyRecordings', tag: 'Report', role: 'publish',
+        summary: 'Read stored recordings back and check them (publish token)',
+        description: 'Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type\'s container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.',
+        body: { description: 'Optional `layers` (id prefixes) and `limit`. An empty body reads back the newest layers.', contentType: 'application/json', required: false, schema: ref('RecordingVerifyRequest') },
+        responses: { '200': json('The read-backs now held.', 'RecordingVerification'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('A read-back is already running.'), '413': problem('Request too large.'), '422': problem('Not a verification request.'), '502': problem('A store could not be read.'), '503': NOT_READY }
+    },
     {
         route: 'GET /api/reports/review-collections', path: '/api/reports/review-collections', operationId: 'listReviewCollections', tag: 'Report', role: 'read',
         summary: 'Review collections: curated sets of recordings, newest first',

package/dist/server/src/recording-verification.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module Recording verification routes
+ *
+ * `/api/reports/recordings/verification`: whether the videos a run published can still be read back from storage as
+ * they were published, apart from whether the run's tests passed. A viewer reads the newest result with a read token
+ * (`GET`, which never touches a blob). A publish token starts a read-back (`POST`), which does read blobs and so is
+ * bounded: the newest 20 layers unless asked for more, at most 200, one pass at a time. The result is kept in this
+ * process only (it is derived, not state: a restart means "not verified yet", never "fine"), and only for layers the
+ * store still holds. It adds nothing to any layer and changes no status, slot or winner. This is the same check as
+ * `atlas report verify-recordings`, and as that command it checks stored bytes, not browser playback.
+ *
+ * @see docs/rich-evidence.md#recording-completeness
+ */
+import type { Hono } from 'hono';
+import type { ObjectStore } from '../../reports/src/object-store.js';
+import type { ReportIndex } from '../../reports/src/report-index.js';
+import type { Auth } from './auth.js';
+/** What the verification routes need from the server around them. */
+export type RecordingVerificationDeps = {
+    /** Every backend's store: a layer is read back from the store that holds it. */
+    readonly stores: readonly ObjectStore[];
+    readonly auth: Auth;
+    readonly index: ReportIndex;
+    readonly now: () => number;
+    readonly unauthorized: (verdict: Extract<ReturnType<Auth['check']>, {
+        ok: false;
+    }>) => Response;
+};
+/**
+ * Registers `GET` and `POST /api/reports/recordings/verification` on `app`. The result of the last read-back of each
+ * layer is held in memory, replaced by a newer one, and served only for layers a store still holds. A layer held by
+ * two backends keeps the reading with more gaps, so a copy that lost its blobs is never hidden by one that did not.
+ */
+export declare function mountRecordingVerification(app: Hono, deps: RecordingVerificationDeps): void;