@crvouga/atlas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,53 @@
+/**
+ * Object-store key layout of the shared reports store. Historical recording addresses use
+ * the full commit sha. Immutable report layers combine across those addresses:
+ *
+ *   index/<13-digit inverted start ms>-<sha>.json   one per published commit;
+ *                                                   sorted keys = newest first
+ *   commits/<sha>/commit.json                       the commit's run record
+ *   commits/<sha>/frame.css                         stylesheet for its snapshots
+ *   commits/<sha>/sources/<source>.json             one source's test metas
+ *   commits/<sha>/bundles/<source>.json              logical file locations
+ *   commits/<sha>/blobs/<content hash>.gz            compressed chunks
+ *
+ * Logical test and frame keys below are entries in the bundle indexes.
+ *
+ * A source is one report bucket of one package (`libs-chess--part-2`).
+ * Writers put a source's tests first and its `sources/` record last, so a
+ * reader that sees the record can read every test it names.
+ */
+/**
+ * Where the reports live in their bucket. Every reader and writer scopes its
+ * store to it, so the keys below are relative to it.
+ */
+export declare const REPORTS_ROOT_PREFIX = "spec-reports";
+export declare const COMMITS_INDEX_PREFIX = "index/";
+export declare function isCommitSha(value: string): boolean;
+/** One path segment the harness could have written (never `.` or `..`). */
+export declare function isKeySegment(value: string): boolean;
+/** A frame file relative to its test (`frames/f-0001.state.json`). */
+export declare function isFramePath(value: string): boolean;
+/** `libs/chess` + `part-2` → `libs-chess--part-2`. */
+export declare function sourceId(packageDir: string, bucket: string): string;
+export declare function commitIndexKey(sha: string, startedAtMs: number): string;
+/** The sha an index key names, or null for anything else. */
+export declare function shaOfIndexKey(key: string): string | null;
+export declare function commitPrefix(sha: string): string;
+export declare function commitKey(sha: string): string;
+export declare function frameCssKey(sha: string): string;
+export declare function sourcesPrefix(sha: string): string;
+export declare function sourceKey(sha: string, source: string): string;
+/** The source a `sources/` key names, or null for anything else. */
+export declare function sourceOfKey(sha: string, key: string): string | null;
+export declare function remoteTestPrefix(sha: string, source: string, testId: string): string;
+export declare function remoteTestReportKey(sha: string, source: string, testId: string): string;
+export declare function remoteTestFileKey(sha: string, source: string, testId: string, file: string): string;
+/**
+ * The id a viewer shows for a test of a source (`libs-chess--part-2/monkey`):
+ * unique across the commit, since two packages may both name a test `monkey`.
+ */
+export declare function viewerTestId(source: string, testId: string): string;
+export declare function splitViewerTestId(id: string): {
+    readonly source: string;
+    readonly testId: string;
+} | null;

package/dist/reports/src/keys.js

