@crvouga/atlas 0.4.0 → 0.6.0

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

@@ -0,0 +1,166 @@
+/**
+ * @module Directory-backed object store
+ *
+ * The {@link ObjectStore} implementation for a local folder: a CI workspace, a downloaded artifact, a mount or a
+ * laptop. Each key is a file under the root; its content type is kept in a sidecar `<key>.content-type`. Writes go
+ * to a temporary `.tmp-*` file and are renamed into place so a reader sees all of an object or none of it. Keys
+ * that could escape the root (`..`, absolute, backslash, empty segments) or collide with the sidecar or temporary
+ * names are rejected with an error. Node/Bun only.
+ *
+ * @see docs/report-contract.md (backends)
+ */
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ObjectStoreWithPrefix } from './store-prefix.js';
+const TYPE_SUFFIX = '.content-type';
+const TEMP_PREFIX = '.tmp-';
+function rejectKey(key) {
+    const parts = key.split('/');
+    const last = parts.at(-1) ?? '';
+    if (key.length === 0 || key.startsWith('/') || key.includes('\\') || parts.some((part) => part.length === 0 || part === '.' || part === '..') || last.endsWith(TYPE_SUFFIX) || last.startsWith(TEMP_PREFIX)) {
+        throw new Error(`Invalid object store key: ${key}`);
+    }
+}
+function fileOf(root, key) {
+    rejectKey(key);
+    const rootPath = path.resolve(root);
+    const file = path.resolve(rootPath, key);
+    if (file !== rootPath && !file.startsWith(rootPath + path.sep))
+        throw new Error(`Invalid object store key: ${key}`);
+    return file;
+}
+function missing(error) {
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+let counter = 0;
+/** Write beside the target and rename into place: a reader sees the whole object or none of it. */
+async function writeAtomically(file, bytes) {
+    const temporary = path.join(path.dirname(file), `${TEMP_PREFIX}${process.pid}-${Date.now().toString(36)}-${(counter += 1).toString(36)}`);
+    try {
+        await writeFile(temporary, bytes);
+        await rename(temporary, file);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+/**
+ * Creates an {@link ObjectStore} on a directory: one file per key, its content type in a sidecar file. The
+ * backend for a CI workspace, a downloaded artifact or a laptop. Writes are atomic, listing reads
+ * only the directories a prefix can reach, and two stores over copies of the same layers can be
+ * merged with `cp -R` because layers are immutable and addressed by content.
+ *
+ * The directory need not exist yet: `put` creates it, and `get`/`head`/`listKeys` on a missing one answer
+ * null/false/`[]`. A missing sidecar reads as `application/octet-stream`. `put` writes the content type before
+ * the bytes, so an object is never visible without its type. `listKeys` returns keys in code-unit order, skips
+ * temporary and sidecar files, and throws on a prefix that is absolute, contains a backslash or `..`. `getUri`
+ * is a `file://` URL. Also implements `listPage` (`after` is exclusive, `limit` defaults to 1000, `next` is the
+ * last returned key while more remain).
+ *
+ * @example
+ * const store = directoryStore('./atlas-reports');
+ * await store.put('layers/blobs/x', new TextEncoder().encode('hi'), 'text/plain');
+ * await store.listKeys('layers/'); // ['layers/blobs/x']
+ */
+export function directoryStore(root) {
+    const store = {
+        async get(key) {
+            const file = fileOf(root, key);
+            try {
+                // The type is beside the object: both are asked for at once.
+                const [content, contentType] = await Promise.all([readFile(file), readFile(file + TYPE_SUFFIX, 'utf8').catch(() => 'application/octet-stream')]);
+                const bytes = content;
+                return {
+                    body: new ReadableStream({
+                        start(controller) {
+                            controller.enqueue(bytes);
+                            controller.close();
+                        }
+                    }),
+                    contentType: contentType.trim() || 'application/octet-stream',
+                    size: bytes.byteLength
+                };
+            }
+            catch (error) {
+                if (missing(error))
+                    return null;
+                throw error;
+            }
+        },
+        async put(key, bytes, contentType) {
+            const file = fileOf(root, key);
+            await mkdir(path.dirname(file), { recursive: true });
+            // The type first: an object is never visible without it.
+            await writeAtomically(file + TYPE_SUFFIX, contentType);
+            await writeAtomically(file, bytes);
+        },
+        async head(key) {
+            try {
+                return (await stat(fileOf(root, key))).isFile();
+            }
+            catch (error) {
+                if (missing(error))
+                    return false;
+                throw error;
+            }
+        },
+        async delete(key) {
+            const file = fileOf(root, key);
+            await rm(file, { force: true });
+            await rm(file + TYPE_SUFFIX, { force: true });
+        },
+        async deleteMany(keys) {
+            for (const key of keys)
+                await store.delete(key);
+        },
+        async getUri(key) {
+            return (await store.head(key)) ? pathToFileURL(fileOf(root, key)).href : null;
+        },
+        async listKeys(prefix = '') {
+            const rootPath = path.resolve(root);
+            const found = [];
+            const walk = async (dir) => {
+                let entries;
+                try {
+                    entries = await readdir(dir, { withFileTypes: true });
+                }
+                catch (error) {
+                    if (missing(error))
+                        return;
+                    throw error;
+                }
+                await Promise.all(entries.map(async (entry) => {
+                    if (entry.name.startsWith(TEMP_PREFIX) || entry.name.endsWith(TYPE_SUFFIX))
+                        return;
+                    const full = path.join(dir, entry.name);
+                    if (entry.isDirectory())
+                        return walk(full);
+                    if (!entry.isFile())
+                        return;
+                    const key = path.relative(rootPath, full).split(path.sep).join('/');
+                    if (key.startsWith(prefix))
+                        found.push(key);
+                }));
+            };
+            // Only the directory a prefix names can hold its keys.
+            const slash = prefix.lastIndexOf('/');
+            if (prefix.startsWith('/') || prefix.includes('\\') || prefix.split('/').some((part) => part === '..'))
+                throw new Error(`Invalid object store prefix: ${prefix}`);
+            await walk(slash < 0 ? rootPath : path.resolve(rootPath, prefix.slice(0, slash)));
+            return found.sort();
+        },
+        async listPage(prefix, options = {}) {
+            const all = await store.listKeys(prefix);
+            const from = options.after === undefined ? 0 : all.findIndex(key => key > options.after);
+            const keys = from < 0 ? [] : all.slice(from, from + (options.limit ?? 1000));
+            return { keys, next: from >= 0 && from + keys.length < all.length ? keys.at(-1) ?? null : null };
+        },
+        withPrefix(prefix) {
+            return new ObjectStoreWithPrefix(store, prefix);
+        }
+    };
+    return store;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * @module Store doctor and IAM policy
+ *
+ * `inspectStore` checks that a store works end to end (credentials, listing, what it holds, writing and reading back a
+ * scratch object) and says what to fix when it does not; `iamPolicy` prints the least-privilege AWS policy for publishers
+ * and readers. Used by `atlas report doctor` and `atlas report policy`, for folders, S3-compatible buckets and Atlas
+ * servers alike.
+ *
+ * @see docs/deploying.md
+ */
+import type { CliBackend } from './cli-stores.js';
+/** One thing `inspectStore` checked: its `name` (`store`, `list`, `contents`, `write`, …), whether it is `ok`, what was seen, and, when it is not, what to `fix`. */
+export type Check = {
+    readonly ok: boolean;
+    readonly name: string;
+    readonly detail: string;
+    readonly fix?: string;
+};
+/** The least an account needs, as an AWS IAM policy. The combined server role also stores operational leases under server/live/. R2, MinIO and the rest have their own policy languages: grant the same actions. */
+export declare function iamPolicy(location: {
+    bucket: string;
+    prefix: string;
+}, role: 'publisher' | 'reader' | 'both'): object;
+/** What the account being checked is for: `publisher` (writes layers), `reader` (reads them) or `both`. It decides which checks run. */
+export type Role = 'publisher' | 'reader' | 'both';
+/** Is this store usable for Atlas, and if not, what exactly is wrong? Each step says what to do. */
+export declare function inspectStore(backend: CliBackend, options?: {
+    readonly role?: Role;
+}): Promise<Check[]>;

package/dist/reports/src/doctor.js

@@ -0,0 +1,85 @@
+/**
+ * @module Store doctor and IAM policy
+ *
+ * `inspectStore` checks that a store works end to end (credentials, listing, what it holds, writing and reading back a
+ * scratch object) and says what to fix when it does not; `iamPolicy` prints the least-privilege AWS policy for publishers
+ * and readers. Used by `atlas report doctor` and `atlas report policy`, for folders, S3-compatible buckets and Atlas
+ * servers alike.
+ *
+ * @see docs/deploying.md
+ */
+import { LAYER_INDEX } from './layer-store.js';
+import { verifyObjectStore } from './object-store-conformance.js';
+/** The least an account needs, as an AWS IAM policy. The combined server role also stores operational leases under server/live/. R2, MinIO and the rest have their own policy languages: grant the same actions. */
+export function iamPolicy(location, role) {
+    const base = location.prefix ? `${location.prefix}/` : '';
+    const bucketArn = `arn:aws:s3:::${location.bucket}`;
+    const statements = [];
+    if (role !== 'reader') {
+        statements.push({ Sid: 'AtlasPublish', Effect: 'Allow', Action: ['s3:PutObject', 's3:GetObject'], Resource: `${bucketArn}/${base}layers/*` }, { Sid: 'AtlasDoctorCleanup', Effect: 'Allow', Action: 's3:DeleteObject', Resource: `${bucketArn}/${base}layers/doctor-*` });
+    }
+    if (role !== 'publisher') {
+        statements.push({ Sid: 'AtlasRead', Effect: 'Allow', Action: 's3:GetObject', Resource: `${bucketArn}/${base}layers/*` });
+    }
+    if (role === 'both')
+        statements.push({ Sid: 'AtlasLiveRuns', Effect: 'Allow', Action: ['s3:GetObject', 's3:PutObject'], Resource: `${bucketArn}/${base}server/live/*` }, { Sid: 'AtlasProjects', Effect: 'Allow', Action: ['s3:GetObject', 's3:PutObject', 's3:DeleteObject'], Resource: [`${bucketArn}/${base}projects/*`, `${bucketArn}/${base}server/projects/*`] });
+    // Publishers need this too: without it S3 answers 403, not 404, when asked whether a layer exists yet.
+    statements.push({ Sid: 'AtlasList', Effect: 'Allow', Action: 's3:ListBucket', Resource: bucketArn, // IfExists: a listing always carries a prefix and is held to it; a HEAD or GET of one object carries none, and
+        // must still be answered "not found" rather than "forbidden".
+        ...(base ? { Condition: { StringLikeIfExists: { 's3:prefix': [base, `${base}*`] } } } : {}) });
+    return { Version: '2012-10-17', Statement: statements };
+}
+const when = (inverted) => {
+    const time = inverted ? Number.MAX_SAFE_INTEGER - Number(inverted) : NaN;
+    return Number.isFinite(time) ? new Date(time).toISOString() : 'unknown';
+};
+/** Is this store usable for Atlas, and if not, what exactly is wrong? Each step says what to do. */
+export async function inspectStore(backend, options = {}) {
+    const role = options.role ?? 'both';
+    const checks = [];
+    const add = (check) => { checks.push(check); return check.ok; };
+    const store = backend.store;
+    const s3 = backend.s3;
+    add({ ok: true, name: 'store', detail: s3?.label ?? backend.label ?? backend.id });
+    if (s3 && role !== 'publisher') {
+        const ping = await s3.ping();
+        add(ping.ok
+            ? { ok: true, name: 'list', detail: `${ping.ms} ms${s3.credentialSource() ? `, credentials from ${s3.credentialSource()}` : ''}` }
+            : { ok: false, name: 'list', detail: ping.error ?? 'failed', fix: 'Check the bucket, region and endpoint in the store URL, and the credentials. `atlas report policy --store <url>` prints the permissions needed.' });
+        if (!ping.ok)
+            return checks;
+    }
+    if (role !== 'publisher') {
+        try {
+            const keys = await store.listKeys(LAYER_INDEX);
+            const [sets, runs] = await Promise.all([store.listKeys('layers/specs/index/'), store.listKeys('layers/runs/index/')]);
+            add({ ok: true, name: 'contents', detail: `${keys.length} layer${keys.length === 1 ? '' : 's'}${keys.length ? ` (newest ${when(/\/(\d{16})-/.exec(keys[0])?.[1])})` : ''}, ${sets.length} spec set${sets.length === 1 ? '' : 's'}, ${runs.length} run${runs.length === 1 ? '' : 's'}` });
+        }
+        catch (error) {
+            add({ ok: false, name: 'contents', detail: error instanceof Error ? error.message : String(error) });
+            return checks;
+        }
+    }
+    if (role === 'reader')
+        return checks;
+    const scratch = `layers/doctor-${Math.random().toString(36).slice(2, 10)}/`;
+    if (role === 'both') {
+        const verification = await verifyObjectStore(store, scratch);
+        add(verification.ok
+            ? { ok: true, name: 'write', detail: 'wrote, listed, read back and deleted a scratch object: the store meets the ObjectStore contract' }
+            : { ok: false, name: 'write', detail: verification.failures.join('; '), fix: 'Publishers need s3:PutObject and s3:GetObject on layers/*, and the doctor s3:DeleteObject on layers/doctor-*. To check a publisher-only or read-only account, pass --role publisher or --role reader.' });
+        return checks;
+    }
+    // A publisher cannot list: prove what it does, which is put, head and get.
+    const key = `${scratch}probe.txt`;
+    try {
+        await store.put(key, new TextEncoder().encode('atlas'), 'text/plain');
+        const found = await store.head(key);
+        await store.delete(key).catch(() => { });
+        add(found ? { ok: true, name: 'write', detail: 'wrote and found a scratch object' } : { ok: false, name: 'write', detail: 'an object was written but could not be found again', fix: 'The account needs s3:GetObject (HeadObject) on layers/*.' });
+    }
+    catch (error) {
+        add({ ok: false, name: 'write', detail: error instanceof Error ? error.message : String(error), fix: 'Publishers need s3:PutObject and s3:GetObject on layers/*, and s3:ListBucket on the bucket (S3 answers 403 instead of 404 for a missing object without it).' });
+    }
+    return checks;
+}

package/dist/reports/src/effective-delta.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module Report deltas
+ *
+ * The client half of "send only what changed": `applyEffectiveDelta` turns the report a viewer holds and a delta from the
+ * server (`GET /api/reports/evidence/effective?since=<version>`) into the current report. Pure and free of Node APIs, so a
+ * browser bundle uses it. The server half is `ReportIndex.delta`; a test holds the two together over random runs.
+ *
+ * @see docs/server.md#reading-only-what-changed
+ */
+import type { LayerEvidence } from './evidence-types.js';
+import type { EffectiveEvidence } from './report-index.js';
+/**
+ * What a server answers when a viewer asks for the report `since` a version it holds and the server still
+ * remembers that version: only what changed. `layers` are whole layers (with the rows that win), replacing those
+ * of the same id; `removed` are layers that no longer win anything. Everything else, `backends` and `notices`
+ * and the count, is sent whole because it is small.
+ *
+ * It is an optimisation and nothing else: applying it gives exactly the report the server would have sent in
+ * full, and a server that does not know it sends the full report, which a viewer takes as it always did.
+ */
+export type EffectiveDelta = Omit<EffectiveEvidence, 'layers'> & {
+    readonly delta: true;
+    /** The version this applies to. */
+    readonly base: string;
+    readonly layers: readonly LayerEvidence[];
+    readonly removed: readonly string[];
+};
+/** Is `value` a delta (`delta: true`, a `base` version, `layers` and `removed`) and not a whole report? Decides which of the two a server answered. */
+export declare const isEffectiveDelta: (value: unknown) => value is EffectiveDelta;
+/**
+ * The report a delta leads to, or null when it does not apply to `held` (a different version): ask for the
+ * whole report then.
+ */
+export declare function applyEffectiveDelta(held: EffectiveEvidence, delta: EffectiveDelta): EffectiveEvidence | null;

package/dist/reports/src/effective-delta.js

@@ -0,0 +1,25 @@
+/**
+ * @module Report deltas
+ *
+ * The client half of "send only what changed": `applyEffectiveDelta` turns the report a viewer holds and a delta from the
+ * server (`GET /api/reports/evidence/effective?since=<version>`) into the current report. Pure and free of Node APIs, so a
+ * browser bundle uses it. The server half is `ReportIndex.delta`; a test holds the two together over random runs.
+ *
+ * @see docs/server.md#reading-only-what-changed
+ */
+/** Is `value` a delta (`delta: true`, a `base` version, `layers` and `removed`) and not a whole report? Decides which of the two a server answered. */
+export const isEffectiveDelta = (value) => typeof value === 'object' && value !== null && value.delta === true && typeof value.base === 'string' && Array.isArray(value.layers) && Array.isArray(value.removed);
+/** The report order: newest first, ties by id. */
+const byRecency = (a, b) => b.layer.recordedAtMs - a.layer.recordedAtMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/**
+ * The report a delta leads to, or null when it does not apply to `held` (a different version): ask for the
+ * whole report then.
+ */
+export function applyEffectiveDelta(held, delta) {
+    if (held.version !== delta.base)
+        return null;
+    const gone = new Set(delta.removed);
+    const replaced = new Set(delta.layers.map(layer => layer.id));
+    const layers = [...held.layers.filter(layer => !gone.has(layer.id) && !replaced.has(layer.id)), ...delta.layers].sort(byRecency);
+    return { version: delta.version, layers, backends: delta.backends, notices: delta.notices, totalLayers: delta.totalLayers };
+}

package/dist/reports/src/evidence-detail.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @module Evidence of one result
+ *
+ * Reads the evidence (attachments, steps, annotations, attempts, tags, labels, links, extensions) that a layer, a
+ * part or a check carries beyond its outcome: the short summary that rides in every report row, one result's full
+ * detail, and the bundle keys its files live under. It only reads; evidence never decides a status, a slot or a
+ * winner, so nothing here affects who wins.
+ *
+ * @see docs/extending.md
+ * @see docs/report-contract.md (evidence)
+ */
+import type { Annotation, Attachment, Attempt, Check, Step } from '../../schema/src/layer.js';
+import type { EvidenceSummary } from './evidence-types.js';
+/** Anything that may carry evidence: a layer, a part or a check. */
+export type EvidenceHolder = {
+    readonly tags?: readonly string[];
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly links?: readonly {
+        readonly url: string;
+        readonly name?: string | undefined;
+        readonly rel?: string | undefined;
+    }[];
+    readonly attachments?: readonly Attachment[];
+    readonly annotations?: readonly Annotation[];
+    readonly steps?: readonly Step[];
+    readonly attempts?: readonly Attempt[];
+    readonly extensions?: Readonly<Record<string, unknown>>;
+};
+/**
+ * What a result carries beyond its outcome, as counts and short facts. It rides in every row of the
+ * report so a list can show "3 attachments, 12 steps" without opening anything; the evidence itself is
+ * read when someone asks for it. Undefined when there is none.
+ *
+ * Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
+ * attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
+ * label the later holder wins. `roles` are the attachments' roles (or, without one, what their media type or file
+ * name implies), sorted and distinct.
+ */
+export declare function summarizeEvidence(...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined;
+/** A role to show when a producer gave none, from the media type: `image`, `video`, `audio`, `snapshot` (text/html), `text` (text, JSON, XML) or `file`. Roles are an open vocabulary; a producer's own role always wins. */
+export declare function roleOfType(contentType: string | undefined): string;
+/** All of one result's evidence, read when someone opens it. */
+export type CheckDetail = {
+    /** The id of the layer the check was read from. */
+    readonly layer: string;
+    /** The kind of the part that holds the check. */
+    readonly kind: string;
+    /** The check as recorded, with all of its evidence. */
+    readonly check: Check;
+    /** What the run as a whole carries: its logs, its links, its labels. */
+    readonly run: EvidenceHolder;
+};
+/** One result's evidence, from a layer: the first check with id `checkId` (in a part of kind `kind`, when given) plus the layer's own evidence. Null when the layer holds no such check. */
+export declare function checkDetailOf(layer: {
+    readonly id: string;
+    readonly parts: readonly {
+        readonly kind: string;
+        readonly checks: readonly Check[];
+    }[];
+} & EvidenceHolder, checkId: string, kind?: string): CheckDetail | null;
+/** What a layer carries as a whole (its tags, labels, links, attachments, annotations and extensions; not its parts' checks). Absent fields stay absent. */
+export declare function runEvidence(layer: EvidenceHolder): EvidenceHolder;
+/** Every distinct bundle key (`bundleKey`) that the attachments of a holder, its steps and its attempts point to, so a layer's files can be copied. Attachments held by `uri` or inline `text` have none. */
+export declare function bundleKeysOf(holder: EvidenceHolder): string[];

package/dist/reports/src/evidence-detail.js

@@ -0,0 +1,92 @@
+import { contentTypeOf } from './media-types.js';
+function count(holder) {
+    return (holder.attachments?.length ?? 0) + (holder.steps?.length ?? 0) + (holder.annotations?.length ?? 0) + (holder.attempts?.length ?? 0) + (holder.tags?.length ?? 0) + (holder.links?.length ?? 0) + Object.keys(holder.labels ?? {}).length + Object.keys(holder.extensions ?? {}).length;
+}
+/**
+ * What a result carries beyond its outcome, as counts and short facts. It rides in every row of the
+ * report so a list can show "3 attachments, 12 steps" without opening anything; the evidence itself is
+ * read when someone asks for it. Undefined when there is none.
+ *
+ * Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
+ * attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
+ * label the later holder wins. `roles` are the attachments' roles (or, without one, what their media type or file
+ * name implies), sorted and distinct.
+ */
+export function summarizeEvidence(...holders) {
+    if (!holders.some(holder => count(holder) > 0))
+        return undefined;
+    const roles = new Set();
+    const tags = new Set();
+    const labels = {};
+    let attachments = 0, steps = 0, annotations = 0, attempts = 0, links = 0;
+    const attachmentsOf = (list) => { for (const item of list ?? []) {
+        attachments += 1;
+        roles.add(item.role ?? roleOfType(item.contentType ?? contentTypeOf(item.name)));
+    } };
+    for (const holder of holders) {
+        attachmentsOf(holder.attachments);
+        // Attachments on steps and attempts are part of the check too.
+        for (const step of holder.steps ?? [])
+            attachmentsOf(step.attachments);
+        for (const attempt of holder.attempts ?? []) {
+            attachmentsOf(attempt.attachments);
+            for (const step of attempt.steps ?? [])
+                attachmentsOf(step.attachments);
+        }
+        steps += holder.steps?.length ?? 0;
+        annotations += holder.annotations?.length ?? 0;
+        attempts += holder.attempts?.length ?? 0;
+        links += holder.links?.length ?? 0;
+        for (const tag of holder.tags ?? [])
+            tags.add(tag);
+        Object.assign(labels, holder.labels);
+    }
+    return { attachments, steps, annotations, attempts, links, tags: [...tags], labels, roles: [...roles].sort() };
+}
+/** A role to show when a producer gave none, from the media type: `image`, `video`, `audio`, `snapshot` (text/html), `text` (text, JSON, XML) or `file`. Roles are an open vocabulary; a producer's own role always wins. */
+export function roleOfType(contentType) {
+    const type = (contentType ?? '').toLowerCase();
+    if (type.startsWith('image/'))
+        return 'image';
+    if (type.startsWith('video/'))
+        return 'video';
+    if (type.startsWith('audio/'))
+        return 'audio';
+    if (type === 'text/html')
+        return 'snapshot';
+    if (type.startsWith('text/') || type.includes('json') || type.includes('xml'))
+        return 'text';
+    return 'file';
+}
+/** One result's evidence, from a layer: the first check with id `checkId` (in a part of kind `kind`, when given) plus the layer's own evidence. Null when the layer holds no such check. */
+export function checkDetailOf(layer, checkId, kind) {
+    for (const part of layer.parts) {
+        if (kind !== undefined && part.kind !== kind)
+            continue;
+        const check = part.checks.find(item => item.id === checkId);
+        if (check)
+            return { layer: layer.id, kind: part.kind, check, run: runEvidence(layer) };
+    }
+    return null;
+}
+/** What a layer carries as a whole (its tags, labels, links, attachments, annotations and extensions; not its parts' checks). Absent fields stay absent. */
+export function runEvidence(layer) {
+    const { tags, labels, links, attachments, annotations, extensions } = layer;
+    return { ...(tags ? { tags } : {}), ...(labels ? { labels } : {}), ...(links ? { links } : {}), ...(attachments ? { attachments } : {}), ...(annotations ? { annotations } : {}), ...(extensions ? { extensions } : {}) };
+}
+/** Every distinct bundle key (`bundleKey`) that the attachments of a holder, its steps and its attempts point to, so a layer's files can be copied. Attachments held by `uri` or inline `text` have none. */
+export function bundleKeysOf(holder) {
+    const keys = new Set();
+    const take = (list) => { for (const item of list ?? [])
+        if (item.bundleKey)
+            keys.add(item.bundleKey); };
+    take(holder.attachments);
+    for (const step of holder.steps ?? [])
+        take(step.attachments);
+    for (const attempt of holder.attempts ?? []) {
+        take(attempt.attachments);
+        for (const step of attempt.steps ?? [])
+            take(step.attachments);
+    }
+    return [...keys];
+}

package/dist/reports/src/evidence-live.d.ts

@@ -1,35 +1,65 @@
+/**
+ * @module Live evidence from running suites
+ *
+ * Shows results the moment each test finishes, before its package has been collected into an archived layer. A
+ * running suite announces itself with a record under `active/` in the local store (see {@link LiveRunRecord});
+ * this module reads the test reports that suite has written so far into a temporary layer (id `live-<source>`,
+ * `live: true`) and drops it once the archived layer arrives or after a short linger. Live layers are a viewing
+ * aid only (this module writes nothing), and an unreadable or half-written report is skipped, not guessed at.
+ */
 import type { Clock } from './clock.js';
 import type { ActiveRun, LayerEvidence, LayerHeader } from './evidence-types.js';
 import type { LayerParameters } from './layer-types.js';
 import type { ObjectStore } from './object-store.js';
 /** What a running spec suite announces under `active/` in the local store. */
 export type LiveRunRecord = {
+    /** The package directory the suite runs in, relative to the repository (`libs/chess`); with `bucket`, it names the source. */
     readonly packageDir: string;
+    /** The suite's bucket within the package (`part-2`); where the run writes each finished test. */
     readonly bucket: string;
+    /** When the run started, epoch milliseconds. A new value for the same source means a new run: tracking restarts. */
     readonly startedAtMs: number;
+    /** How many checks the run expects to execute, when known. */
     readonly plannedChecks?: number;
     /** The client this suite is checking. A different client does not replace it. */
     readonly environment?: string;
+    /** Other string choices that make the results their own slot; non-string or empty values are dropped on reading. */
     readonly parameters?: LayerParameters;
 };
-/** A run announcement with the fields the live layer can trust. Null when it cannot be a run. */
+/**
+ * Validates a parsed `active/` announcement and keeps only the fields the live layer can trust (the environment is
+ * normalised to its slug, parameters are string-to-string). Null when `packageDir`, `bucket` or a numeric
+ * `startedAtMs` is missing, so garbage in `active/` is ignored rather than shown.
+ */
 export declare function liveRunRecord(value: unknown): LiveRunRecord | null;
 /** How the host reaches the results a spec run has written so far. */
 export type LiveSource = {
-    /** The bucket the run writes each finished test into, or null when it cannot be read. */
+    /** The bucket the run writes each finished test into, or null when it cannot be read (the run is then not tracked). */
     readonly bucket: (run: LiveRunRecord) => ObjectStore | null;
-    /** The checkout the runs execute. */
+    /** The checkout the runs execute: its commit and branch, stamped on every live layer. Asked once per refresh pass. */
     readonly origin?: () => Promise<{
         readonly sha: string | null;
         readonly branch: string | null;
     }>;
-    /** The stylesheet the runs' snapshots render with. */
+    /** The stylesheet the runs' snapshots render with (served as `frame.css`). */
     readonly frameCss?: () => Promise<string | null>;
 };
+/** The id of the temporary layer for a source: `live-<source>`. Not a content hash, unlike an archived layer's id. */
 export declare function liveLayerId(source: string): string;
 /**
- * Finished tests of runs that have not been collected into a layer yet, so a
+ * Creates the tracker of finished tests of runs that have not been collected into a layer yet, so a
  * result appears the moment its test ends instead of when its package does.
+ *
+ * The tracker is stateful and meant to live as long as the server: call `refresh` on each poll with the current
+ * `active/` records and the newest archived layers. It returns the live layers (only those with at least one result)
+ * and the runs still in progress with their completed and failed counts. A run that disappears is read one last
+ * time and kept for 30 seconds, or until an archived (non-live) layer of the same producer and environment recorded
+ * at or after its start appears. `find(id)` returns a live layer by `live-<source>` id, and `store(source)` the
+ * bucket its files are read from. A bucket that is being replaced or a report still being written is skipped until
+ * the next pass; `refresh` does not throw for those.
+ *
+ * @param args.live How the host reaches the buckets; without it nothing is tracked.
+ * @param args.backend The backend id stamped on live layers.
  */
 export declare function createLiveEvidence(args: {
     readonly live: LiveSource | undefined;

package/dist/reports/src/evidence-live.js

@@ -17,7 +17,11 @@ function readParameters(value) {
             parameters[key] = item;
     return parameters;
 }
-/** A run announcement with the fields the live layer can trust. Null when it cannot be a run. */
+/**
+ * Validates a parsed `active/` announcement and keeps only the fields the live layer can trust (the environment is
+ * normalised to its slug, parameters are string-to-string). Null when `packageDir`, `bucket` or a numeric
+ * `startedAtMs` is missing, so garbage in `active/` is ignored rather than shown.
+ */
 export function liveRunRecord(value) {
     if (!value || typeof value !== 'object')
         return null;
@@ -38,6 +42,7 @@ export function liveRunRecord(value) {
 /** A finished run stays visible this long while its layer is being collected. */
 const LINGER_MS = 30_000;
 const REPORT = '/report.json';
+/** The id of the temporary layer for a source: `live-<source>`. Not a content hash, unlike an archived layer's id. */
 export function liveLayerId(source) {
     return `live-${source}`;
 }
@@ -50,8 +55,19 @@ function sourceOf(run) {
     }
 }
 /**
- * Finished tests of runs that have not been collected into a layer yet, so a
+ * Creates the tracker of finished tests of runs that have not been collected into a layer yet, so a
  * result appears the moment its test ends instead of when its package does.
+ *
+ * The tracker is stateful and meant to live as long as the server: call `refresh` on each poll with the current
+ * `active/` records and the newest archived layers. It returns the live layers (only those with at least one result)
+ * and the runs still in progress with their completed and failed counts. A run that disappears is read one last
+ * time and kept for 30 seconds, or until an archived (non-live) layer of the same producer and environment recorded
+ * at or after its start appears. `find(id)` returns a live layer by `live-<source>` id, and `store(source)` the
+ * bucket its files are read from. A bucket that is being replaced or a report still being written is skipped until
+ * the next pass; `refresh` does not throw for those.
+ *
+ * @param args.live How the host reaches the buckets; without it nothing is tracked.
+ * @param args.backend The backend id stamped on live layers.
  */
 export function createLiveEvidence(args) {
     const tracked = new Map();