@crvouga/atlas 0.5.0 → 0.6.0

package/dist/server/src/dev.js

@@ -1,23 +1,24 @@
 /**
  * @module `atlas dev`
  *
- * Runs the same server as `atlas serve` on a port of its own, with the viewer's Vite dev server in front of it. Vite proxies
+ * Runs the same server as `atlas serve` on a port of its own, with the client's Vite dev server in front of it. Vite proxies
  * `/api` (server-sent events included) to the server and writes the same address book into the page, so the browser, the
- * uploaders and the viewer all use one host, exactly as in production, and a change to the viewer shows at once.
+ * uploaders and the client all use one host, exactly as in production, and a change to the client shows at once.
  */
 import path from 'node:path';
 import { openConfiguredBackends, serverOptionsOf } from './main.js';
 import { createAtlasServer } from './app.js';
 import { ConfigError, loadServerConfig, SERVER_USAGE } from './config.js';
 import { listen } from './host.js';
+import { fileServerSettings } from './settings.js';
 import { visualizerRoot } from './site.js';
 /** The text `atlas dev --help` prints. Also the source of the `atlas dev` section of `docs/reference/cli.md`. */
-export const DEV_USAGE = `atlas dev: the Atlas server and the viewer, for working on either
+export const DEV_USAGE = `atlas dev: the Atlas server and the client, for working on either
 
   atlas dev [--port 5180] [--host 127.0.0.1] [--data <dir>] [--store <url|id=url>]... [--config atlas.server.json]
 
-  Starts the server (API only, on a port of its own) and the viewer's dev server, which proxies /api to it, so the
-  browser talks to one host and a change to the viewer shows at once. In production \`atlas serve\` does both from
+  Starts the server (API only, on a port of its own) and the client's dev server, which proxies /api to it, so the
+  browser talks to one host and a change to the client shows at once. In production \`atlas serve\` does both from
   one process.
 `;
 /** `atlas dev`. */
@@ -30,16 +31,16 @@ export async function devMain(argv, io) {
     }
     const root = visualizerRoot();
     if (!root) {
-        io.out('atlas dev: the viewer is not installed alongside the server.\n');
+        io.out('atlas dev: the client is not installed alongside the server.\n');
         return 2;
     }
-    // --port is the one the browser uses (the viewer's); the API takes another that nobody needs to know.
+    // --port is the one the browser uses (the client's); the API takes another that nobody needs to know.
     const flagged = argv.findIndex(item => item === '--port');
     const publicPort = flagged >= 0 ? Number(argv[flagged + 1]) : Number(env.ATLAS_PORT ?? env.PORT ?? 5180);
     const forServer = argv.filter((_, i) => i !== flagged && i !== flagged + 1 || flagged < 0);
     let config;
     try {
-        // The API itself listens on a port of its own on this machine; what the user said about --host is for the viewer, the one door.
+        // The API itself listens on a port of its own on this machine; what the user said about --host is for the client, the one door.
         config = loadServerConfig([...forServer, '--port', '0'], { ...env, PORT: undefined, ATLAS_PORT: undefined }, cwd);
     }
     catch (error) {
@@ -50,10 +51,10 @@ export async function devMain(argv, io) {
         throw error;
     }
     const backends = openConfiguredBackends(config, env, cwd);
-    const api = createAtlasServer(serverOptionsOf(config, backends, line => io.out(`${JSON.stringify(line)}\n`)));
-    const running = await listen(api.fetch, { port: 0, host: '127.0.0.1', maxBodyBytes: config.limits.maxObjectMiB * 1024 * 1024 });
+    const api = createAtlasServer({ ...serverOptionsOf(config, backends, line => io.out(`${JSON.stringify(line)}\n`)), settings: fileServerSettings(config, forServer, env, cwd) });
+    const running = await listen(api.fetch, { port: 0, host: '127.0.0.1', maxBodyBytes: Math.max(config.limits.maxObjectMiB, config.limits.maxJsonMiB) * 1024 * 1024 });
     await api.ready;
-    // The viewer's config reads this to proxy /api, and to write the same page config a server would.
+    // The client's config reads this to proxy /api, and to write the same page config a server would.
     process.env.ATLAS_API_URL = running.url.replace('localhost', '127.0.0.1');
     process.env.INIT_CWD = cwd;
     const { createServer } = await import('vite');
@@ -61,9 +62,17 @@ export async function devMain(argv, io) {
         configFile: path.join(root, 'vite.config.ts'),
         configLoader: 'runner',
         root,
-        server: { port: publicPort, host: config.host, strictPort: false }
+        server: { port: publicPort, host: config.host, strictPort: true }
     });