@@ -0,0 +1,122 @@
+/**
+ * Object-store key layout of the shared reports store. Historical recording addresses use
+ * the full commit sha. Immutable report layers combine across those addresses:
+ *
+ *   index/<13-digit inverted start ms>-<sha>.json   one per published commit;
+ *                                                   sorted keys = newest first
+ *   commits/<sha>/commit.json                       the commit's run record
+ *   commits/<sha>/frame.css                         stylesheet for its snapshots
+ *   commits/<sha>/sources/<source>.json             one source's test metas
+ *   commits/<sha>/bundles/<source>.json              logical file locations
+ *   commits/<sha>/blobs/<content hash>.gz            compressed chunks
+ *
+ * Logical test and frame keys below are entries in the bundle indexes.
+ *
+ * A source is one report bucket of one package (`libs-chess--part-2`).
+ * Writers put a source's tests first and its `sources/` record last, so a
+ * reader that sees the record can read every test it names.
+ */
+/**
+ * Where the reports live in their bucket. Every reader and writer scopes its
+ * store to it, so the keys below are relative to it.
+ */
+export const REPORTS_ROOT_PREFIX = 'spec-reports';
+const SHA = /^[0-9a-f]{40}$/;
+/** `sanitizeTestId` output: what the harness names tests and runs. */
+const SEGMENT = /^[a-zA-Z0-9._-]+$/;
+/** Inverted start times sort newest first while there are 13-digit ms. */
+const INVERT_FROM = 9_999_999_999_999;
+export const COMMITS_INDEX_PREFIX = 'index/';
+export function isCommitSha(value) {
+    return SHA.test(value);
+}
+/** One path segment the harness could have written (never `.` or `..`). */
+export function isKeySegment(value) {
+    return SEGMENT.test(value) && value !== '.' && value !== '..';
+}
+/** A frame file relative to its test (`frames/f-0001.state.json`). */
+export function isFramePath(value) {
+    const parts = value.split('/');
+    return parts.length > 0 && parts.every(isKeySegment);
+}
+function assertSha(sha) {
+    if (!isCommitSha(sha)) {
+        throw new Error(`report key needs a full 40-hex commit sha, got "${sha}"`);
+    }
+}
+/** `libs/chess` + `part-2` → `libs-chess--part-2`. */
+export function sourceId(packageDir, bucket) {
+    const id = `${packageDir.replaceAll('/', '-')}--${bucket}`;
+    if (!isKeySegment(id))
+        throw new Error(`not a report source: "${id}"`);
+    return id;
+}
+export function commitIndexKey(sha, startedAtMs) {
+    assertSha(sha);
+    const inverted = String(INVERT_FROM - Math.max(0, Math.floor(startedAtMs)));
+    return `${COMMITS_INDEX_PREFIX}${inverted.padStart(13, '0')}-${sha}.json`;
+}
+/** The sha an index key names, or null for anything else. */
+export function shaOfIndexKey(key) {
+    const m = /^index\/\d{13}-([0-9a-f]{40})\.json$/.exec(key);
+    return m === null ? null : (m[1] ?? null);
+}
+export function commitPrefix(sha) {
+    assertSha(sha);
+    return `commits/${sha}/`;
+}
+export function commitKey(sha) {
+    return `${commitPrefix(sha)}commit.json`;
+}
+export function frameCssKey(sha) {
+    return `${commitPrefix(sha)}frame.css`;
+}
+export function sourcesPrefix(sha) {
+    return `${commitPrefix(sha)}sources/`;
+}
+export function sourceKey(sha, source) {
+    if (!isKeySegment(source))
+        throw new Error(`not a source: "${source}"`);
+    return `${sourcesPrefix(sha)}${source}.json`;
+}
+/** The source a `sources/` key names, or null for anything else. */
+export function sourceOfKey(sha, key) {
+    const head = sourcesPrefix(sha);
+    if (!key.startsWith(head) || !key.endsWith('.json'))
+        return null;
+    const source = key.slice(head.length, -'.json'.length);
+    return isKeySegment(source) ? source : null;
+}
+export function remoteTestPrefix(sha, source, testId) {
+    if (!isKeySegment(source))
+        throw new Error(`not a source: "${source}"`);
+    if (!isKeySegment(testId))
+        throw new Error(`not a test id: "${testId}"`);
+    return `${commitPrefix(sha)}tests/${source}/${testId}/`;
+}
+export function remoteTestReportKey(sha, source, testId) {
+    return `${remoteTestPrefix(sha, source, testId)}report.json`;
+}
+export function remoteTestFileKey(sha, source, testId, file) {
+    const rel = file.replace(/^\/+/, '');
+    if (!isFramePath(rel))
+        throw new Error(`not a frame file: "${file}"`);
+    return `${remoteTestPrefix(sha, source, testId)}${rel}`;
+}
+/**
+ * The id a viewer shows for a test of a source (`libs-chess--part-2/monkey`):
+ * unique across the commit, since two packages may both name a test `monkey`.
+ */
+export function viewerTestId(source, testId) {
+    return `${source}/${testId}`;
+}
+export function splitViewerTestId(id) {
+    const slash = id.indexOf('/');
+    if (slash < 0)
+        return null;
+    const source = id.slice(0, slash);
+    const testId = id.slice(slash + 1);
+    return isKeySegment(source) && isKeySegment(testId)
+        ? { source, testId }
+        : null;
+}

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

