@crvouga/atlas 0.4.0 → 0.6.0

package/dist/reports/src/layers-route.js

@@ -1,11 +1,27 @@
+/**
+ * @module Layers HTTP routes
+ *
+ * The read-only HTTP API the viewer uses to see layers: a paged list of layer headers merged from every backend, the
+ * rows of one layer, its attachments and recorded timelines, the live runs still writing on this machine, and the
+ * spec outline. It is mounted under `/api/reports` by `reportsHost` and by the Atlas server. Immutable layers (64-hex
+ * ids) are read once and cached for good and answered with long-lived `immutable` cache headers; mutable commit-keyed
+ * recordings are re-read after a short wait. A backend that cannot be listed or a layer that cannot be read becomes a
+ * notice in the page, never a silent omission and never a pass. Layers the host's `include` filter rejects are absent
+ * from every route here, so a filter cannot be undone by asking for history.
+ *
+ * @see docs/server.md
+ * @see docs/report-contract.md#failure-behaviour
+ */
 import { Hono } from 'hono';
 import { createBundleReader } from './bundle.js';
 import { eachLimited } from './completion-order.js';
 import { createLiveEvidence, liveRunRecord } from './evidence-live.js';
 import { isFramePath, isKeySegment } from './keys.js';
 import { catalogEntries, catalogLayers } from './layer-catalog.js';
+import { attachmentResponse } from './attachment-response.js';
+import { checkDetailOf, runEvidence } from './evidence-detail.js';
 import { layerEvidence } from './layer-merge.js';
-import { readLayer } from './layer-store.js';
+import { layerSummary, readLayer } from './layer-store.js';
 import { readBytes, readUtf8 } from './object-io.js';
 import { SPEC_RUN_ID } from './publish.js';
 import { testFrameKey, testReportKey } from './recording-keys.js';
@@ -13,9 +29,17 @@ const TTL = 30_000;
 const LOCAL_TTL = 1_500;
 const PAGE = 40;
 const CACHED_ENTRIES = 4_096;
+/** The id of the backend for this machine's own store (`localStore`), where runs may still be writing. */
 export const LOCAL_BACKEND = 'local';
+/** The id of the backend for the shared reports store (`store`). */
 export const SHARED_BACKEND = 'shared';
-/** The stores that contribute layers, in the order they answer for a recording. */
+/**
+ * The stores that contribute layers, in the order they answer for a recording: `localStore` (id `local`, live), then
+ * `store` (id `shared`) when it is a different store, then each of `backends`.
+ *
+ * Throws `Invalid report backend id: "<id>"` when an extra backend's id is not lowercase letters, digits and hyphens
+ * or repeats an earlier id (including `local` and `shared`).
+ */
 export function reportBackends(deps) {
     const backends = [];
     if (deps.localStore)
@@ -29,12 +53,34 @@ export function reportBackends(deps) {
     }
     return backends;
 }
+/** Whether a layer id is a content digest (64 lowercase hex digits), that is an immutable layer. */
 function archived(id) {
     return /^[0-9a-f]{64}$/.test(id);
 }
