@crvouga/atlas 0.4.0 → 0.5.0

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

@@ -1,21 +1,47 @@
+/**
+ * @module Layer types
+ *
+ * The in-memory shapes of a layer: `LayerSummary` (everything but its captured files), `ReportLayer` (the summary plus
+ * the index of those files) and `ReportOutline` (the specs a report is laid over). The stored form is the layer
+ * document of `packages/schema/src/layer.ts`; these types are what the reader and publisher code hands around after
+ * parsing it. Fields follow the layer document, so adding a field here means adding an optional field there.
+ *
+ * @see docs/report-contract.md#the-layer-document
+ */
 import type { BundleIndex } from './bundle.js';
 import type { ReportPart, SpecEntry } from './explorer-types.js';
 import type { SourceRecord } from './protocol.js';
+/** String choices (such as `{ device: 'iphone-15' }`) that make a result its own slot. Compared as sorted key/value pairs. */
 export type LayerParameters = Readonly<Record<string, string>>;
-export type LayerSummary = {
+/** What a layer may carry as a whole. All optional and open: see docs/extending.md. */
+export type LayerExtras = Partial<Pick<import('../../schema/src/layer.js').LayerDocument, 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions'>>;
+/** A layer without its captured files: what composition and the viewer's lists read. */
+export type LayerSummary = LayerExtras & {
+    /** `modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Absent for a clean checkout. Advisory; never changes a status. */
     readonly freshness?: 'unknown' | 'modified';
+    /** The layer's content digest: 64 lowercase hex digits. Opaque to readers. Legacy commit-keyed recordings use `part-<sha>-<id>` or `source-<sha>-<id>` instead. */
     readonly id: string;
+    /** When the checks ran, epoch milliseconds. The newest completed result wins its slot. */
     readonly recordedAtMs: number;
+    /** The stable name of the suite or tool that made the layer. Part of the slot. */
     readonly producer: string;
+    /** Provenance: the commit recorded, or `null`. Never part of the slot. */
     readonly sha: string | null;
+    /** Provenance: the branch recorded, or `null`. Never part of the slot. */
     readonly branch: string | null;
     /** The client this layer checked, when it said. Normalized when the layer is read. */
     readonly environment?: string | null;
+    /** Provenance: the CI run that produced the layer, or `null`. Never part of the slot. */
     readonly runUrl: string | null;
+    /** Free choices that make a result its own slot. The `environment` parameter is read as the environment (see `layerPlace`). */
     readonly parameters: LayerParameters;
+    /** The specs the layer was recorded against, with fingerprints of their text. */
     readonly specs: readonly SpecEntry[];
+    /** The checks, grouped by producer-defined kind. */
     readonly parts: readonly ReportPart[];
+    /** The recorded statechart run behind the layer (timelines and tests), or `null` for a layer of plain checks. */
     readonly source: SourceRecord | null;
+    /** Where the layer's timelines and captured files are read from: its own bundle (`layer`), an older commit-keyed recording (`commit`), or nowhere (`null`). */
     readonly recording: {
         readonly type: 'layer';
     } | {
@@ -24,11 +50,16 @@ export type LayerSummary = {
         readonly source: string;
     } | null;
 };
+/** A layer with the index that locates its captured files (screenshots, frames) in the store. */
 export type ReportLayer = LayerSummary & {
     readonly bundle: BundleIndex;
 };
+/** The current specs a report is laid over, and the commit and changes freshness warnings are judged against. */
 export type ReportOutline = {
+    /** The specs that make the outline of the report. A spec here with no layer shows as having no results. */
     readonly specs: readonly SpecEntry[];
+    /** The commit the specs are from, or `null` when unknown. */
     readonly sha: string | null;
+    /** Paths changed since the layers were recorded; a result touching one is warned as potentially outdated. */
     readonly changedFiles: readonly string[];
 };

package/dist/reports/src/layers-route.d.ts

@@ -1,20 +1,63 @@
+/**
+ * @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 type { ObjectStore } from './object-store.js';
 import type { ReportsAppDeps } from './reports-route.js';
-/** A further store whose layers join the combined report, beside the local and the shared one. */
+/** A further store whose layers join the combined report, beside the local and the shared one. Passed as `backends` in `ReportsAppDeps`. */
 export type ReportBackend = {
-    /** Stable and unique: letters, digits and hyphens. `local` and `shared` are taken. */
+    /** Stable and unique: lowercase letters, digits and hyphens. `local` and `shared` are taken. Appears in cursors and URLs. */
     readonly id: string;
+    /** Human name shown for the backend in the viewer. */
     readonly label: string;
+    /** Where the backend's layers are read from. */
     readonly store: ObjectStore;
 };
 type Backend = ReportBackend & {
     readonly live: boolean;
 };
+/** The id of the backend for this machine's own store (`localStore`), where runs may still be writing. */
 export declare const LOCAL_BACKEND = "local";
+/** The id of the backend for the shared reports store (`store`). */
 export declare 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 declare function reportBackends(deps: ReportsAppDeps): Backend[];
-/** 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 declare function createLayersApp(deps: ReportsAppDeps): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
 export {};

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/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 };
+}