@@ -0,0 +1,5 @@
+import type { ObjectStore } from './object-store.js';
+import type { LayerSummary } from './layer-types.js';
+/** Read existing recordings in place; opening Atlas never rewrites the evidence store. */
+export declare function catalogEntries(store: ObjectStore): Promise<readonly string[]>;
+export declare function catalogLayers(store: ObjectStore, entry: string): Promise<readonly LayerSummary[]>;

package/dist/reports/src/layer-catalog.js

@@ -0,0 +1,39 @@
+import { readUtf8 } from './object-io.js';
+import { readCommit } from './read.js';
+import { readInventory } from './spec-inventory.js';
+import { readParts } from './report-parts.js';
+import { reportStore } from './publication.js';
+import { readStoredSource } from './source-content.js';
+import { sourceParts } from './source-part.js';
+import { LAYER_INDEX, readLayer, layerSummary } from './layer-store.js';
+import { eachLimited } from './completion-order.js';
+/** Read existing recordings in place; opening Atlas never rewrites the evidence store. */
+export async function catalogEntries(store) {
+    const [layers, versions, commits] = await Promise.all([store.listKeys(LAYER_INDEX), store.listKeys('versions/'), store.listKeys('index/')]);
+    const shas = new Set([...versions, ...commits].flatMap(key => /([0-9a-f]{40})\.json$/.exec(key)?.[1] ?? []));
+    return [...layers.map(key => `layer:${key}`), ...[...shas].sort().map(sha => `commit:${sha}`)];
+}
+export async function catalogLayers(store, entry) {
+    if (entry.startsWith('layer:')) {
+        const raw = await readUtf8(store, entry.slice(6));
+        const id = raw && JSON.parse(raw).id;
+        const layer = id ? await readLayer(store, id) : null;
+        if (!layer)
+            throw new Error('An indexed report layer is unavailable');
+        return [layerSummary(layer)];
+    }
+    const sha = entry.slice(7);
+    const [commit, inventory, parts, scoped] = await Promise.all([readCommit(store, sha), readInventory(store, sha), readParts(store, sha), reportStore(store, sha)]);
+    const specs = inventory?.entries ?? [];
+    const layers = parts.map(part => ({ ...(part.freshness ? { freshness: part.freshness } : {}), id: `part-${sha}-${part.id}`, producer: part.id, recordedAtMs: part.recordedAtMs, sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null, parameters: part.parameters ?? {}, specs, parts: [part], source: null, recording: null }));
+    await eachLimited(await scoped.listKeys(`commits/${sha}/sources/`), 8, async (key) => {
+        const sourceId = key.split('/').at(-1).replace(/\.json$/, '');
+        const stored = await readStoredSource(store, sha, sourceId);
+        if (!stored)
+            return;
+        layers.push({ id: `source-${sha}-${sourceId}`, producer: sourceId, recordedAtMs: Math.max(commit?.startedAtMs ?? 0, stored.record.updatedAtMs), sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null, parameters: {}, specs, parts: sourceParts(sha, stored.record), source: stored.record, recording: { type: 'commit', sha, source: sourceId } });
+    });
+    const signature = (part) => JSON.stringify([part.id, part.kind, part.checks]);
+    const sourceEvidence = new Set(layers.filter(layer => layer.source).flatMap(layer => layer.parts.map(signature)));
+    return layers.filter(layer => layer.source || !layer.parts.every(part => !part.parameters && sourceEvidence.has(signature(part))));
+}

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

