@crvouga/atlas 1.16.0 → 1.18.0

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

@@ -1,11 +1,19 @@
 import { type ArtifactFilter, type FilterFields, type FilterName, type QueryFacets } from './artifact-query.js';
 import type { EvidenceMeasurement, EvidenceStatus, SpecEntry } from './explorer-types.js';
 import type { EvidenceSummary, LayerEvidence, LayerHeader, LayerRow, StatusCounts, VideoCounts, VideoRef } from './evidence-types.js';
+import { type RunRecordings } from './recording-receipt.js';
 import { RecordedSpecs } from './recorded-specs.js';
 /** The version of the documents this module writes (`TestCatalog`, `TestHistoryDocument`, `RunList`, `RunDetail`). Only optional fields are added within it. */
 export declare const TEST_CATALOG_VERSION = 1;
 /** Recorded results kept per test, newest first. Older ones are counted in no statistic. */
 export declare const HISTORY_PER_TEST = 100;
+/**
+ * The open `labels` (see docs/extending.md) that say what a result's evidence ran against and who vouches for it: `build`,
+ * `platform`, `applies-to` (builds or commits it is asserted to still hold for), `applies-to-by` (the policy or person that
+ * asserts it), `published-at` and `enriched-at` (when the evidence was published or enriched, epoch milliseconds or an ISO
+ * date: never when the checks ran). A test's current results carry them as `provenance`.
+ */
+export declare const APPLICABILITY_LABELS: readonly ["build", "platform", "applies-to", "applies-to-by", "published-at", "enriched-at"];
 /** One recorded result of a test: when, where, how it went and how long it took, and the layer and run it came from. */
 export type TestResultEntry = {
     /** When it was recorded, epoch ms. */
@@ -32,6 +40,10 @@ export type TestResultEntry = {
     readonly detail: string;
     /** The fingerprint of its spec text the layer recorded, when it recorded one: results with different revisions were recorded against different promises. Absent means not recorded, never "the same". */
     readonly specRevision?: string;
+    /** `modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Absent for a clean checkout, and on results other than a test's current ones. Advisory; never changes a status. */
+    readonly freshness?: 'unknown' | 'modified';
+    /** The labels of its layer and check that say what it ran against and who vouches for it: only those named in {@link APPLICABILITY_LABELS}. Present on a test's current results when it has any. Read by the viewer's evidence applicability; never decides a result. */
+    readonly provenance?: Readonly<Record<string, string>>;
     /** What it carried beyond its outcome (attachments, steps, retries, tags, labels), when anything. */
     readonly evidence?: EvidenceSummary;
     /** Its product-latency measurements (`kind: product-latency`), when it recorded any. Separate from `durationMs`, which is how long the test took (setup, waits and pacing included). */
@@ -82,6 +94,8 @@ export type CatalogSpec = {
     /** The group it belongs to: the spec's own domain, else the folder under `specs/`. */
     readonly domain: string;
     readonly kind: string;
+    /** The fingerprint of the spec text now (the promise), when the spec set or a layer recorded one. A result's `specRevision` is compared with it: different means the promise changed after the result was recorded. Absent: unknown, never "the same". */
+    readonly fingerprint?: string;
 };
 /** One test: what it is, its current status per environment, and how it has gone. */
 export type TestSummary = {
@@ -274,6 +288,11 @@ export type RunSummary = {
      * and references that cannot be played. Absent when it has none, and in a report that carries no video information.
      */
     readonly videos?: VideoCounts;
+    /**
+     * Whether the recordings its layers expected were published, apart from its outcomes (see `runRecordings`). Absent when
+     * none of its layers declared a recording expectation: its completeness is unknown, never complete. Never changes a status.
+     */
+    readonly recordings?: RunRecordings;
     /**
      * Files attached to the run itself, in its layers (and their parts), not to any one check: review movies, archives,
      * summaries. All kinds, videos included. Absent when none, and in a report that carries no such information.
@@ -543,7 +562,7 @@ export declare function fieldsOfRun(run: RunSummary): FilterFields;
  * list.results.map(r => [r.title, r.run, r.sha, r.status]);
  * ```
  */
-export declare function artifactList(history: TestHistory, version: string, query?: ArtifactFilter, page?: {
+export declare function artifactList(history: TestHistory, version: string, asked?: ArtifactFilter, page?: {
     readonly limit?: number;
     readonly offset?: number;
     readonly domainOf?: (specPath: string) => string | undefined;

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

@@ -23,7 +23,8 @@
  * @see docs/server.md#reading-the-report-as-an-agent
  */
 import { displayTag, normalizeTag, normalizeTags } from './artifact-tags.js';
-import { facetsOf, forRuns, labelList, matchesFilter, outcomeOfCounts, splitList, usedFilters } from './artifact-query.js';
+import { facetsOf, forArtifacts, forRuns, labelList, matchesFilter, outcomeOfCounts, splitList, usedFilters } from './artifact-query.js';
+import { runRecordings } from './recording-receipt.js';
 import { videoCounts } from './evidence-detail.js';
 import { productLatency } from './latency.js';
 import { matchesScope, scopeTokens, UNKNOWN_SCOPE } from './evidence-scope.js';
@@ -34,6 +35,13 @@ import { RecordedSpecs } from './recorded-specs.js';
 export const TEST_CATALOG_VERSION = 1;
 /** Recorded results kept per test, newest first. Older ones are counted in no statistic. */
 export const HISTORY_PER_TEST = 100;
+/**
+ * The open `labels` (see docs/extending.md) that say what a result's evidence ran against and who vouches for it: `build`,
+ * `platform`, `applies-to` (builds or commits it is asserted to still hold for), `applies-to-by` (the policy or person that
+ * asserts it), `published-at` and `enriched-at` (when the evidence was published or enriched, epoch milliseconds or an ISO
+ * date: never when the checks ran). A test's current results carry them as `provenance`.
+ */
+export const APPLICABILITY_LABELS = ['build', 'platform', 'applies-to', 'applies-to-by', 'published-at', 'enriched-at'];
 const FAILURE_RANK = { passed: 0, 'not-run': 1, running: 2, failed: 3 };
 /** How tests are ordered. */
 export const TEST_SORTS = ['spec', 'title', 'recent', 'slowest', 'failures', 'flaky', 'runs'];
@@ -141,7 +149,7 @@ export class TestHistory {
         const key = runKey(layer);
         let run = this.#runs.get(key);
         if (!run) {
-            run = { key, runUrl: layer.runUrl, branch: layer.branch, sha: layer.sha, start: layer.recordedAtMs, end: layer.recordedAtMs, firstAt: layer.recordedAtMs, first: layer.id, producers: new Set(), environments: new Set(), layers: 0, runId: layer.run?.id, title: undefined, titledAt: 0, titledBy: '', freshness: undefined, videos: [], attachments: 0, members: [], evidence: { tags: new Set(), artifactTags: new Set(), roles: new Set(), labels: new Set() } };
+            run = { key, runUrl: layer.runUrl, branch: layer.branch, sha: layer.sha, start: layer.recordedAtMs, end: layer.recordedAtMs, firstAt: layer.recordedAtMs, first: layer.id, producers: new Set(), environments: new Set(), layers: 0, runId: layer.run?.id, title: undefined, titledAt: 0, titledBy: '', freshness: undefined, videos: [], receipts: [], attachments: 0, members: [], evidence: { tags: new Set(), artifactTags: new Set(), roles: new Set(), labels: new Set() } };
             this.#runs.set(key, run);
         }
         // A run is told by its first layer (by time, then id), whatever order its layers arrive in.
@@ -170,6 +178,7 @@ export class TestHistory {
         run.layers += 1;
         if (layer.evidence?.videos)
             run.videos.push(...layer.evidence.videos);
+        run.receipts.push(layer.recordings);
         const held = layer.evidence?.attachments ?? 0;
         run.attachments += held;
         const layerVideos = videoCounts(layer.evidence?.videos);
@@ -369,6 +378,7 @@ function runSummary(run, cells) {
     }
     failed.sort((a, b) => compareText(a.i.slot, b.i.slot) || compareText(a.r.o.place, b.r.o.place) || compareText(a.r.k, b.r.k));
     const video = videoCounts(videos);
+    const recordings = runRecordings(run.receipts);
     const failing = failed.slice(0, 20).map(cell => ({ key: cell.i.slot, title: cell.i.title, environment: cell.r.o.environment, detail: (cell.r.t.split('\n')[0] ?? '').slice(0, 500) }));
     return {
         key: run.key, ...(run.runId ? { runId: run.runId } : {}), ...(run.title ? { title: run.title } : {}), ...(run.freshness ? { freshness: run.freshness } : {}),
@@ -377,6 +387,7 @@ function runSummary(run, cells) {
         producers: [...run.producers].sort(), environments: [...run.environments].sort(),
         layers: run.layers, tests: tests.size, counts, totalDurationMs: measured ? total : null, failing,
         ...(video ? { videos: video } : {}),
+        ...(recordings ? { recordings } : {}),
         ...(run.attachments ? { attachments: run.attachments } : {}),
         ...(carried.artifactTags.size ? { artifactTags: [...carried.artifactTags].sort() } : {}),
         ...(carried.roles.size ? { types: typesOf(carried.roles, (video?.recordings ?? 0) > 0) } : {}),
@@ -409,6 +420,7 @@ export function catalogSpec(path, known) {
         title: entry?.title || (base ? base[0].toUpperCase() + base.slice(1) : path),
         domain: entry?.domain || folder,
         kind: entry?.kind || (/\.([^./]+)$/.exec(path)?.[1] ?? 'unknown'),
+        ...(entry?.fingerprint ? { fingerprint: entry.fingerprint } : {}),
     };
 }
 function statsOf(history, outcomes, tags, labels) {
@@ -464,11 +476,18 @@ function statsOf(history, outcomes, tags, labels) {
         firstSeenMs, lastSeenMs, lastPassedAtMs, lastFailedAtMs, runs: runs.size, branches,
     };
 }
-function outcomeOf(result) {
-    return entryOf(result.layer, result.row, result.layer.backend);
+/** A current result with what the layer recorded about its spec and about what it ran against (see {@link APPLICABILITY_LABELS}). */
+function outcomeOf(result, fingerprints = {}) {
+    const labels = { ...(result.layer.evidence?.labels ?? {}), ...(result.row.evidence?.labels ?? {}) };
+    const provenance = Object.fromEntries(APPLICABILITY_LABELS.filter(name => typeof labels[name] === 'string').map(name => [name, labels[name]]));
+    return {
+        ...entryOf(result.layer, result.row, result.layer.backend, fingerprints),
+        ...(result.layer.freshness ? { freshness: result.layer.freshness } : {}),
+        ...(Object.keys(provenance).length ? { provenance } : {}),
+    };
 }
-function summaryOf(slot, history, known) {
-    const outcomes = slot.outcomes.map(outcomeOf);
+function summaryOf(slot, history, known, fingerprintsOf) {
+    const outcomes = slot.outcomes.map(result => outcomeOf(result, fingerprintsOf(result.layer.id)));
     const tags = new Set();
     const artifactTags = new Set();
     const inheritedTags = new Set();
@@ -586,7 +605,8 @@ export function catalogModel(layers, sources = {}) {
     const known = (path) => recorded.get(path);
     const combined = combineEvidence({ specs: [], sha: null, changedFiles: [] }, layers);
     const slots = checkSlots(combined.unassigned);
-    const tests = slots.map(slot => summaryOf(slot, history, known));
+    const fingerprints = new Map(layers.map(entry => [entry.layer.id, entry.fingerprints]));
+    const tests = slots.map(slot => summaryOf(slot, history, known, id => fingerprints.get(id)));
     const byKey = new Map(tests.map(test => [test.key, test]));
     const haystacks = new Map(tests.map(test => [test.key, haystackOf(test)]));
     const counts = emptyCounts();
@@ -721,7 +741,7 @@ export function fieldsOfRun(run) {
         text: [run.title ?? '', run.key, run.branch ?? '', run.sha ?? '', ...run.producers, ...run.environments, ...artifactTags, ...(run.tags ?? []), ...labels].join('\n').toLowerCase(),
         artifactTags, tags: [...new Set([...(run.tags ?? []), ...artifactTags])], types, media: types.map(type => ({ type, tags: artifactTags })), labels,
         environments: run.environments, producers: run.producers, branches: run.branch ? [run.branch] : [], shas: run.sha ? [run.sha.toLowerCase()] : [],
-        outcomes: [outcomeOfCounts(run.counts)], at: run.endedAtMs,
+        outcomes: [outcomeOfCounts(run.counts)], recordings: [run.recordings?.state ?? 'unknown'], at: run.endedAtMs,
     };
 }
 /**
@@ -736,7 +756,9 @@ export function fieldsOfRun(run) {
  * list.results.map(r => [r.title, r.run, r.sha, r.status]);
  * ```
  */
-export function artifactList(history, version, query = {}, page = {}) {
+export function artifactList(history, version, asked = {}, page = {}) {
+    // Recording completeness is a property of a run: a recorded result is not asked about it.
+    const query = forArtifacts(asked);
     const domains = new Map();
     const domainOf = (path) => {
         if (path === null)

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

@@ -90,6 +90,7 @@ export declare const VideoRefSchema: z.ZodObject<{
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     recording: z.ZodOptional<z.ZodString>;
     available: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodObject<{
         surface: z.ZodOptional<z.ZodString>;
         deviceKind: z.ZodOptional<z.ZodString>;
@@ -115,6 +116,7 @@ export declare const VideoCountsSchema: z.ZodObject<{
     references: z.ZodNumber;
     recordings: z.ZodNumber;
     unavailable: z.ZodNumber;
+    missing: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 /** What a result carries beyond its outcome, as counts and short facts. Present only when there is something. */
 export declare const EvidenceSummarySchema: z.ZodObject<{
@@ -141,6 +143,7 @@ export declare const EvidenceSummarySchema: z.ZodObject<{
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         recording: z.ZodOptional<z.ZodString>;
         available: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
         scope: z.ZodOptional<z.ZodObject<{
             surface: z.ZodOptional<z.ZodString>;
             deviceKind: z.ZodOptional<z.ZodString>;
@@ -217,6 +220,7 @@ export declare const LayerHeaderSchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
+            reason: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -304,6 +308,7 @@ export declare const LayerRowSchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
+            reason: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -409,6 +414,7 @@ export declare const LayerRowsSchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -516,6 +522,7 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -617,6 +624,7 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -713,6 +721,7 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
+                    reason: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -814,6 +823,7 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
+                    reason: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -931,6 +941,7 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
+                    reason: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -1032,6 +1043,7 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
+                    reason: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -1141,6 +1153,7 @@ export declare const EvidencePageSchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -1721,6 +1734,7 @@ export declare const ReviewSnapshotSchema: z.ZodObject<{
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         recording: z.ZodOptional<z.ZodString>;
         available: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
         scope: z.ZodOptional<z.ZodObject<{
             surface: z.ZodOptional<z.ZodString>;
             deviceKind: z.ZodOptional<z.ZodString>;
@@ -1784,6 +1798,7 @@ export declare const ReviewEntrySchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
+            reason: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -1866,6 +1881,7 @@ export declare const ReviewCollectionSchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -2025,6 +2041,7 @@ export declare const ReviewCollectionDetailSchema: z.ZodObject<{
                     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
+                    reason: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -2156,6 +2173,7 @@ export declare const ReviewManifestSchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -2255,6 +2273,11 @@ export declare const TestResultEntrySchema: z.ZodObject<{
     backend: z.ZodString;
     detail: z.ZodString;
     specRevision: z.ZodOptional<z.ZodString>;
+    freshness: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        modified: "modified";
+    }>>;
+    provenance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     evidence: z.ZodOptional<z.ZodObject<{
         attachments: z.ZodNumber;
         steps: z.ZodNumber;
@@ -2279,6 +2302,7 @@ export declare const TestResultEntrySchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
+            reason: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -2329,6 +2353,7 @@ export declare const TestSummarySchema: z.ZodObject<{
         title: z.ZodString;
         domain: z.ZodString;
         kind: z.ZodString;
+        fingerprint: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
     status: z.ZodEnum<{
         passed: "passed";
@@ -2359,6 +2384,11 @@ export declare const TestSummarySchema: z.ZodObject<{
         backend: z.ZodString;
         detail: z.ZodString;
         specRevision: z.ZodOptional<z.ZodString>;
+        freshness: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            modified: "modified";
+        }>>;
+        provenance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         evidence: z.ZodOptional<z.ZodObject<{
             attachments: z.ZodNumber;
             steps: z.ZodNumber;
@@ -2383,6 +2413,7 @@ export declare const TestSummarySchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -2586,6 +2617,7 @@ export declare const TestCatalogSchema: z.ZodObject<{
             title: z.ZodString;
             domain: z.ZodString;
             kind: z.ZodString;
+            fingerprint: z.ZodOptional<z.ZodString>;
             tests: z.ZodNumber;
             counts: z.ZodRecord<z.ZodEnum<{
                 passed: "passed";
@@ -2628,6 +2660,7 @@ export declare const TestCatalogSchema: z.ZodObject<{
             title: z.ZodString;
             domain: z.ZodString;
             kind: z.ZodString;
+            fingerprint: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>>;
         status: z.ZodEnum<{
             passed: "passed";
@@ -2658,6 +2691,11 @@ export declare const TestCatalogSchema: z.ZodObject<{
             backend: z.ZodString;
             detail: z.ZodString;
             specRevision: z.ZodOptional<z.ZodString>;
+            freshness: z.ZodOptional<z.ZodEnum<{
+                unknown: "unknown";
+                modified: "modified";
+            }>>;
+            provenance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             evidence: z.ZodOptional<z.ZodObject<{
                 attachments: z.ZodNumber;
                 steps: z.ZodNumber;
@@ -2682,6 +2720,7 @@ export declare const TestCatalogSchema: z.ZodObject<{
                     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
+                    reason: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -2860,6 +2899,7 @@ export declare const TestHistorySchema: z.ZodObject<{
             title: z.ZodString;
             domain: z.ZodString;
             kind: z.ZodString;
+            fingerprint: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>>;
         status: z.ZodEnum<{
             passed: "passed";
@@ -2890,6 +2930,11 @@ export declare const TestHistorySchema: z.ZodObject<{
             backend: z.ZodString;
             detail: z.ZodString;
             specRevision: z.ZodOptional<z.ZodString>;
+            freshness: z.ZodOptional<z.ZodEnum<{
+                unknown: "unknown";
+                modified: "modified";
+            }>>;
+            provenance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             evidence: z.ZodOptional<z.ZodObject<{
                 attachments: z.ZodNumber;
                 steps: z.ZodNumber;
@@ -2914,6 +2959,7 @@ export declare const TestHistorySchema: z.ZodObject<{
                     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
+                    reason: z.ZodOptional<z.ZodString>;
                     scope: z.ZodOptional<z.ZodObject<{
                         surface: z.ZodOptional<z.ZodString>;
                         deviceKind: z.ZodOptional<z.ZodString>;
@@ -3013,6 +3059,11 @@ export declare const TestHistorySchema: z.ZodObject<{
         backend: z.ZodString;
         detail: z.ZodString;
         specRevision: z.ZodOptional<z.ZodString>;
+        freshness: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            modified: "modified";
+        }>>;
+        provenance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         evidence: z.ZodOptional<z.ZodObject<{
             attachments: z.ZodNumber;
             steps: z.ZodNumber;
@@ -3037,6 +3088,7 @@ export declare const TestHistorySchema: z.ZodObject<{
                 tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
                 scope: z.ZodOptional<z.ZodObject<{
                     surface: z.ZodOptional<z.ZodString>;
                     deviceKind: z.ZodOptional<z.ZodString>;
@@ -3238,6 +3290,21 @@ export declare const ReportRunSchema: z.ZodObject<{
         references: z.ZodNumber;
         recordings: z.ZodNumber;
         unavailable: z.ZodNumber;
+        missing: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    recordings: z.ZodOptional<z.ZodObject<{
+        state: z.ZodEnum<{
+            unknown: "unknown";
+            complete: "complete";
+            incomplete: "incomplete";
+            "none-expected": "none-expected";
+        }>;
+        expected: z.ZodNumber;
+        published: z.ZodNumber;
+        skipped: z.ZodNumber;
+        unresolved: z.ZodNumber;
+        notApplicable: z.ZodNumber;
+        layersWithoutReceipt: z.ZodNumber;
     }, z.core.$loose>>;
     attachments: z.ZodOptional<z.ZodNumber>;
     artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -3284,6 +3351,10 @@ export declare const QueryFacetsSchema: z.ZodObject<{
         value: z.ZodString;
         count: z.ZodNumber;
     }, z.core.$loose>>>;
+    recordings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 /** `GET /api/reports/runs`: runs, newest first. */
 export declare const RunListSchema: z.ZodObject<{
@@ -3325,6 +3396,21 @@ export declare const RunListSchema: z.ZodObject<{
             references: z.ZodNumber;
             recordings: z.ZodNumber;
             unavailable: z.ZodNumber;
+            missing: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+        recordings: z.ZodOptional<z.ZodObject<{
+            state: z.ZodEnum<{
+                unknown: "unknown";
+                complete: "complete";
+                incomplete: "incomplete";
+                "none-expected": "none-expected";
+            }>;
+            expected: z.ZodNumber;
+            published: z.ZodNumber;
+            skipped: z.ZodNumber;
+            unresolved: z.ZodNumber;
+            notApplicable: z.ZodNumber;
+            layersWithoutReceipt: z.ZodNumber;
         }, z.core.$loose>>;
         attachments: z.ZodOptional<z.ZodNumber>;
         artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -3367,6 +3453,10 @@ export declare const RunListSchema: z.ZodObject<{
             value: z.ZodString;
             count: z.ZodNumber;
         }, z.core.$loose>>>;
+        recordings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
 /** One recorded result that carries evidence: where and when it was recorded and what it carries. */
@@ -3406,6 +3496,7 @@ export declare const ArtifactResultSchema: z.ZodObject<{
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         recording: z.ZodOptional<z.ZodString>;
         available: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
         scope: z.ZodOptional<z.ZodObject<{
             surface: z.ZodOptional<z.ZodString>;
             deviceKind: z.ZodOptional<z.ZodString>;
@@ -3476,6 +3567,7 @@ export declare const ArtifactListSchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
+            reason: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -3537,6 +3629,10 @@ export declare const ArtifactListSchema: z.ZodObject<{
             value: z.ZodString;
             count: z.ZodNumber;
         }, z.core.$loose>>>;
+        recordings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>>;
     }, z.core.$loose>;
 }, z.core.$loose>;
 /** `GET /api/reports/runs/detail`: one run and its last result for every test, environment and producer it recorded. */
@@ -3578,6 +3674,21 @@ export declare const RunDetailSchema: z.ZodObject<{
             references: z.ZodNumber;
             recordings: z.ZodNumber;
             unavailable: z.ZodNumber;
+            missing: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+        recordings: z.ZodOptional<z.ZodObject<{
+            state: z.ZodEnum<{
+                unknown: "unknown";
+                complete: "complete";
+                incomplete: "incomplete";
+                "none-expected": "none-expected";
+            }>;
+            expected: z.ZodNumber;
+            published: z.ZodNumber;
+            skipped: z.ZodNumber;
+            unresolved: z.ZodNumber;
+            notApplicable: z.ZodNumber;
+            layersWithoutReceipt: z.ZodNumber;
         }, z.core.$loose>>;
         attachments: z.ZodOptional<z.ZodNumber>;
         artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -3610,6 +3721,7 @@ export declare const RunDetailSchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
+            reason: z.ZodOptional<z.ZodString>;
             scope: z.ZodOptional<z.ZodObject<{
                 surface: z.ZodOptional<z.ZodString>;
                 deviceKind: z.ZodOptional<z.ZodString>;
@@ -3647,6 +3759,7 @@ export declare const RunDetailSchema: z.ZodObject<{
             references: z.ZodNumber;
             recordings: z.ZodNumber;
             unavailable: z.ZodNumber;
+            missing: z.ZodOptional<z.ZodNumber>;
         }, z.core.$loose>>;
     }, z.core.$loose>>>;
 }, z.core.$loose>;

package/dist/schema/src/api.js

@@ -71,13 +71,15 @@ export const VideoRefSchema = z.looseObject({
     tags: z.array(z.string()).optional().describe('The normalized tags of this attachment itself. Absent when it has none (and in documents of older servers)'),
     recording: z.string().optional().describe('What identifies the bytes; references with the same value are one recording. Absent when it cannot be played'),
     available: z.boolean().describe('False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer\'s own bundle does not hold'),
+    reason: z.string().optional().describe('Why it is unavailable, when the report can tell: `not-in-bundle` is a file the layer names but does not hold (stored, then gone). An open vocabulary: treat an unknown reason as plain unavailable'),
     scope: EvidenceScopeSchema.optional().describe('What this recording shows as its producer declared it: its own `scope`, else its attempt\'s, check\'s, part\'s or layer\'s. Absent: the scope is unknown, never live, physical or audible')
 });
 /** Video references as counts: how many are referenced, how many distinct recordings can be played, how many cannot. */
 export const VideoCountsSchema = z.looseObject({
     references: z.number().int().nonnegative().describe('Every reference to a video; identical bytes referenced twice count twice'),
     recordings: z.number().int().nonnegative().describe('Distinct playable recordings'),
-    unavailable: z.number().int().nonnegative().describe('References that name no bytes, or bytes the layer does not hold')
+    unavailable: z.number().int().nonnegative().describe('References that name no bytes, or bytes the layer does not hold'),
+    missing: z.number().int().positive().optional().describe('Of `unavailable`, those that name a file the layer\'s bundle does not hold (stored, then gone). Absent when there are none')
 });
 /** What a result carries beyond its outcome, as counts and short facts. Present only when there is something. */
 export const EvidenceSummarySchema = z.looseObject({
@@ -432,13 +434,18 @@ export const TestResultEntrySchema = z.looseObject({
     backend: z.string(),
     detail: z.string().describe('Why it has its status, at most 500 characters'),
     specRevision: z.string().optional().describe('The fingerprint of its spec text that the layer recorded, when it recorded one. Two results with different revisions were recorded against different promises. Absent: not recorded, never assumed to match'),
+    freshness: z.enum(['modified', 'unknown']).optional().describe('`modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Absent for a clean checkout, on results other than a test\'s current ones, and from an older server. Advisory; never changes a status'),
+    provenance: z.record(z.string(), z.string()).optional().describe('The labels of its layer and check that say what it ran against and who vouches for it: `build`, `platform`, `applies-to`, `applies-to-by`, `published-at`, `enriched-at`. Present on a test\'s current results when it has any, and absent from an older server. Never decides a result'),
     evidence: EvidenceSummarySchema.optional(),
     latency: z.array(MeasurementSchema).optional().describe('Its product-latency measurements (`kind: product-latency`), when it recorded any. Separate from `durationMs`, which is how long the test took')
 });
 const DurationStatsSchema = z.looseObject({
     count: z.number().int().nonnegative(), totalMs: z.number(), avgMs: z.number(), p50Ms: z.number(), p95Ms: z.number(), minMs: z.number(), maxMs: z.number(), lastMs: z.number()
 });
-const CatalogSpecSchema = z.looseObject({ path: z.string(), title: z.string(), domain: z.string(), kind: z.string() });
+const CatalogSpecSchema = z.looseObject({
+    path: z.string(), title: z.string(), domain: z.string(), kind: z.string(),
+    fingerprint: z.string().optional().describe('The fingerprint of the spec text now (the promise). Compare it with a result\'s `specRevision`: different means the promise changed after the result was recorded. Absent: unknown, never "the same". Absent from an older server')
+});
 /** One test of the catalog: what it is, its current result per environment, and how it has gone over its recorded history. */
 export const TestSummarySchema = z.looseObject({
     key: z.string().describe('The test\'s identity, `JSON.stringify([specPath, id])`. Pass it to `/api/reports/tests/history?key=`'),
@@ -620,6 +627,12 @@ export const ReportRunSchema = z.looseObject({
     totalDurationMs: z.number().nullable(),
     failing: z.array(z.looseObject({ key: z.string(), title: z.string(), environment: z.string().nullable(), detail: z.string() })),
     videos: VideoCountsSchema.optional().describe('Its videos, from its layers and the last result of each test. Absent when it has none or the report carries no video information'),
+    recordings: z.looseObject({
+        state: z.enum(['complete', 'incomplete', 'none-expected', 'unknown']).describe('`incomplete` when an expected recording was skipped or unresolved; else `unknown` when a layer declared no expectations; else `complete` when something was expected and `none-expected` when nothing was'),
+        expected: z.number().int().nonnegative(), published: z.number().int().nonnegative().describe('Of the expected recordings, uploaded or referenced by address'),
+        skipped: z.number().int().nonnegative(), unresolved: z.number().int().nonnegative(), notApplicable: z.number().int().nonnegative(),
+        layersWithoutReceipt: z.number().int().nonnegative().describe('Layers of the run that declared no recording expectations: nothing is claimed for them')
+    }).optional().describe('Whether the recordings its layers expected were published, apart from its outcomes. Absent when no layer declared an expectation: its completeness is unknown, never complete. Matched by the `recordings` filter'),
     attachments: z.number().int().positive().optional().describe('Files attached to the run itself, in its layers, not to a check. Absent when there are none'),
     artifactTags: z.array(z.string()).optional().describe('The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers'),
     tags: z.array(z.string()).optional().describe('The tags of its checks and layers, which its attachments inherit (what `inherited=1` also matches). Absent when none'),
@@ -632,7 +645,8 @@ export const QueryFacetValueSchema = z.looseObject({ value: z.string(), count: z
 export const QueryFacetsSchema = z.looseObject({
     artifactTags: z.array(QueryFacetValueSchema), types: z.array(QueryFacetValueSchema), labels: z.array(QueryFacetValueSchema).describe('Values are `key=value`'),
     environments: z.array(QueryFacetValueSchema), producers: z.array(QueryFacetValueSchema), branches: z.array(QueryFacetValueSchema), outcomes: z.array(QueryFacetValueSchema),
-    domains: z.array(QueryFacetValueSchema).optional().describe('Only for artifacts: runs have no domain')
+    domains: z.array(QueryFacetValueSchema).optional().describe('Only for artifacts: runs have no domain'),
+    recordings: z.array(QueryFacetValueSchema).optional().describe('Only for runs: `complete`, `incomplete`, `none-expected` and `unknown` with how many runs have each. Absent on servers that predate the filter')
 });
 /** `GET /api/reports/runs`: runs, newest first. */
 export const RunListSchema = z.looseObject({