@crvouga/atlas 0.4.0 → 0.5.0

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

@@ -1,37 +1,68 @@
-/** Shared search, filter, group and sort for reports and the tests inside one. */
+/**
+ * @module Catalog search, filter, group and sort
+ *
+ * The pure view logic behind the viewer's list of reports (and of the tests inside one): given entities and a
+ * query (text, status, grouping, sort), it returns the groups to draw. It owns no data and does no I/O; the
+ * caller maps its own records to {@link CatalogEntity}. Input is never mutated.
+ */
+/** A status filter: one of the four result statuses as the list names them (`skipped` is a check that was `not-run`), or `all`. */
 export type CatalogStatus = 'all' | 'passed' | 'failed' | 'skipped' | 'running';
+/** What the list is grouped by; `none` gives one group named `All`. */
 export type CatalogGroup = 'none' | 'file' | 'status' | 'package' | 'runtime';
+/** How entities are ordered inside a group: `recent` keeps the input order, `name` is by title, `duration` is longest first, `status` is failed first then by title. */
 export type CatalogSort = 'recent' | 'name' | 'duration' | 'status';
+/** How the list is drawn. */
 export type CatalogLayout = 'list' | 'grid';
+/** The user's current choices, mirrored in the URL (see {@link catalogParams}). */
 export type CatalogQuery = {
+    /** Free text; matched case-insensitively as a substring of each entity's `search` text. Blank matches everything. */
     readonly q: string;
     readonly status: CatalogStatus;
     readonly group: CatalogGroup;
     readonly sort: CatalogSort;
     readonly layout: CatalogLayout;
 };
+/** One row of the list: a report or a test, flattened to what the list needs. */
 export type CatalogEntity = {
+    /** Stable identifier of the row. */
     readonly id: string;
     readonly title: string;
+    /** A status string; only `passed`, `failed`, `skipped` and `running` are counted and ranked, any other sorts after them. */
     readonly status: string;
+    /** Duration in milliseconds, or null when unknown (sorted last by `duration`, counted as 0 in a group's total). */
     readonly durationMs: number | null;
     /** Group label for `file` (a source file, or a branch). */
     readonly file: string;
+    /** Group label for `package`; empty groups under `Other`. */
     readonly packageName: string;
+    /** Group label for `runtime`; empty groups under `Other`. */
     readonly runtime: string;
     /** One muted line under the title: a failure, or a date. */
     readonly detail: string;
+    /** Everything the text query may match (title, ids, paths, ...), built by the caller. */
     readonly search: string;
+    /** Where selecting the row navigates, or null when it is not a link. */
     readonly href: string | null;
 };
+/** One drawn group of the list. */
 export type CatalogGroupView = {
     readonly name: string;
+    /** Sum of the members' durations in milliseconds; unknown durations count as 0. */
     readonly durationMs: number;
+    /** How many members have status `failed`. */
     readonly failed: number;
     readonly entities: readonly CatalogEntity[];
 };
+/** Counts entities per status filter (`all` is the total); a status the list does not know is counted only in `all`. */
 export declare function catalogCounts(entities: readonly CatalogEntity[]): Record<CatalogStatus, number>;
-/** The list's search params, dropped when a test route carries frame and zoom. */
+/** Keeps only the list's own URL search params (`q`, `status`, `group`, `sort`, `layout`, `spec`, `tab`, `partq`) and drops empty ones, so a test route's frame and zoom params do not leak into a link back to the list. */
 export declare function catalogParams(params: Readonly<Record<string, string>>): Record<string, string>;
-/** Filter, sort, then one group per chosen key. `recent` keeps input order. */
+/**
+ * Filters entities by the query's status and text, sorts them, then splits them into one group per value of the
+ * chosen key. `recent` keeps input order.
+ *
+ * Group order: for `status`, failed, running, skipped, passed; otherwise alphabetical by name with `Other` (the
+ * label for an empty file, package or runtime) last. With `none` there is a single group named `All`. When
+ * nothing matches, no group is returned.
+ */
 export declare function arrangeCatalog(entities: readonly CatalogEntity[], query: CatalogQuery): readonly CatalogGroupView[];