@@ -0,0 +1,43 @@
+import type { EvidenceStatus, SpecEntry } from './explorer-types.js';
+import type { LayerEvidence, LayerHeader, LayerRow, StatusCounts } from './evidence-types.js';
+import type { LayerParameters, LayerSummary, ReportOutline } from './layer-types.js';
+/** Advisory identity, never a cryptographic integrity check. */
+export declare function textFingerprint(text: string): string;
+export declare function specPath(path: string): string;
+export declare function parameterKey(parameters: LayerParameters): string;
+/** Recorded timings qualify an outcome. They are a result of their own only when nothing else checked the same thing. */
+export declare function isDiagnosticKind(kind: string): boolean;
+export declare function emptyCounts(): Record<EvidenceStatus, number>;
+/** Outcomes of a layer: its checks, without the timings that only qualify them. */
+export declare function outcomeCounts(rows: readonly LayerRow[]): StatusCounts;
+/** A layer as the explorer reads it: its origin, and each check as one row. */
+export declare function layerEvidence(summary: LayerSummary, backend: string): LayerEvidence;
+export type EvidenceResult = {
+    /** One producer's check of one kind under one parameter set. */
+    readonly key: string;
+    /** The check itself, whatever kind of evidence and parameters describe it. */
+    readonly slot: string;
+    readonly layer: LayerHeader;
+    readonly row: LayerRow;
+    readonly parameters: LayerParameters;
+    readonly warning: string | null;
+};
+export type CombinedEvidence = {
+    readonly specs: readonly {
+        readonly spec: SpecEntry;
+        readonly results: EvidenceResult[];
+    }[];
+    readonly unassigned: EvidenceResult[];
+};
+/** One linear pass. Latest completed result wins only its own check/parameter slot. */
+export declare function combineEvidence(outline: ReportOutline, layers: readonly LayerEvidence[]): CombinedEvidence;
+export declare function slotKey(path: string, id: string): string;
+/** Suppress the mutable address of an execution already archived as an immutable layer. */
+export declare function distinctHeaders<T extends {
+    readonly id: string;
+    readonly execution: string;
+}>(layers: readonly T[]): T[];
+export declare function distinctEvidence(layers: readonly LayerEvidence[]): LayerEvidence[];
+/** Suppress the mutable address of an execution already archived as an immutable layer. */
+export declare function distinctLayers(layers: readonly LayerSummary[]): LayerSummary[];
+export declare function layerExecutionKey(layer: LayerSummary): string;

package/dist/reports/src/layer-merge.js

