@crvouga/atlas 0.4.0 → 0.6.0

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

@@ -1,5 +1,11 @@
+import { summarizeEvidence } from './evidence-detail.js';
 import { layerPlace } from './layer-axes.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 function textFingerprint(text) {
     let a = 2166136261, b = 5381;
     for (let i = 0; i < text.length; i++) {
@@ -8,20 +14,37 @@ export function textFingerprint(text) {
     }
     return `${text.length}:${(a >>> 0).toString(16)}:${(b >>> 0).toString(16)}`;
 }
+/**
+ * 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 function specPath(path) {
-    return path.replaceAll('\\', '/').replace(/^\.\//, '').replace(/^.*?(?=specs\/)/, '');
+    // Up to the first folder named exactly `specs`: `myspecs/x` is not in one.
+    return path.replaceAll('\\', '/').replace(/^\.\//, '').replace(/^(?:.*?\/)?(?=specs\/)/, '');
 }
+/** Serialises parameters as JSON key/value pairs sorted by key, so equal parameter sets compare equal as strings. */
 export function parameterKey(parameters) {
     return JSON.stringify(Object.entries(parameters).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
 }
-/** 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 function isDiagnosticKind(kind) {
     return kind === 'performance';
 }
+/** A fresh status tally with every status at zero. */
 export function emptyCounts() {
     return { passed: 0, failed: 0, running: 0, 'not-run': 0 };
 }
-/** 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 function outcomeCounts(rows) {
     const outcomes = rows.some(row => !isDiagnosticKind(row.kind)) ? rows.filter(row => !isDiagnosticKind(row.kind)) : rows;
     const counts = emptyCounts();
@@ -29,28 +52,49 @@ export function outcomeCounts(rows) {
         counts[row.status] += 1;
     return counts;
 }
-/** 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 function layerEvidence(summary, backend) {
     const place = layerPlace(summary);
     const source = summary.source;
     const tests = new Map(source?.tests.map(test => [`${source.source}/${test.testId}`, test]) ?? []);
-    const rows = summary.parts.flatMap(part => part.checks.map(check => {
-        const test = tests.get(check.id);
-        const variant = test ? { system: test.system, runtime: test.runtime, seed: test.seed } : {};
-        return {
-            kind: part.kind,
-            id: check.id,
-            title: check.title,
-            status: check.status,
-            specPath: check.specPath ? specPath(check.specPath) : null,
-            detail: check.detail,
-            measurements: check.measurements,
-            testId: test?.testId ?? null,
-            variant,
-            durationMs: test?.durationMs ?? null,
-        };
-    }));
+    // A layer's checks repeat a handful of spec paths; each is normalized once.
+    const normalized = new Map();
+    const specOf = (path) => {
+        let found = normalized.get(path);
+        if (found === undefined)
+            normalized.set(path, found = specPath(path));
+        return found;
+    };
+    const rows = [];
+    for (const part of summary.parts) {
+        for (const check of part.checks) {
+            const test = tests.get(check.id);
+            const evidence = summarizeEvidence(check);
+            rows.push({
+                kind: part.kind,
+                id: check.id,
+                title: check.title,
+                status: check.status,
+                specPath: check.specPath ? specOf(check.specPath) : null,
+                detail: check.detail,
+                measurements: check.measurements,
+                testId: test?.testId ?? null,
+                variant: test ? { system: test.system, runtime: test.runtime, seed: test.seed } : {},
+                durationMs: test?.durationMs ?? check.durationMs ?? null,
+                ...(evidence ? { evidence } : {}),
+            });
+        }
+    }
     const recording = summary.recording;
+    const layerSummaryEvidence = summarizeEvidence(summary, ...summary.parts);
     const layer = {
         ...(summary.freshness ? { freshness: summary.freshness } : {}),
         id: summary.id,
@@ -67,6 +111,7 @@ export function layerEvidence(summary, backend) {
         live: false,
         counts: outcomeCounts(rows),
         execution: textFingerprint(layerExecutionKey(summary)),
+        ...(layerSummaryEvidence ? { evidence: layerSummaryEvidence } : {}),
     };
     const fingerprints = {};
     for (const spec of summary.specs)
@@ -74,6 +119,12 @@ export function layerEvidence(summary, backend) {
             fingerprints[specPath(spec.path)] = spec.fingerprint;
     return { id: summary.id, layer, rows, fingerprints };
 }
+/**
+ * The freshness warning for one result, or `null` when it is current. Checked in this order: a live run has none;
+ * a `modified` or `unknown` layer; a spec that is not in the outline; a missing fingerprint on either side; a
+ * fingerprint that differs from the current spec; related files that changed; a layer sha that differs from the
+ * outline's (or either absent). Advisory only: a warning never changes a status.
+ */
 function warning(layer, path, current, outline, recorded, relatedChanged) {
     if (layer.live)
         return null;
@@ -97,8 +148,15 @@ const RANK = { passed: 0, 'not-run': 1, running: 2, failed: 3 };
 function completed(status) {
     return status === 'passed' || status === 'failed';
 }
-/** A newer completed result takes its slot. An unfinished one never replaces a completed one, and a tie fails. */
-function replaces(next, prior) {
+/**
+ * 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 function replaces(next, prior) {
     const done = completed(next.row.status);
     const priorDone = completed(prior.row.status);
     if (done !== priorDone)
@@ -107,9 +165,22 @@ function replaces(next, prior) {
         return next.layer.recordedAtMs > prior.layer.recordedAtMs;
     if (RANK[next.row.status] !== RANK[prior.row.status])
         return RANK[next.row.status] > RANK[prior.row.status];
-    return next.layer.id > prior.layer.id;
+    // The last tie-break is total, so no input order can change the answer.
+    return layerOrder(next.layer) > layerOrder(prior.layer);
+}
+function layerOrder(layer) {
+    return `${layer.id}|${layer.backend}`;
 }
-/** 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 function combineEvidence(outline, layers) {
     const specs = new Map(outline.specs.map(spec => [specPath(spec.path), { spec, results: [] }]));
     const changed = new Set(outline.changedFiles.map(specPath));
@@ -117,12 +188,13 @@ export function combineEvidence(outline, layers) {
     for (const { layer, rows, fingerprints } of distinctEvidence(layers)) {
         const scope = layer.packageDir;
         const related = outline.changedFiles.some(file => scope ? file.startsWith(`${scope}/`) : !specPath(file).startsWith('specs/'));
+        const keyOf = layerResultKeys(layer);
         for (const row of rows) {
             // Environment and the layer's other choices split the slot. A harness
             // seed does not: a focused rerun replaces the check it repeated.
             const parameters = layer.parameters;
             const path = row.specPath ?? '';
-            const key = JSON.stringify([layer.producer, row.kind, path, row.id, layer.environment ?? '', parameterKey(parameters)]);
+            const key = keyOf(row);
             const result = { key, slot: slotKey(path, row.id), layer, row, parameters, warning: warning(layer, path, specs.get(path)?.spec, outline, fingerprints[path], related || changed.has(path)) };
             const prior = winners.get(key);
             if (!prior || replaces(result, prior))
@@ -134,26 +206,70 @@ export function combineEvidence(outline, layers) {
         (specs.get(result.row.specPath ?? '')?.results ?? unassigned).push(result);
     return { specs: [...specs.values()], unassigned };
 }
+/**
+ * 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 function resultKey(layer, row) {
+    return JSON.stringify([layer.producer, row.kind, row.specPath ?? '', row.id, layer.environment ?? '', parameterKey(layer.parameters)]);
+}
+/**
+ * `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 function layerResultKeys(layer) {
+    const producer = JSON.stringify(layer.producer);
+    const tail = `,${JSON.stringify(layer.environment ?? '')},${JSON.stringify(parameterKey(layer.parameters))}]`;
+    return row => `[${producer},${JSON.stringify(row.kind)},${JSON.stringify(row.specPath ?? '')},${JSON.stringify(row.id)}${tail}`;
+}
+/** The key of a check regardless of producer, environment and parameters: a JSON array of its spec path and check id. */
 export function slotKey(path, id) {
     return JSON.stringify([path, id]);
 }
+/** Whether a layer id is a content digest (64 lowercase hex digits), that is an immutable layer rather than a mutable address. */
 function archived(id) {
     return /^[0-9a-f]{64}$/.test(id);
 }
-/** 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 function distinctHeaders(layers) {
     const kept = new Set(layers.filter(layer => archived(layer.id)).map(layer => layer.execution));
-    return [...new Map(layers.filter(layer => archived(layer.id) || !kept.has(layer.execution)).map(layer => [layer.id, layer])).values()];
+    const chosen = new Map();
+    for (const layer of layers) {
+        if (!archived(layer.id) && kept.has(layer.execution))
+            continue;
+        const key = archived(layer.id) ? layer.id : `${layer.backend ?? ''}|${layer.id}`;
+        const prior = chosen.get(key);
+        if (!prior || (layer.backend ?? '') < (prior.backend ?? ''))
+            chosen.set(key, layer);
+    }
+    return [...chosen.values()];
 }
+/** Keeps, in input order, only the layers `distinctHeaders` keeps, and each `backend|id` once. */
 export function distinctEvidence(layers) {
-    const kept = new Set(distinctHeaders(layers.map(entry => entry.layer)).map(layer => layer.id));
-    return [...new Map(layers.filter(entry => kept.has(entry.id)).map(entry => [entry.id, entry])).values()];
+    const kept = new Set(distinctHeaders(layers.map(entry => entry.layer)).map(layer => `${layer.backend}|${layer.id}`));
+    const emitted = new Set();
+    return layers.filter(entry => {
+        const key = `${entry.layer.backend}|${entry.id}`;
+        if (!kept.has(key) || emitted.has(key))
+            return false;
+        emitted.add(key);
+        return true;
+    });
 }
-/** 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 function distinctLayers(layers) {
     const kept = new Set(layers.filter(layer => archived(layer.id)).map(layerExecutionKey));
     return [...new Map(layers.filter(layer => archived(layer.id) || !kept.has(layerExecutionKey(layer))).map(layer => [layer.id, layer])).values()];
 }
+/** A string equal for the mutable and the archived address of one execution: its producer, sha, time and parts. */
 export function layerExecutionKey(layer) {
     return JSON.stringify([layer.producer, layer.sha, layer.recordedAtMs, layer.parts]);
 }

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

@@ -1,6 +1,24 @@
+/**
+ * @module Archiving a recorded run as a layer
+ *
+ * Turns one published source (a package bucket of recorded statechart or test runs with timelines and screenshots)
+ * into an immutable layer, so it composes with every other layer. It is the bridge from the commit-keyed recordings
+ * to the layer store and is called only by `publishSource`.
+ */
 import type { HtmlReportTest } from './recording-bundle.js';
 import { type BundleIndex } from './bundle.js';
 import type { ObjectStore } from './object-store.js';
 import type { SourceRecord } from './protocol.js';
 import type { PublishSourceArgs } from './publish.js';
+/**
+ * Writes `source` and its recorded files as an immutable layer and returns it (see `publishLayerBundle`).
+ *
+ * The layer is recorded at the later of the commit's start and the source's `updatedAtMs`, with the commit's branch and
+ * run URL, the commit's spec inventory (empty when none), the source's parts, `parameters` from `args`, the environment
+ * normalised from `args.environment` or the `environment` parameter, and `recording: { type: 'layer' }`. Its bundle
+ * holds the commit's `frame.css` and each test's `tests/<testId>/report.json` and `tests/<testId>/files/<file>`.
+ * `bundle`, when given, is an index of those files already written for this source (keys under
+ * `commits/<sha>/tests/<source>/`); then only `frame.css` is written here and the index is re-keyed to the layer's
+ * layout. The same inputs give the same layer, so publishing twice is harmless. Store errors reject.
+ */
 export declare function archiveSourceLayer(store: ObjectStore, args: PublishSourceArgs, source: SourceRecord, tests: readonly HtmlReportTest[], bundle?: BundleIndex): Promise<import('./layer-types.js').ReportLayer>;

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

@@ -5,6 +5,17 @@ import { readInventory } from './spec-inventory.js';
 import { sourceParts } from './source-part.js';
 import { sourceEntries } from './source-entries.js';
 import { publishLayerBundle } from './layer-store.js';
+/**
+ * Writes `source` and its recorded files as an immutable layer and returns it (see `publishLayerBundle`).
+ *
+ * The layer is recorded at the later of the commit's start and the source's `updatedAtMs`, with the commit's branch and
+ * run URL, the commit's spec inventory (empty when none), the source's parts, `parameters` from `args`, the environment
+ * normalised from `args.environment` or the `environment` parameter, and `recording: { type: 'layer' }`. Its bundle
+ * holds the commit's `frame.css` and each test's `tests/<testId>/report.json` and `tests/<testId>/files/<file>`.
+ * `bundle`, when given, is an index of those files already written for this source (keys under
+ * `commits/<sha>/tests/<source>/`); then only `frame.css` is written here and the index is re-keyed to the layer's
+ * layout. The same inputs give the same layer, so publishing twice is harmless. Store errors reject.
+ */
 export async function archiveSourceLayer(store, args, source, tests, bundle) {
     const [commit, inventory, css] = await Promise.all([readCommit(store, args.sha), readInventory(store, args.sha), readFrameCss(store, args.sha)]);
     const recordedAtMs = Math.max(commit?.startedAtMs ?? 0, source.updatedAtMs);

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

@@ -1,10 +1,52 @@
+/**
+ * @module Layer storage
+ *
+ * Reads and writes layers in an `ObjectStore`: the immutable manifest at `layers/manifests/<id>.json`, the catalog
+ * entry at `layers/index/<inverted-time>-<id>.json`, and the captured files under `layers/blobs/`. A layer is written
+ * bottom up (files, then manifest, then catalog entry) so a reader never meets an entry whose content has not arrived,
+ * and every key is derived from content so two producers never write different bytes to one key.
+ *
+ * @see docs/report-contract.md#where-bytes-go
+ */
 import { type BundleIndex, type BundleEntry } from './bundle.js';
 import type { ObjectStore } from './object-store.js';
 import type { LayerSummary, ReportLayer } from './layer-types.js';
+/** The key prefix under which every layer's catalog entry is written. */
 export declare const LAYER_INDEX = "layers/index/";
+/** The store key of a layer's manifest. Throws `Invalid layer id` unless `id` is 64 lowercase hex digits, so an id can never address another key. */
 export declare function layerKey(id: string): string;
+/**
+ * Writes a layer whose captured files arrive as a stream, then its manifest and catalog entry, and returns it.
+ *
+ * The files are packed into content-addressed blobs under `layers/blobs/` first (`writeBundle`), then
+ * `publishLayerBundle` does the rest. The id is computed from the content, so publishing the same layer again
+ * writes the same keys.
+ */
 export declare function publishLayer(store: ObjectStore, summary: Omit<LayerSummary, 'id'>, entries: AsyncIterable<BundleEntry>): Promise<ReportLayer>;
+/**
+ * The key of a layer's catalog entry: `layers/index/<16 digits>-<id>.json`, where the digits are
+ * `Number.MAX_SAFE_INTEGER - floor(max(0, recordedAtMs))` zero-padded. The time is inverted so a listing in key order
+ * is newest first. The entry makes a layer visible, so it is written last, after the layer and its files.
+ */
+export declare function layerCatalogKey(recordedAtMs: number, id: string): string;
+/**
+ * Writes a layer whose captured files are already stored (`bundle` locates them) and returns it with its id.
+ *
+ * The id is the SHA-256 of the JSON of `{ schemaVersion, ...summary, bundle }`, so recording the same thing the same
+ * way gives the same id. Writes the manifest only if `head` says it is absent, then always writes the catalog entry
+ * (same key, same bytes on a repeat), so a retry is harmless and a crash between the two leaves a manifest no catalog
+ * entry names, never the reverse. Store errors reject; nothing is validated here (the publishers do that).
+ */
 export declare function publishLayerBundle(store: ObjectStore, summary: Omit<LayerSummary, 'id'>, bundle: BundleIndex): Promise<ReportLayer>;
+/**
+ * Reads and validates a layer manifest, returning it without `schemaVersion`, or `null` when no manifest exists.
+ *
+ * A manifest that is present but cannot be read is an error naming why, never a half-read layer: it throws when the
+ * bytes are not JSON, fail the layer schema, or are a newer major schema version. Callers turn that into a notice,
+ * which fails the gate. Throws `Invalid layer id` for a malformed `id`. The id is not recomputed from the content.
+ */
 export declare function readLayer(store: ObjectStore, id: string): Promise<ReportLayer | null>;
+/** Reads one captured file (a screenshot, a frame, a recorded report) of a layer, or `null` when the layer or the file is missing. Throws like `readLayer`. */
 export declare function readLayerFile(store: ObjectStore, id: string, file: string): Promise<BundleEntry | null>;
+/** Drops a layer's bundle index, leaving the summary composition reads. */
 export declare function layerSummary(layer: ReportLayer): LayerSummary;

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

@@ -1,35 +1,93 @@
+/**
+ * @module Layer storage
+ *
+ * Reads and writes layers in an `ObjectStore`: the immutable manifest at `layers/manifests/<id>.json`, the catalog
+ * entry at `layers/index/<inverted-time>-<id>.json`, and the captured files under `layers/blobs/`. A layer is written
+ * bottom up (files, then manifest, then catalog entry) so a reader never meets an entry whose content has not arrived,
+ * and every key is derived from content so two producers never write different bytes to one key.
+ *
+ * @see docs/report-contract.md#where-bytes-go
+ */
 import { createBundleReader, writeBundle } from './bundle.js';
 import { readUtf8, writeUtf8 } from './object-io.js';
+import { LAYER_SCHEMA_VERSION, parseLayerDocument } from '../../schema/src/layer.js';
+/** The key prefix under which every layer's catalog entry is written. */
 export const LAYER_INDEX = 'layers/index/';
+/** The store key of a layer's manifest. Throws `Invalid layer id` unless `id` is 64 lowercase hex digits, so an id can never address another key. */
 export function layerKey(id) {
     if (!/^[0-9a-f]{64}$/.test(id))
         throw new Error('Invalid layer id');
     return `layers/manifests/${id}.json`;
 }
+/**
+ * Writes a layer whose captured files arrive as a stream, then its manifest and catalog entry, and returns it.
+ *
+ * The files are packed into content-addressed blobs under `layers/blobs/` first (`writeBundle`), then
+ * `publishLayerBundle` does the rest. The id is computed from the content, so publishing the same layer again
+ * writes the same keys.
+ */
 export async function publishLayer(store, summary, entries) {
     const bundle = await writeBundle(store, entries, 'layers/blobs/');
     return publishLayerBundle(store, summary, bundle);
 }
+/**
+ * The key of a layer's catalog entry: `layers/index/<16 digits>-<id>.json`, where the digits are
+ * `Number.MAX_SAFE_INTEGER - floor(max(0, recordedAtMs))` zero-padded. The time is inverted so a listing in key order
+ * is newest first. The entry makes a layer visible, so it is written last, after the layer and its files.
+ */
+export function layerCatalogKey(recordedAtMs, id) {
+    return `${LAYER_INDEX}${String(Number.MAX_SAFE_INTEGER - Math.max(0, Math.floor(recordedAtMs))).padStart(16, '0')}-${id}.json`;
+}
+/**
+ * Writes a layer whose captured files are already stored (`bundle` locates them) and returns it with its id.
+ *
+ * The id is the SHA-256 of the JSON of `{ schemaVersion, ...summary, bundle }`, so recording the same thing the same
+ * way gives the same id. Writes the manifest only if `head` says it is absent, then always writes the catalog entry
+ * (same key, same bytes on a repeat), so a retry is harmless and a crash between the two leaves a manifest no catalog
+ * entry names, never the reverse. Store errors reject; nothing is validated here (the publishers do that).
+ */
 export async function publishLayerBundle(store, summary, bundle) {
-    const body = JSON.stringify({ ...summary, bundle });
+    // The id is the digest of exactly this document without it, so every producer that records the same thing writes the same layer.
+    const body = JSON.stringify({ schemaVersion: LAYER_SCHEMA_VERSION, ...summary, bundle });
     const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(body));
     const id = [...new Uint8Array(digest)].map(byte => byte.toString(16).padStart(2, '0')).join('');
     const layer = { ...summary, id, bundle };
     // Immutable manifest first, independent catalog entry last: concurrent producers never overwrite one another.
     if (!(await store.head(layerKey(id))))
-        await writeUtf8(store, layerKey(id), JSON.stringify(layer), 'application/json');
-    const inverse = String(Number.MAX_SAFE_INTEGER - Math.max(0, Math.floor(summary.recordedAtMs))).padStart(16, '0');
-    await writeUtf8(store, `${LAYER_INDEX}${inverse}-${id}.json`, JSON.stringify({ id }), 'application/json');
+        await writeUtf8(store, layerKey(id), JSON.stringify({ schemaVersion: LAYER_SCHEMA_VERSION, ...layer }), 'application/json');
+    await writeUtf8(store, layerCatalogKey(summary.recordedAtMs, id), JSON.stringify({ id }), 'application/json');
     return layer;
 }
+/**
+ * Reads and validates a layer manifest, returning it without `schemaVersion`, or `null` when no manifest exists.
+ *
+ * A manifest that is present but cannot be read is an error naming why, never a half-read layer: it throws when the
+ * bytes are not JSON, fail the layer schema, or are a newer major schema version. Callers turn that into a notice,
+ * which fails the gate. Throws `Invalid layer id` for a malformed `id`. The id is not recomputed from the content.
+ */
 export async function readLayer(store, id) {
     const raw = await readUtf8(store, layerKey(id));
-    return raw === null ? null : JSON.parse(raw);
+    if (raw === null)
+        return null;
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Layer ${id.slice(0, 12)} is not JSON`);
+    }
+    const parsed = parseLayerDocument(json);
+    if (!parsed.ok)
+        throw new Error(`Layer ${id.slice(0, 12)}: ${parsed.reason}`);
+    const { schemaVersion: _version, ...layer } = parsed.layer;
+    return layer;
 }
+/** Reads one captured file (a screenshot, a frame, a recorded report) of a layer, or `null` when the layer or the file is missing. Throws like `readLayer`. */
 export async function readLayerFile(store, id, file) {
     const layer = await readLayer(store, id);
     return layer ? createBundleReader(store, layer.bundle)(file) : null;
 }
+/** Drops a layer's bundle index, leaving the summary composition reads. */
 export function layerSummary(layer) {
     const { bundle: _, ...summary } = layer;
     return summary;

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

@@ -1,21 +1,47 @@
+/**
+ * @module Layer types
+ *
+ * The in-memory shapes of a layer: `LayerSummary` (everything but its captured files), `ReportLayer` (the summary plus
+ * the index of those files) and `ReportOutline` (the specs a report is laid over). The stored form is the layer
+ * document of `packages/schema/src/layer.ts`; these types are what the reader and publisher code hands around after
+ * parsing it. Fields follow the layer document, so adding a field here means adding an optional field there.
+ *
+ * @see docs/report-contract.md#the-layer-document
+ */
 import type { BundleIndex } from './bundle.js';
 import type { ReportPart, SpecEntry } from './explorer-types.js';
 import type { SourceRecord } from './protocol.js';
+/** String choices (such as `{ device: 'iphone-15' }`) that make a result its own slot. Compared as sorted key/value pairs. */
 export type LayerParameters = Readonly<Record<string, string>>;
-export type LayerSummary = {
+/** What a layer may carry as a whole. All optional and open: see docs/extending.md. */
+export type LayerExtras = Partial<Pick<import('../../schema/src/layer.js').LayerDocument, 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions'>>;
+/** A layer without its captured files: what composition and the viewer's lists read. */
+export type LayerSummary = LayerExtras & {
+    /** `modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Absent for a clean checkout. Advisory; never changes a status. */
     readonly freshness?: 'unknown' | 'modified';
+    /** The layer's content digest: 64 lowercase hex digits. Opaque to readers. Legacy commit-keyed recordings use `part-<sha>-<id>` or `source-<sha>-<id>` instead. */
     readonly id: string;
+    /** When the checks ran, epoch milliseconds. The newest completed result wins its slot. */
     readonly recordedAtMs: number;
+    /** The stable name of the suite or tool that made the layer. Part of the slot. */
     readonly producer: string;
+    /** Provenance: the commit recorded, or `null`. Never part of the slot. */
     readonly sha: string | null;
+    /** Provenance: the branch recorded, or `null`. Never part of the slot. */
     readonly branch: string | null;
     /** The client this layer checked, when it said. Normalized when the layer is read. */
     readonly environment?: string | null;
+    /** Provenance: the CI run that produced the layer, or `null`. Never part of the slot. */
     readonly runUrl: string | null;
+    /** Free choices that make a result its own slot. The `environment` parameter is read as the environment (see `layerPlace`). */
     readonly parameters: LayerParameters;
+    /** The specs the layer was recorded against, with fingerprints of their text. */
     readonly specs: readonly SpecEntry[];
+    /** The checks, grouped by producer-defined kind. */
     readonly parts: readonly ReportPart[];
+    /** The recorded statechart run behind the layer (timelines and tests), or `null` for a layer of plain checks. */
     readonly source: SourceRecord | null;
+    /** Where the layer's timelines and captured files are read from: its own bundle (`layer`), an older commit-keyed recording (`commit`), or nowhere (`null`). */
     readonly recording: {
         readonly type: 'layer';
     } | {
@@ -24,11 +50,16 @@ export type LayerSummary = {
         readonly source: string;
     } | null;
 };
+/** A layer with the index that locates its captured files (screenshots, frames) in the store. */
 export type ReportLayer = LayerSummary & {
     readonly bundle: BundleIndex;
 };
+/** The current specs a report is laid over, and the commit and changes freshness warnings are judged against. */
 export type ReportOutline = {
+    /** The specs that make the outline of the report. A spec here with no layer shows as having no results. */
     readonly specs: readonly SpecEntry[];
+    /** The commit the specs are from, or `null` when unknown. */
     readonly sha: string | null;
+    /** Paths changed since the layers were recorded; a result touching one is warned as potentially outdated. */
     readonly changedFiles: readonly string[];
 };

package/dist/reports/src/layers-route.d.ts

@@ -1,20 +1,63 @@
+/**
+ * @module Layers HTTP routes
+ *
+ * The read-only HTTP API the viewer uses to see layers: a paged list of layer headers merged from every backend, the
+ * rows of one layer, its attachments and recorded timelines, the live runs still writing on this machine, and the
+ * spec outline. It is mounted under `/api/reports` by `reportsHost` and by the Atlas server. Immutable layers (64-hex
+ * ids) are read once and cached for good and answered with long-lived `immutable` cache headers; mutable commit-keyed
+ * recordings are re-read after a short wait. A backend that cannot be listed or a layer that cannot be read becomes a
+ * notice in the page, never a silent omission and never a pass. Layers the host's `include` filter rejects are absent
+ * from every route here, so a filter cannot be undone by asking for history.
+ *
+ * @see docs/server.md
+ * @see docs/report-contract.md#failure-behaviour
+ */
 import { Hono } from 'hono';
 import type { ObjectStore } from './object-store.js';
 import type { ReportsAppDeps } from './reports-route.js';
-/** A further store whose layers join the combined report, beside the local and the shared one. */
+/** A further store whose layers join the combined report, beside the local and the shared one. Passed as `backends` in `ReportsAppDeps`. */
 export type ReportBackend = {
-    /** Stable and unique: letters, digits and hyphens. `local` and `shared` are taken. */
+    /** Stable and unique: lowercase letters, digits and hyphens. `local` and `shared` are taken. Appears in cursors and URLs. */
     readonly id: string;
+    /** Human name shown for the backend in the viewer. */
     readonly label: string;
+    /** Where the backend's layers are read from. */
     readonly store: ObjectStore;
 };
 type Backend = ReportBackend & {
     readonly live: boolean;
 };
+/** The id of the backend for this machine's own store (`localStore`), where runs may still be writing. */
 export declare const LOCAL_BACKEND = "local";
+/** The id of the backend for the shared reports store (`store`). */
 export declare const SHARED_BACKEND = "shared";
-/** The stores that contribute layers, in the order they answer for a recording. */
+/**
+ * The stores that contribute layers, in the order they answer for a recording: `localStore` (id `local`, live), then
+ * `store` (id `shared`) when it is a different store, then each of `backends`.
+ *
+ * Throws `Invalid report backend id: "<id>"` when an extra backend's id is not lowercase letters, digits and hyphens
+ * or repeats an earlier id (including `local` and `shared`).
+ */
 export declare function reportBackends(deps: ReportsAppDeps): Backend[];
-/** Bounded pages of layer origins, each layer's checks read once, and the runs still writing. */
+/**
+ * Builds the Hono app that serves layers: bounded pages of layer origins, each layer's checks read once, and the
+ * runs still writing. Throws (as `reportBackends`) when a backend id is invalid.
+ *
+ * Routes, relative to where it is mounted:
+ * - `GET /outline` the current specs as `{ specs, sha, changedFiles }` (503 when the host has no outline), cached 30 s.
+ * - `GET /outline/spec?path=` one outline spec's text; 404 for a path not in the outline.
+ * - `GET /evidence?cursor=&retry=` one page of layer headers (`EvidencePage`) from 40 catalog entries across all
+ *   backends: immutable layers newest first, then commit-keyed recordings. Without a cursor it also carries the live
+ *   runs of this machine. `cursor` is the previous page's; 409 when it no longer matches the listing (refresh).
+ *   Any `retry` value re-lists backends that were unavailable now instead of after the wait.
+ * - `GET /evidence/rows/:backend/:id` the checks and spec fingerprints of one layer (`LayerRows`).
+ * - `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer, or one check's detail.
+ * - `GET /layers/:id/blobs/*` an attachment of an immutable layer by its bundle key, served by `attachmentResponse`.
+ * - `GET /layers/:id/*` the recorded `frame.css`, `tests/<test>/report.json` and `tests/<test>/files/<frame>` of a layer.
+ * - `GET /live/:source/frame.css` and `GET /live/:source/tests/:testId/*` the same for a run still writing (uncached).
+ *
+ * Directory listings are cached for 30 s (1.5 s for the local store). A listing that fails keeps the previous keys and
+ * marks the backend unavailable; the page then carries a notice.
+ */
 export declare function createLayersApp(deps: ReportsAppDeps): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
 export {};