-/** Bounded pages of layer origins, each layer's checks read once, and the runs still writing. */
+/**
+ * Builds the Hono app that serves layers: bounded pages of layer origins, each layer's checks read once, and the
+ * runs still writing. Throws (as `reportBackends`) when a backend id is invalid.
+ *
+ * Routes, relative to where it is mounted:
+ * - `GET /outline` the current specs as `{ specs, sha, changedFiles }` (503 when the host has no outline), cached 30 s.
+ * - `GET /outline/spec?path=` one outline spec's text; 404 for a path not in the outline.
+ * - `GET /evidence?cursor=&retry=` one page of layer headers (`EvidencePage`) from 40 catalog entries across all
+ *   backends: immutable layers newest first, then commit-keyed recordings. Without a cursor it also carries the live
+ *   runs of this machine. `cursor` is the previous page's; 409 when it no longer matches the listing (refresh).
+ *   Any `retry` value re-lists backends that were unavailable now instead of after the wait.
+ * - `GET /evidence/rows/:backend/:id` the checks and spec fingerprints of one layer (`LayerRows`).
+ * - `GET /evidence/detail/:backend/:id?check=&kind=` the run-level evidence of an immutable layer, or one check's detail.
+ * - `GET /layers/:id/blobs/*` an attachment of an immutable layer by its bundle key, served by `attachmentResponse`.
+ * - `GET /layers/:id/*` the recorded `frame.css`, `tests/<test>/report.json` and `tests/<test>/files/<frame>` of a layer.
+ * - `GET /live/:source/frame.css` and `GET /live/:source/tests/:testId/*` the same for a run still writing (uncached).
+ *
+ * Directory listings are cached for 30 s (1.5 s for the local store). A listing that fails keeps the previous keys and
+ * marks the backend unavailable; the page then carries a notice.
+ */
 export function createLayersApp(deps) {
     const backends = reportBackends(deps);
+    // Layers the host leaves out are left out of every route, so a filter cannot be undone by asking for history.
+    const include = deps.include ?? (() => true);
     const listings = backends.map(() => undefined);
     let pending = null;
     const loaded = new Map();
@@ -109,8 +155,9 @@ export function createLayersApp(deps) {
         let reader = readers.get(id);
         if (!reader) {
             for (const backend of backends) {
-                const layer = await readLayer(backend.store, id);
-                if (!layer)
+                const layer = await readLayer(backend.store, id).catch(() => null);
+                // A layer the host leaves out has no files to give either.
+                if (!layer || !include(layerEvidence(layerSummary(layer), backend.id).layer))
                     continue;
                 reader = createBundleReader(backend.store, layer.bundle);
                 if (readers.size >= 8)
@@ -185,7 +232,8 @@ export function createLayersApp(deps) {
         await eachLimited(selected, 8, async (entry) => {
             try {
                 for (const evidence of await entryEvidence(entry))
-                    layers.push(evidence.layer);
+                    if (include(evidence.layer))
+                        layers.push(evidence.layer);
             }
             catch {
                 notices.push('A report layer could not be loaded. Its outcome is unknown.');
@@ -207,11 +255,42 @@ export function createLayersApp(deps) {
         const backend = backends.findIndex(known => known.id === c.req.param('backend'));
         const id = c.req.param('id');
         const evidence = backend < 0 ? null : await findEvidence(backend, id);
-        if (!evidence)
+        if (!evidence || !include(evidence.layer))
             return c.notFound();
         const rows = { id: evidence.id, rows: evidence.rows, fingerprints: evidence.fingerprints };
         return c.json(rows, 200, { 'cache-control': archived(id) ? 'public, max-age=31536000, immutable' : 'no-cache' });
     });
+    // The files a layer carries for its checks: screenshots, videos, traces, logs, snapshots, anything.
+    app.get('/layers/:id/blobs/*', async (c) => {
+        const id = c.req.param('id');
+        let key;
+        try {
+            key = decodeURIComponent(new URL(c.req.url).pathname.split(`/layers/${id}/blobs/`)[1] ?? '');
+        }
+        catch {
+            return c.json({ error: 'Invalid attachment path' }, 400);
+        }
+        if (!archived(id) || !key || key.split('/').some(part => !part || part === '.' || part === '..'))
+            return c.notFound();
+        const entry = await file(id, key);
+        return entry ? attachmentResponse(c.req.raw, entry, `"${id.slice(0, 16)}-${key.replace(/[^\w.-]/g, '_')}"`) : c.notFound();
+    });
+    // Everything one result carries: its timeline, attachments, annotations, retries and extensions.
+    app.get('/evidence/detail/:backend/:id', async (c) => {
+        const backend = backends.find(known => known.id === c.req.param('backend'));
+        const id = c.req.param('id');
+        if (!backend || !archived(id))
+            return c.notFound();
+        const layer = await readLayer(backend.store, id).catch(() => null);
+        if (!layer || !include(layerEvidence(layerSummary(layer), backend.id).layer))
+            return c.notFound();
+        const checkId = c.req.query('check');
+        const headers = { 'cache-control': 'public, max-age=31536000, immutable' };
+        if (checkId === undefined)
+            return c.json({ layer: id, run: runEvidence(layer) }, 200, headers);
+        const detail = checkDetailOf(layer, checkId, c.req.query('kind'));
+        return detail ? c.json(detail, 200, headers) : c.notFound();
+    });
     app.get('/layers/:id/*', async (c) => {
         const id = c.req.param('id');
         let path;

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

@@ -0,0 +1,34 @@
+import type { z } from 'zod/v4';
+import type { LiveCheck, LiveRunStartSchema } from '../../schema/src/live-run.js';
+/** Fixed identity of a live invocation; a UUID is generated when omitted. */
+export type LiveIdentity = Omit<z.input<typeof LiveRunStartSchema>, 'id'> & {
+    id?: string;
+};
+/** Transport and batching configuration. Defaults: 250 ms batches, 5 s heartbeats and 10 s request timeouts. */
+export type LiveReporterOptions = {
+    url: string;
+    project?: string;
+    token?: string;
+    flushMs?: number;
+    heartbeatMs?: number;
+    timeoutMs?: number;
+    onError?: (error: Error) => void;
+};
+/** Producer handle. check never throws transport errors into a test; finish flushes and rejects if publication failed. */
+export type LiveReporter = {
+    readonly id: string;
+    readonly finishedAtMs?: number;
+    check(check: LiveCheck): void;
+    flush(): Promise<void>;
+    finish(status?: 'completed' | 'interrupted', reason?: string): Promise<void>;
+};
+/**
+ * Start publishing immediately, batch changing checks, and send independent heartbeats while the producer is alive.
+ * The same failed batch is retried with the same sequence and content; never silently replace a lost update.
+ * @example
+ * const run = createLiveReporter({ producer: 'unit', plannedChecks: 10 }, { url: 'http://localhost:5180' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'running' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'passed' });
+ * await run.finish();
+ */
+export declare function createLiveReporter(identity: LiveIdentity, options: LiveReporterOptions): LiveReporter;

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

@@ -0,0 +1,122 @@
+/** @module Reporting a live run to Atlas
+ * Streams bounded check deltas while tests execute. Heartbeats are independent of progress; finished results are
+ * published by the server as ordinary immutable layers. A final flush is awaited before a runner exits.
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * Start publishing immediately, batch changing checks, and send independent heartbeats while the producer is alive.
+ * The same failed batch is retried with the same sequence and content; never silently replace a lost update.
+ * @example
+ * const run = createLiveReporter({ producer: 'unit', plannedChecks: 10 }, { url: 'http://localhost:5180' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'running' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'passed' });
+ * await run.finish();
+ */
+export function createLiveReporter(identity, options) {
+    const base = new URL(options.url);
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
+        throw new Error('Atlas live reporter needs an HTTP(S) server URL without credentials, query or fragment.');
+    const id = identity.id ?? randomUUID();
+    const endpoint = `${base.href.replace(/\/$/, '')}/api/live/${id}`;
+    let sequence = 0;
+    let finishedAtMs;
+    let closed = false;
+    let timer;
+    let error;
+    const pending = new Map();
+    const known = new Map();
+    let failed;
+    const reportError = (caught) => { error = caught instanceof Error ? caught : new Error(String(caught)); options.onError?.(error); };
+    async function request(method, payload, suffix = '') {
+        const text = payload === undefined ? undefined : JSON.stringify(payload);
+        for (let attempt = 0;; attempt++) {
+            try {
+                const response = await fetch(endpoint + suffix, { method, redirect: 'error', signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+                    headers: { 'content-type': 'application/json', ...(options.project ? { 'x-atlas-project': options.project } : {}), ...(options.token ? { authorization: `Bearer ${options.token}` } : {}) }, body: text });
+                const status = response.status;
+                const json = response.headers.get('content-type')?.includes('application/json');
+                if (response.ok && !json) {
+                    await response.body?.cancel();
+                    throw Object.assign(new Error('Atlas live reporter: the endpoint is not an Atlas server. Start or restart `bun atlas`.'), { permanent: true });
+                }
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    throw Object.assign(new Error(`Atlas live reporter: HTTP ${status}`), { permanent: status < 500 && status !== 429 });
+                }
+                return await response.json();
+            }
+            catch (caught) {
+                if (attempt >= 2 || caught.permanent)
+                    throw caught;
+                await new Promise(resolve => setTimeout(resolve, 250 * 2 ** attempt));
+            }
+        }
+    }
+    const ready = request('POST', { ...identity, id });
+    void ready.catch(reportError);
+    let queue = Promise.resolve();
+    let draining;
+    const flush = () => {
+        if (draining)
+            return draining;
+        queue = queue.then(async () => {
+            await ready;
+            while (failed || pending.size) {
+                if (!failed) {
+                    const checks = [...pending.values()].slice(0, 1000);
+                    checks.forEach(check => pending.delete(check.id));
+                    failed = { sequence: sequence + 1, checks };
+                }
+                await request('PATCH', failed);
+                sequence = failed.sequence;
+                failed = undefined;
+            }
+            error = undefined;
+        }).catch(reportError);
+        draining = queue.finally(() => { draining = undefined; });
+        return draining;
+    };
+    const heartbeat = setInterval(() => { if (!closed)
+        void ready.then(async () => { await request('POST', undefined, '/heartbeat'); if (!closed && (failed || pending.size))
+            void flush(); }).catch(caught => { if (!closed)
+            reportError(caught); }); }, options.heartbeatMs ?? 5000);
+    heartbeat.unref?.();
+    const check = (given) => {
+        if (closed)
+            throw new Error('This live reporter is closed.');
+        const check = { id: given.id, title: given.title.slice(0, 2048), status: given.status, detail: (given.detail ?? '').slice(0, 8000),
+            ...(given.specPath ? { specPath: given.specPath } : {}), ...(given.durationMs === undefined ? {} : { durationMs: given.durationMs }),
+            ...(given.steps?.length ? { steps: given.steps.slice(-20).map(step => ({ name: step.name.slice(0, 2048), ...(step.status ? { status: step.status.slice(0, 100) } : {}) })) } : {}) };
+        if (JSON.stringify(known.get(check.id)) === JSON.stringify(check))
+            return;
+        known.set(check.id, check);
+        pending.set(check.id, check);
+        if (!timer) {
+            timer = setTimeout(() => { timer = undefined; void flush(); }, options.flushMs ?? 250);
+            timer.unref?.();
+        }
+    };
+    return { id, get finishedAtMs() { return finishedAtMs; }, check, flush, async finish(status = 'completed', reason) {
+            if (closed) {
+                await queue;
+                if (error)
+                    throw error;
+                return;
+            }
+            const unfinished = [...known.values()].filter(check => check.status === 'running');
+            if (unfinished.length) {
+                status = 'interrupted';
+                reason ??= 'The producer ended without a final outcome for running checks.';
+                unfinished.forEach(value => check({ ...value, status: 'not-run', detail: reason }));
+            }
+            closed = true;
+            clearInterval(heartbeat);
+            clearTimeout(timer);
+            await flush();
+            if (error)
+                throw error;
+            const result = await request('PATCH', { sequence: sequence + 1, checks: [], finish: status, ...(reason ? { reason } : {}) });
+            finishedAtMs = result.finishedAtMs;
+            sequence++;
+        } };
+}

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

@@ -0,0 +1,11 @@
+/**
+ * @module Media types by file extension
+ *
+ * A small fixed table from file extension to media type, used when a captured file arrives without a type. It is a
+ * fallback guess from the name only: the bytes are never sniffed, and a type the producer gave always wins.
+ */
+/**
+ * The media type for a file name, from its last extension, case-insensitively. Anything not in the table, and a name
+ * with no extension, is `application/octet-stream`. Never reads the content.
+ */
+export declare function contentTypeOf(file: string): string;

package/dist/reports/src/media-types.js

@@ -0,0 +1,22 @@
+/**
+ * @module Media types by file extension
+ *
+ * A small fixed table from file extension to media type, used when a captured file arrives without a type. It is a
+ * fallback guess from the name only: the bytes are never sniffed, and a type the producer gave always wins.
+ */
+/** Media types by file extension (lowercase, no dot), for attachments whose producer did not say. */
+const TYPES = {
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', avif: 'image/avif', svg: 'image/svg+xml', ico: 'image/x-icon', bmp: 'image/bmp',
+    mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime', mkv: 'video/x-matroska', ogv: 'video/ogg',
+    mp3: 'audio/mpeg', wav: 'audio/wav', ogg: 'audio/ogg', m4a: 'audio/mp4', flac: 'audio/flac',
+    vtt: 'text/vtt', srt: 'application/x-subrip', txt: 'text/plain; charset=utf-8', log: 'text/plain; charset=utf-8', md: 'text/markdown; charset=utf-8', csv: 'text/csv', html: 'text/html; charset=utf-8', htm: 'text/html; charset=utf-8', css: 'text/css',
+    json: 'application/json', ndjson: 'application/x-ndjson', har: 'application/json', xml: 'application/xml', yaml: 'application/yaml', yml: 'application/yaml', pdf: 'application/pdf',
+    zip: 'application/zip', gz: 'application/gzip', tgz: 'application/gzip', tar: 'application/x-tar', mmd: 'text/plain; charset=utf-8', diff: 'text/x-diff', patch: 'text/x-diff'
+};
+/**
+ * The media type for a file name, from its last extension, case-insensitively. Anything not in the table, and a name
+ * with no extension, is `application/octet-stream`. Never reads the content.
+ */
+export function contentTypeOf(file) {
+    return TYPES[file.split('.').at(-1)?.toLowerCase() ?? ''] ?? 'application/octet-stream';
+}

package/dist/reports/src/namespace-guard.d.ts

@@ -1,11 +1,20 @@
+/**
+ * @module Object key guards
+ *
+ * Throws on object-store keys that could escape their prefix. The checks are lexical only (empty, leading `/`, `..`,
+ * missing namespace); they do not normalise a key or decide whether an object exists.
+ */
 /**
  * Validates a wire key before any remote object-store I/O. Every S3 command
  * for the shared bucket must pass this gate so projects cannot clobber
  * each other's prefixes.
+ *
+ * Throws `Error` when `key` is empty, starts with `/`, contains `..` anywhere, is exactly `namespace` (with or without
+ * a trailing `/`), or does not start with `namespace`. Returns nothing when the key is acceptable.
  */
 export declare function assertRemoteObjectKey(key: string, namespace: string): void;
 /**
  * Validates a logical key before {@link ObjectStoreWithPrefix} scopes it under
- * a namespace or feature prefix.
+ * a namespace or feature prefix. Throws `Error` when `key` is empty, starts with `/`, or contains `..` anywhere.
  */
 export declare function assertLogicalObjectKey(key: string): void;

package/dist/reports/src/namespace-guard.js

@@ -1,7 +1,16 @@
+/**
+ * @module Object key guards
+ *
+ * Throws on object-store keys that could escape their prefix. The checks are lexical only (empty, leading `/`, `..`,
+ * missing namespace); they do not normalise a key or decide whether an object exists.
+ */
 /**
  * Validates a wire key before any remote object-store I/O. Every S3 command
  * for the shared bucket must pass this gate so projects cannot clobber
  * each other's prefixes.
+ *
+ * Throws `Error` when `key` is empty, starts with `/`, contains `..` anywhere, is exactly `namespace` (with or without
+ * a trailing `/`), or does not start with `namespace`. Returns nothing when the key is acceptable.
  */
 export function assertRemoteObjectKey(key, namespace) {
     if (key.length === 0) {
@@ -25,7 +34,7 @@ export function assertRemoteObjectKey(key, namespace) {
 }
 /**
  * Validates a logical key before {@link ObjectStoreWithPrefix} scopes it under
- * a namespace or feature prefix.
+ * a namespace or feature prefix. Throws `Error` when `key` is empty, starts with `/`, or contains `..` anywhere.
  */
 export function assertLogicalObjectKey(key) {
     if (key.length === 0) {

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

@@ -1,8 +1,20 @@
+/**
+ * @module Explorer navigation host
+ *
+ * The seam between a reports explorer and the page it is embedded in: where the address (hash), keyboard and title
+ * live. It is a type only; a host (usually the browser) supplies the implementation, which keeps the explorer free of
+ * `window` and testable.
+ */
 /** Host navigation and keyboard events, scoped to one reports explorer. */
 export type ReportNavigation = {
+    /** The current location hash, as the host holds it, with or without the leading `#` (the route parser accepts both). */
     readonly readHash: () => string;
+    /** Sets the hash (given with its leading `#`, like `#/test/<id>`); `replace` true replaces the current history entry instead of adding one. */
     readonly writeHash: (hash: string, replace: boolean) => void;
+    /** Calls `listener` whenever the hash changes; returns the function that stops listening. */
     readonly subscribeHash: (listener: () => void) => () => void;
+    /** Calls `listener` for keyboard events scoped to this explorer; returns the function that stops listening. */
     readonly subscribeKeys: (listener: (event: KeyboardEvent) => void) => () => void;
+    /** Sets the page title. */
     readonly setTitle: (title: string) => void;
 };

package/dist/reports/src/navigation.js

@@ -0,0 +1,7 @@
+/**
+ * @module Explorer navigation host
+ *
+ * The seam between a reports explorer and the page it is embedded in: where the address (hash), keyboard and title
+ * live. It is a type only; a host (usually the browser) supplies the implementation, which keeps the explorer free of
+ * `window` and testable.
+ */

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

@@ -1,9 +1,16 @@
+/**
+ * @module Reading and writing whole objects
+ *
+ * Small helpers over `ObjectStore` for the common case of an object read or written whole: draining a stream,
+ * decoding UTF-8, and encoding text for `put`. They hold the object in memory, so they are for manifests, catalog
+ * entries and bounded blobs, not for large files. Errors from the store are not caught.
+ */
 import type { ObjectStore } from './object-store.js';
-/** Drain a {@link ReadableStream} into a single byte array. */
+/** Drains a stream into one byte array (it reads the stream to its end; it holds every chunk in memory). */
 export declare function readBytes(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;
-/** Read object bytes as UTF-8 text, or `null` when the key is missing. */
+/** Reads an object as UTF-8 text, or `null` when the key is missing. Invalid UTF-8 is decoded leniently (replacement characters), not rejected. Transport errors throw. */
 export declare function readUtf8(store: ObjectStore, key: string): Promise<string | null>;
-/** Write UTF-8 text under `key` with the given content type (default text/plain). */
+/** Writes UTF-8 text under `key` with the given content type (default `text/plain; charset=utf-8`). Overwrites; transport errors throw. */
 export declare function writeUtf8(store: ObjectStore, key: string, text: string, contentType?: string): Promise<void>;
-/** Read object bytes, or `null` when the key is missing. */
+/** Reads an object's bytes whole, or `null` when the key is missing. Transport errors throw. */
 export declare function readObjectBytes(store: ObjectStore, key: string): Promise<Uint8Array | null>;

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

@@ -1,4 +1,4 @@
-/** Drain a {@link ReadableStream} into a single byte array. */
+/** Drains a stream into one byte array (it reads the stream to its end; it holds every chunk in memory). */
 export async function readBytes(stream) {
     const reader = stream.getReader();
     const chunks = [];
@@ -20,7 +20,7 @@ export async function readBytes(stream) {
     }
     return out;
 }
-/** Read object bytes as UTF-8 text, or `null` when the key is missing. */
+/** Reads an object as UTF-8 text, or `null` when the key is missing. Invalid UTF-8 is decoded leniently (replacement characters), not rejected. Transport errors throw. */
 export async function readUtf8(store, key) {
     const obj = await store.get(key);
     if (obj === null)
@@ -28,11 +28,11 @@ export async function readUtf8(store, key) {
     const bytes = await readBytes(obj.body);
     return new TextDecoder().decode(bytes);
 }
-/** Write UTF-8 text under `key` with the given content type (default text/plain). */
+/** Writes UTF-8 text under `key` with the given content type (default `text/plain; charset=utf-8`). Overwrites; transport errors throw. */
 export async function writeUtf8(store, key, text, contentType = 'text/plain; charset=utf-8') {
     await store.put(key, new TextEncoder().encode(text), contentType);
 }
-/** Read object bytes, or `null` when the key is missing. */
+/** Reads an object's bytes whole, or `null` when the key is missing. Transport errors throw. */
 export async function readObjectBytes(store, key) {
     const obj = await store.get(key);
     if (obj === null)

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

@@ -0,0 +1,27 @@
+import type { ObjectStore } from './object-store.js';
+/** The outcome of `verifyObjectStore`: `ok` is true exactly when `failures` is empty. */
+export type StoreVerification = {
+    readonly ok: boolean;
+    readonly failures: readonly string[];
+};
+/**
+ * Checks a backend against the {@link ObjectStore} contract before trusting it with evidence. It
+ * writes a few objects under a scratch prefix and removes them. Use it in the test suite of an S3,
+ * GCS, R2 or HTTP adapter; an adapter that passes composes with every other backend.
+ *
+ * It is a plain async function, so it runs under any test runner and from a script. It checks: a missing key reads
+ * `null` (`get`, `getUri`) and `false` (`head`); `put` overwrites and round-trips bytes, size and content type;
+ * `listKeys` is in code-unit order, filters by any string prefix and is empty for an unused one; `withPrefix` scopes
+ * reads and writes; `delete` and `deleteMany` accept missing keys. A failed expectation is reported in `failures`;
+ * an exception from the store is reported as one `threw: ...` failure rather than thrown. It does not check
+ * `listPage`.
+ *
+ * @param store the backend to verify.
+ * @param scratch the key prefix to write under; defaults to a random `atlas-conformance-<id>/`. If you pass one,
+ * nothing else may live under it: the check asserts that `listKeys(scratch)` returns exactly the four objects it wrote.
+ *
+ * @example
+ * const { ok, failures } = await verifyObjectStore(myStore);
+ * if (!ok) throw new Error(failures.join('\n'));
+ */
+export declare function verifyObjectStore(store: ObjectStore, scratch?: string): Promise<StoreVerification>;

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

@@ -0,0 +1,87 @@
+/**
+ * @module ObjectStore conformance check
+ *
+ * Runs the `ObjectStore` contract against any implementation, so a new backend (GCS, an HTTP service, a device lab) can
+ * prove it composes with the others before it holds evidence. It is a plain async function with no test-runner
+ * dependency. It writes only under a scratch prefix and removes what it wrote.
+ *
+ * @see docs/report-contract.md#backends
+ */
+import { readBytes } from './object-io.js';
+const text = (value) => new TextEncoder().encode(value);
+/**
+ * Checks a backend against the {@link ObjectStore} contract before trusting it with evidence. It
+ * writes a few objects under a scratch prefix and removes them. Use it in the test suite of an S3,
+ * GCS, R2 or HTTP adapter; an adapter that passes composes with every other backend.
+ *
+ * It is a plain async function, so it runs under any test runner and from a script. It checks: a missing key reads
+ * `null` (`get`, `getUri`) and `false` (`head`); `put` overwrites and round-trips bytes, size and content type;
+ * `listKeys` is in code-unit order, filters by any string prefix and is empty for an unused one; `withPrefix` scopes
+ * reads and writes; `delete` and `deleteMany` accept missing keys. A failed expectation is reported in `failures`;
+ * an exception from the store is reported as one `threw: ...` failure rather than thrown. It does not check
+ * `listPage`.
+ *
+ * @param store the backend to verify.
+ * @param scratch the key prefix to write under; defaults to a random `atlas-conformance-<id>/`. If you pass one,
+ * nothing else may live under it: the check asserts that `listKeys(scratch)` returns exactly the four objects it wrote.
+ *
+ * @example
+ * const { ok, failures } = await verifyObjectStore(myStore);
+ * if (!ok) throw new Error(failures.join('\n'));
+ */
+export async function verifyObjectStore(store, scratch = `atlas-conformance-${Math.random().toString(36).slice(2, 10)}/`) {
+    const failures = [];
+    const expect = (ok, message) => { if (!ok)
+        failures.push(message); };
+    const key = (name) => `${scratch}${name}`;
+    const created = [];
+    try {
+        expect((await store.get(key('missing'))) === null, 'get returns null for a missing key');
+        expect((await store.head(key('missing'))) === false, 'head returns false for a missing key');
+        expect((await store.getUri(key('missing'))) === null, 'getUri returns null for a missing key');
+        await store.delete(key('missing'));
+        const payload = new Uint8Array([0, 1, 2, 254, 255]);
+        created.push(key('a/b.json'));
+        await store.put(key('a/b.json'), payload, 'application/json');
+        await store.put(key('a/b.json'), payload, 'application/json');
+        const stored = await store.get(key('a/b.json'));
+        expect(stored !== null, 'a written key can be read');
+        if (stored) {
+            expect(stored.contentType.startsWith('application/json'), 'the content type round-trips');
+            const bytes = await readBytes(stored.body);
+            expect(bytes.length === payload.length && payload.every((byte, i) => bytes[i] === byte), 'bytes round-trip exactly');
+            expect(stored.size === payload.length, 'size is the byte length');
+        }
+        expect(await store.head(key('a/b.json')), 'head is true for a written key');
+        await store.put(key('a/b.json'), text('{}'), 'application/json');
+        const replaced = await store.get(key('a/b.json'));
+        expect(replaced !== null && (await readBytes(replaced.body)).length === 2, 'put overwrites the same key');
+        for (const name of ['a/c.json', 'a/d/e.json', 'z.json']) {
+            created.push(key(name));
+            await store.put(key(name), text(name), 'text/plain');
+        }
+        const all = await store.listKeys(scratch);
+        expect(JSON.stringify(all) === JSON.stringify([...all].sort()), 'listKeys is sorted by code unit');
+        expect(all.length === 4, 'listKeys lists every key under the prefix, nothing else');
+        const nested = await store.listKeys(key('a/'));
+        expect(nested.length === 3 && nested.every((name) => name.startsWith(key('a/'))), 'listKeys filters by prefix, including across directories');
+        expect((await store.listKeys(key('a/c'))).length === 1, 'a prefix need not end at a separator');
+        expect((await store.listKeys(key('nothing/'))).length === 0, 'listKeys is empty for an unused prefix');
+        const scoped = store.withPrefix(scratch);
+        expect((await scoped.listKeys()).length === 4 && (await scoped.listKeys())[0] === 'a/b.json', 'withPrefix scopes keys, which are relative to it');
+        await scoped.put('scoped.json', text('s'), 'text/plain');
+        created.push(key('scoped.json'));
+        expect(await store.head(key('scoped.json')), 'a write through withPrefix lands under the prefix');
+        await store.delete(key('z.json'));
+        expect(!(await store.head(key('z.json'))), 'delete removes a key');
+        await store.deleteMany([key('a/c.json'), key('a/d/e.json'), key('missing-too')]);
+        expect(!(await store.head(key('a/c.json'))) && !(await store.head(key('a/d/e.json'))), 'deleteMany removes keys, missing ones included');
+    }
+    catch (error) {
+        failures.push(`threw: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        await store.deleteMany(created).catch(() => { });
+    }
+    return { ok: failures.length === 0, failures };
+}