@crvouga/atlas 0.4.0 → 0.6.0

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

@@ -1,41 +1,34 @@
 /**
- * Content-addressed binary object storage.
+ * @module ObjectStore interface
  *
- * Tiny, async, transport-agnostic surface — exactly what a "blob keyed by id"
- * cache needs (TTS audio, exported files, derived avatars, etc.). Implementations
- * live in sibling `impl-*.ts` files (S3/R2, in-memory, file-system).
+ * The one interface a backend implements: seven async methods over keys and bytes, with no transactions, renames,
+ * locks or conditional writes. That is what lets a directory, an S3-compatible bucket, an HTTP server and a device
+ * lab hold the same report. Implementations here are `directoryStore`, `s3Store` and `httpStore`; `verifyObjectStore`
+ * proves a new one. This interface is part of the stable report contract.
  *
- * Mirrors the {@link ../sql-client/interface.ts SqlClient} shape: one interface,
- * multiple `impl-*.ts` siblings, plus a conformance suite in `interface.test.ts`.
+ * Read semantics: `get` returns `null` when the key is missing; transport and parse errors throw. `head` returns
+ * `false` for a missing key and never throws on "not found".
  *
- * Read semantics:
- *   - {@link ObjectStore.get} returns `null` when the key is missing. Transport /
- *     parse errors throw.
- *   - {@link ObjectStore.head} returns `false` for a missing key (never throws on
- *     "not found"). Transport errors throw.
+ * Write semantics: `put` is idempotent (writing a key twice overwrites without error) and the stored `contentType`
+ * round-trips through `get`. `delete` and `deleteMany` on a missing key are no-ops.
  *
- * Write semantics:
- *   - {@link ObjectStore.put} MUST be idempotent: writing the same key twice
- *     overwrites without error. Stored `contentType` MUST round-trip through
- *     {@link ObjectStore.get}.
- *   - {@link ObjectStore.delete} on a missing key is a no-op (does not throw).
+ * URI semantics: `getUri` returns a URL the host can load directly (a `file://` URL for a directory, a presigned URL
+ * for S3), or `null` for a missing key or a store with no addressable URL.
  *
- * URI semantics:
- *   - {@link ObjectStore.getUri} returns a URL the host runtime can load
- *     directly (`file://` on native, `blob:` on web). Stores that don't expose
- *     direct URLs (e.g. remote R2 — bytes must be streamed through HTTP)
- *     return `null`. Returns `null` when the key is missing.
+ * Listing: `listKeys` returns keys in sorted code-unit order, optionally only those starting with `prefix`.
  *
- * Listing:
- *   - {@link ObjectStore.listKeys} returns keys in sorted code-unit order
- *     (deterministic). Optional `prefix` filters to keys that start with it.
+ * @see docs/report-contract.md#backends
  */
+/** An object read from a store: a one-shot byte stream with its media type and length. */
 export interface StoredObject {
     /** Stream of stored bytes. Single-use; consume or discard before issuing more I/O on the same store. */
     readonly body: ReadableStream<Uint8Array>;
+    /** The media type the object was written with. */
     readonly contentType: string;
+    /** The length of the object in bytes. */
     readonly size: number;
 }