@@ -0,0 +1,154 @@
+/** Advisory identity, never a cryptographic integrity check. */
+export function textFingerprint(text) {
+    let a = 2166136261, b = 5381;
+    for (let i = 0; i < text.length; i++) {
+        a = Math.imul(a ^ text.charCodeAt(i), 16777619);
+        b = Math.imul(b, 33) ^ text.charCodeAt(i);
+    }
+    return `${text.length}:${(a >>> 0).toString(16)}:${(b >>> 0).toString(16)}`;
+}
+export function specPath(path) {
+    return path.replaceAll('\\', '/').replace(/^\.\//, '').replace(/^.*?(?=specs\/)/, '');
+}
+export function parameterKey(parameters) {
+    return JSON.stringify(Object.entries(parameters).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+}
+/** Recorded timings qualify an outcome. They are a result of their own only when nothing else checked the same thing. */
+export function isDiagnosticKind(kind) {
+    return kind === 'performance';
+}
+export function emptyCounts() {
+    return { passed: 0, failed: 0, running: 0, 'not-run': 0 };
+}
+/** Outcomes of a layer: its checks, without the timings that only qualify them. */
+export function outcomeCounts(rows) {
+    const outcomes = rows.some(row => !isDiagnosticKind(row.kind)) ? rows.filter(row => !isDiagnosticKind(row.kind)) : rows;
+    const counts = emptyCounts();
+    for (const row of outcomes)
+        counts[row.status] += 1;
+    return counts;
+}
+/** A layer as the explorer reads it: its origin, and each check as one row. */
+export function layerEvidence(summary, backend) {
+    const source = summary.source;
+    const tests = new Map(source?.tests.map(test => [`${source.source}/${test.testId}`, test]) ?? []);
+    const rows = summary.parts.flatMap(part => part.checks.map(check => {
+        const test = tests.get(check.id);
+        const variant = test ? { system: test.system, runtime: test.runtime, seed: test.seed } : {};
+        return {
+            kind: part.kind,
+            id: check.id,
+            title: check.title,
+            status: check.status,
+            specPath: check.specPath ? specPath(check.specPath) : null,
+            detail: check.detail,
+            measurements: check.measurements,
+            testId: test?.testId ?? null,
+            variant,
+            durationMs: test?.durationMs ?? null,
+        };
+    }));
+    const recording = summary.recording;
+    const layer = {
+        ...(summary.freshness ? { freshness: summary.freshness } : {}),
+        id: summary.id,
+        backend,
+        producer: summary.producer,
+        packageDir: source?.packageDir ?? null,
+        recordedAtMs: summary.recordedAtMs,
+        sha: summary.sha,
+        branch: summary.branch,
+        runUrl: summary.runUrl,
+        parameters: summary.parameters,
+        recording: recording === null ? null : recording.type === 'layer' ? { type: 'layer', layer: summary.id } : recording,
+        live: false,
+        counts: outcomeCounts(rows),
+        execution: textFingerprint(layerExecutionKey(summary)),
+    };
+    const fingerprints = {};
+    for (const spec of summary.specs)
+        if (spec.fingerprint)
+            fingerprints[specPath(spec.path)] = spec.fingerprint;
+    return { id: summary.id, layer, rows, fingerprints };
+}
+function warning(layer, path, current, outline, recorded, relatedChanged) {
+    if (layer.live)
+        return null;
+    if (layer.freshness === 'modified')
+        return 'Potentially outdated: recorded from a modified checkout';
+    if (layer.freshness === 'unknown')
+        return 'Freshness unknown: recording origin was not captured';
+    if (!path || !current)
+        return 'Spec is not in the current outline';
+    if (!recorded || !current.fingerprint)
+        return 'Freshness unknown: no recorded spec fingerprint';
+    if (recorded !== current.fingerprint)
+        return 'Potentially outdated: spec changed';
+    if (relatedChanged)
+        return 'Potentially outdated: related files changed';
+    if (!layer.sha || !outline.sha || layer.sha !== outline.sha)
+        return 'Potentially outdated: related code has not been compared';
+    return null;
+}
+const RANK = { passed: 0, 'not-run': 1, running: 2, failed: 3 };
+function completed(status) {
+    return status === 'passed' || status === 'failed';
+}
+/** A newer completed result takes its slot. An unfinished one never replaces a completed one, and a tie fails. */
+function replaces(next, prior) {
+    const done = completed(next.row.status);
+    const priorDone = completed(prior.row.status);
+    if (done !== priorDone)
+        return done;
+    if (next.layer.recordedAtMs !== prior.layer.recordedAtMs)
+        return next.layer.recordedAtMs > prior.layer.recordedAtMs;
+    if (RANK[next.row.status] !== RANK[prior.row.status])
+        return RANK[next.row.status] > RANK[prior.row.status];
+    return next.layer.id > prior.layer.id;
+}
+/** One linear pass. Latest completed result wins only its own check/parameter slot. */
+export function combineEvidence(outline, layers) {
+    const specs = new Map(outline.specs.map(spec => [specPath(spec.path), { spec, results: [] }]));
+    const changed = new Set(outline.changedFiles.map(specPath));
+    const winners = new Map();
+    for (const { layer, rows, fingerprints } of distinctEvidence(layers)) {
+        const scope = layer.packageDir;
+        const related = outline.changedFiles.some(file => scope ? file.startsWith(`${scope}/`) : !specPath(file).startsWith('specs/'));
+        for (const row of rows) {
+            const parameters = { ...layer.parameters, ...row.variant };
+            const path = row.specPath ?? '';
+            const key = JSON.stringify([layer.producer, row.kind, path, row.id, parameterKey(parameters)]);
+            const result = { key, slot: slotKey(path, row.id), layer, row, parameters, warning: warning(layer, path, specs.get(path)?.spec, outline, fingerprints[path], related || changed.has(path)) };
+            const prior = winners.get(key);
+            if (!prior || replaces(result, prior))
+                winners.set(key, result);
+        }
+    }
+    const unassigned = [];
+    for (const result of winners.values())
+        (specs.get(result.row.specPath ?? '')?.results ?? unassigned).push(result);
+    return { specs: [...specs.values()], unassigned };
+}
+export function slotKey(path, id) {
+    return JSON.stringify([path, id]);
+}
+function archived(id) {
+    return /^[0-9a-f]{64}$/.test(id);
+}
+/** Suppress the mutable address of an execution already archived as an immutable layer. */
+export function distinctHeaders(layers) {
+    const kept = new Set(layers.filter(layer => archived(layer.id)).map(layer => layer.execution));
+    return [...new Map(layers.filter(layer => archived(layer.id) || !kept.has(layer.execution)).map(layer => [layer.id, layer])).values()];
+}
+export function distinctEvidence(layers) {
+    const kept = new Set(distinctHeaders(layers.map(entry => entry.layer)).map(layer => layer.id));
+    return [...new Map(layers.filter(entry => kept.has(entry.id)).map(entry => [entry.id, entry])).values()];
+}
+/** Suppress the mutable address of an execution already archived as an immutable layer. */
+export function distinctLayers(layers) {
+    const kept = new Set(layers.filter(layer => archived(layer.id)).map(layerExecutionKey));
+    return [...new Map(layers.filter(layer => archived(layer.id) || !kept.has(layerExecutionKey(layer))).map(layer => [layer.id, layer])).values()];
+}
+export function layerExecutionKey(layer) {
+    return JSON.stringify([layer.producer, layer.sha, layer.recordedAtMs, layer.parts]);
+}

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

@@ -0,0 +1,6 @@
+import type { HtmlReportTest } from './recording-bundle.js';
+import { type BundleIndex } from './bundle.js';
+import type { ObjectStore } from './object-store.js';
+import type { SourceRecord } from './protocol.js';
+import type { PublishSourceArgs } from './publish.js';
+export declare function archiveSourceLayer(store: ObjectStore, args: PublishSourceArgs, source: SourceRecord, tests: readonly HtmlReportTest[], bundle?: BundleIndex): Promise<import('./layer-types.js').ReportLayer>;

package/dist/reports/src/layer-source.js

@@ -0,0 +1,32 @@
+import { writeBundle } from './bundle.js';
+import { readCommit, readFrameCss } from './read.js';
+import { readInventory } from './spec-inventory.js';
+import { sourceParts } from './source-part.js';
+import { sourceEntries } from './source-entries.js';
+import { publishLayerBundle } from './layer-store.js';
+export async function archiveSourceLayer(store, args, source, tests, bundle) {
+    const [commit, inventory, css] = await Promise.all([readCommit(store, args.sha), readInventory(store, args.sha), readFrameCss(store, args.sha)]);
+    const recordedAtMs = Math.max(commit?.startedAtMs ?? 0, source.updatedAtMs);
+    const runId = args.runId ?? 'latest';
+    const prefix = `commits/${args.sha}/tests/${source.source}/`;
+    const layerPath = (key) => {
+        const tail = key.slice(prefix.length), slash = tail.indexOf('/');
+        const test = tail.slice(0, slash), file = tail.slice(slash + 1);
+        return `tests/${test}/${file === 'report.json' ? file : `files/${file}`}`;
+    };
+    async function* entries() {
+        if (css)
+            yield { key: 'frame.css', bytes: new Uint8Array(await new Response(css.body).arrayBuffer()), contentType: css.contentType };
+        if (bundle)
+            return;
+        for await (const entry of sourceEntries(args, source.source, tests, runId))
+            yield { ...entry, key: layerPath(entry.key) };
+    }
+    const index = await writeBundle(store, entries(), 'layers/blobs/');
+    for (const [key, value] of Object.entries(bundle ?? {}))
+        index[layerPath(key)] = value;
+    return publishLayerBundle(store, {
+        ...(args.freshness ? { freshness: args.freshness } : {}), producer: source.source, recordedAtMs, sha: args.sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null,
+        parameters: args.parameters ?? {}, specs: inventory?.entries ?? [], parts: sourceParts(args.sha, source), source, recording: { type: 'layer' },
+    }, index);
+}

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

@@ -0,0 +1,10 @@
+import { type BundleIndex, type BundleEntry } from './bundle.js';
+import type { ObjectStore } from './object-store.js';
+import type { LayerSummary, ReportLayer } from './layer-types.js';
+export declare const LAYER_INDEX = "layers/index/";
+export declare function layerKey(id: string): string;
+export declare function publishLayer(store: ObjectStore, summary: Omit<LayerSummary, 'id'>, entries: AsyncIterable<BundleEntry>): Promise<ReportLayer>;
+export declare function publishLayerBundle(store: ObjectStore, summary: Omit<LayerSummary, 'id'>, bundle: BundleIndex): Promise<ReportLayer>;
+export declare function readLayer(store: ObjectStore, id: string): Promise<ReportLayer | null>;
+export declare function readLayerFile(store: ObjectStore, id: string, file: string): Promise<BundleEntry | null>;
+export declare function layerSummary(layer: ReportLayer): LayerSummary;

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

@@ -0,0 +1,36 @@
+import { createBundleReader, writeBundle } from './bundle.js';
+import { readUtf8, writeUtf8 } from './object-io.js';
+export const LAYER_INDEX = 'layers/index/';
+export function layerKey(id) {
+    if (!/^[0-9a-f]{64}$/.test(id))
+        throw new Error('Invalid layer id');
+    return `layers/manifests/${id}.json`;
+}
+export async function publishLayer(store, summary, entries) {
+    const bundle = await writeBundle(store, entries, 'layers/blobs/');
+    return publishLayerBundle(store, summary, bundle);
+}
+export async function publishLayerBundle(store, summary, bundle) {
+    const body = JSON.stringify({ ...summary, bundle });
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(body));
+    const id = [...new Uint8Array(digest)].map(byte => byte.toString(16).padStart(2, '0')).join('');
+    const layer = { ...summary, id, bundle };
+    // Immutable manifest first, independent catalog entry last: concurrent producers never overwrite one another.
+    if (!(await store.head(layerKey(id))))
+        await writeUtf8(store, layerKey(id), JSON.stringify(layer), 'application/json');
+    const inverse = String(Number.MAX_SAFE_INTEGER - Math.max(0, Math.floor(summary.recordedAtMs))).padStart(16, '0');
+    await writeUtf8(store, `${LAYER_INDEX}${inverse}-${id}.json`, JSON.stringify({ id }), 'application/json');
+    return layer;
+}
+export async function readLayer(store, id) {
+    const raw = await readUtf8(store, layerKey(id));
+    return raw === null ? null : JSON.parse(raw);
+}
+export async function readLayerFile(store, id, file) {
+    const layer = await readLayer(store, id);
+    return layer ? createBundleReader(store, layer.bundle)(file) : null;
+}
+export function layerSummary(layer) {
+    const { bundle: _, ...summary } = layer;
+    return summary;
+}

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

@@ -0,0 +1,32 @@
+import type { BundleIndex } from './bundle.js';
+import type { ReportPart, SpecEntry } from './explorer-types.js';
+import type { SourceRecord } from './protocol.js';
+export type LayerParameters = Readonly<Record<string, string>>;
+export type LayerSummary = {
+    readonly freshness?: 'unknown' | 'modified';
+    readonly id: string;
+    readonly recordedAtMs: number;
+    readonly producer: string;
+    readonly sha: string | null;
+    readonly branch: string | null;
+    readonly runUrl: string | null;
+    readonly parameters: LayerParameters;
+    readonly specs: readonly SpecEntry[];
+    readonly parts: readonly ReportPart[];
+    readonly source: SourceRecord | null;
+    readonly recording: {
+        readonly type: 'layer';
+    } | {
+        readonly type: 'commit';
+        readonly sha: string;
+        readonly source: string;
+    } | null;
+};
+export type ReportLayer = LayerSummary & {
+    readonly bundle: BundleIndex;
+};
+export type ReportOutline = {
+    readonly specs: readonly SpecEntry[];
+    readonly sha: string | null;
+    readonly changedFiles: readonly string[];
+};

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

@@ -0,0 +1,20 @@
+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. */
+export type ReportBackend = {
+    /** Stable and unique: letters, digits and hyphens. `local` and `shared` are taken. */
+    readonly id: string;
+    readonly label: string;
+    readonly store: ObjectStore;
+};
+type Backend = ReportBackend & {
+    readonly live: boolean;
+};
+export declare const LOCAL_BACKEND = "local";
+export declare const SHARED_BACKEND = "shared";
+/** The stores that contribute layers, in the order they answer for a recording. */
+export declare function reportBackends(deps: ReportsAppDeps): Backend[];
+/** Bounded pages of layer origins, each layer's checks read once, and the runs still writing. */
+export declare function createLayersApp(deps: ReportsAppDeps): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export {};