@crvouga/atlas 1.6.0 → 1.8.0

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

@@ -252,6 +252,17 @@ export declare const LayerRowSchema: z.ZodObject<{
         value: z.ZodNumber;
         unit: z.ZodString;
         limit: z.ZodOptional<z.ZodNumber>;
+        kind: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        intended: z.ZodOptional<z.ZodObject<{
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        source: z.ZodOptional<z.ZodString>;
+        outcome: z.ZodOptional<z.ZodString>;
+        instrumentation: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$loose>>;
     testId: z.ZodNullable<z.ZodString>;
     variant: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -320,6 +331,17 @@ export declare const LayerRowsSchema: z.ZodObject<{
             value: z.ZodNumber;
             unit: z.ZodString;
             limit: z.ZodOptional<z.ZodNumber>;
+            kind: z.ZodOptional<z.ZodString>;
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+            intended: z.ZodOptional<z.ZodObject<{
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            source: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
+            instrumentation: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, z.core.$loose>>;
         testId: z.ZodNullable<z.ZodString>;
         variant: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -390,6 +412,17 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
             value: z.ZodNumber;
             unit: z.ZodString;
             limit: z.ZodOptional<z.ZodNumber>;
+            kind: z.ZodOptional<z.ZodString>;
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+            intended: z.ZodOptional<z.ZodObject<{
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            source: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
+            instrumentation: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, z.core.$loose>>;
         testId: z.ZodNullable<z.ZodString>;
         variant: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -544,6 +577,17 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                 value: z.ZodNumber;
                 unit: z.ZodString;
                 limit: z.ZodOptional<z.ZodNumber>;
+                kind: z.ZodOptional<z.ZodString>;
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+                intended: z.ZodOptional<z.ZodObject<{
+                    from: z.ZodOptional<z.ZodString>;
+                    to: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+                source: z.ZodOptional<z.ZodString>;
+                outcome: z.ZodOptional<z.ZodString>;
+                instrumentation: z.ZodOptional<z.ZodString>;
+                labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             }, z.core.$loose>>;
             testId: z.ZodNullable<z.ZodString>;
             variant: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -719,6 +763,17 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                 value: z.ZodNumber;
                 unit: z.ZodString;
                 limit: z.ZodOptional<z.ZodNumber>;
+                kind: z.ZodOptional<z.ZodString>;
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+                intended: z.ZodOptional<z.ZodObject<{
+                    from: z.ZodOptional<z.ZodString>;
+                    to: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+                source: z.ZodOptional<z.ZodString>;
+                outcome: z.ZodOptional<z.ZodString>;
+                instrumentation: z.ZodOptional<z.ZodString>;
+                labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             }, z.core.$loose>>;
             testId: z.ZodNullable<z.ZodString>;
             variant: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -1312,6 +1367,17 @@ export declare const CheckDetailSchema: z.ZodObject<{
             value: z.ZodNumber;
             unit: z.ZodString;
             limit: z.ZodOptional<z.ZodNumber>;
+            kind: z.ZodOptional<z.ZodString>;
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+            intended: z.ZodOptional<z.ZodObject<{
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            source: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
+            instrumentation: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, z.core.$loose>>>;
         durationMs: z.ZodOptional<z.ZodNumber>;
         recordingExpectation: z.ZodOptional<z.ZodString>;
@@ -1498,6 +1564,23 @@ export declare const TestResultEntrySchema: z.ZodObject<{
             }, z.core.$loose>>;
         }, z.core.$loose>>>;
     }, z.core.$loose>>;
+    latency: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodNumber;
+        unit: z.ZodString;
+        limit: z.ZodOptional<z.ZodNumber>;
+        kind: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        intended: z.ZodOptional<z.ZodObject<{
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        source: z.ZodOptional<z.ZodString>;
+        outcome: z.ZodOptional<z.ZodString>;
+        instrumentation: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 /** One test of the catalog: what it is, its current result per environment, and how it has gone over its recorded history. */
 export declare const TestSummarySchema: z.ZodObject<{
@@ -1578,6 +1661,23 @@ export declare const TestSummarySchema: z.ZodObject<{
                 }, z.core.$loose>>;
             }, z.core.$loose>>>;
         }, z.core.$loose>>;
+        latency: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodNumber;
+            unit: z.ZodString;
+            limit: z.ZodOptional<z.ZodNumber>;
+            kind: z.ZodOptional<z.ZodString>;
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+            intended: z.ZodOptional<z.ZodObject<{
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            source: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
+            instrumentation: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$loose>>>;
     }, z.core.$loose>>;
     stats: z.ZodObject<{
         results: z.ZodNumber;
@@ -1853,6 +1953,23 @@ export declare const TestCatalogSchema: z.ZodObject<{
                     }, z.core.$loose>>;
                 }, z.core.$loose>>>;
             }, z.core.$loose>>;
+            latency: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                value: z.ZodNumber;
+                unit: z.ZodString;
+                limit: z.ZodOptional<z.ZodNumber>;
+                kind: z.ZodOptional<z.ZodString>;
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+                intended: z.ZodOptional<z.ZodObject<{
+                    from: z.ZodOptional<z.ZodString>;
+                    to: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+                source: z.ZodOptional<z.ZodString>;
+                outcome: z.ZodOptional<z.ZodString>;
+                instrumentation: z.ZodOptional<z.ZodString>;
+                labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$loose>>>;
         }, z.core.$loose>>;
         stats: z.ZodObject<{
             results: z.ZodNumber;
@@ -2055,6 +2172,23 @@ export declare const TestHistorySchema: z.ZodObject<{
                     }, z.core.$loose>>;
                 }, z.core.$loose>>>;
             }, z.core.$loose>>;
+            latency: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                value: z.ZodNumber;
+                unit: z.ZodString;
+                limit: z.ZodOptional<z.ZodNumber>;
+                kind: z.ZodOptional<z.ZodString>;
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+                intended: z.ZodOptional<z.ZodObject<{
+                    from: z.ZodOptional<z.ZodString>;
+                    to: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+                source: z.ZodOptional<z.ZodString>;
+                outcome: z.ZodOptional<z.ZodString>;
+                instrumentation: z.ZodOptional<z.ZodString>;
+                labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$loose>>>;
         }, z.core.$loose>>;
         stats: z.ZodObject<{
             results: z.ZodNumber;
@@ -2154,6 +2288,23 @@ export declare const TestHistorySchema: z.ZodObject<{
                 }, z.core.$loose>>;
             }, z.core.$loose>>>;
         }, z.core.$loose>>;
+        latency: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodNumber;
+            unit: z.ZodString;
+            limit: z.ZodOptional<z.ZodNumber>;
+            kind: z.ZodOptional<z.ZodString>;
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+            intended: z.ZodOptional<z.ZodObject<{
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            source: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
+            instrumentation: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$loose>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
 /** A run: the layers that name the same execution (else share a run URL, else a branch and commit), with what they recorded. */

package/dist/schema/src/api.js

@@ -14,7 +14,7 @@
  * @see docs/server.md
  */
 import { z } from 'zod/v4';
-import { CheckSchema, EvidenceScopeSchema, LayerRunSchema } from './layer.js';
+import { CheckSchema, EvidenceScopeSchema, LayerRunSchema, MeasurementSchema } from './layer.js';
 /** One of the statuses a check has in a report: `passed`, `failed`, `running` (not finished) or `not-run`. Closed. */
 export const EvidenceStatusSchema = z.enum(['passed', 'failed', 'running', 'not-run']);
 /**
@@ -124,7 +124,7 @@ export const LayerRowSchema = z.looseObject({
     status: EvidenceStatusSchema,
     specPath: z.string().nullable().describe('The spec the check belongs to, `specs/<path>`, or null'),
     detail: z.string().describe('Why it has this status; empty when there is nothing to add'),
-    measurements: z.array(z.looseObject({ name: z.string(), value: z.number(), unit: z.string(), limit: z.number().optional() })),
+    measurements: z.array(MeasurementSchema),
     testId: z.string().nullable(),
     variant: z.record(z.string(), z.string()),
     durationMs: z.number().nullable(),
@@ -270,7 +270,8 @@ export const TestResultEntrySchema = z.looseObject({
     layer: z.string().describe('The id of the layer that recorded it'),
     backend: z.string(),
     detail: z.string().describe('Why it has its status, at most 500 characters'),
-    evidence: EvidenceSummarySchema.optional()
+    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()

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

@@ -74,16 +74,40 @@ export declare const LayerRunSchema: z.ZodObject<{
 }, z.core.$loose>;
 /** The execution of a layer, parsed from `LayerRunSchema`. */
 export type LayerRun = z.output<typeof LayerRunSchema>;
+/** The `kind` of a measurement that is a named, user-visible product latency (see docs/rich-evidence.md#product-latency). */
+export declare const PRODUCT_LATENCY_KIND = "product-latency";
+/** The two ends of a measured interval, named in the producer's words: `{ from: 'submit pressed', to: 'confirmation visible' }`. */
+export declare const MeasurementBoundarySchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
 /**
  * A number a check measured, such as a latency or a size, with its unit and an optional allowance. A measurement over
  * its `limit` is reported and never changes the check's status.
+ *
+ * A measurement of `kind` `product-latency` is how quickly the product responded to a user, between two named events.
+ * It is not the check's duration (which includes setup, waits and pacing) and a number with no `kind` is never read as
+ * product latency. All the fields after `limit` are optional and describe the measurement; none decides a status.
  */
 export declare const MeasurementSchema: z.ZodObject<{
     name: z.ZodString;
     value: z.ZodNumber;
     unit: z.ZodString;
     limit: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    intended: z.ZodOptional<z.ZodObject<{
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    source: z.ZodOptional<z.ZodString>;
+    outcome: z.ZodOptional<z.ZodString>;
+    instrumentation: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$loose>;
+/** A measurement as stored in a layer, parsed from `MeasurementSchema`. */
+export type Measurement = z.output<typeof MeasurementSchema>;
 /**
  * Structured data of a producer's or tool's own, by namespace: `{ "com.example.coverage": { … } }`.
  * Use a name you own (a reverse domain, or your tool's name). Readers preserve it and never fail on it.
@@ -867,6 +891,17 @@ export declare const CheckSchema: z.ZodObject<{
         value: z.ZodNumber;
         unit: z.ZodString;
         limit: z.ZodOptional<z.ZodNumber>;
+        kind: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        intended: z.ZodOptional<z.ZodObject<{
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        source: z.ZodOptional<z.ZodString>;
+        outcome: z.ZodOptional<z.ZodString>;
+        instrumentation: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$loose>>>;
     durationMs: z.ZodOptional<z.ZodNumber>;
     recordingExpectation: z.ZodOptional<z.ZodString>;
@@ -1338,6 +1373,17 @@ export declare const ReportPartSchema: z.ZodObject<{
             value: z.ZodNumber;
             unit: z.ZodString;
             limit: z.ZodOptional<z.ZodNumber>;
+            kind: z.ZodOptional<z.ZodString>;
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+            intended: z.ZodOptional<z.ZodObject<{
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            source: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
+            instrumentation: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, z.core.$loose>>>;
         durationMs: z.ZodOptional<z.ZodNumber>;
         recordingExpectation: z.ZodOptional<z.ZodString>;
@@ -1708,6 +1754,17 @@ export declare const LayerSourceSchema: z.ZodObject<{
                 value: z.ZodNumber;
                 unit: z.ZodString;
                 limit: z.ZodOptional<z.ZodNumber>;
+                kind: z.ZodOptional<z.ZodString>;
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+                intended: z.ZodOptional<z.ZodObject<{
+                    from: z.ZodOptional<z.ZodString>;
+                    to: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+                source: z.ZodOptional<z.ZodString>;
+                outcome: z.ZodOptional<z.ZodString>;
+                instrumentation: z.ZodOptional<z.ZodString>;
+                labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             }, z.core.$loose>>>;
             durationMs: z.ZodOptional<z.ZodNumber>;
             recordingExpectation: z.ZodOptional<z.ZodString>;
@@ -2324,6 +2381,17 @@ export declare const LayerDocumentSchema: z.ZodObject<{
                 value: z.ZodNumber;
                 unit: z.ZodString;
                 limit: z.ZodOptional<z.ZodNumber>;
+                kind: z.ZodOptional<z.ZodString>;
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+                intended: z.ZodOptional<z.ZodObject<{
+                    from: z.ZodOptional<z.ZodString>;
+                    to: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+                source: z.ZodOptional<z.ZodString>;
+                outcome: z.ZodOptional<z.ZodString>;
+                instrumentation: z.ZodOptional<z.ZodString>;
+                labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             }, z.core.$loose>>>;
             durationMs: z.ZodOptional<z.ZodNumber>;
             recordingExpectation: z.ZodOptional<z.ZodString>;
@@ -2693,6 +2761,17 @@ export declare const LayerDocumentSchema: z.ZodObject<{
                     value: z.ZodNumber;
                     unit: z.ZodString;
                     limit: z.ZodOptional<z.ZodNumber>;
+                    kind: z.ZodOptional<z.ZodString>;
+                    from: z.ZodOptional<z.ZodString>;
+                    to: z.ZodOptional<z.ZodString>;
+                    intended: z.ZodOptional<z.ZodObject<{
+                        from: z.ZodOptional<z.ZodString>;
+                        to: z.ZodOptional<z.ZodString>;
+                    }, z.core.$loose>>;
+                    source: z.ZodOptional<z.ZodString>;
+                    outcome: z.ZodOptional<z.ZodString>;
+                    instrumentation: z.ZodOptional<z.ZodString>;
+                    labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 }, z.core.$loose>>>;
                 durationMs: z.ZodOptional<z.ZodNumber>;
                 recordingExpectation: z.ZodOptional<z.ZodString>;
@@ -2901,6 +2980,17 @@ export declare const PublishChecksSchema: z.ZodObject<{
             value: z.ZodNumber;
             unit: z.ZodString;
             limit: z.ZodOptional<z.ZodNumber>;
+            kind: z.ZodOptional<z.ZodString>;
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+            intended: z.ZodOptional<z.ZodObject<{
+                from: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            source: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
+            instrumentation: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, z.core.$loose>>>;
         durationMs: z.ZodOptional<z.ZodNumber>;
         recordingExpectation: z.ZodOptional<z.ZodString>;

package/dist/schema/src/layer.js

@@ -62,15 +62,34 @@ export const LayerRunSchema = z.looseObject({
     startedAtMs: z.number().nonnegative().optional().describe('When the execution started, epoch milliseconds'),
     endedAtMs: z.number().nonnegative().optional().describe('When the execution ended, epoch milliseconds')
 });
+/** The `kind` of a measurement that is a named, user-visible product latency (see docs/rich-evidence.md#product-latency). */
+export const PRODUCT_LATENCY_KIND = 'product-latency';
+/** The two ends of a measured interval, named in the producer's words: `{ from: 'submit pressed', to: 'confirmation visible' }`. */
+export const MeasurementBoundarySchema = z.looseObject({
+    from: z.string().min(1).optional().describe('The event the interval starts at: `end of speech`, `submit pressed`'),
+    to: z.string().min(1).optional().describe('The event the interval ends at: `audible response`, `confirmation visible`')
+});
 /**
  * A number a check measured, such as a latency or a size, with its unit and an optional allowance. A measurement over
  * its `limit` is reported and never changes the check's status.
+ *
+ * A measurement of `kind` `product-latency` is how quickly the product responded to a user, between two named events.
+ * It is not the check's duration (which includes setup, waits and pacing) and a number with no `kind` is never read as
+ * product latency. All the fields after `limit` are optional and describe the measurement; none decides a status.
  */
 export const MeasurementSchema = z.looseObject({
     name: z.string().min(1),
     value: z.number().describe('A finite number'),
     unit: z.string(),
-    limit: z.number().optional().describe('The allowance. A measurement over it is reported, and never fails the check by itself')
+    limit: z.number().optional().describe('The allowance, or budget. A measurement over it is reported, and never fails the check by itself'),
+    kind: z.string().min(1).optional().describe('What the number is, in an open vocabulary. `product-latency`: a user-visible response time between `from` and `to`. Absent: just a number, never read as product latency'),
+    from: z.string().min(1).optional().describe('The event the interval starts at. Without both `from` and `to` a latency is shown but no product claim is made from it'),
+    to: z.string().min(1).optional().describe('The event the interval ends at'),
+    intended: MeasurementBoundarySchema.optional().describe('The interval the name of the measurement claims, when what was measured is only part of it. If `intended.to` differs from `to` (or `intended.from` from `from`) the measurement is shown as partial, never as the complete interval'),
+    source: z.string().optional().describe('How it was measured: `app-instrumentation`, `trace`, `recording-analysis`'),
+    outcome: z.string().min(1).optional().describe('`observed` (the default), `timeout` or `failed`. For anything but `observed` the value is how long the observation waited: at least that much, so it counts against a budget and is never dropped'),
+    instrumentation: z.string().optional().describe('The version or method of the measurement. A change of it between two sets of observations is disclosed when they are compared'),
+    labels: z.record(z.string(), z.string()).optional().describe('What the observation is comparable with: `device`, `build`, `network`. `device` and `build` group the observations and, when two groups differ in the others, the comparison says so')
 });
 /**
  * Structured data of a producer's or tool's own, by namespace: `{ "com.example.coverage": { … } }`.

package/docs/extending.md

@@ -34,7 +34,7 @@ carry any of these. Every one is optional.
 | `scope{}` | What the evidence does and does not show: surface, device kind, synthetic data, scripted dependencies, audio, pacing, what was asserted and its limits. Unknown when absent. See [Evidence scope](rich-evidence.md#evidence-scope). |
 | `links[]` | Where to read more: the CI run, the issue, the trace client. |
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |
-| `measurements[]` | Numbers, with units and an allowance (already part of the contract). |
+| `measurements[]` | Numbers, with units and an allowance (already part of the contract). A measurement of `kind` `product-latency` names a user-visible response time between two events; see [Product latency](rich-evidence.md#product-latency). |
 
 An attachment may carry its own `tags[]` (`demo`): shown as `#demo` and searchable; see
 [Tagging artifacts and demos](rich-evidence.md#tagging-artifacts-and-demos).
@@ -104,6 +104,23 @@ every kind of evidence and values from the future) and `layer-extensibility.test
 fields survive at every level, malformed evidence is dropped without losing the result, and a reader of the
 first version of the format still reads it all.
 
+### Saying what failed
+
+A failed check or step may declare the expectation it broke under the `atlas.failure` extension, so a reviewer sees
+it before the raw log. Every field is optional, and the declaration never changes the result.
+
+```json
+{
+  "name": "The list includes tea", "kind": "then", "status": "failed",
+  "extensions": { "atlas.failure": { "expected": "tea in the list", "actual": "the list is empty", "attribution": "product" } }
+}
+```
+
+`expected` and `actual` are shown as written. `attribution` is `product`, `test-harness` or `environment`; leave it out
+when you do not know, and the viewer says the cause is unknown. It is never inferred from the message. Whether setup
+failed before the behavior started comes from the failed step's `kind`: `hook`, `setup`, `fixture`, `before`,
+`beforeAll`, `beforeEach` or `given` mean preparation; `when`, `then`, `assertion` or `expect` mean the behavior.
+
 ## Attach evidence
 
 ### From the command line