+/** A place that holds objects by key: the backend interface of the report contract. Keys are `/`-separated strings; see each method for its rules. */
 export interface ObjectStore {
     /** Returns the stored object, or `null` if no value exists for `key`. */
     get(key: string): Promise<StoredObject | null>;
@@ -65,3 +58,19 @@ export interface ObjectStore {
      */
     withPrefix(prefix: string): ObjectStore;
 }
+/**
+ * Optional, beyond the seven methods: list one page of keys, starting after a key. A reader that has
+ * already seen most of a catalog uses it to find what is new without listing all of it. A store without
+ * it works the same, a little slower. Pages are in the same code-unit order as {@link ObjectStore.listKeys}.
+ */
+export interface PagedListing {
+    listPage(prefix: string, options?: {
+        readonly after?: string;
+        readonly limit?: number;
+    }): Promise<{
+        readonly keys: readonly string[]; /** The `after` for the next page, or null on the last. */
+        readonly next: string | null;
+    }>;
+}
+/** Whether a store also implements `PagedListing`. */
+export declare function isPaged(store: ObjectStore): store is ObjectStore & PagedListing;

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

@@ -1,32 +1,25 @@
 /**
- * Content-addressed binary object storage.
+ * @module ObjectStore interface
  *
- * Tiny, async, transport-agnostic surface — exactly what a "blob keyed by id"
- * cache needs (TTS audio, exported files, derived avatars, etc.). Implementations
- * live in sibling `impl-*.ts` files (S3/R2, in-memory, file-system).
+ * The one interface a backend implements: seven async methods over keys and bytes, with no transactions, renames,
+ * locks or conditional writes. That is what lets a directory, an S3-compatible bucket, an HTTP server and a device
+ * lab hold the same report. Implementations here are `directoryStore`, `s3Store` and `httpStore`; `verifyObjectStore`
+ * proves a new one. This interface is part of the stable report contract.
  *
- * Mirrors the {@link ../sql-client/interface.ts SqlClient} shape: one interface,
- * multiple `impl-*.ts` siblings, plus a conformance suite in `interface.test.ts`.
+ * Read semantics: `get` returns `null` when the key is missing; transport and parse errors throw. `head` returns
+ * `false` for a missing key and never throws on "not found".
  *
- * Read semantics:
- *   - {@link ObjectStore.get} returns `null` when the key is missing. Transport /
- *     parse errors throw.
- *   - {@link ObjectStore.head} returns `false` for a missing key (never throws on
- *     "not found"). Transport errors throw.
+ * Write semantics: `put` is idempotent (writing a key twice overwrites without error) and the stored `contentType`
+ * round-trips through `get`. `delete` and `deleteMany` on a missing key are no-ops.
  *
- * Write semantics:
- *   - {@link ObjectStore.put} MUST be idempotent: writing the same key twice
- *     overwrites without error. Stored `contentType` MUST round-trip through
- *     {@link ObjectStore.get}.
- *   - {@link ObjectStore.delete} on a missing key is a no-op (does not throw).
+ * URI semantics: `getUri` returns a URL the host can load directly (a `file://` URL for a directory, a presigned URL
+ * for S3), or `null` for a missing key or a store with no addressable URL.
  *
- * URI semantics:
- *   - {@link ObjectStore.getUri} returns a URL the host runtime can load
- *     directly (`file://` on native, `blob:` on web). Stores that don't expose
- *     direct URLs (e.g. remote R2 — bytes must be streamed through HTTP)
- *     return `null`. Returns `null` when the key is missing.
+ * Listing: `listKeys` returns keys in sorted code-unit order, optionally only those starting with `prefix`.
  *
- * Listing:
- *   - {@link ObjectStore.listKeys} returns keys in sorted code-unit order
- *     (deterministic). Optional `prefix` filters to keys that start with it.
+ * @see docs/report-contract.md#backends
  */
+/** Whether a store also implements `PagedListing`. */
+export function isPaged(store) {
+    return typeof store.listPage === 'function';
+}

package/dist/reports/src/parse-with.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module Schema parsing with readable errors
+ *
+ * One helper that parses untrusted input with a Zod schema and turns every problem into a single error message that
+ * names each failing path, so a publisher can tell a person exactly which field to fix.
+ */
+import type { z } from 'zod/v4';
+/**
+ * Parses `input` with `schema` and returns the parsed value, or throws one `Error` naming every problem by its path.
+ *
+ * The message is `<subject>: <path>: <message>; <path>: <message>`, with `(input)` as the path of a problem at the
+ * root. Nothing is returned partially: on any problem it throws.
+ *
+ * @param subject what is being parsed, as the person would call it (for example `checks file`); prefixes the message.
+ */
+export declare function parseWith<S extends z.ZodType>(schema: S, input: unknown, subject: string): z.output<S>;

package/dist/reports/src/parse-with.js

@@ -0,0 +1,14 @@
+/**
+ * Parses `input` with `schema` and returns the parsed value, or throws one `Error` naming every problem by its path.
+ *
+ * The message is `<subject>: <path>: <message>; <path>: <message>`, with `(input)` as the path of a problem at the
+ * root. Nothing is returned partially: on any problem it throws.
+ *
+ * @param subject what is being parsed, as the person would call it (for example `checks file`); prefixes the message.
+ */
+export function parseWith(schema, input, subject) {
+    const parsed = schema.safeParse(input);
+    if (parsed.success)
+        return parsed.data;
+    throw new Error(`${subject}: ${parsed.error.issues.map(issue => `${issue.path.join('.') || '(input)'}: ${issue.message}`).join('; ')}`);
+}

package/dist/reports/src/performance-part.d.ts

@@ -1,6 +1,30 @@
+/**
+ * @module Performance part of a report
+ *
+ * Turns the measured step timings of recorded test runs into a `performance`-kind report part, one check per run,
+ * so slow actions show beside the behaviour checks. The part is diagnostic: `performance` is the kind that composition
+ * leaves out of counts when anything else was recorded, and a measurement over its limit never fails a check on its
+ * own (here only a step over the allowance marks the diagnostic check `failed`).
+ *
+ * @see docs/report-contract.md#statuses-and-the-gate
+ */
 import type { RunReport } from './report-types.js';
 import type { ReportPart } from './explorer-types.js';
-/** Diagnostic budgets over recorded self time; no missing measurement becomes a pass. */
+/**
+ * Builds a `performance` part with one check per run report, judging each step's own recorded time against
+ * `allowanceMs`. No missing measurement becomes a pass.
+ *
+ * A check is `failed` when any step's self time is over `allowanceMs`; `not-run` when the run has no steps or any step
+ * has no measurement; otherwise `passed`. Its `id` and `title` are the run's `testId` and `title`, its `specPath` the
+ * run's `sourceFile` when known, and it carries one measurement, `Longest own action` in ms with the allowance as its
+ * `limit`, when anything was measured. The part's id is `recorded-performance`. Throws `Invalid performance allowance`
+ * when `allowanceMs` is not a positive finite number.
+ *
+ * @param args.sha the commit the runs were recorded at.
+ * @param args.recordedAtMs when the runs were recorded, epoch milliseconds.
+ * @param args.allowanceMs the diagnostic allowance for one step's own time, in milliseconds.
+ * @param args.reports the recorded runs.
+ */
 export declare function performancePart(args: {
     readonly sha: string;
     readonly recordedAtMs: number;

package/dist/reports/src/performance-part.js

@@ -1,5 +1,19 @@
 import { performanceRows } from './performance.js';
-/** Diagnostic budgets over recorded self time; no missing measurement becomes a pass. */
+/**
+ * Builds a `performance` part with one check per run report, judging each step's own recorded time against
+ * `allowanceMs`. No missing measurement becomes a pass.
+ *
+ * A check is `failed` when any step's self time is over `allowanceMs`; `not-run` when the run has no steps or any step
+ * has no measurement; otherwise `passed`. Its `id` and `title` are the run's `testId` and `title`, its `specPath` the
+ * run's `sourceFile` when known, and it carries one measurement, `Longest own action` in ms with the allowance as its
+ * `limit`, when anything was measured. The part's id is `recorded-performance`. Throws `Invalid performance allowance`
+ * when `allowanceMs` is not a positive finite number.
+ *
+ * @param args.sha the commit the runs were recorded at.
+ * @param args.recordedAtMs when the runs were recorded, epoch milliseconds.
+ * @param args.allowanceMs the diagnostic allowance for one step's own time, in milliseconds.
+ * @param args.reports the recorded runs.
+ */
 export function performancePart(args) {
     if (!Number.isFinite(args.allowanceMs) || args.allowanceMs <= 0)
         throw new Error('Invalid performance allowance');

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

@@ -1,13 +1,33 @@
+/**
+ * @module Performance heat of recorded steps
+ *
+ * Classifies each step of a recorded run by how long its own work took against an allowance, ranks hotspots, and
+ * indexes steps to a frame for a heatmap. Pure functions over `ReportStep` trees. The allowance is a diagnostic
+ * threshold, not a portable CPU or paint-time assertion.
+ */
 import type { ReportStep } from './report-types.js';
 import { type FlatFrame, type FlatStep } from './frames.js';
+/** How a step's own time compares with the allowance: `unmeasured` (no valid time), `cool`, `warm` (over a quarter of it) or `slow` (over it). */
 export type HeatBand = 'unmeasured' | 'cool' | 'warm' | 'slow';
+/** A flattened step with its heat band. */
 export type PerformanceRow = FlatStep & {
+    /** The step's `performance.selfMs` classified by `heatBand`. */
     readonly band: HeatBand;
 };
+/**
+ * Classifies a duration in milliseconds against `allowanceMs`: `unmeasured` when it is missing, not finite or
+ * negative; `slow` when over the allowance; `warm` when over a quarter of it; otherwise `cool`.
+ */
 export declare function heatBand(ms: number | undefined, allowanceMs: number): HeatBand;
+/** Flattens a step tree depth-first (parents before children) into rows, each banded by its own recorded time (`performance.selfMs`) against `allowanceMs`. */
 export declare function performanceRows(steps: readonly ReportStep[], allowanceMs: number): PerformanceRow[];
-/** Self time attributes nested work once, instead of ranking every ancestor as slow. */
+/** The measured rows, longest own time first and earlier rows first on a tie. Self time attributes nested work once, instead of ranking every ancestor as slow. Sorts in place the array it builds, not `rows`. */
 export declare function performanceHotspots(rows: readonly PerformanceRow[]): PerformanceRow[];
+/** Formats a millisecond duration for display with two decimals, like `12.34 ms`. */
 export declare function measuredMs(ms: number): string;
-/** Linear lookup for a large heatmap; includes a parent's first descendant frame. */
+/**
+ * Maps each step to a frame in one linear pass: its own first frame, or failing that the first frame of its first
+ * child that has one (found walking `rows` from the end, so deeper steps resolve first). Steps with no frame in their
+ * subtree are absent. Meant for a large heatmap where a per-step search would be quadratic.
+ */
 export declare function performanceFrameIndex(rows: readonly PerformanceRow[], frames: readonly FlatFrame[]): ReadonlyMap<ReportStep, FlatFrame>;

package/dist/reports/src/performance.js

@@ -1,4 +1,8 @@
 import { flattenSteps } from './frames.js';
+/**
+ * Classifies a duration in milliseconds against `allowanceMs`: `unmeasured` when it is missing, not finite or
+ * negative; `slow` when over the allowance; `warm` when over a quarter of it; otherwise `cool`.
+ */
 export function heatBand(ms, allowanceMs) {
     if (ms === undefined || !Number.isFinite(ms) || ms < 0)
         return 'unmeasured';
@@ -6,23 +10,29 @@ export function heatBand(ms, allowanceMs) {
         return 'slow';
     return ms > allowanceMs / 4 ? 'warm' : 'cool';
 }
+/** Flattens a step tree depth-first (parents before children) into rows, each banded by its own recorded time (`performance.selfMs`) against `allowanceMs`. */
 export function performanceRows(steps, allowanceMs) {
     return flattenSteps(steps).map((row) => ({
         ...row,
         band: heatBand(row.step.performance?.selfMs, allowanceMs),
     }));
 }
-/** Self time attributes nested work once, instead of ranking every ancestor as slow. */
+/** The measured rows, longest own time first and earlier rows first on a tie. Self time attributes nested work once, instead of ranking every ancestor as slow. Sorts in place the array it builds, not `rows`. */
 export function performanceHotspots(rows) {
     return rows
         .filter((row) => row.band !== 'unmeasured')
         .sort((a, b) => (b.step.performance?.selfMs ?? 0) - (a.step.performance?.selfMs ?? 0) ||
         a.index - b.index);
 }
+/** Formats a millisecond duration for display with two decimals, like `12.34 ms`. */
 export function measuredMs(ms) {
     return `${ms.toFixed(2)} ms`;
 }
-/** Linear lookup for a large heatmap; includes a parent's first descendant frame. */
+/**
+ * Maps each step to a frame in one linear pass: its own first frame, or failing that the first frame of its first
+ * child that has one (found walking `rows` from the end, so deeper steps resolve first). Steps with no frame in their
+ * subtree are absent. Meant for a large heatmap where a per-step search would be quadratic.
+ */
 export function performanceFrameIndex(rows, frames) {
     const byStep = new Map();
     for (const frame of frames) {

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

@@ -1,10 +1,19 @@
 /**
- * Persist the TanStack query cache. Frame-file queries stay out of this
- * document — those bytes live in {@link ReportCache} on their own keys.
+ * @module Query cache persistence
+ *
+ * Persists the viewer's TanStack query cache into a `ReportCache` (IndexedDB in the browser) so a reload starts from
+ * what was already fetched. Frame-file queries stay out of this document: those bytes live in `ReportCache` on their
+ * own keys.
  */
 import { type Persister } from '@tanstack/query-persist-client-core';
 import type { QueryClient } from '@tanstack/solid-query';
 import type { ReportCache } from './fetcher.js';
+/** A TanStack `Persister` that keeps the whole query client as one JSON string under one key in `cache`. A stored value that is not valid JSON is removed and treated as no cache. */
 export declare function reportPersister(cache: ReportCache): Persister;
-/** Restore the cache, then keep writing it. Returns unsubscribe. */
+/**
+ * Restores the query client from `cache`, then keeps writing it back as queries change. Returns
+ * `[unsubscribe, restored]`: the function that stops writing, and a promise that settles when the restore is done.
+ * Only successful queries are stored, never `blob` queries (those are the frame files); a stored cache older than a
+ * week, or from a different cache version, is discarded.
+ */
 export declare function attachReportCache(client: QueryClient, cache: ReportCache): [() => void, Promise<void>];

package/dist/reports/src/persist.js

@@ -1,10 +1,14 @@
 /**
- * Persist the TanStack query cache. Frame-file queries stay out of this
- * document — those bytes live in {@link ReportCache} on their own keys.
+ * @module Query cache persistence
+ *
+ * Persists the viewer's TanStack query cache into a `ReportCache` (IndexedDB in the browser) so a reload starts from
+ * what was already fetched. Frame-file queries stay out of this document: those bytes live in `ReportCache` on their
+ * own keys.
  */
 import { persistQueryClient, } from '@tanstack/query-persist-client-core';
 const CACHE_KEY = 'reports-query-cache';
 const WEEK = 7 * 24 * 60 * 60 * 1000;
+/** A TanStack `Persister` that keeps the whole query client as one JSON string under one key in `cache`. A stored value that is not valid JSON is removed and treated as no cache. */
 export function reportPersister(cache) {
     return {
         persistClient: (client) => cache.set(CACHE_KEY, JSON.stringify(client)),
@@ -26,7 +30,12 @@ export function reportPersister(cache) {
 function keepQuery(query) {
     return query.state.status === 'success' && query.queryKey[1] !== 'blob';
 }
-/** Restore the cache, then keep writing it. Returns unsubscribe. */
+/**
+ * Restores the query client from `cache`, then keeps writing it back as queries change. Returns
+ * `[unsubscribe, restored]`: the function that stops writing, and a promise that settles when the restore is done.
+ * Only successful queries are stored, never `blob` queries (those are the frame files); a stored cache older than a
+ * week, or from a different cache version, is discarded.
+ */
 export function attachReportCache(client, cache) {
     return persistQueryClient({
         queryClient: client,

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

@@ -1,5 +1,22 @@
+/**
+ * @module Phone frame geometry
+ *
+ * The fixed size of the phone-shaped frame snapshots are shown in, how to scale it to a box, and cleaning of
+ * recorded page HTML before it is shown.
+ */
+/** Width of the phone frame snapshots render in, in CSS pixels. */
 export declare const PHONE_W = 390;
+/** Height of the phone frame snapshots render in, in CSS pixels. */
 export declare const PHONE_H = 844;
+/**
+ * The scale to draw the phone frame at: a fixed `0.5`, `0.75` or `1` for modes `'50'`, `'75'`, `'100'`; for any other
+ * mode, the largest scale up to 1 that fits a wrapper of `wrapW` by `wrapH` pixels (leaving 8 px), or `0.4` when
+ * that is not a positive finite number.
+ */
 export declare function zoomScale(mode: string, wrapW: number, wrapH: number): number;
-/** Drop scripts and the external shell stylesheet (frameCss replaces it). */
+/**
+ * Removes every `<script>` element and the `<link>` to `snapshot-shell.css` from recorded page HTML. The stylesheet is
+ * replaced by the layer's `frame.css`. This is a regex rewrite, not a sanitiser: inline event handlers and everything
+ * else stay, so it is not a security boundary (render snapshots in a sandbox).
+ */
 export declare function cleanSnapshotHtml(html: string): string;

package/dist/reports/src/phone.js

@@ -1,7 +1,20 @@
+/**
+ * @module Phone frame geometry
+ *
+ * The fixed size of the phone-shaped frame snapshots are shown in, how to scale it to a box, and cleaning of
+ * recorded page HTML before it is shown.
+ */
+/** Width of the phone frame snapshots render in, in CSS pixels. */
 export const PHONE_W = 390;
+/** Height of the phone frame snapshots render in, in CSS pixels. */
 export const PHONE_H = 844;
 const SHELL_LINK_RE = /<link\b[^>]*href=["'][^"']*snapshot-shell\.css["'][^>]*>\s*/gi;
 const SCRIPT_RE = /<script\b[^>]*>[\s\S]*?<\/script>/gi;
+/**
+ * The scale to draw the phone frame at: a fixed `0.5`, `0.75` or `1` for modes `'50'`, `'75'`, `'100'`; for any other
+ * mode, the largest scale up to 1 that fits a wrapper of `wrapW` by `wrapH` pixels (leaving 8 px), or `0.4` when
+ * that is not a positive finite number.
+ */
 export function zoomScale(mode, wrapW, wrapH) {
     if (mode === '50')
         return 0.5;
@@ -12,7 +25,11 @@ export function zoomScale(mode, wrapW, wrapH) {
     const s = Math.min(1, (wrapW - 8) / PHONE_W, (wrapH - 8) / PHONE_H);
     return !Number.isFinite(s) || s <= 0 ? 0.4 : s;
 }
-/** Drop scripts and the external shell stylesheet (frameCss replaces it). */
+/**
+ * Removes every `<script>` element and the `<link>` to `snapshot-shell.css` from recorded page HTML. The stylesheet is
+ * replaced by the layer's `frame.css`. This is a regex rewrite, not a sanitiser: inline event handlers and everything
+ * else stay, so it is not a security boundary (render snapshots in a sandbox).
+ */
 export function cleanSnapshotHtml(html) {
     return html.replace(SCRIPT_RE, '').replace(SHELL_LINK_RE, '');
 }

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

@@ -1,7 +1,12 @@
 /**
- * What the shared reports store holds and what a reports API streams from it.
- * Types only plus a Server-Sent Events codec: safe in a Worker, a CLI and a
- * browser alike.
+ * @module Commit-keyed recording protocol
+ *
+ * The shapes of what the reports store holds for a commit (`commits/<sha>/commit.json`, `sources/<source>.json`) and of
+ * the Server-Sent Events a reports API streams about them, plus the codec for those events. These are the older,
+ * commit-keyed recordings that layers are composed beside; layers themselves are described by the layer document.
+ * Types and a small codec only, so it is safe in a Worker, a CLI and a browser alike.
+ *
+ * @see docs/report-backends.md
  */
 import type { HtmlReportBlob } from './recording-bundle.js';
 import type { ReportTestStatus, RunReport, RunReportMeta } from './report-types.js';
@@ -10,11 +15,15 @@ import type { ReportPartOutput, WorkspaceVersion } from './explorer-types.js';
 export type CommitState = 'running' | 'complete';
 /** `commits/<sha>/commit.json`: one published run of every spec of a commit. */
 export type CommitRecord = {
+    /** The full 40-hex commit sha. */
     readonly sha: string;
     readonly branch: string;
+    /** The CI run that published it, or `null`. */
     readonly runUrl: string | null;
     readonly state: CommitState;
+    /** When the run started, epoch milliseconds. */
     readonly startedAtMs: number;
+    /** When the run closed, epoch milliseconds; `null` while running. */
     readonly endedAtMs: number | null;
     /** Worst status over every source; null while running. */
     readonly status: ReportTestStatus | null;
@@ -23,12 +32,15 @@ export type CommitRecord = {
 export type SourceRecord = {
     /** Producer measurements travel with reusable source content. */
     readonly evidence?: readonly ReportPartOutput[];
+    /** The source id: the package dir with `/` as `-`, `--`, and the bucket (`libs-chess--part-2`). */
     readonly source: string;
     /** Repo-relative package dir (`libs/chess`). */
     readonly packageDir: string;
     /** The bucket under the package's report dir (`part-2`, `all`). */
     readonly bucket: string;
+    /** `failed` if any test failed, `skipped` if all were skipped, else `passed`. */
     readonly status: ReportTestStatus;
+    /** When the source was last updated, epoch milliseconds; the layer made from it is recorded at this time (or the commit's start if later). */
     readonly updatedAtMs: number;
     /** The client this source checked, when the run said. */
     readonly environment?: string;
@@ -37,12 +49,16 @@ export type SourceRecord = {
     /** Each test's meta, test-runner outcomes already applied. */
     readonly tests: readonly RunReportMeta[];
 };
+/** One page of the commit list (`GET /` of the reports API), newest commit first. */
 export type CommitPage = {
     readonly commits: readonly CommitRecord[];
     /** Pass back as `?cursor=` for the next, older page; null on the last. */
     readonly cursor: string | null;
+    /** The checkout the host serves, when it serves one. */
     readonly workspace?: WorkspaceVersion;
+    /** Why the list is partial or empty, for a person to read. */
     readonly notice?: string;
+    /** Versions that have evidence in the stores, on the first page only. */
     readonly evidenceVersions?: readonly string[];
 };
 /** `GET …/:sha/events`: the commit, then each source as it is read. */
@@ -68,8 +84,9 @@ export type TestEvent = {
     readonly type: 'end';
     readonly found: boolean;
 };
+/** The `content-type` of an event stream response. */
 export declare const EVENT_STREAM_CONTENT_TYPE = "text/event-stream; charset=utf-8";
-/** One SSE message: `event:` is the event's `type`, `data:` its JSON. */
+/** Encodes one event as one SSE message: `event:` is the event's `type`, `data:` its JSON, ended by a blank line. */
 export declare function encodeSseEvent(event: CommitEvent | TestEvent): string;
 /**
  * Incremental SSE decoder: feed it text as it arrives, get back each
@@ -78,5 +95,10 @@ export declare function encodeSseEvent(event: CommitEvent | TestEvent): string;
  */
 export declare class SseDecoder<T> {
     #private;
+    /**
+     * Adds `chunk` (any split of the stream, `\r\n` and `\r` read as `\n`) and returns the parsed `data` of every
+     * message it completes, in order. An unfinished message is kept for the next call. A message with no `data:`
+     * line is skipped. Throws a `SyntaxError` when a message's data is not JSON; that message is already consumed.
+     */
     push(chunk: string): T[];
 }

package/dist/reports/src/protocol.js

@@ -1,10 +1,16 @@
 /**
- * What the shared reports store holds and what a reports API streams from it.
- * Types only plus a Server-Sent Events codec: safe in a Worker, a CLI and a
- * browser alike.
+ * @module Commit-keyed recording protocol
+ *
+ * The shapes of what the reports store holds for a commit (`commits/<sha>/commit.json`, `sources/<source>.json`) and of
+ * the Server-Sent Events a reports API streams about them, plus the codec for those events. These are the older,
+ * commit-keyed recordings that layers are composed beside; layers themselves are described by the layer document.
+ * Types and a small codec only, so it is safe in a Worker, a CLI and a browser alike.
+ *
+ * @see docs/report-backends.md
  */
+/** The `content-type` of an event stream response. */
 export const EVENT_STREAM_CONTENT_TYPE = 'text/event-stream; charset=utf-8';
-/** One SSE message: `event:` is the event's `type`, `data:` its JSON. */
+/** Encodes one event as one SSE message: `event:` is the event's `type`, `data:` its JSON, ended by a blank line. */
 export function encodeSseEvent(event) {
     return `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
 }
@@ -15,6 +21,11 @@ export function encodeSseEvent(event) {
  */
 export class SseDecoder {
     #buffer = '';
+    /**
+     * Adds `chunk` (any split of the stream, `\r\n` and `\r` read as `\n`) and returns the parsed `data` of every
+     * message it completes, in order. An unfinished message is kept for the next call. A message with no `data:`
+     * line is skipped. Throws a `SyntaxError` when a message's data is not JSON; that message is already consumed.
+     */
     push(chunk) {
         this.#buffer += chunk.replace(/\r\n?/g, '\n');
         const out = [];

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

@@ -1,4 +1,24 @@
-/** Attempt-local commit records; immutable successful content remains shared. */
+/**
+ * @module Per-attempt publication scope
+ *
+ * Lets concurrent CI attempts for one commit publish without overwriting each other: a store view that redirects the
+ * commit-local keys (`commits/<sha>/...`) into `attempts/<publicationId>/`, while immutable shared content
+ * (the spec inventory and spec bodies, blobs, layers) stays where it is. `reportStore` finds the right view for a
+ * commit from the pointer `openCommit` leaves.
+ */
 import type { ObjectStore } from './object-store.js';
+/**
+ * A view of `store` for one CI attempt: keys under `commits/` go to `attempts/<publicationId>/commits/...`, except
+ * `commits/<sha>/inventory.json` and `commits/<sha>/specs/...`, which stay shared; all other keys are unchanged.
+ * Listing a `commits/` prefix lists only the attempt's own copies, with the `attempts/<id>/` part removed.
+ *
+ * Throws `Invalid report publication id` unless `publicationId` is letters, digits, `.`, `_`, `:` or `-` and is not
+ * `.` or `..`, so an id can never address another key.
+ */
 export declare function publicationStore(store: ObjectStore, publicationId: string): ObjectStore;
+/**
+ * The store view to read a commit's records from: the attempt-scoped view when the commit's `commit.json` is a
+ * pointer `{ "publicationId": ... }` (written by `openCommit` when given a `publicationId`), otherwise `store`
+ * itself, also when the commit has no record. Throws if `commit.json` is not JSON.
+ */
 export declare function reportStore(store: ObjectStore, sha: string): Promise<ObjectStore>;

package/dist/reports/src/publication.js

@@ -1,7 +1,22 @@
-/** Attempt-local commit records; immutable successful content remains shared. */
+/**
+ * @module Per-attempt publication scope
+ *
+ * Lets concurrent CI attempts for one commit publish without overwriting each other: a store view that redirects the
+ * commit-local keys (`commits/<sha>/...`) into `attempts/<publicationId>/`, while immutable shared content
+ * (the spec inventory and spec bodies, blobs, layers) stays where it is. `reportStore` finds the right view for a
+ * commit from the pointer `openCommit` leaves.
+ */
 import { readUtf8 } from './object-io.js';
 import { ObjectStoreWithPrefix } from './store-prefix.js';
 import { commitKey } from './keys.js';
+/**
+ * A view of `store` for one CI attempt: keys under `commits/` go to `attempts/<publicationId>/commits/...`, except
+ * `commits/<sha>/inventory.json` and `commits/<sha>/specs/...`, which stay shared; all other keys are unchanged.
+ * Listing a `commits/` prefix lists only the attempt's own copies, with the `attempts/<id>/` part removed.
+ *
+ * Throws `Invalid report publication id` unless `publicationId` is letters, digits, `.`, `_`, `:` or `-` and is not
+ * `.` or `..`, so an id can never address another key.
+ */
 export function publicationStore(store, publicationId) {
     if (!/^[a-zA-Z0-9._:-]+$/.test(publicationId) ||
         publicationId === '.' ||
@@ -24,6 +39,11 @@ export function publicationStore(store, publicationId) {
     };
     return scoped;
 }
+/**
+ * The store view to read a commit's records from: the attempt-scoped view when the commit's `commit.json` is a
+ * pointer `{ "publicationId": ... }` (written by `openCommit` when given a `publicationId`), otherwise `store`
+ * itself, also when the commit has no record. Throws if `commit.json` is not JSON.
+ */
 export async function reportStore(store, sha) {
     const text = await readUtf8(store, commitKey(sha));
     if (text === null)

package/dist/reports/src/publish-checks.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module Publishing checks as a layer
+ *
+ * `publishChecks` turns the checks of one producer into one immutable layer in any store: the whole integration for a suite
+ * that has no timeline to record. Attachments of any kind are stored by content (the same screenshot attached ten times is
+ * stored once). Nothing here reads a clock or the environment, so the same input is always the same layer and a retried CI
+ * step changes nothing.
+ *
+ * @see docs/integrating.md
+ * @see docs/extending.md
+ */
+import { type PublishChecksInput } from '../../schema/src/layer.js';
+import type { ReportLayer } from './layer-types.js';
+import type { ObjectStore } from './object-store.js';
+/** Limits that protect the machine publishing: the largest single attachment, and the most attachment bytes in one layer (they are held in memory while stored). */
+export type PublishChecksOptions = {
+    /** Refuse a single attachment larger than this many bytes. Default 512 MiB. */
+    readonly maxAttachmentBytes?: number;
+    /** Refuse a layer whose attachments together are larger than this, because they are held in memory while stored. Default 2 GiB. */
+    readonly maxTotalAttachmentBytes?: number;
+};
+/**
+ * Publish the checks of one producer as one immutable layer. This is the whole integration for a
+ * suite that has no timelines to record: Gherkin scenarios, a Quint run, a DMN table test, an SLO
+ * evaluation, a linter, anything that ends in "this check passed or failed".
+ *
+ * A check may carry whatever evidence its framework has: attachments of any media type (screenshots,
+ * videos, traces, logs, DOM snapshots…), timeline steps, annotations, retries, tags, labels, links and
+ * namespaced `extensions`. All of it is optional (docs/extending.md).
+ *
+ * Nothing here reads a clock: `recordedAtMs` is when the checks ran, given by the caller. Publishing
+ * the same input twice therefore writes the same layer, and a retried CI step changes nothing.
+ * Each check's `id` is its identity across runs. It must be stable and unique within the layer.
+ */
+export declare function publishChecks(store: ObjectStore, input: PublishChecksInput, options?: PublishChecksOptions): Promise<ReportLayer>;