@crvouga/atlas 0.4.0 → 0.6.0

package/dist/reports/src/keys.d.ts

@@ -1,6 +1,9 @@
 /**
- * Object-store key layout of the shared reports store. Historical recording addresses use
- * the full commit sha. Immutable report layers combine across those addresses:
+ * @module Commit-keyed object-store key layout
+ *
+ * Builds and validates the keys of the commit-addressed layout of the shared reports store. Historical recording
+ * addresses use the full commit sha. Immutable report layers (`layers/…`, see `docs/report-contract.md`) combine
+ * across those addresses:
  *
  *   index/<13-digit inverted start ms>-<sha>.json   one per published commit;
  *                                                   sorted keys = newest first
@@ -15,38 +18,53 @@
  * A source is one report bucket of one package (`libs-chess--part-2`).
  * Writers put a source's tests first and its `sources/` record last, so a
  * reader that sees the record can read every test it names.
+ *
+ * Every builder validates its inputs (a full 40-hex sha, path-safe segments) and throws on a bad one, so a key
+ * made here can never climb out of its prefix.
  */
 /**
  * Where the reports live in their bucket. Every reader and writer scopes its
  * store to it, so the keys below are relative to it.
  */
 export declare const REPORTS_ROOT_PREFIX = "spec-reports";
+/** The prefix of the per-commit catalog entries, `index/`. */
 export declare const COMMITS_INDEX_PREFIX = "index/";
+/** Whether the value is a full 40-digit lowercase hex commit sha (an abbreviated sha is not). */
 export declare function isCommitSha(value: string): boolean;
 /** One path segment the harness could have written (never `.` or `..`). */
 export declare function isKeySegment(value: string): boolean;
 /** A frame file relative to its test (`frames/f-0001.state.json`). */
 export declare function isFramePath(value: string): boolean;
-/** `libs/chess` + `part-2` → `libs-chess--part-2`. */
+/** The id of a source (one report bucket of one package): `libs/chess` + `part-2` → `libs-chess--part-2`. Throws `not a report source` when the result is not a safe key segment. */
 export declare function sourceId(packageDir: string, bucket: string): string;
+/** The catalog key of a commit, `index/<13-digit inverted start ms>-<sha>.json`: the time is inverted so a listing is newest first. Negative times count as 0. Throws for a sha that is not 40 hex digits. */
 export declare function commitIndexKey(sha: string, startedAtMs: number): string;
 /** The sha an index key names, or null for anything else. */
 export declare function shaOfIndexKey(key: string): string | null;
+/** The folder of everything recorded for a commit, `commits/<sha>/`. Throws for a sha that is not 40 hex digits. */
 export declare function commitPrefix(sha: string): string;
+/** The key of the commit's run record, `commits/<sha>/commit.json`. */
 export declare function commitKey(sha: string): string;
+/** The key of the stylesheet the commit's snapshots render with, `commits/<sha>/frame.css`. */
 export declare function frameCssKey(sha: string): string;
+/** The folder of a commit's source records, `commits/<sha>/sources/`. */
 export declare function sourcesPrefix(sha: string): string;
+/** The key of one source's record, `commits/<sha>/sources/<source>.json`; written last, after the source's tests. Throws `not a source` for an unsafe name. */
 export declare function sourceKey(sha: string, source: string): string;
 /** The source a `sources/` key names, or null for anything else. */
 export declare function sourceOfKey(sha: string, key: string): string | null;
+/** The folder of one recorded test, `commits/<sha>/tests/<source>/<testId>/`. Throws for an unsafe source or test id. */
 export declare function remoteTestPrefix(sha: string, source: string, testId: string): string;
+/** The key of a recorded test's report, `<test folder>/report.json`. */
 export declare function remoteTestReportKey(sha: string, source: string, testId: string): string;
+/** The key of a file a recorded test captured (a frame, a snapshot), inside its folder. A leading `/` is dropped; throws `not a frame file` for a path with an unsafe segment (`..`, empty or odd characters). */
 export declare function remoteTestFileKey(sha: string, source: string, testId: string, file: string): string;
 /**
  * The id a viewer shows for a test of a source (`libs-chess--part-2/monkey`):
  * unique across the commit, since two packages may both name a test `monkey`.
  */
 export declare function viewerTestId(source: string, testId: string): string;
