@crvouga/atlas 0.3.0 → 0.5.0

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. Latest completed result wins only its own check/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;

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

@@ -1,4 +1,11 @@
-/** Advisory identity, never a cryptographic integrity check. */
+import { summarizeEvidence } from './evidence-detail.js';
+import { layerPlace } from './layer-axes.js';
+/**
+ * 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++) {
@@ -7,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();
@@ -28,27 +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,
@@ -58,12 +104,14 @@ export function layerEvidence(summary, backend) {
         recordedAtMs: summary.recordedAtMs,
         sha: summary.sha,
         branch: summary.branch,
+        environment: place.environment,
         runUrl: summary.runUrl,
-        parameters: summary.parameters,
+        parameters: place.parameters,
         recording: recording === null ? null : recording.type === 'layer' ? { type: 'layer', layer: summary.id } : recording,
         live: false,
         counts: outcomeCounts(rows),
         execution: textFingerprint(layerExecutionKey(summary)),
+        ...(layerSummaryEvidence ? { evidence: layerSummaryEvidence } : {}),
     };
     const fingerprints = {};
     for (const spec of summary.specs)
@@ -71,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;
@@ -94,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)
@@ -104,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. Latest completed result wins only its own check/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));
@@ -114,10 +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) {
-            const parameters = { ...layer.parameters, ...row.variant };
+            // 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, 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))
@@ -129,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

@@ -1,9 +1,21 @@
 import { writeBundle } from './bundle.js';
+import { normalizeEnvironment } from './layer-axes.js';
 import { readCommit, readFrameCss } from './read.js';
 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);
@@ -25,8 +37,10 @@ export async function archiveSourceLayer(store, args, source, tests, bundle) {
     const index = await writeBundle(store, entries(), 'layers/blobs/');
     for (const [key, value] of Object.entries(bundle ?? {}))
         index[layerPath(key)] = value;
+    const environment = normalizeEnvironment(args.environment ?? args.parameters?.environment);
     return publishLayerBundle(store, {
         ...(args.freshness ? { freshness: args.freshness } : {}), producer: source.source, recordedAtMs, sha: args.sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null,
+        ...(environment ? { environment } : {}),
         parameters: args.parameters ?? {}, specs: inventory?.entries ?? [], parts: sourceParts(args.sha, source), source, recording: { type: 'layer' },
     }, index);
 }

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;