package/dist/reports/src/catalog.js

@@ -1,10 +1,17 @@
-/** Shared search, filter, group and sort for reports and the tests inside one. */
+/**
+ * @module Catalog search, filter, group and sort
+ *
+ * The pure view logic behind the viewer's list of reports (and of the tests inside one): given entities and a
+ * query (text, status, grouping, sort), it returns the groups to draw. It owns no data and does no I/O; the
+ * caller maps its own records to {@link CatalogEntity}. Input is never mutated.
+ */
 const STATUS_RANK = {
     failed: 0,
     running: 1,
     skipped: 2,
     passed: 3,
 };
+/** Counts entities per status filter (`all` is the total); a status the list does not know is counted only in `all`. */
 export function catalogCounts(entities) {
     const counts = {
         all: entities.length,
@@ -83,7 +90,7 @@ const LIST_KEYS = [
     'tab',
     'partq',
 ];
-/** The list's search params, dropped when a test route carries frame and zoom. */
+/** Keeps only the list's own URL search params (`q`, `status`, `group`, `sort`, `layout`, `spec`, `tab`, `partq`) and drops empty ones, so a test route's frame and zoom params do not leak into a link back to the list. */
 export function catalogParams(params) {
     const out = {};
     for (const key of LIST_KEYS) {
@@ -93,7 +100,14 @@ export function catalogParams(params) {
     }
     return out;
 }
-/** Filter, sort, then one group per chosen key. `recent` keeps input order. */
+/**
+ * Filters entities by the query's status and text, sorts them, then splits them into one group per value of the
+ * chosen key. `recent` keeps input order.
+ *
+ * Group order: for `status`, failed, running, skipped, passed; otherwise alphabetical by name with `Other` (the
+ * label for an empty file, package or runtime) last. With `none` there is a single group named `All`. When
+ * nothing matches, no group is returned.
+ */
 export function arrangeCatalog(entities, query) {
     const shown = entities.filter((entity) => matches(entity, query));
     const sorted = query.sort === 'recent'

package/dist/reports/src/cli-stores.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module Stores named on a command line
+ *
+ * Turns `--store`, `--backends` and `ATLAS_STORE` into opened backends for the `atlas report` commands, and reads the
+ * small flag grammar those commands share (`--name value`, repeatable). A mistyped directory is an error here, never
+ * an empty store: a gate that read nothing must not read as a pass.
+ *
+ * @see docs/deploying.md
+ */
+import type { BackendInput } from './compose.js';
+import { type OpenedStore } from './store-url.js';
+type Env = Readonly<Record<string, string | undefined>>;
+/** A backend of a command: what `combineBackends` reads, plus, when it came from a URL, how it was opened (`location`, `server`, `s3`). */
+export type CliBackend = BackendInput & Partial<OpenedStore>;
+/** Every value given for `--<name>`, in order. `--name` with nothing after it is ignored. */
+export declare function values(argv: readonly string[], name: string): string[];
+/** The first value given for `--<name>`, or `undefined`. */
+export declare function value(argv: readonly string[], name: string): string | undefined;
+/**
+ * Every store a command reads: `--store` (a directory or `s3://…`, optionally `id=url`), then
+ * `--backends <module>`, or `ATLAS_STORE` when neither is given. A directory that is not there is an
+ * error: a mistyped path must never read as an empty store.
+ */
+export declare function backendsOf(argv: readonly string[], base: string, env: Env): Promise<CliBackend[]>;
+/** The one store a command writes to. A directory is created; a bucket must already exist. */
+export declare function writeStoreOf(flag: string | undefined, base: string, env: Env, name?: string): OpenedStore;
+/**
+ * Which layers take part, from `--branch <name>` (repeatable) and `--ignore-modified`. By default all do:
+ * a report is whatever the newest results are, wherever they were recorded. A gate that must speak for
+ * a branch narrows it; the narrowing is yours to choose, never Atlas's.
+ */
+export declare function layerFilter(argv: readonly string[], env: Env): ((layer: {
+    readonly branch: string | null;
+    readonly freshness?: 'unknown' | 'modified';
+}) => boolean) | undefined;
+export {};

package/dist/reports/src/cli-stores.js

@@ -0,0 +1,73 @@
+/**
+ * @module Stores named on a command line
+ *
+ * Turns `--store`, `--backends` and `ATLAS_STORE` into opened backends for the `atlas report` commands, and reads the
+ * small flag grammar those commands share (`--name value`, repeatable). A mistyped directory is an error here, never
+ * an empty store: a gate that read nothing must not read as a pass.
+ *
+ * @see docs/deploying.md
+ */
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { openBackends, openStore, storeSpecs } from './store-url.js';
+/** Every value given for `--<name>`, in order. `--name` with nothing after it is ignored. */
+export function values(argv, name) {
+    return argv.flatMap((token, i) => (token === `--${name}` && argv[i + 1] !== undefined ? [argv[i + 1]] : []));
+}
+/** The first value given for `--<name>`, or `undefined`. */
+export function value(argv, name) {
+    return values(argv, name)[0];
+}
+/**
+ * Every store a command reads: `--store` (a directory or `s3://…`, optionally `id=url`), then
+ * `--backends <module>`, or `ATLAS_STORE` when neither is given. A directory that is not there is an
+ * error: a mistyped path must never read as an empty store.
+ */
+export async function backendsOf(argv, base, env) {
+    const specs = storeSpecs(values(argv, 'store'), env);
+    const backends = openBackends(specs, { base, env });
+    backends.forEach((backend, i) => {
+        const location = backend.location;
+        if (location?.kind === 'directory' && (!existsSync(location.directory) || !statSync(location.directory).isDirectory())) {
+            throw new Error(`Store directory not found: ${specs[i].replace(/^[a-z0-9-]+=/, '')}. If a node failed to publish or upload, fix that first`);
+        }
+    });
+    const used = new Set(backends.map(backend => backend.id));
+    for (const file of values(argv, 'backends')) {
+        const mod = (await import(pathToFileURL(path.resolve(base, file)).href));
+        if (!mod.default)
+            throw new Error(`${file} has no default export: a list of { id, label?, store }`);
+        for (const backend of typeof mod.default === 'function' ? await mod.default() : mod.default) {
+            if (used.has(backend.id))
+                throw new Error(`Two stores are named "${backend.id}"`);
+            used.add(backend.id);
+            backends.push(backend);
+        }
+    }
+    if (!backends.length)
+        throw new Error('Give at least one --store <dir or s3://bucket/prefix> (or --backends <module>), or set ATLAS_STORE');
+    return backends;
+}
+/** The one store a command writes to. A directory is created; a bucket must already exist. */
+export function writeStoreOf(flag, base, env, name = 'store') {
+    const specs = flag ? [flag] : storeSpecs([], env);
+    if (specs.length !== 1)
+        throw new Error(specs.length ? `Give one --${name} to write to (ATLAS_STORE names ${specs.length})` : `Give --${name} <dir or s3://bucket/prefix>, or set ATLAS_STORE`);
+    const opened = openStore(/^([a-z0-9-]+)=(.+)$/.exec(specs[0])?.[2] ?? specs[0], { base, env });
+    if (opened.location.kind === 'directory')
+        mkdirSync(opened.location.directory, { recursive: true });
+    return opened;
+}
+/**
+ * Which layers take part, from `--branch <name>` (repeatable) and `--ignore-modified`. By default all do:
+ * a report is whatever the newest results are, wherever they were recorded. A gate that must speak for
+ * a branch narrows it; the narrowing is yours to choose, never Atlas's.
+ */
+export function layerFilter(argv, env) {
+    const branches = [...values(argv, 'branch'), ...(env.ATLAS_ONLY_BRANCH ?? '').split(/[\s,]+/).filter(Boolean)];
+    const ignoreModified = argv.includes('--ignore-modified') || env.ATLAS_IGNORE_MODIFIED === '1' || env.ATLAS_IGNORE_MODIFIED === 'true';
+    if (!branches.length && !ignoreModified)
+        return undefined;
+    return layer => (!branches.length || (layer.branch !== null && branches.includes(layer.branch))) && (!ignoreModified || layer.freshness === undefined);
+}

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

@@ -1,11 +1,16 @@
 /**
- * Injectable wall / virtual time for deterministic simulation.
- * Production uses {@link wallClock} / {@link wallTimers}.
+ * @module Injectable time
+ *
+ * The two time dependencies of the reports code, as types, so tests and simulations can supply virtual time.
+ * Production hosts pass `{ now: Date.now }` and wrappers over the global timers (see `host.ts`). There is no
+ * default implementation in this module.
  */
+/** The clock a reader or route uses to decide when polling or tailing has run long enough. */
 export type Clock = {
     /** Epoch milliseconds (virtual or wall). */
     readonly now: () => number;
 };
+/** The timer functions the reports code schedules work with; each handle is opaque and only passed back to the matching `clear*`. */
 export type Timers = {
     readonly setTimeout: (fn: () => void, ms: number) => unknown;
     readonly clearTimeout: (handle: unknown) => void;

package/dist/reports/src/clock.js

@@ -1,4 +1,7 @@
 /**
- * Injectable wall / virtual time for deterministic simulation.
- * Production uses {@link wallClock} / {@link wallTimers}.
+ * @module Injectable time
+ *
+ * The two time dependencies of the reports code, as types, so tests and simulations can supply virtual time.
+ * Production hosts pass `{ now: Date.now }` and wrappers over the global timers (see `host.ts`). There is no
+ * default implementation in this module.
  */

package/dist/reports/src/completion-order.d.ts

@@ -1,10 +1,23 @@
 /**
- * Run `tasks` at most `limit` at a time and yield each result the moment it
- * settles, so one slow read never holds back faster siblings. A rejection
- * is rethrown to the consumer once every started task has settled.
+ * @module Bounded concurrency
+ *
+ * Small helpers that run async work with a cap on how many tasks are in flight, used for reading and writing many
+ * store objects without flooding the backend. They differ from `Promise.all` in three ways: the cap, results in
+ * completion order (not input order), and failure handling: once one task rejects, no new task is started,
+ * those already started are allowed to finish, and then the first error is rethrown.
+ */
+/**
+ * Runs `tasks` at most `limit` at a time (at least 1) and yields each result the moment it
+ * settles, so one slow read never holds back faster siblings. Results come in completion order, not input
+ * order. A rejection is rethrown to the consumer once every started task has settled; no results are yielded
+ * after the first failure.
  */
 export declare function inCompletionOrder<T>(tasks: readonly (() => Promise<T>)[], limit: number): AsyncGenerator<T>;
-/** Apply `work` to every item, at most `limit` at a time. */
+/** Applies `work` to every item, at most `limit` at a time, and resolves when all are done; rejects with the first error as {@link inCompletionOrder} does. */
 export declare function eachLimited<T>(items: readonly T[], limit: number, work: (item: T) => Promise<void>): Promise<void>;
-/** Consume a lazy input with backpressure, draining started work before failure. */
+/**
+ * Consumes a lazy (async) input with backpressure: it pulls the next item only while fewer than `limit` works are
+ * running, so a huge or generated input is never held in memory at once. After a failure it stops pulling,
+ * waits for the started work to settle, then rethrows the first error.
+ */
 export declare function eachLimitedStream<T>(items: AsyncIterable<T>, limit: number, work: (item: T) => Promise<void>): Promise<void>;

package/dist/reports/src/completion-order.js

@@ -1,7 +1,16 @@
 /**
- * Run `tasks` at most `limit` at a time and yield each result the moment it
- * settles, so one slow read never holds back faster siblings. A rejection
- * is rethrown to the consumer once every started task has settled.
+ * @module Bounded concurrency
+ *
+ * Small helpers that run async work with a cap on how many tasks are in flight, used for reading and writing many
+ * store objects without flooding the backend. They differ from `Promise.all` in three ways: the cap, results in
+ * completion order (not input order), and failure handling: once one task rejects, no new task is started,
+ * those already started are allowed to finish, and then the first error is rethrown.
+ */
+/**
+ * Runs `tasks` at most `limit` at a time (at least 1) and yields each result the moment it
+ * settles, so one slow read never holds back faster siblings. Results come in completion order, not input
+ * order. A rejection is rethrown to the consumer once every started task has settled; no results are yielded
+ * after the first failure.
  */
 export async function* inCompletionOrder(tasks, limit) {
     const width = Math.max(1, Math.floor(limit));
@@ -42,14 +51,18 @@ export async function* inCompletionOrder(tasks, limit) {
     if (outcome.failure !== null)
         throw outcome.failure.error;
 }
-/** Apply `work` to every item, at most `limit` at a time. */
+/** Applies `work` to every item, at most `limit` at a time, and resolves when all are done; rejects with the first error as {@link inCompletionOrder} does. */
 export async function eachLimited(items, limit, work) {
     const tasks = items.map((item) => () => work(item));
     for await (const _ of inCompletionOrder(tasks, limit)) {
         // Results are void; draining is the point.
     }
 }
-/** Consume a lazy input with backpressure, draining started work before failure. */
+/**
+ * Consumes a lazy (async) input with backpressure: it pulls the next item only while fewer than `limit` works are
+ * running, so a huge or generated input is never held in memory at once. After a failure it stops pulling,
+ * waits for the started work to settle, then rethrows the first error.
+ */
 export async function eachLimitedStream(items, limit, work) {
     const width = Math.max(1, Math.floor(limit));
     const running = new Set();

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

@@ -0,0 +1,80 @@
+import type { BackendInfo, LayerHeader, StatusCounts } from './evidence-types.js';
+import { type CombinedEvidence, type EvidenceResult } from './layer-merge.js';
+import type { ReportOutline } from './layer-types.js';
+import type { ObjectStore } from './object-store.js';
+/** A store that contributes layers. Any {@link ObjectStore} is one: a directory, a bucket, a device lab. */
+export type BackendInput = {
+    /** Stable and unique: lowercase letters, digits and hyphens. It names where a result came from. */
+    readonly id: string;
+    /** What a person sees in notices and in the viewer. Defaults to `id`. */
+    readonly label?: string;
+    /** Where the layers are. Only read from. */
+    readonly store: ObjectStore;
+};
+/** Options of {@link combineBackends}. */
+export type CombineOptions = {
+    /** The specs the report is laid out against. When omitted, the specs the layers recorded. */
+    readonly outline?: ReportOutline;
+    /** Layers read at once, across all backends. Default 16. */
+    readonly concurrency?: number;
+    /**
+     * Leave layers out, to see what earlier ones said (a layer for which this returns false takes no part: not in the
+     * results, the layer list, the counts, or the recorded specs). Layers are still read; this filters after reading.
+     */
+    readonly include?: (layer: LayerHeader) => boolean;
+};
+/** What a report says in numbers. Timings that only qualify a check are not counted as checks. */
+export type ReportSummary = {
+    /** Counts of the winning results by status, and their total. */
+    readonly checks: StatusCounts & {
+        readonly total: number;
+    };
+    /** The same counts per environment slug, keys sorted; results with no environment are under `unspecified`. */
+    readonly byEnvironment: Readonly<Record<string, StatusCounts & {
+        readonly total: number;
+    }>>;
+    /** Specs in the outline with no result at all. */
+    readonly specsWithoutEvidence: readonly string[];
+};
+/** A report: the results laid over the specs, with what was read and what could not be. */
+export type CombinedReport = {
+    /** Every spec in the outline with the winning result of each of its slots, plus results that belong to no spec in the outline. */
+    readonly combined: CombinedEvidence;
+    /** Every distinct layer that was read, newest first. A layer several backends hold is one layer. */
+    readonly layers: readonly LayerHeader[];
+    /** Every backend given, sorted by id, with whether it could be read. */
+    readonly backends: readonly BackendInfo[];
+    /** What could not be read. A gate treats any of these as unknown, never as a pass. */
+    readonly notices: readonly string[];
+    /** The numbers of `combined`, computed once for the gate and the viewer. */
+    readonly summary: ReportSummary;
+};
+/**
+ * Counts results by status. Diagnostic results (parts of kind `performance`, which only qualify a check) are left out
+ * whenever any other result is present; if only diagnostics exist, they are counted so the report is not empty.
+ */
+export declare function countResults(results: readonly EvidenceResult[]): StatusCounts & {
+    total: number;
+};
+/** Counts a combined report's winning results in total and per environment, and lists the specs that have no result at all. */
+export declare function summarize(combined: CombinedEvidence): ReportSummary;
+/**
+ * Reads every layer of every backend and lays them over the specs. Layers are the only input:
+ * a report is a function of the set of layers, so the order of backends and layers, and how they
+ * were split across machines, branches and runs, does not change it.
+ *
+ * A backend that cannot be read, or a layer that cannot be understood, is named in `notices` and
+ * leaves everything else usable; a gate must treat any notice as unknown, never as a pass. A layer held by
+ * several backends is one layer. Only an invalid backend `id` (not lowercase letters, digits and hyphens, or
+ * repeated) throws, before anything is read. Backends are only read from.
+ *
+ * When `options.outline` is omitted, the specs are the ones the included layers recorded (the newest
+ * recording of each spec path wins), with no commit sha.
+ *
+ * @example
+ * const outline = await loadDirectoryOutline('./specs'); // optional: without it the layers' own specs are used
+ * const report = await combineBackends([{ id: 'ci', store: directoryStore('./atlas-reports') }], { outline });
+ * report.summary.checks.failed; // number of slots whose winner failed
+ * report.notices; // non-empty means something could not be read
+ */
+export declare function combineBackends(backends: readonly BackendInput[], options?: CombineOptions): Promise<CombinedReport>;

package/dist/reports/src/compose.js

@@ -0,0 +1,117 @@
+/**
+ * @module Combining backends into one report
+ *
+ * The entry point that turns stores of layers into a report: it reads every layer from every {@link BackendInput},
+ * lays them over the specs, and counts the outcome. It owns reading and failure reporting (an unreadable backend or
+ * layer becomes a notice, never a pass); the rule for which result wins a slot lives in `layer-merge.ts`. A report
+ * is computed, never stored, and is a function of the set of layers: the order and split of backends does not
+ * change it.
+ *
+ * @see docs/report-contract.md (how layers compose, guarantees)
+ */
+import { eachLimited } from './completion-order.js';
+import { catalogEntries, catalogLayers } from './layer-catalog.js';
+import { combineEvidence, distinctHeaders, emptyCounts, isDiagnosticKind, layerEvidence, specPath } from './layer-merge.js';
+const BACKEND_ID = /^[a-z0-9-]+$/;
+/**
+ * Counts results by status. Diagnostic results (parts of kind `performance`, which only qualify a check) are left out
+ * whenever any other result is present; if only diagnostics exist, they are counted so the report is not empty.
+ */
+export function countResults(results) {
+    const outcomes = results.some(result => !isDiagnosticKind(result.row.kind)) ? results.filter(result => !isDiagnosticKind(result.row.kind)) : results;
+    const counts = emptyCounts();
+    for (const result of outcomes)
+        counts[result.row.status] += 1;
+    return { ...counts, total: outcomes.length };
+}
+/** Counts a combined report's winning results in total and per environment, and lists the specs that have no result at all. */
+export function summarize(combined) {
+    const results = [...combined.specs.flatMap(entry => entry.results), ...combined.unassigned];
+    const environments = new Map();
+    for (const result of results) {
+        const key = result.layer.environment ?? 'unspecified';
+        const group = environments.get(key);
+        if (group)
+            group.push(result);
+        else
+            environments.set(key, [result]);
+    }
+    return {
+        checks: countResults(results),
+        byEnvironment: Object.fromEntries([...environments].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([key, value]) => [key, countResults(value)])),
+        specsWithoutEvidence: combined.specs.filter(entry => entry.results.length === 0).map(entry => entry.spec.path)
+    };
+}
+/**
+ * Reads every layer of every backend and lays them over the specs. Layers are the only input:
+ * a report is a function of the set of layers, so the order of backends and layers, and how they
+ * were split across machines, branches and runs, does not change it.
+ *
+ * A backend that cannot be read, or a layer that cannot be understood, is named in `notices` and
+ * leaves everything else usable; a gate must treat any notice as unknown, never as a pass. A layer held by
+ * several backends is one layer. Only an invalid backend `id` (not lowercase letters, digits and hyphens, or
+ * repeated) throws, before anything is read. Backends are only read from.
+ *
+ * When `options.outline` is omitted, the specs are the ones the included layers recorded (the newest
+ * recording of each spec path wins), with no commit sha.
+ *
+ * @example
+ * const outline = await loadDirectoryOutline('./specs'); // optional: without it the layers' own specs are used
+ * const report = await combineBackends([{ id: 'ci', store: directoryStore('./atlas-reports') }], { outline });
+ * report.summary.checks.failed; // number of slots whose winner failed
+ * report.notices; // non-empty means something could not be read
+ */
+export async function combineBackends(backends, options = {}) {
+    const seen = new Set();
+    for (const backend of backends) {
+        if (!BACKEND_ID.test(backend.id) || seen.has(backend.id))
+            throw new Error(`Invalid report backend id: "${backend.id}". Use unique lowercase letters, digits and hyphens`);
+        seen.add(backend.id);
+    }
+    const notices = [];
+    const info = [];
+    const entries = [];
+    await Promise.all(backends.map(async (backend) => {
+        try {
+            for (const entry of await catalogEntries(backend.store))
+                entries.push({ backend, entry });
+            info.push({ id: backend.id, label: backend.label ?? backend.id, live: false, available: true });
+        }
+        catch (error) {
+            info.push({ id: backend.id, label: backend.label ?? backend.id, live: false, available: false });
+            notices.push(`${backend.label ?? backend.id} is unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }));
+    entries.sort((a, b) => (a.backend.id < b.backend.id ? -1 : a.backend.id > b.backend.id ? 1 : a.entry < b.entry ? -1 : a.entry > b.entry ? 1 : 0));
+    const loaded = [];
+    await eachLimited(entries, options.concurrency ?? 16, async ({ backend, entry }) => {
+        try {
+            for (const summary of await catalogLayers(backend.store, entry)) {
+                loaded.push({ evidence: layerEvidence(summary, backend.id), specs: summary.specs });
+            }
+        }
+        catch (error) {
+            notices.push(`${backend.label ?? backend.id}: a layer could not be read, so its outcome is unknown (${error instanceof Error ? error.message : String(error)})`);
+        }
+    });
+    const include = options.include;
+    const kept = include ? loaded.filter(item => include(item.evidence.layer)) : loaded;
+    const layers = kept.map(item => item.evidence);
+    // The specs a report is laid over come from the layers that are in it, not from ones left out.
+    const recorded = new Map();
+    if (!options.outline) {
+        for (const { evidence, specs } of kept) {
+            for (const spec of specs) {
+                const key = specPath(spec.path);
+                const prior = recorded.get(key);
+                const at = evidence.layer.recordedAtMs;
+                if (!prior || at > prior.at || (at === prior.at && (spec.fingerprint ?? '') > (prior.entry.fingerprint ?? '')))
+                    recorded.set(key, { entry: { ...spec, path: key }, at });
+            }
+        }
+    }
+    const outline = options.outline ?? { specs: [...recorded.values()].map(item => item.entry).sort((a, b) => (a.path < b.path ? -1 : 1)), sha: null, changedFiles: [] };
+    const combined = combineEvidence(outline, layers);
+    const headers = distinctHeaders(layers.map(evidence => evidence.layer)).sort((a, b) => b.recordedAtMs - a.recordedAtMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return { combined, layers: headers, backends: info.sort((a, b) => (a.id < b.id ? -1 : 1)), notices: [...new Set(notices)].sort(), summary: summarize(combined) };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * @module Copying layers between stores
+ *
+ * `copyStore` copies the layers one store has and another lacks: how partial reports meet (each CI node publishes to its own
+ * store; copying them together is the aggregate). It is idempotent, commutative and safe to repeat, because layers are
+ * immutable and named by their content, and it writes in dependency order (files, then documents, then catalog entries) so a
+ * reader of the destination, or a server that checks, never sees something before what it names.
+ *
+ * @see docs/report-contract.md
+ */
+import type { ObjectStore } from './object-store.js';
+/**
+ * Copy every layer object (`layers/…`) of `from` that `to` does not have. Only layers: they are
+ * immutable, so an object that exists is already right. Commit-keyed legacy objects are mutable and
+ * are left where they are. This is how partial reports meet: each CI
+ * node publishes into its own store, and copying them together is the aggregate, because layers are
+ * immutable, addressed by content, and never share a key with different bytes. It is idempotent,
+ * commutative and safe to repeat after a failure.
+ *
+ * A layer's catalog entry is copied last, and its manifest after its files, so a reader of `to` never sees an
+ * entry for a layer whose content has not arrived.
+ */
+export declare function copyStore(from: ObjectStore, to: ObjectStore, options?: {
+    readonly concurrency?: number;
+}): Promise<{
+    readonly copied: number;
+    readonly skipped: number;
+    readonly ignored: number;
+}>;

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

@@ -0,0 +1,52 @@
+/**
+ * @module Copying layers between stores
+ *
+ * `copyStore` copies the layers one store has and another lacks: how partial reports meet (each CI node publishes to its own
+ * store; copying them together is the aggregate). It is idempotent, commutative and safe to repeat, because layers are
+ * immutable and named by their content, and it writes in dependency order (files, then documents, then catalog entries) so a
+ * reader of the destination, or a server that checks, never sees something before what it names.
+ *
+ * @see docs/report-contract.md
+ */
+import { eachLimited } from './completion-order.js';
+import { readBytes } from './object-io.js';
+/**
+ * What is copied after what it names, so a reader (or a server that checks) never sees one without its content:
+ * files first, then the documents that name files (a layer's manifest, a spec set, a run's manifest), then the
+ * catalog entries that make a document visible.
+ */
+const isCatalog = (key) => key.includes('/index/');
+const isDocument = (key) => /^layers\/(manifests\/|specs\/sets\/|runs\/[^/]+\/manifest\.json$)/.test(key);
+/**
+ * Copy every layer object (`layers/…`) of `from` that `to` does not have. Only layers: they are
+ * immutable, so an object that exists is already right. Commit-keyed legacy objects are mutable and
+ * are left where they are. This is how partial reports meet: each CI
+ * node publishes into its own store, and copying them together is the aggregate, because layers are
+ * immutable, addressed by content, and never share a key with different bytes. It is idempotent,
+ * commutative and safe to repeat after a failure.
+ *
+ * A layer's catalog entry is copied last, and its manifest after its files, so a reader of `to` never sees an
+ * entry for a layer whose content has not arrived.
+ */
+export async function copyStore(from, to, options = {}) {
+    const everything = await from.listKeys();
+    const keys = everything.filter(key => key.startsWith('layers/'));
+    const width = options.concurrency ?? 16;
+    let copied = 0, skipped = 0;
+    const copy = async (key) => {
+        if (await to.head(key)) {
+            skipped += 1;
+            return;
+        }
+        const stored = await from.get(key);
+        if (!stored)
+            return;
+        await to.put(key, await readBytes(stored.body), stored.contentType);
+        copied += 1;
+    };
+    await eachLimited(keys.filter(key => !isCatalog(key) && !isDocument(key)), width, copy);
+    await eachLimited(keys.filter(key => !isCatalog(key) && isDocument(key)), width, copy);
+    await eachLimited(keys.filter(isCatalog), width, copy);
+    // Said, not silent: whatever is not a layer was left where it is.
+    return { copied, skipped, ignored: everything.length - keys.length };
+}