+/** The inverse of {@link viewerTestId}: splits at the first `/`; null when either side is not a safe key segment. */
 export declare function splitViewerTestId(id: string): {
     readonly source: string;
     readonly testId: string;

package/dist/reports/src/keys.js

@@ -1,6 +1,9 @@
 /**
- * Object-store key layout of the shared reports store. Historical recording addresses use
- * the full commit sha. Immutable report layers combine across those addresses:
+ * @module Commit-keyed object-store key layout
+ *
+ * Builds and validates the keys of the commit-addressed layout of the shared reports store. Historical recording
+ * addresses use the full commit sha. Immutable report layers (`layers/…`, see `docs/report-contract.md`) combine
+ * across those addresses:
  *
  *   index/<13-digit inverted start ms>-<sha>.json   one per published commit;
  *                                                   sorted keys = newest first
@@ -15,6 +18,9 @@
  * A source is one report bucket of one package (`libs-chess--part-2`).
  * Writers put a source's tests first and its `sources/` record last, so a
  * reader that sees the record can read every test it names.
+ *
+ * Every builder validates its inputs (a full 40-hex sha, path-safe segments) and throws on a bad one, so a key
+ * made here can never climb out of its prefix.
  */
 /**
  * Where the reports live in their bucket. Every reader and writer scopes its
@@ -26,7 +32,9 @@ const SHA = /^[0-9a-f]{40}$/;
 const SEGMENT = /^[a-zA-Z0-9._-]+$/;
 /** Inverted start times sort newest first while there are 13-digit ms. */
 const INVERT_FROM = 9_999_999_999_999;
+/** The prefix of the per-commit catalog entries, `index/`. */
 export const COMMITS_INDEX_PREFIX = 'index/';
+/** Whether the value is a full 40-digit lowercase hex commit sha (an abbreviated sha is not). */
 export function isCommitSha(value) {
     return SHA.test(value);
 }
@@ -44,13 +52,14 @@ function assertSha(sha) {
         throw new Error(`report key needs a full 40-hex commit sha, got "${sha}"`);
     }
 }
-/** `libs/chess` + `part-2` → `libs-chess--part-2`. */
+/** The id of a source (one report bucket of one package): `libs/chess` + `part-2` → `libs-chess--part-2`. Throws `not a report source` when the result is not a safe key segment. */
 export function sourceId(packageDir, bucket) {
     const id = `${packageDir.replaceAll('/', '-')}--${bucket}`;
     if (!isKeySegment(id))
         throw new Error(`not a report source: "${id}"`);
     return id;
 }