-    await vite.listen();
+    try {
+        await vite.listen();
+    }
+    catch (error) {
+        api.close();
+        await vite.close();
+        await running.close(2_000);
+        throw error;
+    }
     vite.printUrls();
     io.out(`Data in ${path.relative(cwd, config.data) || config.data}. Publish with: ATLAS_STORE=${vite.resolvedUrls?.local[0] ?? `http://localhost:${publicPort}`} atlas report publish …\n`);
     await new Promise(resolve => {

package/dist/server/src/events.d.ts

@@ -2,15 +2,15 @@
  * @module Server-sent events
  *
  * What the server tells every connected viewer the moment it happens. A viewer that misses some (a dropped connection, a
- * laptop that slept) loses nothing: events say "something changed", the state is always fetched, and a viewer reads again
+ * laptop that slept) loses nothing: report events announce changes, run events carry bounded progress snapshots, and a viewer reads authoritative state again
  * when it reconnects. `EventHub` encodes each event once for all viewers, sends a named `ping` every heartbeat so proxies
  * keep the connection and a quiet server is told apart from a dead one, refuses past a maximum number of viewers (they poll
  * instead), and lets go of a viewer that has stopped reading rather than hold its backlog.
  *
  * @see docs/server.md#streaming
  */
-/** The events the server publishes: `hello` (sent first to a new viewer), `report` (layers arrived) and `atlas:change` (specs or runs changed). `ping` is the heartbeat, sent by the hub itself. */
-export type EventName = 'hello' | 'report' | 'atlas:change';
+/** The events the server publishes: `hello` (sent first to a new viewer), `report` (layers arrived) `atlas:change` (specs or runs changed), `run` (a bounded live lease snapshot), and `projects` (project discovery changed). `ping` is the heartbeat, sent by the hub itself. */
+export type EventName = 'hello' | 'report' | 'atlas:change' | 'run' | 'projects';
 /** The viewers connected to `/api/events` and how to reach them all. One hub per server. */
 export declare class EventHub {
     #private;

package/dist/server/src/events.js

@@ -2,7 +2,7 @@
  * @module Server-sent events
  *
  * What the server tells every connected viewer the moment it happens. A viewer that misses some (a dropped connection, a
- * laptop that slept) loses nothing: events say "something changed", the state is always fetched, and a viewer reads again
+ * laptop that slept) loses nothing: report events announce changes, run events carry bounded progress snapshots, and a viewer reads authoritative state again
  * when it reconnects. `EventHub` encodes each event once for all viewers, sends a named `ping` every heartbeat so proxies
  * keep the connection and a quiet server is told apart from a dead one, refuses past a maximum number of viewers (they poll
  * instead), and lets go of a viewer that has stopped reading rather than hold its backlog.

package/dist/server/src/index.d.ts

@@ -14,3 +14,5 @@ export { EventHub, type EventName } from './events.js';
 export { listen, type RunningServer } from './host.js';
 export { serveMain } from './main.js';
 export { classify, validateUpload, validKey, Refusal } from './validate.js';
+export { fileServerSettings, type ServerSettings, type SettingsSnapshot } from './settings.js';
+export { LiveRuns, LiveRunError } from './live-runs.js';

package/dist/server/src/index.js

@@ -14,3 +14,5 @@ export { EventHub } from './events.js';
 export { listen } from './host.js';
 export { serveMain } from './main.js';
 export { classify, validateUpload, validKey, Refusal } from './validate.js';
+export { fileServerSettings } from './settings.js';
+export { LiveRuns, LiveRunError } from './live-runs.js';

package/dist/server/src/live-runs.d.ts

@@ -0,0 +1,52 @@
+import type { z } from 'zod/v4';
+import { type LiveRun, type LiveRunStartSchema, type LiveRunUpdateSchema } from '../../schema/src/live-run.js';
+import type { ObjectStore } from '../../reports/src/object-store.js';
+import type { ReportLayer } from '../../reports/src/layer-types.js';
+type Start = z.output<typeof LiveRunStartSchema>;
+type Update = z.output<typeof LiveRunUpdateSchema>;
+/** A refused run update: 403 another publisher, 404 unknown run, 409 stale/terminal run, or 429 capacity. */
+export declare class LiveRunError extends Error {
+    readonly status: 403 | 404 | 409 | 429;
+    constructor(status: 403 | 404 | 409 | 429, message: string);
+}
+/**
+ * One server's live feed. Heartbeats never create result layers. Persisted summaries contain at most 20 recent
+ * checks and 10 active checks; completed results live in ordinary immutable layers. Leases expire by server time.
+ * @example
+ * const live = new LiveRuns({ store, timeoutMs: 30_000, stalledMs: 900_000, onChange: () => {}, onLayer: async () => {} });
+ */
+export declare class LiveRuns {
+    private readonly options;
+    private readonly held;
+    private readonly attempts;
+    private readonly queues;
+    /** Resolves after restoring summaries and interrupting leases left by a previous server process. */
+    readonly ready: Promise<void>;
+    private readonly now;
+    constructor(options: {
+        store: ObjectStore;
+        timeoutMs: number;
+        stalledMs: number;
+        now?: () => number;
+        onChange: (run: LiveRun) => void;
+        onLayer: (key: string, layer: ReportLayer) => Promise<void>;
+    });
+    private restore;
+    private save;
+    private locked;
+    private state;
+    private interrupt;
+    private expired;
+    private requireLive;
+    /** Read the most recent 50 summaries. Progress detail and counters are already bounded and cached. */
+    list(): Promise<LiveRun[]>;
+    /** Register one producer lease. Retrying an identical start is idempotent. */
+    start(input: Start, owner: string): Promise<LiveRun>;
+    /** Renew liveness by server receipt time, independently of whether a test made progress. */
+    heartbeat(id: string, owner: string): Promise<void>;
+    /** Apply one ordered progress batch and publish its completed checks before acknowledging it. */
+    update(id: string, input: Update, owner: string): Promise<LiveRun>;
+    /** Expire silent producers and optional progress stalls. Heartbeats cannot revive an expired run. */
+    sweep(): Promise<void>;
+}
+export {};

package/dist/server/src/live-runs.js

@@ -0,0 +1,229 @@
+/** @module Live run leases
+ * Tracks producer heartbeats independently of progress, publishes completed checks incrementally, and persists
+ * bounded run summaries. A server restart interrupts outstanding leases rather than inventing continued progress.
+ */
+import { createHash } from 'node:crypto';
+import { LiveRunSchema } from '../../schema/src/live-run.js';
+import { readUtf8, writeUtf8 } from '../../reports/src/object-io.js';
+import { publishChecks } from '../../reports/src/publish-checks.js';
+import { layerCatalogKey } from '../../reports/src/layer-store.js';
+const PREFIX = 'server/live/';
+const keyOf = (run) => `${PREFIX}${String(Number.MAX_SAFE_INTEGER - run.startedAtMs).padStart(16, '0')}-${run.id}.json`;
+/** A refused run update: 403 another publisher, 404 unknown run, 409 stale/terminal run, or 429 capacity. */
+export class LiveRunError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * One server's live feed. Heartbeats never create result layers. Persisted summaries contain at most 20 recent
+ * checks and 10 active checks; completed results live in ordinary immutable layers. Leases expire by server time.
+ * @example
+ * const live = new LiveRuns({ store, timeoutMs: 30_000, stalledMs: 900_000, onChange: () => {}, onLayer: async () => {} });
+ */
+export class LiveRuns {
+    options;
+    held = new Map();
+    attempts = new Map();
+    queues = new Map();
+    /** Resolves after restoring summaries and interrupting leases left by a previous server process. */
+    ready;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.ready = this.restore();
+        // Requests await ready and surface failures; no unhandled rejection while a backend is unavailable.
+        void this.ready.catch(() => undefined);
+    }
+    async restore() {
+        const keys = (await this.options.store.listKeys(PREFIX)).slice(0, 200);
+        for (const key of keys) {
+            const text = await readUtf8(this.options.store, key);
+            if (text === null)
+                continue;
+            const stored = JSON.parse(text);
+            const run = LiveRunSchema.parse(stored.run);
+            const state = { run, owner: stored.owner, digest: stored.digest, states: new Map() };
+            this.held.set(run.id, state);
+            if (run.status === 'running')
+                await this.interrupt(state, 'The Atlas server restarted before the run completed.');
+        }
+    }
+    async save(state) {
+        await writeUtf8(this.options.store, keyOf(state.run), JSON.stringify({ run: state.run, owner: state.owner, digest: state.digest }), 'application/json');
+    }
+    locked(id, action) {
+        const next = (this.queues.get(id) ?? Promise.resolve()).catch(() => { }).then(action);
+        this.queues.set(id, next);
+        return next.finally(() => { if (this.queues.get(id) === next)
+            this.queues.delete(id); });
+    }
+    state(id, owner) {
+        const held = this.held.get(id);
+        if (!held)
+            throw new LiveRunError(404, 'Unknown run.');
+        if (held.owner !== owner)
+            throw new LiveRunError(403, 'This run belongs to another publisher.');
+        return held;
+    }
+    async interrupt(state, reason) {
+        const next = { ...state, states: new Map(), run: { ...state.run, status: 'interrupted', reason, finishedAtMs: this.now(), running: 0,
+                current: state.run.current.map(check => ({ ...check, status: 'not-run', detail: reason })) } };
+        await this.save(next);
+        this.held.set(next.run.id, next);
+        this.options.onChange(next.run);
+    }
+    expired(run) {
+        if (this.now() - run.lastHeartbeatAtMs >= this.options.timeoutMs)
+            return 'Producer heartbeat timed out. The run may have exited or lost its connection.';
+        if (this.options.stalledMs > 0 && this.now() - run.lastProgressAtMs >= this.options.stalledMs)
+            return 'No test progress arrived before the configured stall timeout.';
+        return undefined;
+    }
+    async requireLive(state) {
+        if (state.run.status !== 'running')
+            throw new LiveRunError(409, 'This run has ended.');
+        const reason = this.expired(state.run);
+        if (reason) {
+            await this.interrupt(state, reason);
+            throw new LiveRunError(409, reason);
+        }
+    }
+    /** Read the most recent 50 summaries. Progress detail and counters are already bounded and cached. */
+    async list() {
+        await this.ready;
+        return [...this.held.values()].map(state => state.run).sort((a, b) => b.startedAtMs - a.startedAtMs || a.id.localeCompare(b.id)).slice(0, 50);
+    }
+    /** Register one producer lease. Retrying an identical start is idempotent. */
+    async start(input, owner) {
+        await this.ready;
+        return this.locked(input.id, async () => {
+            const prior = this.held.get(input.id);
+            if (prior) {
+                const found = this.state(input.id, owner);
+                if (Object.entries(input).some(([key, value]) => found.run[key] !== value))
+                    throw new LiveRunError(409, 'A run id cannot be reused with another identity.');
+                return found.run;
+            }
+            if ([...this.held.values()].filter(state => state.run.status === 'running').length >= 100)
+                throw new LiveRunError(429, 'Too many live runs.');
+            const now = this.now();
+            const state = { owner, digest: '', states: new Map(), run: { ...input, status: 'running', sequence: 0, startedAtMs: now, lastHeartbeatAtMs: now, lastProgressAtMs: now, completed: 0, passed: 0, failed: 0, notRun: 0, running: 0, current: [], recent: [] } };
+            await this.save(state);
+            this.held.set(input.id, state);
+            // Retain bounded terminal history in memory; durable summaries remain in the configured backend.
+            if (this.held.size > 200) {
+                const old = [...this.held.values()].filter(value => value.run.status !== 'running').sort((a, b) => a.run.startedAtMs - b.run.startedAtMs)[0];
+                if (old)
+                    this.held.delete(old.run.id);
+            }
+            this.options.onChange(state.run);
+            return state.run;
+        });
+    }
+    /** Renew liveness by server receipt time, independently of whether a test made progress. */
+    async heartbeat(id, owner) {
+        await this.ready;
+        await this.locked(id, async () => {
+            const state = this.state(id, owner);
+            await this.requireLive(state);
+            const next = { ...state, run: { ...state.run, lastHeartbeatAtMs: this.now() } };
+            await this.save(next);
+            this.held.set(id, next);
+            this.options.onChange(next.run);
+        });
+    }
+    /** Apply one ordered progress batch and publish its completed checks before acknowledging it. */
+    async update(id, input, owner) {
+        await this.ready;
+        return this.locked(id, async () => {
+            const state = this.state(id, owner);
+            const digest = createHash('sha256').update(JSON.stringify(input)).digest('hex');
+            if (input.sequence === state.run.sequence && digest === state.digest)
+                return state.run;
+            await this.requireLive(state);
+            if (input.sequence !== state.run.sequence + 1)
+                throw new LiveRunError(409, 'This run ended or its progress sequence is stale.');
+            if (state.states.size + input.checks.filter(check => !state.states.has(check.id)).length > 100_000)
+                throw new LiveRunError(429, 'A live run may track at most 100000 check identities.');
+            const priorAttempt = this.attempts.get(id);
+            if (priorAttempt && (priorAttempt.sequence !== input.sequence || priorAttempt.digest !== digest))
+                throw new LiveRunError(409, 'Retry the pending sequence with identical content.');
+            const now = priorAttempt?.at ?? Math.max(this.now(), state.run.lastProgressAtMs + 1);
+            const states = new Map(state.states);
+            const run = { ...state.run, sequence: input.sequence, lastHeartbeatAtMs: now, ...(input.checks.length ? { lastProgressAtMs: now } : {}) };
+            const current = new Map(run.current.map(check => [check.id, check]));
+            for (const check of input.checks) {
+                const prior = states.get(check.id);
+                if (prior === 'running')
+                    run.running--;
+                else if (prior) {
+                    run.completed--;
+                    if (prior === 'passed')
+                        run.passed--;
+                    else if (prior === 'failed')
+                        run.failed--;
+                    else
+                        run.notRun--;
+                }
+                states.set(check.id, check.status);
+                if (check.status === 'running') {
+                    run.running++;
+                    current.set(check.id, check);
+                }
+                else {
+                    run.completed++;
+                    if (check.status === 'passed')
+                        run.passed++;
+                    else if (check.status === 'failed')
+                        run.failed++;
+                    else
+                        run.notRun++;
+                    current.delete(check.id);
+                }
+            }
+            run.current = [...current.values()].slice(-10);
+            run.recent = [...input.checks].reverse().concat(run.recent.filter(check => !input.checks.some(next => next.id === check.id))).slice(0, 20);
+            if (input.finish) {
+                if (input.finish === 'completed' && run.running)
+                    throw new LiveRunError(409, 'Finish running checks before completing the run.');
+                run.status = input.finish;
+                run.finishedAtMs = now;
+                run.reason = input.reason;
+                if (input.finish === 'interrupted') {
+                    run.running = 0;
+                    run.current = run.current.map(check => ({ ...check, status: 'not-run', detail: input.reason ?? 'Run interrupted.' }));
+                }
+                states.clear();
+            }
+            const finished = input.checks.filter(check => check.status !== 'running');
+            this.attempts.set(id, { sequence: input.sequence, digest, at: now });
+            if (finished.length) {
+                const layer = await publishChecks(this.options.store, { producer: state.run.producer, environment: state.run.environment, branch: state.run.branch, sha: state.run.sha, recordedAtMs: now,
+                    labels: { 'atlas.run': id }, checks: finished });
+                await this.options.onLayer(layerCatalogKey(layer.recordedAtMs, layer.id), layer);
+            }
+            const next = { ...state, states, run, digest };
+            await this.save(next);
+            this.held.set(id, next);
+            this.attempts.delete(id);
+            this.options.onChange(run);
+            return run;
+        });
+    }
+    /** Expire silent producers and optional progress stalls. Heartbeats cannot revive an expired run. */
+    async sweep() {
+        await this.ready;
+        await Promise.all([...this.held.keys()].map(id => this.locked(id, async () => {
+            const state = this.held.get(id);
+            if (state.run.status !== 'running')
+                return;
+            const reason = this.expired(state.run);
+            if (reason)
+                await this.interrupt(state, reason);
+        })));
+    }
+}

package/dist/server/src/main.d.ts

@@ -2,7 +2,7 @@
  * @module `atlas serve`
  *
  * Starts the Atlas server from its configuration: opens every backend (creating the data folder), proves the upload
- * backend can be written to before listening, finds or builds the viewer, listens at once (so a liveness probe finds the
+ * backend can be written to before listening, finds or builds the client, listens at once (so a liveness probe finds the
  * process while a large backend is still being read), and stops cleanly on SIGTERM or SIGINT. `serverOptionsOf` is shared
  * with `atlas dev`, so the two run the same server.
  *

package/dist/server/src/main.js

@@ -2,7 +2,7 @@
  * @module `atlas serve`
  *
  * Starts the Atlas server from its configuration: opens every backend (creating the data folder), proves the upload
- * backend can be written to before listening, finds or builds the viewer, listens at once (so a liveness probe finds the
+ * backend can be written to before listening, finds or builds the client, listens at once (so a liveness probe finds the
  * process while a large backend is still being read), and stops cleanly on SIGTERM or SIGINT. `serverOptionsOf` is shared
  * with `atlas dev`, so the two run the same server.
  *
@@ -14,6 +14,7 @@ import { openStore } from '../../reports/src/store-url.js';
 import { createAtlasServer } from './app.js';
 import { ConfigError, loadServerConfig, SERVER_USAGE } from './config.js';
 import { listen } from './host.js';
+import { fileServerSettings } from './settings.js';
 import { findSite } from './site.js';
 /** Open every backend of a configuration. The data folder is made if it is not there. */
 export function openConfiguredBackends(config, env, cwd) {
@@ -45,9 +46,10 @@ export function serverOptionsOf(config, backends, log) {
         ? (layer) => (!branches?.length || (layer.branch !== null && branches.includes(layer.branch))) && (!config.include.ignoreModified || layer.freshness === undefined)
         : undefined;
     return {
-        backends, write: config.writeId, tokens: config.tokens, anonymousRead: config.anonymousRead,
+        backends, write: config.writeId,
+        ...(/^https?:\/\//.test(config.backends.find(backend => backend.id === config.writeId).url) ? { liveStore: backends[0].store } : {}), tokens: config.tokens, anonymousRead: config.anonymousRead,
         ...(config.outlineBranch ? { outlineBranch: config.outlineBranch } : {}), ...(include ? { include } : {}),
-        refreshMs: config.refreshSeconds * 1000, limits: config.limits, heartbeatMs: config.heartbeatSeconds * 1000,
+        runTimeoutMs: config.runTimeoutSeconds * 1000, runStallMs: config.runStallSeconds * 1000, refreshMs: config.refreshSeconds * 1000, limits: config.limits, heartbeatMs: config.heartbeatSeconds * 1000,
         ...(config.log && log ? { log } : {})
     };
 }
@@ -80,8 +82,8 @@ export async function serveMain(argv, io) {
     }
     const site = await findSite(config.site, cwd, io.out);
     if (!site)
-        io.out('No viewer to serve: build one with `atlas-visualizer build --no-data --out atlas-site`. The API is served meanwhile.\n');
-    const server = createAtlasServer({ ...serverOptionsOf(config, backends, line => io.out(`${JSON.stringify(line)}\n`)), ...(site ? { site } : {}) });
+        io.out('No Atlas client to serve: build one with `atlas client build --no-data --out atlas-site`. The API is served meanwhile.\n');
+    const server = createAtlasServer({ settings: fileServerSettings(config, argv, env, cwd), ...serverOptionsOf(config, backends, line => io.out(`${JSON.stringify(line)}\n`)), ...(site ? { site } : {}) });
     // Listen at once: the first pass over a large backend can take a while, and a liveness probe must find the
     // process meanwhile. /readyz is 503 until there is a report to show.
     const running = await listen(server.fetch, { port: config.port, host: config.host, maxBodyBytes: Math.max(config.limits.maxObjectMiB, config.limits.maxJsonMiB) * 1024 * 1024 });

package/dist/server/src/openapi.d.ts

@@ -1,5 +1,5 @@
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
-export declare const API_VERSION = "1.0.0";
+export declare const API_VERSION = "1.3.0";
 /** Who may call an operation: `none` (anyone), or the least role that may (`read` < `publish` < `admin`). */
 export type Role = 'none' | 'read' | 'publish' | 'admin';
 type JsonSchema = Record<string, unknown>;
@@ -42,10 +42,7 @@ export type Operation = {
     readonly body?: Body;
     readonly responses: Readonly<Record<string, Response>>;
 };
-/**
- * Every operation of the API. The order is the order of the document. The descriptions are the documentation an
- * agent reads, so they say what to send, what comes back, and what to do when it does not work.
- */
+/** Every node operation and the same stable report protocol inside each project namespace. */
 export declare const OPERATIONS: readonly Operation[];
 /**
  * Routes the server registers that are not operations of this API, each with the reason. The coverage test skips

package/dist/server/src/openapi.js

@@ -13,10 +13,11 @@
  * operations and new events. See AGENTS.md ("The server is a living application").
  */
 import { z } from 'zod/v4';
+import { ProjectsSchema } from '../../schema/src/project.js';
 import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema } from '../../schema/src/api.js';
-import { AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
+import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
-export const API_VERSION = '1.0.0';
+export const API_VERSION = '1.3.0';
 /** The JSON Schema of a Zod schema, as OpenAPI 3.1 embeds it. `output` for what the server sends, `input` for what it accepts. */
 function schemaOf(schema, io = 'output') {
     const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { target: 'draft-2020-12', unrepresentable: 'any', io });
@@ -27,13 +28,15 @@ function schemaOf(schema, io = 'output') {
  * the shape the server sends, `input` the shape it accepts.
  */
 const COMPONENTS = {
+    LiveRun: [LiveRunSchema, 'output'], LiveRunStart: [LiveRunStartSchema, 'input'], LiveRunUpdate: [LiveRunUpdateSchema, 'input'],
+    ServerEditableSettings: [ServerEditableSettingsSchema, 'input'], ServerSettingsSnapshot: [ServerSettingsSnapshotSchema, 'output'],
     Problem: [ProblemSchema, 'output'], Health: [HealthSchema, 'output'], Ready: [ReadySchema, 'output'], ServerInfo: [ServerInfoSchema, 'output'],
     EffectiveEvidence: [EffectiveEvidenceSchema, 'output'], EffectiveDelta: [EffectiveDeltaSchema, 'output'], ReportStatus: [ReportStatusSchema, 'output'],
     PublishChecks: [PublishChecksSchema.partial({ recordedAtMs: true }), 'input'], ChecksResult: [ChecksResultSchema, 'output'],
     StoreListing: [StoreListingSchema, 'output'], StoreWriteResult: [StoreWriteResultSchema, 'output'],
     Outline: [OutlineSchema, 'output'], EvidencePage: [EvidencePageSchema, 'output'], LayerRows: [LayerRowsSchema, 'output'], CheckDetail: [CheckDetailSchema, 'output'],
     SpecIndex: [SpecIndexSchema, 'output'], ReportSources: [ReportSourcesSchema, 'output'], RunsIndex: [RunsIndexSchema, 'output'],
-    HelloEvent: [HelloEventSchema, 'output'], ReportEvent: [ReportEventSchema, 'output'], AtlasChangeEvent: [AtlasChangeSchema, 'output'], PingEvent: [PingEventSchema, 'output']
+    RunEvent: [LiveRunSchema, 'output'], HelloEvent: [HelloEventSchema, 'output'], ReportEvent: [ReportEventSchema, 'output'], AtlasChangeEvent: [AtlasChangeSchema, 'output'], PingEvent: [PingEventSchema, 'output']
 };
 const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
 const str = { type: 'string' };
@@ -49,7 +52,54 @@ const LAYER_ID = { name: 'id', in: 'path', required: true, description: 'A layer
  * Every operation of the API. The order is the order of the document. The descriptions are the documentation an
  * agent reads, so they say what to send, what comes back, and what to do when it does not work.
  */
-export const OPERATIONS = [
+const BASE_OPERATIONS = [
+    {
+        route: 'GET /api/projects', path: '/api/projects', operationId: 'getProjects', tag: 'Projects', role: 'read',
+        summary: 'List projects on this Atlas node', description: 'Projects are created on their first authenticated upload. All report, spec, recording and live-run data is isolated by project. Unqualified API calls address the legacy default project. Tokens retain their node-wide role; project partitioning is not a tenant authorization boundary.',
+        responses: { '200': { description: 'Available project identities.', contentType: 'application/json', schema: schemaOf(ProjectsSchema) }, '401': UNAUTHORIZED, '503': problem('The project catalog is unavailable.') }
+    },
+    {
+        route: 'GET /api/live', path: '/api/live', operationId: 'listLiveRuns', tag: 'Live', role: 'read',
+        summary: 'Live test progress and recent invocations', description: 'Returns up to 50 recent producer leases, including running, completed and interrupted runs. Counters and recent check/step updates are bounded; authentication credentials are never returned. Consume run events for immediate bounded snapshots; re-fetch after reconnect or atlas:change with scope runs on older servers.',
+        responses: { '200': { description: 'Recent live run summaries.', contentType: 'application/json', schema: { type: 'object', properties: { runs: { type: 'array', items: ref('LiveRun') } }, required: ['runs'] } }, '401': UNAUTHORIZED }
+    },
+    {
+        route: 'POST /api/live/:id', path: '/api/live/{id}', operationId: 'startLiveRun', tag: 'Live', role: 'publish',
+        summary: 'Start a live producer lease', description: 'Register a UUID run id and fixed producer identity before tests begin. Retrying the same identity and token is idempotent. The server timestamps receipt. Send heartbeats every 5 seconds and progress as tests execute. The default heartbeat timeout is 30 seconds; a 15-minute progress stall is configurable separately.',
+        parameters: [{ name: 'id', in: 'path', required: true, description: 'Producer-generated UUID, also given in the body.', schema: str }],
+        body: { description: 'Fixed invocation identity and optional planned test count.', contentType: 'application/json', required: true, schema: ref('LiveRunStart') },
+        responses: { '201': json('The registered lease.', 'LiveRun'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('The id already belongs to another invocation.'), '413': problem('Request too large.'), '422': problem('Invalid identity.'), '429': problem('Live run capacity reached.') }
+    },
+    {
+        route: 'PATCH /api/live/:id', path: '/api/live/{id}', operationId: 'updateLiveRun', tag: 'Live', role: 'publish',
+        summary: 'Publish progress or finish an invocation', description: 'Apply ordered check deltas, starting at sequence 1. Retry a sequence with identical content only. Completed results become immutable report layers immediately; running checks remain operational progress and do not replace historical winners. Finish as completed or interrupted. Stale updates cannot revive an expired lease; pending checks never become passes.',
+        parameters: [{ name: 'id', in: 'path', required: true, description: 'The UUID of a run started with this publisher token.', schema: str }],
+        body: { description: 'At most 1000 unique check updates; optional terminal state and reason.', contentType: 'application/json', required: true, schema: ref('LiveRunUpdate') },
+        responses: { '200': json('Updated progress.', 'LiveRun'), '401': UNAUTHORIZED, '403': FORBIDDEN, '404': problem('Unknown run.'), '409': problem('Run ended or sequence is stale.'), '413': problem('Request too large.'), '422': problem('Invalid progress.'), '429': problem('Run check capacity reached.') }
+    },
+    {
+        route: 'POST /api/live/:id/heartbeat', path: '/api/live/{id}/heartbeat', operationId: 'heartbeatLiveRun', tag: 'Live', role: 'publish',
+        summary: 'Renew a producer heartbeat', description: 'Renew a running lease using server receipt time, independently of test progress. No result layers are created. Heartbeats cannot revive terminal runs or bypass the configured progress-stall timeout. The producer token must be the one that started this invocation.',
+        parameters: [{ name: 'id', in: 'path', required: true, description: 'The UUID of this producer invocation.', schema: str }],
+        responses: { '200': { description: 'Heartbeat received.', contentType: 'application/json', schema: { type: 'object', properties: { ok: { const: true } } } }, '401': UNAUTHORIZED, '403': FORBIDDEN, '404': problem('Unknown run.'), '409': problem('Run ended or its lease expired.'), '422': problem('Invalid run id.') }
+    },
+    {
+        route: 'GET /admin', path: '/admin', operationId: 'getSettingsPage', tag: 'Operations', role: 'read',
+        summary: 'Server settings page', description: 'A standalone settings editor. Supply an admin Bearer token in the page to read or save configuration. The token is held only in memory.',
+        responses: { '200': { description: 'Settings editor.', contentType: 'text/html', schema: str }, '401': UNAUTHORIZED }
+    },
+    {
+        route: 'GET /api/settings', path: '/api/settings', operationId: 'getSettings', tag: 'Operations', role: 'admin',
+        summary: 'Read server settings', description: 'Returns editable persisted storage/report settings, active settings, a revision, and configuration precedence. Authentication settings are excluded. Requires an admin Bearer token. Embedded applications may manage settings outside this API.',
+        responses: { '200': json('Settings and revision.', 'ServerSettingsSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '503': problem('Configuration is managed by the embedding application.') }
+    },
+    {
+        route: 'PUT /api/settings', path: '/api/settings', operationId: 'saveSettings', tag: 'Operations', role: 'admin',
+        summary: 'Save settings for the next restart', description: 'Replaces editable storage/report settings, preserving authentication and other file fields. Atomically persists a validated configuration; no report data is moved. Environment variables and flags override these values after restart. Requires an admin Bearer token, same-origin requests in browsers, and a current revision.',
+        parameters: [{ name: 'If-Match', in: 'header', required: true, description: 'The quoted revision returned by GET /api/settings.', schema: str }],
+        body: { description: 'Editable fields from ServerConfig, excluding authentication, host, port and site. Maximum 64 KiB.', contentType: 'application/json', required: true, schema: ref('ServerEditableSettings') },
+        responses: { '200': json('Saved settings and new revision. Restart required.', 'ServerSettingsSnapshot'), '401': UNAUTHORIZED, '403': FORBIDDEN, '409': problem('Settings changed; reload before saving.'), '413': problem('Settings exceed the body limit.'), '422': problem('Invalid configuration.'), '428': problem('A quoted settings revision is required.'), '503': problem('Configuration is managed by the embedding application.') }
+    },
     {
         route: 'GET /healthz', path: '/healthz', operationId: 'getHealth', tag: 'Operations', role: 'none',
         summary: 'Is the process up',
@@ -84,13 +134,15 @@ export const OPERATIONS = [
         route: 'GET /api/events', path: '/api/events', operationId: 'streamEvents', tag: 'Live', role: 'read',
         summary: 'Server-sent events: results arrived, specs or runs changed',
         description: [
-            'A `text/event-stream` that stays open. Events say *that* something changed; the state is always fetched, so a client that missed events (a dropped connection) loses nothing: read again on reconnect.',
+            'A `text/event-stream` that stays open. Report events announce changes, and run events carry bounded live progress snapshots; authoritative state can always be fetched, so a client that missed events (a dropped connection) loses nothing: read again on reconnect.',
             '',
             '| event | data |',
             '| --- | --- |',
-            '| `hello` | `{ version, ready, time }`, sent first |',
+            '| `hello` | `{ version, ready, time, heartbeatMs? }`, sent first |',
             '| `report` | `{ version, totalLayers, added: [{ id, producer, environment, branch, sha, recordedAtMs, counts }], addedTotal }`: layers arrived |',
             '| `atlas:change` | `{ scope: "specs" \\| "runs", files, runIds }`: new specs or runs |',
+            '| `run` | A LiveRun snapshot after start, progress, heartbeat, completion, or interruption; contains no producer credentials |',
+            '| `projects` | `{}` when the node discovers another project; refresh `/api/projects` |',
             '| `ping` | `{}` every `heartbeatSeconds`, so a quiet server is told apart from a dead connection |',
             '',
             'Past `limits.maxStreams` viewers the answer is `503` with `Retry-After`: poll `/api/reports/evidence/effective` instead. A browser needs no code beyond `new EventSource("/api/events")`; other clients send the token as `Authorization: Bearer`.'
@@ -295,6 +347,18 @@ export const OPERATIONS = [
         responses: { '200': { description: 'The file.', contentType: 'application/octet-stream', schema: { type: 'string', format: 'binary' } }, '401': UNAUTHORIZED, '404': problem('No such run or file.') }
     }
 ];
+const NODE_OPERATIONS = new Set(['/api/projects', '/api/settings', '/api/server', '/api/openapi.json']);
+const PROJECT_PARAMETER = { name: 'project', in: 'query', description: 'Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.', schema: { type: 'string', pattern: '^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$', maxLength: 64 }, example: 'todo-app' };
+/** Every node operation and the same stable report protocol inside each project namespace. */
+export const OPERATIONS = BASE_OPERATIONS.flatMap(operation => {
+    if (!operation.path.startsWith('/api/') || NODE_OPERATIONS.has(operation.path))
+        return [operation];
+    return [{ ...operation, parameters: [...(operation.parameters ?? []), PROJECT_PARAMETER] }, {
+            ...operation, route: operation.route.replace('/api/', '/api/projects/:project/'), path: operation.path.replace('/api/', '/api/projects/{project}/'),
+            operationId: `${operation.operationId}ForProject`, parameters: [{ ...PROJECT_PARAMETER, in: 'path', required: true }, ...(operation.parameters ?? [])],
+            description: `${operation.description}\n\nScoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.`
+        }];
+});
 /**
  * Routes the server registers that are not operations of this API, each with the reason. The coverage test skips
  * these and only these.
@@ -341,7 +405,7 @@ export function openApiDocument(options = {}) {
             version: API_VERSION,
             summary: 'Take in test results from every environment, keep them, and show everyone the combined report, live.',
             description: [
-                'One Atlas server per project. Clients upload layers of results (`POST /api/checks`, or the store protocol under `/api/store`); viewers read the combined report (`/api/reports/evidence/effective`) and are told when it changes (`/api/events`). A report is layered, never partitioned: the newest completed result of every check wins its slot, whoever sent it.',
+                'One Atlas node serves multiple projects. Clients select a project using ?project=<slug>, X-Atlas-Project, or /api/projects/<slug>/… . Each project has independent specs, layers, recordings, status, and event streams. Within each project, the newest completed result of every check wins its slot. Unqualified requests address the legacy default project.',
                 '',
                 '**Authentication.** With tokens configured, send `Authorization: Bearer <token>`. Roles: `read` < `publish` < `admin`. Uploading needs a Bearer token; a browser\'s HTTP Basic sign-in (any user name, the token as the password) is accepted for reading only. A server with no tokens is open and listens on this machine only unless told otherwise.',
                 '',

package/dist/server/src/projects.d.ts

@@ -0,0 +1,3 @@
+import type { AtlasServer, AtlasServerOptions } from './app.js';
+/** Wrap the single-project protocol in project selection. Auth, upload validation and composition stay identical. */
+export declare function projectServer(options: AtlasServerOptions, create: (options: AtlasServerOptions) => AtlasServer): AtlasServer;