@crvouga/atlas 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog: @crvouga/atlas
 
-## 1.15.0 (2026-10-29)
+## 1.17.0 (2026-10-29)
+
+### Features
+
+- read evidence applicability in the test explorer's list, sort and detail ([14181aa](https://github.com/crvouga/atlas/commit/14181aa391fb824c85364c4f5d93e1a6ccede176))
+
+## 1.16.0 (2026-10-28)
+
+### Features
+
+- explain catalog counts and identity in a Catalog health tab with persistent root mappings (#71) ([0974e7a](https://github.com/crvouga/atlas/commit/0974e7a8d16b126c47e79a004974a629275122ad))
+
+## 1.15.0 (2026-10-28)
 
 ### Features
 

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

@@ -3,10 +3,18 @@ import type { CatalogModel } from './test-catalog.js';
 export declare const CATALOG_HEALTH_VERSION = 1;
 /** The most paths listed in one finding; its `count` is always the whole. */
 export declare const HEALTH_ITEM_LIMIT = 25;
-/** Declares that paths under `from` are the same specs as paths under `to`, e.g. `{ from: '', to: 'specs/' }`. Empty `from` matches every path. */
+/** The label a producer puts on a check to give its behavior (the promise) an id that outlives renames and moves. */
+export declare const BEHAVIOR_ID_LABEL = "behavior-id";
+/** The label a producer puts on a check to give one example of a scenario outline an id of its own. */
+export declare const EXAMPLE_ID_LABEL = "example-id";
+/**
+ * Declares that paths under `from` are the same specs as paths under `to`, e.g. `{ from: '', to: 'specs/' }`. Empty `from`
+ * matches every path. `source` says where it was declared (the server's configuration or the request); it changes nothing.
+ */
 export type RootMapping = {
     readonly from: string;
     readonly to: string;
+    readonly source?: 'configuration' | 'request';
 };
 /** One thing worth a look. */
 export type HealthItem = {
@@ -18,7 +26,7 @@ export type HealthItem = {
     }[];
 };
 /** Codes of `HealthFinding.code`. The set grows; a reader treats an unknown code as informational. */
-export type HealthCode = 'ambiguous-spec-path' | 'unmatched-spec-path' | 'duplicate-spec-content' | 'duplicate-spec-title' | 'generic-domain' | 'tests-without-spec' | 'no-spec-definitions' | 'fallback-identity' | 'unused-root-mapping' | 'spec-without-execution' | 'historical-only';
+export type HealthCode = 'ambiguous-spec-path' | 'unmatched-spec-path' | 'duplicate-spec-content' | 'duplicate-spec-title' | 'generic-domain' | 'tests-without-spec' | 'no-spec-definitions' | 'fallback-identity' | 'unused-root-mapping' | 'declared-id-split' | 'spec-without-execution' | 'historical-only';
 /** A finding: what is inconsistent, how many it affects, and what to change. */
 export type HealthFinding = {
     readonly code: HealthCode;
@@ -100,6 +108,10 @@ export type CatalogHealth = {
         readonly checks: number;
         /** Checks whose id equals their title: no stable id was given. */
         readonly fallbackIdentity: number;
+        /** Checks that declare a `behavior-id` label. Optional: absent from documents written before it existed. */
+        readonly declaredBehaviorIds?: number;
+        /** Checks that declare an `example-id` label. */
+        readonly declaredExampleIds?: number;
         readonly basis: string;
     };
     readonly domains: readonly {
@@ -110,6 +122,7 @@ export type CatalogHealth = {
         readonly from: string;
         readonly to: string;
         readonly matched: number;
+        readonly source?: 'configuration' | 'request';
     }[];
     readonly aliases: readonly SpecAlias[];
     readonly findings: readonly HealthFinding[];

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

@@ -7,6 +7,10 @@ export const HEALTH_ITEM_LIMIT = 25;
 const CANDIDATE_LIMIT = 5;
 /** Folder names that say where a spec lives, not what it is about. A domain with one of these names is likely a root folder. */
 const GENERIC_DOMAINS = new Set(['specs', 'spec', 'product', 'features', 'feature', 'tests', 'test', 'e2e', 'src', 'app', 'docs', 'overview', 'root', 'default']);
+/** The label a producer puts on a check to give its behavior (the promise) an id that outlives renames and moves. */
+export const BEHAVIOR_ID_LABEL = 'behavior-id';
+/** The label a producer puts on a check to give one example of a scenario outline an id of its own. */
+export const EXAMPLE_ID_LABEL = 'example-id';
 /** Parses `from>to` (as `?root=` gives it) into a mapping. Returns null when there is no `>`. Whitespace around each side is trimmed. */
 export function parseRootMapping(text) {
     const at = text.indexOf('>');
@@ -164,6 +168,21 @@ export function catalogHealth(model, roots = []) {
     const fallback = model.tests.filter(test => test.id === test.title);
     if (fallback.length)
         findings.push(finding('fallback-identity', 'info', 'These checks use their title as their id. A check is its spec path and id, so renaming one starts a new check and splits its history. Have the producer send a stable `id`.', fallback.map(test => ({ path: test.id })), fallback.length));
+    const split = [];
+    for (const label of [BEHAVIOR_ID_LABEL, EXAMPLE_ID_LABEL]) {
+        const byId = new Map();
+        for (const test of model.tests) {
+            const id = test.labels[label];
+            if (id)
+                byId.set(id, [...(byId.get(id) ?? []), test]);
+        }
+        for (const [id, tests] of [...byId].sort(([a], [b]) => byText(a, b))) {
+            if (tests.length > 1)
+                split.push({ path: `${label}=${id}`, candidates: tests.map(test => test.specPath ? `${test.specPath}  ${test.id}` : test.id).sort(byText).slice(0, CANDIDATE_LIMIT).map(path => ({ path, reason: `same ${label}` })) });
+        }
+    }
+    if (split.length)
+        findings.push(finding('declared-id-split', 'info', 'These declared ids sit on more than one check: the promise was renamed or moved, or two checks claim it. Atlas keeps the checks apart (a check is its spec path and id), so their histories are separate.', split));
     const unused = ordered.filter(mapping => !matched.get(mapping)?.size);
     if (unused.length)
         findings.push(finding('unused-root-mapping', 'warning', 'These root mappings matched no spec path. Check `from` against the paths in the report.', unused.map(mapping => ({ path: `${mapping.from}>${mapping.to}` }))));
@@ -213,10 +232,12 @@ export function catalogHealth(model, roots = []) {
         identity: {
             checks: model.tests.length,
             fallbackIdentity: fallback.length,
-            basis: 'A check is its spec path and its id. A check whose producer sent no id is known by its title, so a rename is a new check; a spec is known by its path, joined to another only by a declared root mapping.'
+            declaredBehaviorIds: model.tests.filter(test => test.labels[BEHAVIOR_ID_LABEL]).length,
+            declaredExampleIds: model.tests.filter(test => test.labels[EXAMPLE_ID_LABEL]).length,
+            basis: 'A check is its spec path and its id. A check whose producer sent no id is known by its title, so a rename is a new check; a spec is known by its path, joined to another only by a declared root mapping. The labels behavior-id and example-id are counted and checked for ids shared by several checks; they do not change which check a result belongs to.'
         },
         domains,
-        roots: ordered.map(mapping => ({ from: mapping.from, to: mapping.to, matched: matched.get(mapping)?.size ?? 0 })),
+        roots: ordered.map(mapping => ({ from: mapping.from, to: mapping.to, matched: matched.get(mapping)?.size ?? 0, ...(mapping.source ? { source: mapping.source } : {}) })),
         aliases,
         findings
     };

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

@@ -6,6 +6,13 @@ import { RecordedSpecs } from './recorded-specs.js';
 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 +39,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 +93,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 = {

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

@@ -34,6 +34,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'];
@@ -409,6 +416,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 +472,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 +601,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();

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

@@ -2255,6 +2255,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;
@@ -2329,6 +2334,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 +2365,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;
@@ -2586,6 +2597,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 +2640,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 +2671,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;
@@ -2808,6 +2826,8 @@ export declare const CatalogHealthSchema: z.ZodObject<{
     identity: z.ZodObject<{
         checks: z.ZodNumber;
         fallbackIdentity: z.ZodNumber;
+        declaredBehaviorIds: z.ZodOptional<z.ZodNumber>;
+        declaredExampleIds: z.ZodOptional<z.ZodNumber>;
         basis: z.ZodString;
     }, z.core.$loose>;
     domains: z.ZodArray<z.ZodObject<{
@@ -2818,6 +2838,10 @@ export declare const CatalogHealthSchema: z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         matched: z.ZodNumber;
+        source: z.ZodOptional<z.ZodEnum<{
+            request: "request";
+            configuration: "configuration";
+        }>>;
     }, z.core.$loose>>;
     aliases: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
@@ -2854,6 +2878,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";
@@ -2884,6 +2909,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;
@@ -3007,6 +3037,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;

package/dist/schema/src/api.js

@@ -432,13 +432,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=`'),
@@ -533,9 +538,15 @@ export const CatalogHealthSchema = z.looseObject({
         testsWithoutSpec: nonneg,
         explanation: z.array(z.string())
     }),
-    identity: z.looseObject({ checks: nonneg, fallbackIdentity: nonneg.describe('Checks whose id equals their title'), basis: z.string() }),
+    identity: z.looseObject({
+        checks: nonneg,
+        fallbackIdentity: nonneg.describe('Checks whose id equals their title'),
+        declaredBehaviorIds: nonneg.optional().describe('Checks that declare a `behavior-id` label'),
+        declaredExampleIds: nonneg.optional().describe('Checks that declare an `example-id` label'),
+        basis: z.string()
+    }),
     domains: z.array(z.looseObject({ name: z.string(), specs: nonneg })).describe('Specs per domain, most first'),
-    roots: z.array(z.looseObject({ from: z.string(), to: z.string(), matched: nonneg.describe('Distinct paths the mapping changed') })),
+    roots: z.array(z.looseObject({ from: z.string(), to: z.string(), matched: nonneg.describe('Distinct paths the mapping changed'), source: z.enum(['configuration', 'request']).optional().describe('Where it was declared: the server\'s `catalog.roots` setting or this request\'s `root` parameter') })),
     aliases: z.array(z.looseObject({ path: z.string(), sources: z.array(z.string()) })).describe('Logical specs seen under more than one original path, joined by a root mapping'),
     findings: z.array(z.looseObject({
         code: z.string().describe('An open set: treat a code you do not know as informational'),

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

@@ -66,6 +66,9 @@ export declare const ServerConfigSchema: z.ZodObject<{
         branches: z.ZodOptional<z.ZodArray<z.ZodString>>;
         ignoreModified: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    catalog: z.ZodDefault<z.ZodObject<{
+        roots: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     refreshSeconds: z.ZodDefault<z.ZodNumber>;
     limits: z.ZodDefault<z.ZodObject<{
         maxObjectMiB: z.ZodDefault<z.ZodNumber>;

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

@@ -50,6 +50,11 @@ export const ServerConfigSchema = z.strictObject({
         ignoreModified: z.boolean().optional().describe('Leave out layers from modified checkouts and unknown origins')
     })
         .default({}),
+    catalog: z
+        .strictObject({
+        roots: z.array(z.string().refine((value) => value.includes('>'), { message: 'Write a root mapping as from>to, e.g. ">specs/" (paths under `from` are the same specs as paths under `to`)' })).default([]).describe('Root mappings `from>to` that relate spec paths a producer publishes to the paths the specs are recorded under (an empty `from` matches every path). The catalog health report applies them to every request, beside any `root` the request adds')
+    })
+        .default({ roots: [] }),
     refreshSeconds: z.number().min(1).default(10).describe('How often the backends are looked at for layers written by something other than this server'),
     limits: z
         .strictObject({

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

@@ -30,6 +30,8 @@ export type AtlasServerOptions = {
     /** The built viewer. Without it, only the API is served. */
     readonly site?: string;
     readonly outlineBranch?: string;
+    /** Root mappings `from>to` the catalog health report always applies (the `catalog.roots` setting), beside any `root` a request adds. */
+    readonly catalogRoots?: readonly string[];
     readonly include?: (layer: LayerHeader) => boolean;
     readonly refreshMs?: number;
     readonly limits?: {

package/dist/server/src/app.js

@@ -26,7 +26,7 @@ import { reportStatus } from '../../reports/src/report-status.js';
 import { ReportIndex } from '../../reports/src/report-index.js';
 import { listRunSummaries, readRunFile } from '../../reports/src/run-bundle.js';
 import { latestSpecSet, readSpecBody } from '../../reports/src/spec-set.js';
-import { catalogHealth, healthMarkdown, parseRootMappings } from '../../reports/src/catalog-health.js';
+import { catalogHealth, healthMarkdown, parseRootMapping, parseRootMappings } from '../../reports/src/catalog-health.js';
 import { parseArtifactFilter } from '../../reports/src/artifact-query.js';
 import { filterUiCatalog, pageUiCatalog, parseUiCatalogQuery, uiCatalog, uiCatalogMarkdown } from '../../reports/src/ui-catalog.js';
 import { parseReliabilityScope, reliability, reliabilityMarkdown } from '../../reports/src/reliability.js';
@@ -451,12 +451,16 @@ function createProjectApplication(options) {
         const document = () => testCatalog(found, query);
         return answer(c, found.version, document, () => catalogMarkdown(document()), `tests|${new URL(c.req.url).search}|${wantsMarkdown(c)}`);
     });
+    const configuredRoots = (options.catalogRoots ?? []).flatMap(text => parseRootMapping(text) ?? []).map(mapping => ({ ...mapping, source: 'configuration' }));
     app.get('/api/reports/tests/health', async (c) => {
         if (!index.ready)
             return notReady(c);
         const found = await catalog();
         const params = new URL(c.req.url).searchParams;
-        const document = () => catalogHealth(found, parseRootMappings(params));
+        // The mappings the operator configured, then those this request adds (one already configured is not counted twice).
+        const requested = parseRootMappings(params).filter(mapping => !configuredRoots.some(item => item.from === mapping.from && item.to === mapping.to));
+        const roots = [...configuredRoots, ...requested.map(mapping => ({ ...mapping, source: 'request' }))];
+        const document = () => catalogHealth(found, roots);
         return answer(c, found.version, document, () => healthMarkdown(document()), `health|${params.getAll('root').join('\u0001')}|${wantsMarkdown(c)}`);
     });
     app.get('/api/reports/tests/history', async (c) => {

package/dist/server/src/config.js

@@ -57,6 +57,7 @@ export const SERVER_SETTINGS = [
     { summary: 'Whose specs the report is laid over', key: 'outlineBranch', flag: '--outline-branch <branch>', env: ['ATLAS_OUTLINE_BRANCH'], default: '`main`, then `master`, then the newest', example: { value: 'trunk', read: c => c.outlineBranch, expected: 'trunk' } },
     { summary: 'Only layers recorded on these branches take part', key: 'include.branches', flag: '--branch <name>` (repeatable)', env: ['ATLAS_ONLY_BRANCH'], default: 'all', example: { value: 'main', read: c => c.include.branches, expected: ['main'] } },
     { summary: 'Leave out layers from modified checkouts and unknown origins', key: 'include.ignoreModified', flag: '--ignore-modified', env: ['ATLAS_IGNORE_MODIFIED'], default: 'no', example: { value: '1', read: c => c.include.ignoreModified, expected: true } },
+    { summary: 'Root mappings `from>to` that join spec paths a producer publishes to the paths the specs are recorded under, for the catalog health report (comma-separated; an empty `from` matches every path)', key: 'catalog.roots', flag: null, env: ['ATLAS_CATALOG_ROOTS'], default: 'none', example: { value: '>specs/,apps/>specs/web/', read: c => c.catalog.roots, expected: ['>specs/', 'apps/>specs/web/'] } },
     { summary: 'How often (seconds) the backends are looked at for layers written by something else', key: 'refreshSeconds', flag: '--refresh <seconds>', env: ['ATLAS_REFRESH_SECONDS'], default: '`10`', example: { value: '30', read: c => c.refreshSeconds, expected: 30 } },
     { summary: 'Let anyone look, not upload', key: 'auth.anonymousRead', flag: '--anonymous-read', env: ['ATLAS_ANONYMOUS_READ'], default: 'no', example: { value: '1', read: c => c.anonymousRead, expected: true } },
     { summary: 'Listen publicly with no tokens (something in front signs people in)', key: 'auth.insecure', flag: '--insecure', env: ['ATLAS_INSECURE'], default: 'no', example: { value: '1', read: c => c.insecure, expected: true } },
@@ -151,6 +152,9 @@ export function loadServerConfig(argv, env, cwd, read = file => readFileSync(fil
             limits[key] = Number(env[variable]);
     }
     merged.limits = limits;
+    const roots = list(env.ATLAS_CATALOG_ROOTS);
+    if (roots.length)
+        merged.catalog = { ...raw.catalog, roots };
     if (flags.insecure || truthy(env.ATLAS_INSECURE))
         auth.insecure = true;
     if (flags['anonymous-read'] || truthy(env.ATLAS_ANONYMOUS_READ))

package/dist/server/src/main.js

@@ -56,6 +56,7 @@ export function serverOptionsOf(config, backends, log) {
         backends, write: S3_BACKEND_ID,
         tokens: config.tokens, anonymousRead: config.anonymousRead,
         ...(config.outlineBranch ? { outlineBranch: config.outlineBranch } : {}), ...(include ? { include } : {}),
+        ...(config.catalog.roots.length ? { catalogRoots: config.catalog.roots } : {}),
         runTimeoutMs: config.runTimeoutSeconds * 1000, runStallMs: config.runStallSeconds * 1000, refreshMs: config.refreshSeconds * 1000, limits: config.limits, heartbeatMs: config.heartbeatSeconds * 1000,
         ...(config.log && log ? { log } : {})
     };

package/dist/server/src/openapi.js

@@ -313,10 +313,10 @@ const BASE_OPERATIONS = [
             '',
             '`counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.',
             '',
-            'Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check\'s label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.'
+            'Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check\'s label `outline` names the outline its example belongs to; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. Send `format=markdown` for Markdown.'
         ].join('\n'),
         parameters: [
-            { name: 'root', in: 'query', description: 'A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.', schema: str, example: '>specs/' },
+            { name: 'root', in: 'query', description: 'A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.', schema: str, example: '>specs/' },
             { name: 'format', in: 'query', description: '`markdown` for a Markdown report instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
         ],
         responses: { '200': { ...json('The diagnostics.', 'CatalogHealth'), headers: { ETag: { description: 'Changes with the report, its history and the mappings.', schema: str } } }, '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }

package/docs/extending.md

@@ -30,7 +30,7 @@ carry any of these. Every one is optional.
 | `annotations[]` | Notes about the result: a warning, a deprecation, an accessibility finding, a coverage figure. |
 | `attempts[]` | Every try, when the check was retried. |
 | `tags[]` | Free labels to filter by: `smoke`, `payments`. |
-| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). |
+| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release, and `published-at` and `enriched-at` (epoch milliseconds or an ISO date) to show when it was published or enriched apart from when the checks ran (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). `behavior-id` and `example-id` declare a stable id for the behavior and for one example of an outline, and `outline` names the outline; the [catalog health](server.md#reading-the-report-as-an-agent) report counts them and names an id shared by several checks. They never change which check a result belongs to. |
 | `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. |

package/docs/reference/http-api.md

@@ -550,9 +550,9 @@ Diagnoses the report's metadata, so a domain filter or a coverage percentage can
 
 `counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.
 
-Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.
+Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. Send `format=markdown` for Markdown.
 
-- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.
 - `format` (query): `markdown` for a Markdown report instead of JSON.
 - `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
 
@@ -566,12 +566,12 @@ Diagnoses the report's metadata, so a domain filter or a coverage percentage can
 
 `counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.
 
-Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.
+Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. Send `format=markdown` for Markdown.
 
 Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
 
 - `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
-- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.
 - `format` (query): `markdown` for a Markdown report instead of JSON.
 
 Responses: `200` The diagnostics.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.

package/docs/reference/reports.md

@@ -806,6 +806,10 @@ Explains why the Specs and the Tests of a report may disagree, and what a produc
 - **Fallback identity.** A check whose id is its title has no stable id; renaming it starts a new check. Counted, not
   guessed at.
 
+- **Declared ids.** A producer may say what a check is with the labels `behavior-id` (the promise) and `example-id`
+  (one example of an outline). Atlas counts them and names ids that sit on more than one check; it does not join the
+  checks, because a check is still its spec path and id.
+
 It only reads: it never changes a status, a slot or a winner, so it cannot disagree with the report it describes.
 Optional label `outline` on a check names the scenario outline its example belongs to.
 
@@ -827,13 +831,30 @@ export const HEALTH_ITEM_LIMIT = …
 
 The most paths listed in one finding; its `count` is always the whole.
 
+#### `BEHAVIOR_ID_LABEL`
+
+```ts
+export const BEHAVIOR_ID_LABEL = …
+```
+
+The label a producer puts on a check to give its behavior (the promise) an id that outlives renames and moves.
+
+#### `EXAMPLE_ID_LABEL`
+
+```ts
+export const EXAMPLE_ID_LABEL = …
+```
+
+The label a producer puts on a check to give one example of a scenario outline an id of its own.
+
 #### `RootMapping`
 
 ```ts
-export type RootMapping = { readonly from: string; readonly to: string };
+export type RootMapping = { readonly from: string; readonly to: string; readonly source?: 'configuration' | 'request' };
 ```
 
-Declares that paths under `from` are the same specs as paths under `to`, e.g. `{ from: '', to: 'specs/' }`. Empty `from` matches every path.
+Declares that paths under `from` are the same specs as paths under `to`, e.g. `{ from: '', to: 'specs/' }`. Empty `from`
+matches every path. `source` says where it was declared (the server's configuration or the request); it changes nothing.
 
 #### `HealthItem`
 
@@ -860,6 +881,7 @@ export type HealthCode =
   | 'no-spec-definitions'
   | 'fallback-identity'
   | 'unused-root-mapping'
+  | 'declared-id-split'
   | 'spec-without-execution'
   | 'historical-only';
 ```
@@ -9556,6 +9578,17 @@ export const HISTORY_PER_TEST = …
 
 Recorded results kept per test, newest first. Older ones are counted in no statistic.
 
+#### `APPLICABILITY_LABELS`
+
+```ts
+export const APPLICABILITY_LABELS = …
+```
+
+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`.
+
 #### `TestResultEntry`
 
 ```ts
@@ -9584,6 +9617,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). */
@@ -9658,6 +9695,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;
 };
 ```
 

package/docs/reference/server.md

@@ -31,6 +31,8 @@ export type AtlasServerOptions = {
   /** The built viewer. Without it, only the API is served. */
   readonly site?: string;
   readonly outlineBranch?: string;
+  /** Root mappings `from>to` the catalog health report always applies (the `catalog.roots` setting), beside any `root` a request adds. */
+  readonly catalogRoots?: readonly string[];
   readonly include?: (layer: LayerHeader) => boolean;
   readonly refreshMs?: number;
   readonly limits?: { readonly maxObjectMiB?: number; readonly maxJsonMiB?: number; readonly maxStreams?: number };