+/** The catalog key of a commit, `index/<13-digit inverted start ms>-<sha>.json`: the time is inverted so a listing is newest first. Negative times count as 0. Throws for a sha that is not 40 hex digits. */
 export function commitIndexKey(sha, startedAtMs) {
     assertSha(sha);
     const inverted = String(INVERT_FROM - Math.max(0, Math.floor(startedAtMs)));
@@ -61,19 +70,24 @@ export function shaOfIndexKey(key) {
     const m = /^index\/\d{13}-([0-9a-f]{40})\.json$/.exec(key);
     return m === null ? null : (m[1] ?? null);
 }
+/** The folder of everything recorded for a commit, `commits/<sha>/`. Throws for a sha that is not 40 hex digits. */
 export function commitPrefix(sha) {
     assertSha(sha);
     return `commits/${sha}/`;
 }
+/** The key of the commit's run record, `commits/<sha>/commit.json`. */
 export function commitKey(sha) {
     return `${commitPrefix(sha)}commit.json`;
 }
+/** The key of the stylesheet the commit's snapshots render with, `commits/<sha>/frame.css`. */
 export function frameCssKey(sha) {
     return `${commitPrefix(sha)}frame.css`;
 }
+/** The folder of a commit's source records, `commits/<sha>/sources/`. */
 export function sourcesPrefix(sha) {
     return `${commitPrefix(sha)}sources/`;
 }
+/** The key of one source's record, `commits/<sha>/sources/<source>.json`; written last, after the source's tests. Throws `not a source` for an unsafe name. */
 export function sourceKey(sha, source) {
     if (!isKeySegment(source))
         throw new Error(`not a source: "${source}"`);
@@ -87,6 +101,7 @@ export function sourceOfKey(sha, key) {
     const source = key.slice(head.length, -'.json'.length);
     return isKeySegment(source) ? source : null;
 }
+/** The folder of one recorded test, `commits/<sha>/tests/<source>/<testId>/`. Throws for an unsafe source or test id. */
 export function remoteTestPrefix(sha, source, testId) {
     if (!isKeySegment(source))
         throw new Error(`not a source: "${source}"`);
@@ -94,9 +109,11 @@ export function remoteTestPrefix(sha, source, testId) {
         throw new Error(`not a test id: "${testId}"`);
     return `${commitPrefix(sha)}tests/${source}/${testId}/`;
 }
+/** The key of a recorded test's report, `<test folder>/report.json`. */
 export function remoteTestReportKey(sha, source, testId) {
     return `${remoteTestPrefix(sha, source, testId)}report.json`;
 }
+/** The key of a file a recorded test captured (a frame, a snapshot), inside its folder. A leading `/` is dropped; throws `not a frame file` for a path with an unsafe segment (`..`, empty or odd characters). */
 export function remoteTestFileKey(sha, source, testId, file) {
     const rel = file.replace(/^\/+/, '');
     if (!isFramePath(rel))
@@ -110,6 +127,7 @@ export function remoteTestFileKey(sha, source, testId, file) {
 export function viewerTestId(source, testId) {
     return `${source}/${testId}`;
 }
+/** The inverse of {@link viewerTestId}: splits at the first `/`; null when either side is not a safe key segment. */
 export function splitViewerTestId(id) {
     const slash = id.indexOf('/');
     if (slash < 0)

package/dist/reports/src/layer-axes.d.ts

@@ -1,18 +1,48 @@
+/**
+ * @module Environment axis of a layer
+ *
+ * Owns how a layer's `environment` (the client that was checked: `ios`, `desktop-web`, ...) is normalised to a stable
+ * slug, read from either the `environment` field or an `environment` parameter, and shown to people. The environment
+ * is part of the slot a check fills, so two spellings of one client must normalise to one id or their results would
+ * never replace each other; an unrecognised name is kept as its own slug rather than rejected.
+ *
+ * @see docs/report-contract.md
+ */
 import type { LayerParameters, LayerSummary } from './layer-types.js';
 /**
- * Clients a product is checked on. Any other recorded name is kept, so a new
+ * The environments Atlas names and labels out of the box. Any other recorded name is kept, so a new
  * client layers beside these instead of being dropped or renamed away.
  */
 export declare const REPORT_ENVIRONMENTS: readonly ["desktop-web", "mobile-web", "ios", "android"];
-/** A stable environment id. Blank means the layer did not say, so older layers still compose. */
+/**
+ * Turns any spelling of a client name into a stable lowercase slug, or `null` when none was given.
+ *
+ * Trims, lowercases, turns whitespace and underscores into `-`, drops every other character outside `a-z0-9-`,
+ * collapses repeated `-`, then maps known aliases (`iPhone` and `iPad` to `ios`, `mobile browser` to `mobile-web`,
+ * `desktop` to `desktop-web`). A name with no alias is returned as its slug. `null`, `undefined` and a value that
+ * slugs to nothing return `null`, which means "the layer did not say", so older layers still compose.
+ *
+ * @example
+ * normalizeEnvironment('Desktop Web'); // 'desktop-web'
+ * normalizeEnvironment('iPhone'); // 'ios'
+ * normalizeEnvironment('Smart TV'); // 'smart-tv'
+ * normalizeEnvironment('  '); // null
+ */
 export declare function normalizeEnvironment(value: string | null | undefined): string | null;
 /**
- * Environment is its own axis. A layer may name it on the field or as a
- * parameter; the parameter is then not also a free choice.
+ * Splits a layer into the two slot axes it fills: its normalised environment and its remaining parameters.
+ *
+ * The environment is the layer's `environment` field, or when that is `null` or absent the `environment` parameter
+ * (an empty-string field does not fall back to the parameter). The `environment` parameter is always removed from
+ * the returned `parameters`, so it is never both an environment and a free choice that splits the slot twice.
  */
 export declare function layerPlace(summary: Pick<LayerSummary, 'environment' | 'parameters'>): {
     environment: string | null;
     parameters: LayerParameters;
 };
-/** How an environment id reads in the report. */
+/**
+ * The human label of an environment id: `Desktop web`, `Mobile web`, `iOS`, `Android` for the known ids,
+ * `Unspecified` for a missing one, and otherwise the id with its first word capitalised and `-` shown as a space
+ * (`smart-tv` reads `Smart tv`).
+ */
 export declare function environmentLabel(id: string | null | undefined): string;

package/dist/reports/src/layer-axes.js

@@ -1,5 +1,5 @@
 /**
- * Clients a product is checked on. Any other recorded name is kept, so a new
+ * The environments Atlas names and labels out of the box. Any other recorded name is kept, so a new
  * client layers beside these instead of being dropped or renamed away.
  */
 export const REPORT_ENVIRONMENTS = ['desktop-web', 'mobile-web', 'ios', 'android'];
@@ -16,7 +16,20 @@ const ALIASES = {
     ipad: 'ios',
     android: 'android',
 };
-/** A stable environment id. Blank means the layer did not say, so older layers still compose. */
+/**
+ * Turns any spelling of a client name into a stable lowercase slug, or `null` when none was given.
+ *
+ * Trims, lowercases, turns whitespace and underscores into `-`, drops every other character outside `a-z0-9-`,
+ * collapses repeated `-`, then maps known aliases (`iPhone` and `iPad` to `ios`, `mobile browser` to `mobile-web`,
+ * `desktop` to `desktop-web`). A name with no alias is returned as its slug. `null`, `undefined` and a value that
+ * slugs to nothing return `null`, which means "the layer did not say", so older layers still compose.
+ *
+ * @example
+ * normalizeEnvironment('Desktop Web'); // 'desktop-web'
+ * normalizeEnvironment('iPhone'); // 'ios'
+ * normalizeEnvironment('Smart TV'); // 'smart-tv'
+ * normalizeEnvironment('  '); // null
+ */
 export function normalizeEnvironment(value) {
     if (value == null)
         return null;
@@ -26,8 +39,11 @@ export function normalizeEnvironment(value) {
     return ALIASES[slug] ?? slug;
 }
 /**
- * Environment is its own axis. A layer may name it on the field or as a
- * parameter; the parameter is then not also a free choice.
+ * Splits a layer into the two slot axes it fills: its normalised environment and its remaining parameters.
+ *
+ * The environment is the layer's `environment` field, or when that is `null` or absent the `environment` parameter
+ * (an empty-string field does not fall back to the parameter). The `environment` parameter is always removed from
+ * the returned `parameters`, so it is never both an environment and a free choice that splits the slot twice.
  */
 export function layerPlace(summary) {
     const { environment: named, ...rest } = summary.parameters;
@@ -39,7 +55,11 @@ const LABELS = {
     ios: 'iOS',
     android: 'Android',
 };
-/** How an environment id reads in the report. */
+/**
+ * The human label of an environment id: `Desktop web`, `Mobile web`, `iOS`, `Android` for the known ids,
+ * `Unspecified` for a missing one, and otherwise the id with its first word capitalised and `-` shown as a space
+ * (`smart-tv` reads `Smart tv`).
+ */
 export function environmentLabel(id) {
     if (!id)
         return 'Unspecified';

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

@@ -1,5 +1,32 @@
+/**
+ * @module Layer catalog of one backend
+ *
+ * Lists what one backend holds as catalog entries (immutable layers under `layers/index/`, and commit-keyed
+ * recordings written before layers existed) and turns one entry into the layer summaries it stands for. It only
+ * reads: opening Atlas never rewrites a store. Whether a backend can be read at all, and how entries from several
+ * backends combine, is decided by the callers (`compose.ts`, `layers-route.ts`).
+ *
+ * @see docs/report-contract.md
+ */
 import type { ObjectStore } from './object-store.js';
 import type { LayerSummary } from './layer-types.js';
-/** Read existing recordings in place; opening Atlas never rewrites the evidence store. */
+/**
+ * Lists one backend's catalog entries as opaque strings to pass to `catalogLayers`.
+ *
+ * An entry is `layer:<key>` for each key under `layers/index/` (listed newest first, in the store's own key order),
+ * followed by `commit:<sha>` for every 40-hex commit named by a key under `versions/` or `index/` (a store written
+ * before layers existed, sorted by sha). Only lists keys; reads no layer. A store that cannot be listed throws.
+ * Existing recordings are read in place and never rewritten.
+ */
 export declare function catalogEntries(store: ObjectStore): Promise<readonly string[]>;
+/**
+ * Reads the layer summaries one catalog entry from `catalogEntries` stands for.
+ *
+ * A `layer:` entry yields exactly one summary (the layer the catalog entry names, without its bundle) and throws
+ * when the entry is not JSON, names no layer, the layer is missing, or the layer cannot be parsed, so the caller can
+ * report it as a notice instead of counting it as a pass. A `commit:` entry yields the older commit-keyed
+ * recordings of that sha: one summary per stored part (`part-<sha>-<id>`) and one per stored source
+ * (`source-<sha>-<id>`); a part whose checks a source already carries, and that has no parameters, is dropped so the
+ * same evidence is not counted twice. Those ids are mutable addresses, not content digests.
+ */
 export declare function catalogLayers(store: ObjectStore, entry: string): Promise<readonly LayerSummary[]>;

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

@@ -7,12 +7,29 @@ import { readStoredSource } from './source-content.js';
 import { sourceParts } from './source-part.js';
 import { LAYER_INDEX, readLayer, layerSummary } from './layer-store.js';
 import { eachLimited } from './completion-order.js';
-/** Read existing recordings in place; opening Atlas never rewrites the evidence store. */
+/**
+ * Lists one backend's catalog entries as opaque strings to pass to `catalogLayers`.
+ *
+ * An entry is `layer:<key>` for each key under `layers/index/` (listed newest first, in the store's own key order),
+ * followed by `commit:<sha>` for every 40-hex commit named by a key under `versions/` or `index/` (a store written
+ * before layers existed, sorted by sha). Only lists keys; reads no layer. A store that cannot be listed throws.
+ * Existing recordings are read in place and never rewritten.
+ */
 export async function catalogEntries(store) {
     const [layers, versions, commits] = await Promise.all([store.listKeys(LAYER_INDEX), store.listKeys('versions/'), store.listKeys('index/')]);
     const shas = new Set([...versions, ...commits].flatMap(key => /([0-9a-f]{40})\.json$/.exec(key)?.[1] ?? []));
     return [...layers.map(key => `layer:${key}`), ...[...shas].sort().map(sha => `commit:${sha}`)];
 }
+/**
+ * Reads the layer summaries one catalog entry from `catalogEntries` stands for.
+ *
+ * A `layer:` entry yields exactly one summary (the layer the catalog entry names, without its bundle) and throws
+ * when the entry is not JSON, names no layer, the layer is missing, or the layer cannot be parsed, so the caller can
+ * report it as a notice instead of counting it as a pass. A `commit:` entry yields the older commit-keyed
+ * recordings of that sha: one summary per stored part (`part-<sha>-<id>`) and one per stored source
+ * (`source-<sha>-<id>`); a part whose checks a source already carries, and that has no parameters, is dropped so the
+ * same evidence is not counted twice. Those ids are mutable addresses, not content digests.
+ */
 export async function catalogLayers(store, entry) {
     if (entry.startsWith('layer:')) {
         const raw = await readUtf8(store, entry.slice(6));

package/dist/reports/src/layer-merge.d.ts

@@ -1,43 +1,132 @@
+/**
+ * @module Layer composition: slots, winners and de-duplication
+ *
+ * The pure core of the composition rule: it flattens layers into rows, computes the slot key each row fills, decides
+ * which result wins a slot, and removes the duplicate copies of one immutable layer held by several backends. It does
+ * no I/O. The winner order (a completed result beats an unfinished one, then the newer `recordedAtMs`, then
+ * `failed` over `passed` and `running` over `not-run`, then the greater `layerId|backendId`) is a total order and is
+ * part of the stable report contract: changing it changes every report. `report-index.ts` folds layers into the same
+ * winners incrementally and must always equal `combineEvidence`.
+ *
+ * @see docs/report-contract.md#how-layers-compose
+ */
 import type { EvidenceStatus, SpecEntry } from './explorer-types.js';
 import type { LayerEvidence, LayerHeader, LayerRow, StatusCounts } from './evidence-types.js';
 import type { LayerParameters, LayerSummary, ReportOutline } from './layer-types.js';
-/** Advisory identity, never a cryptographic integrity check. */
+/**
+ * A short, deterministic fingerprint of a spec's text, shaped `<length>:<hash>:<hash>` (the length in UTF-16 code
+ * units and two 32-bit hashes in hex). A layer records it per spec so a reader can warn when the spec changed
+ * since ("Potentially outdated: spec changed"). Advisory identity only: it is not collision resistant and never an
+ * integrity check.
+ */
 export declare function textFingerprint(text: string): string;
+/**
+ * Normalises a check's or spec's path to its `specs/<path inside the specs directory>` form, so the same spec
+ * recorded from different checkouts is one spec.
+ *
+ * Converts `\` to `/`, drops a leading `./`, and drops everything before the first path segment named exactly
+ * `specs`. A path with no such segment is returned unchanged (apart from the first two steps).
+ *
+ * @example
+ * specPath('packages/app/specs/join.feature'); // 'specs/join.feature'
+ * specPath('myspecs/x.feature'); // 'myspecs/x.feature'
+ */
 export declare function specPath(path: string): string;
+/** Serialises parameters as JSON key/value pairs sorted by key, so equal parameter sets compare equal as strings. */
 export declare function parameterKey(parameters: LayerParameters): string;
-/** Recorded timings qualify an outcome. They are a result of their own only when nothing else checked the same thing. */
+/** Whether a part `kind` only qualifies an outcome (today only `performance`) and so is not counted as a check when anything else is recorded. */
 export declare function isDiagnosticKind(kind: string): boolean;
+/** A fresh status tally with every status at zero. */
 export declare function emptyCounts(): Record<EvidenceStatus, number>;
-/** Outcomes of a layer: its checks, without the timings that only qualify them. */
+/**
+ * Counts rows by status, leaving out the diagnostic rows (see `isDiagnosticKind`) that only qualify an outcome.
+ * When every row is diagnostic they are counted, so a layer of timings alone is not empty.
+ */
 export declare function outcomeCounts(rows: readonly LayerRow[]): StatusCounts;
-/** A layer as the explorer reads it: its origin, and each check as one row. */
+/**
+ * Flattens a layer into what composition reads: a header (origin, normalised environment and parameters, counts,
+ * evidence summary), one row per check of every part, and the spec fingerprints it recorded.
+ *
+ * `backend` is the id of the backend the layer was read from; it only breaks ties between copies. Paths in rows and
+ * fingerprints go through `specPath`. When the layer has a recorded `source`, a row whose check id matches one of its
+ * tests also gets that test's `testId`, `variant` and duration. The result is `live: false`: a layer read from a
+ * store is never a run still in progress.
+ */
 export declare function layerEvidence(summary: LayerSummary, backend: string): LayerEvidence;
+/** The winning result of one slot: which layer and row it came from, and whether it may be stale. */
 export type EvidenceResult = {
-    /** One producer's check of one kind under one parameter set. */
+    /** One producer's check of one kind under one parameter set. See `resultKey`. */
     readonly key: string;
-    /** The check itself, whatever kind of evidence and parameters describe it. */
+    /** The check itself, whatever kind of evidence and parameters describe it. See `slotKey`. */
     readonly slot: string;
+    /** The layer that recorded this result. */
     readonly layer: LayerHeader;
+    /** The check as recorded. */
     readonly row: LayerRow;
+    /** The layer's parameters other than the environment. */
     readonly parameters: LayerParameters;
+    /** Why the result may be out of date, or `null` when nothing suggests it. Advisory: never changes the status. */
     readonly warning: string | null;
 };
+/**
+ * Whether `next` should take the slot currently held by `prior`: the winner rule of the report contract.
+ *
+ * In order: a completed result (`passed`, `failed`) beats an unfinished one (`running`, `not-run`) whatever their
+ * times; otherwise the greater `recordedAtMs` wins; at the same time `failed` beats `passed` and `running` beats
+ * `not-run`; at the same status the greater `layerId|backendId` wins. The last step makes the order total, so the
+ * answer never depends on the order results are offered in. Returns `false` for two identical results.
+ */
+export declare function replaces(next: EvidenceResult, prior: EvidenceResult): boolean;
+/** The winners of every slot, grouped under the spec of the current outline they belong to. */
 export type CombinedEvidence = {
+    /** One entry per spec of the outline, in outline order (a spec with no results has an empty list). */
     readonly specs: readonly {
         readonly spec: SpecEntry;
         readonly results: EvidenceResult[];
     }[];
+    /** Winners whose spec path is absent or not in the outline (a removed spec keeps its evidence here). */
     readonly unassigned: EvidenceResult[];
 };
-/** One linear pass. The newest completed result wins only its own check, environment and parameter slot. */
+/**
+ * Lays layers over the outline of current specs and returns the winner of every slot.
+ *
+ * One linear pass over the rows of the layers (after `distinctEvidence`). The slot is producer, kind, spec path,
+ * check id, environment and parameters; `replaces` picks the winner, so the result does not depend on the order of
+ * `layers`. Branch, sha, backend and run never split a slot. Each result carries a freshness `warning`, computed
+ * against `outline`, that does not affect which result wins.
+ *
+ * @see docs/report-contract.md#how-layers-compose
+ */
 export declare function combineEvidence(outline: ReportOutline, layers: readonly LayerEvidence[]): CombinedEvidence;
+/**
+ * The key of the slot a row fills: a JSON array of producer, kind, spec path (`''` when none), check id, environment
+ * (`''` when none) and the sorted parameters. Two results with the same key compete; the winner is `replaces`.
+ */
+export declare function resultKey(layer: Pick<LayerHeader, 'producer' | 'environment' | 'parameters'>, row: Pick<LayerRow, 'kind' | 'specPath' | 'id'>): string;
+/**
+ * `resultKey` for every row of one layer, which share all but three parts of it. The strings are exactly
+ * those `resultKey` makes (they are keys that persist in no store, but two ways of making one must agree),
+ * without sorting and writing the layer's parameters once per check.
+ */
+export declare function layerResultKeys(layer: Pick<LayerHeader, 'producer' | 'environment' | 'parameters'>): (row: Pick<LayerRow, 'kind' | 'specPath' | 'id'>) => string;
+/** The key of a check regardless of producer, environment and parameters: a JSON array of its spec path and check id. */
 export declare function slotKey(path: string, id: string): string;
-/** Suppress the mutable address of an execution already archived as an immutable layer. */
+/**
+ * De-duplicates layer headers: the same layer held by several backends is one layer.
+ *
+ * Suppresses the mutable address of an execution already archived as an immutable layer. An
+ * immutable layer (64-hex id) held by several backends is one layer, reported by the backend whose id sorts
+ * first, whatever order they were read in. A mutable one is its backend's own and is kept once per backend.
+ * Returns the survivors, not necessarily in input order.
+ */
 export declare function distinctHeaders<T extends {
     readonly id: string;
     readonly execution: string;
+    readonly backend?: string;
 }>(layers: readonly T[]): T[];
+/** Keeps, in input order, only the layers `distinctHeaders` keeps, and each `backend|id` once. */
 export declare function distinctEvidence(layers: readonly LayerEvidence[]): LayerEvidence[];
-/** Suppress the mutable address of an execution already archived as an immutable layer. */
+/** Drops each mutable layer whose execution is already archived as an immutable one, and keeps one summary per id. */
 export declare function distinctLayers(layers: readonly LayerSummary[]): LayerSummary[];
+/** A string equal for the mutable and the archived address of one execution: its producer, sha, time and parts. */
 export declare function layerExecutionKey(layer: LayerSummary): string;