@rehearsal-labs/retest 0.1.0 → 0.2.0

package/dist/shared/png.js

@@ -0,0 +1,251 @@
+import { crc32, deflateSync, inflateSync } from 'node:zlib';
+/** Thrown for bytes that are not a PNG Retest reads. The message says what the bytes were. */
+export class PngError extends Error {
+    name = 'PngError';
+}
+/** The most bytes a decoded picture may take, filter bytes included, so a damaged file cannot ask for all memory. */
+export const maxPictureBytes = 512 * 1024 * 1024;
+const signature = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a);
+const readable = 'Retest reads 8-bit RGB and RGBA PNGs without interlacing, as browsers write them';
+// Bytes per pixel by colour type, for the two types Retest reads: RGB and RGBA.
+const channelsByType = { 2: 3, 6: 4 };
+const typeNames = { 0: 'greyscale', 3: 'a palette of colours', 4: 'greyscale with alpha' };
+/**
+ * Decodes a PNG into RGBA pixels: 8-bit RGB or RGBA, not interlaced, its rows filtered with any of the five filters.
+ * Every chunk's checksum is checked. RGB pixels get an alpha of 255. Throws `PngError` for anything else.
+ *
+ * @example readPng(bytes).width // 1280
+ */
+export function readPng(bytes) {
+    if (bytes.length < signature.length || signature.some((byte, index) => bytes[index] !== byte))
+        throw new PngError('The file is not a PNG: it does not start with the PNG signature.');
+    const chunks = readChunks(bytes);
+    const [header] = chunks;
+    if (header === undefined || header.type !== 'IHDR' || header.data.length !== 13)
+        throw new PngError('The PNG does not start with its header chunk.');
+    const view = new DataView(header.data.buffer, header.data.byteOffset, header.data.byteLength);
+    const width = view.getUint32(0);
+    const height = view.getUint32(4);
+    const [bitDepth, colourType, compression, filterMethod, interlace] = header.data.subarray(8);
+    if (width === 0 || height === 0)
+        throw new PngError(`The PNG is ${width} by ${height} pixels, and a picture needs at least one pixel each way.`);
+    if (bitDepth !== 8)
+        throw new PngError(`The PNG has ${String(bitDepth)}-bit channels. ${readable}.`);
+    const channels = channelsByType[colourType ?? -1];
+    if (channels === undefined)
+        throw new PngError(`The PNG holds ${typeNames[colourType ?? -1] ?? `colour type ${String(colourType)}`}. ${readable}.`);
+    if (interlace !== 0)
+        throw new PngError(`The PNG is interlaced. ${readable}.`);
+    if (compression !== 0 || filterMethod !== 0)
+        throw new PngError('The PNG names a compression or filter method the format does not define.');
+    const stride = width * channels;
+    const filtered = height * (stride + 1);
+    if (!Number.isSafeInteger(filtered) || filtered > maxPictureBytes || width * height * 4 > maxPictureBytes)
+        throw new PngError(`The PNG is ${width} by ${height} pixels, more than Retest decodes.`);
+    const text = {};
+    const compressed = [];
+    let ended = false;
+    for (const chunk of chunks.slice(1)) {
+        if (chunk.type === 'IEND') {
+            ended = true;
+            break;
+        }
+        if (chunk.type === 'IHDR')
+            throw new PngError('The PNG has a second header chunk.');
+        if (chunk.type === 'IDAT')
+            compressed.push(chunk.data);
+        else if (chunk.type === 'tEXt')
+            readText(chunk.data, text);
+        // A chunk whose type starts with a capital letter is critical: a reader that does not know it must not show the picture.
+        else if (chunk.type !== 'PLTE' && isCritical(chunk.type))
+            throw new PngError(`The PNG holds a ${chunk.type} chunk, which Retest does not know and must not skip.`);
+    }
+    if (!ended)
+        throw new PngError('The PNG ends before its end chunk, so it is cut short.');
+    if (compressed.length === 0)
+        throw new PngError('The PNG holds no image data.');
+    let raw;
+    try {
+        raw = inflateSync(Buffer.concat(compressed), { maxOutputLength: filtered });
+    }
+    catch {
+        throw new PngError(`The PNG's image data does not inflate to the ${width} by ${height} pixels its header states.`);
+    }
+    if (raw.length !== filtered)
+        throw new PngError(`The PNG's image data holds ${raw.length} bytes, and ${width} by ${height} pixels need ${filtered}.`);
+    return { width, height, data: toRgba(unfilter(raw, height, stride, channels), channels), text };
+}
+/**
+ * Encodes RGBA pixels as a PNG: RGB when every pixel is opaque, RGBA otherwise, each row with the filter that leaves the
+ * smallest sum, as libpng chooses, and any `tEXt` chunks the options name.
+ *
+ * @example writePng({ width: 1, height: 1, data: Uint8Array.of(255, 0, 0, 255) }, { text: { 'retest:scale': '2' } })
+ */
+export function writePng(image, options = {}) {
+    const { width, height, data } = image;
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1)
+        throw new RangeError(`A picture is at least 1 by 1 pixel, not ${width} by ${height}.`);
+    if (data.length !== width * height * 4)
+        throw new RangeError(`${width} by ${height} RGBA pixels take ${width * height * 4} bytes, not ${data.length}.`);
+    const opaque = isOpaque(data);
+    const channels = opaque ? 3 : 4;
+    const pixels = opaque ? toRgb(data) : data;
+    const header = new Uint8Array(13);
+    const view = new DataView(header.buffer);
+    view.setUint32(0, width);
+    view.setUint32(4, height);
+    header.set([8, opaque ? 2 : 6, 0, 0, 0], 8);
+    const texts = Object.entries(options.text ?? {}).map(([keyword, value]) => chunk('tEXt', textData(keyword, value)));
+    const compressed = deflateSync(filterRows(pixels, height, width * channels, channels));
+    return Buffer.concat([signature, chunk('IHDR', header), ...texts, chunk('IDAT', compressed), chunk('IEND', new Uint8Array(0))]);
+}
+function readChunks(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const chunks = [];
+    let offset = signature.length;
+    while (offset < bytes.length) {
+        if (offset + 12 > bytes.length)
+            throw new PngError('The PNG is cut short inside a chunk.');
+        const length = view.getUint32(offset);
+        const end = offset + 12 + length;
+        if (end > bytes.length)
+            throw new PngError('The PNG is cut short inside a chunk.');
+        const typeBytes = bytes.subarray(offset + 4, offset + 8);
+        const type = String.fromCharCode(...typeBytes);
+        if (!/^[A-Za-z]{4}$/.test(type))
+            throw new PngError('The PNG holds a chunk whose type is not four letters, so it is damaged.');
+        const data = bytes.subarray(offset + 8, offset + 8 + length);
+        const stated = view.getUint32(offset + 8 + length);
+        if (crc32(bytes.subarray(offset + 4, offset + 8 + length)) !== stated)
+            throw new PngError(`The PNG's ${type} chunk fails its checksum, so the file is damaged.`);
+        chunks.push({ type, data });
+        offset = end;
+        if (type === 'IEND')
+            break;
+    }
+    return chunks;
+}
+function isCritical(type) {
+    const first = type.charCodeAt(0);
+    return first >= 0x41 && first <= 0x5a;
+}
+function readText(data, text) {
+    const separator = data.indexOf(0);
+    if (separator < 1 || separator > 79)
+        return;
+    text[Buffer.from(data.subarray(0, separator)).toString('latin1')] = Buffer.from(data.subarray(separator + 1)).toString('latin1');
+}
+function textData(keyword, value) {
+    if (!/^[\x20-\x7e\xa1-\xff]{1,79}$/.test(keyword) || keyword !== keyword.trim())
+        throw new RangeError(`A PNG text keyword is 1 to 79 Latin-1 letters, not ${JSON.stringify(keyword)}.`);
+    if (!/^[\n\x20-\x7e\xa1-\xff]*$/.test(value))
+        throw new RangeError('A PNG text holds Latin-1 letters and line feeds only.');
+    return Buffer.concat([Buffer.from(keyword, 'latin1'), Uint8Array.of(0), Buffer.from(value, 'latin1')]);
+}
+function chunk(type, data) {
+    const head = new Uint8Array(8);
+    const view = new DataView(head.buffer);
+    view.setUint32(0, data.length);
+    head.set(Buffer.from(type, 'latin1'), 4);
+    const tail = new Uint8Array(4);
+    new DataView(tail.buffer).setUint32(0, crc32(Buffer.concat([head.subarray(4), data])));
+    return Buffer.concat([head, data, tail]);
+}
+// Each row is stored as a filter byte and the row's bytes, each the difference from a prediction made from the byte to
+// its left, the one above it and the one above and to the left. Undoing it adds the prediction back, row by row.
+function unfilter(raw, height, stride, channels) {
+    const out = new Uint8Array(height * stride);
+    for (let row = 0; row < height; row++) {
+        const filter = raw[row * (stride + 1)];
+        const source = row * (stride + 1) + 1;
+        const target = row * stride;
+        const above = target - stride;
+        if (filter === undefined || filter > 4)
+            throw new PngError(`The PNG's row ${row + 1} names filter ${String(filter)}, and the format has filters 0 to 4.`);
+        for (let column = 0; column < stride; column++) {
+            const left = column >= channels ? (out[target + column - channels] ?? 0) : 0;
+            const up = row > 0 ? (out[above + column] ?? 0) : 0;
+            const upLeft = row > 0 && column >= channels ? (out[above + column - channels] ?? 0) : 0;
+            out[target + column] = ((raw[source + column] ?? 0) + predict(filter, left, up, upLeft)) & 0xff;
+        }
+    }
+    return out;
+}
+function predict(filter, left, up, upLeft) {
+    switch (filter) {
+        case 1:
+            return left;
+        case 2:
+            return up;
+        case 3:
+            return (left + up) >> 1;
+        case 4:
+            return paeth(left, up, upLeft);
+        default:
+            return 0;
+    }
+}
+function paeth(left, up, upLeft) {
+    const estimate = left + up - upLeft;
+    const toLeft = Math.abs(estimate - left);
+    const toUp = Math.abs(estimate - up);
+    const toUpLeft = Math.abs(estimate - upLeft);
+    if (toLeft <= toUp && toLeft <= toUpLeft)
+        return left;
+    return toUp <= toUpLeft ? up : upLeft;
+}
+// Each row gets the filter whose output, read as signed bytes, has the smallest sum of magnitudes: the heuristic the
+// specification suggests, which keeps flat colour and gradients small for deflate.
+function filterRows(pixels, height, stride, channels) {
+    const out = new Uint8Array(height * (stride + 1));
+    const candidate = new Uint8Array(stride);
+    for (let row = 0; row < height; row++) {
+        const target = row * (stride + 1);
+        let best = Number.POSITIVE_INFINITY;
+        for (let filter = 0; filter <= 4; filter++) {
+            let sum = 0;
+            for (let column = 0; column < stride; column++) {
+                const at = row * stride + column;
+                const left = column >= channels ? (pixels[at - channels] ?? 0) : 0;
+                const up = row > 0 ? (pixels[at - stride] ?? 0) : 0;
+                const upLeft = row > 0 && column >= channels ? (pixels[at - stride - channels] ?? 0) : 0;
+                const value = ((pixels[at] ?? 0) - predict(filter, left, up, upLeft)) & 0xff;
+                candidate[column] = value;
+                sum += value < 128 ? value : 256 - value;
+            }
+            if (sum >= best)
+                continue;
+            best = sum;
+            out[target] = filter;
+            out.set(candidate, target + 1);
+        }
+    }
+    return out;
+}
+function isOpaque(data) {
+    for (let index = 3; index < data.length; index += 4)
+        if (data[index] !== 255)
+            return false;
+    return true;
+}
+function toRgb(data) {
+    const out = new Uint8Array((data.length / 4) * 3);
+    for (let from = 0, to = 0; from < data.length; from += 4, to += 3) {
+        out[to] = data[from] ?? 0;
+        out[to + 1] = data[from + 1] ?? 0;
+        out[to + 2] = data[from + 2] ?? 0;
+    }
+    return out;
+}
+function toRgba(pixels, channels) {
+    if (channels === 4)
+        return pixels;
+    const out = new Uint8Array((pixels.length / 3) * 4);
+    for (let from = 0, to = 0; from < pixels.length; from += 3, to += 4) {
+        out[to] = pixels[from] ?? 0;
+        out[to + 1] = pixels[from + 1] ?? 0;
+        out[to + 2] = pixels[from + 2] ?? 0;
+        out[to + 3] = 255;
+    }
+    return out;
+}

package/dist/shared/process-ownership.d.ts

@@ -39,6 +39,8 @@ export declare class OwnedProcessGroup {
     get initialProcessAbsent(): boolean;
     /** Failed metadata readings remain visible even when a later reading proves the launch ended. */
     get readProblems(): readonly string[];
+    /** Whether the launch has been read once, whatever the reading found or however it failed. */
+    get captured(): boolean;
     /** Records descendants only while their chain reaches an already verified process this owner launched. */
     capture(deadline?: Deadline): string[];
     /**
@@ -46,8 +48,9 @@ export declare class OwnedProcessGroup {
      * The reading is a moment old when it is applied, which only adds records with their start times; every signal still
      * reads its pid fresh. A reading that fails records nothing and is not kept as a read problem, since it decides
      * nothing and the next `capture` reads again. With a cleanup deadline, failures are retained. A newer applied
-     * snapshot wins over an outstanding background reading. Before the first `capture`, or on a system without
-     * `readAsync`, it is `capture` itself.
+     * snapshot wins over an outstanding background reading. It reads the host as it is when asked: a reading begun
+     * before, which cannot hold a process born since, is never taken, though later callers may share this one. Before
+     * the first `capture`, or on a system without `readAsync`, it is `capture` itself.
      */
     captureAsync(deadline?: Deadline): Promise<string[]>;
     /**
@@ -64,7 +67,10 @@ export declare class OwnedProcessGroup {
      * reuse inside it would also need the same start second and an unreadable or identical command.
      */
     signalReport(signal: NodeJS.Signals, deadline?: Deadline): ProcessSignalReport;
-    /** Ordinary cleanup uses asynchronous readings; each signal still immediately follows its own fresh identity. */
+    /**
+     * Ordinary cleanup uses asynchronous readings; each signal still immediately follows its own fresh identity. The
+     * table it records descendants from is begun after it was asked, so a helper born just before is recorded and ended.
+     */
     signalReportAsync(signal: NodeJS.Signals, deadline?: Deadline): Promise<ProcessSignalReport>;
     /** Keeps every failure and identity refusal visible to callers that do not reconcile a later full absence. */
     signal(signal: NodeJS.Signals, deadline?: Deadline): string[];
@@ -72,7 +78,12 @@ export declare class OwnedProcessGroup {
     signalNow(signal: NodeJS.Signals, deadline?: Deadline): string[];
     /** A failed liveness reading holds the resource. Once observed gone, this owner never names these pids again. */
     remains(deadline?: Deadline): boolean;
-    /** A failed or deadline-limited reading retains the resource, just as the synchronous exit-hook reading does. */
+    /**
+     * A failed or deadline-limited reading retains the resource, just as the synchronous exit-hook reading does. It may
+     * take a reading begun before it was asked: a group with no process left when the table was read has none left to
+     * start another. Callers asking at once share one reading, and once one of them sees the group gone the others stop
+     * reading.
+     */
     remainsAsync(deadline?: Deadline): Promise<boolean>;
 }
 /**

package/dist/shared/process-ownership.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-ownership.d.ts","sourceRoot":"","sources":["../../src/shared/process-ownership.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"process-ownership.d.ts","sourceRoot":"","sources":["../../src/shared/process-ownership.ts"],"names":[],"mappings":"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"}

package/dist/shared/process-ownership.js

@@ -24,7 +24,14 @@ export class OwnedProcessGroup {
     #initialProcessAbsent = false;
     // Keep one launch birth after pruning its pid, to distinguish a later group reusing that numeric id.
     #launchIdentity;
-    #revision = 0;
+    // Each reading, and each change made from a single process's own reading, takes the next number as it begins.
+    // `#newest` is the number of the newest one applied: a reading that began before it is stale.
+    #sequence = 0;
+    #newest = 0;
+    // Cleanup runs several waits on one group at once: its end, its output and the stop itself. Each starting a `ps` of
+    // its own, with each applied snapshot discarding the others' as stale, multiplied the readings on a loaded host until
+    // none was confirmed within the cleanup bound. They share the reading in flight instead.
+    #tableReading;
     constructor(pid, parentPid = process.pid, system = host) {
         if (!Number.isSafeInteger(pid) || pid < 2 || !Number.isSafeInteger(parentPid) || parentPid < 1)
             throw new TypeError('A launched process needs a valid pid and parent pid.');
@@ -40,6 +47,10 @@ export class OwnedProcessGroup {
     get readProblems() {
         return [...this.#readProblems];
     }
+    /** Whether the launch has been read once, whatever the reading found or however it failed. */
+    get captured() {
+        return this.#initialized;
+    }
     #failedRead(error) {
         const problem = `Could not read ownership of process ${this.#pid}: ${errorMessage(error)}`;
         this.#readProblems.add(problem);
@@ -59,36 +70,38 @@ export class OwnedProcessGroup {
             this.#initialized = true;
             return [this.#failedRead(error)];
         }
-        return this.#captureFrom(processes);
+        return this.#captureFrom(processes, this.#next());
     }
     /**
      * `capture` from a reading taken without holding the thread, for recording a new process while other work goes on.
      * The reading is a moment old when it is applied, which only adds records with their start times; every signal still
      * reads its pid fresh. A reading that fails records nothing and is not kept as a read problem, since it decides
      * nothing and the next `capture` reads again. With a cleanup deadline, failures are retained. A newer applied
-     * snapshot wins over an outstanding background reading. Before the first `capture`, or on a system without
-     * `readAsync`, it is `capture` itself.
+     * snapshot wins over an outstanding background reading. It reads the host as it is when asked: a reading begun
+     * before, which cannot hold a process born since, is never taken, though later callers may share this one. Before
+     * the first `capture`, or on a system without `readAsync`, it is `capture` itself.
      */
     async captureAsync(deadline) {
         if (this.#retired)
             return [];
-        const readAsync = this.#system.readAsync;
-        if (!this.#initialized || readAsync === undefined)
+        if (!this.#initialized || this.#system.readAsync === undefined)
             return this.capture(deadline);
-        const revision = this.#revision;
-        let processes;
+        const asked = this.#sequence;
+        let read;
         try {
             checkDeadline(deadline);
-            processes = await readAsync.call(this.#system, deadline);
+            read = await this.#sharedTable(deadline, asked);
             checkDeadline(deadline);
         }
         catch (error) {
             return deadline === undefined ? [] : [this.#failedRead(error)];
         }
-        return this.#retired || revision !== this.#revision ? [] : this.#captureFrom(processes);
+        if (this.#retired || !this.#fresh(read.reading))
+            return [];
+        return this.#captureFrom(read.processes, read.reading.sequence);
     }
-    #captureFrom(processes) {
-        this.#revision += 1;
+    #captureFrom(processes, sequence) {
+        this.#newest = Math.max(this.#newest, sequence);
         const initial = !this.#initialized;
         this.#initialized = true;
         const root = processes.find((entry) => entry.pid === this.#pid);
@@ -153,7 +166,7 @@ export class OwnedProcessGroup {
             if (current === undefined || !running(current)) {
                 this.#records.delete(pid);
                 this.#unowned.delete(pid);
-                this.#revision += 1;
+                this.#newest = this.#next();
                 return undefined;
             }
             if (!this.#sameRecorded(record, current))
@@ -214,7 +227,7 @@ export class OwnedProcessGroup {
             this.#initialized = true;
             return { problems: [this.#failedRead(error)], identityRefusals: [] };
         }
-        const problems = this.#captureFrom(processes);
+        const problems = this.#captureFrom(processes, this.#next());
         const identityRefusals = [];
         for (const record of [...this.#records.values()].reverse()) {
             let current;
@@ -232,23 +245,27 @@ export class OwnedProcessGroup {
         }
         return { problems, identityRefusals };
     }
-    /** Ordinary cleanup uses asynchronous readings; each signal still immediately follows its own fresh identity. */
+    /**
+     * Ordinary cleanup uses asynchronous readings; each signal still immediately follows its own fresh identity. The
+     * table it records descendants from is begun after it was asked, so a helper born just before is recorded and ended.
+     */
     async signalReportAsync(signal, deadline) {
         if (this.#retired)
             return { problems: [], identityRefusals: [] };
-        let processes;
+        const asked = this.#sequence;
+        let read;
         try {
             checkDeadline(deadline);
-            processes = await this.#readFreshTableAsync(deadline);
+            read = await this.#readFreshTableAsync(deadline, asked);
             checkDeadline(deadline);
         }
         catch (error) {
             this.#initialized = true;
             return { problems: [this.#failedRead(error)], identityRefusals: [] };
         }
-        if (this.#retired)
+        if (this.#retired || read === undefined)
             return { problems: [], identityRefusals: [] };
-        const problems = this.#captureFrom(processes);
+        const problems = this.#captureFrom(read.processes, read.reading.sequence);
         const identityRefusals = [];
         for (const record of [...this.#records.values()].reverse()) {
             let current;
@@ -275,7 +292,7 @@ export class OwnedProcessGroup {
         if (current === undefined || !running(current)) {
             this.#records.delete(record.pid);
             this.#unowned.delete(record.pid);
-            this.#revision += 1;
+            this.#newest = this.#next();
             return;
         }
         if (!this.#sameRecorded(record, current)) {
@@ -320,17 +337,58 @@ export class OwnedProcessGroup {
             return this.#system.readProcess(pid, deadline);
         return this.#system.read(deadline).find((entry) => entry.pid === pid);
     }
-    #readTableAsync(deadline) {
-        return this.#system.readAsync === undefined ? Promise.resolve(this.#system.read(deadline)) : this.#system.readAsync(deadline);
+    async #readTableAsync(deadline) {
+        return this.#system.readAsync === undefined ? this.#system.read(deadline) : this.#system.readAsync(deadline);
     }
-    async #readFreshTableAsync(deadline) {
+    #next() {
+        this.#sequence += 1;
+        return this.#sequence;
+    }
+    // The reading running now while nothing newer was applied since it began, which a caller waits for rather than start
+    // another `ps`; otherwise a new one under this caller's deadline. A caller that gives `asked`, the number current when
+    // it asked, takes only a reading begun after it.
+    #tableReadingFor(deadline, asked) {
+        const running = this.#tableReading;
+        if (running !== undefined && this.#fresh(running) && (asked === undefined || running.sequence > asked))
+            return running;
+        const reading = { processes: this.#readTableAsync(deadline), deadline, sequence: this.#next() };
+        this.#tableReading = reading;
+        const finished = () => { if (this.#tableReading === reading)
+            this.#tableReading = undefined; };
+        reading.processes.then(finished, finished);
+        return reading;
+    }
+    // One completed table reading. A caller waits for a reading another caller started only within its own deadline. When
+    // that reading fails, as one the other caller's shorter deadline ended does, it moves to a fresh one within its own.
+    async #sharedTable(deadline, asked) {
         for (;;) {
             checkDeadline(deadline);
-            const revision = this.#revision;
-            const processes = await this.#readTableAsync(deadline);
+            const reading = this.#tableReadingFor(deadline, asked);
+            if (reading.deadline === deadline)
+                return { processes: await reading.processes, reading };
+            try {
+                return { processes: await withinDeadline(reading.processes, deadline), reading };
+            }
+            catch {
+                checkDeadline(deadline);
+            }
+        }
+    }
+    // A snapshot may be applied while nothing newer was. Its own callers apply it after one another, which ages nothing.
+    #fresh(reading) {
+        return reading.sequence >= this.#newest;
+    }
+    // Undefined once the group has been shown gone, which no later reading can change.
+    async #readFreshTableAsync(deadline, asked) {
+        for (;;) {
+            if (this.#retired)
+                return undefined;
+            const read = await this.#sharedTable(deadline, asked);
             checkDeadline(deadline);
-            if (revision === this.#revision)
-                return processes;
+            if (this.#retired)
+                return undefined;
+            if (this.#fresh(read.reading))
+                return read;
         }
     }
     /** Keeps every failure and identity refusal visible to callers that do not reconcile a later full absence. */
@@ -356,26 +414,33 @@ export class OwnedProcessGroup {
             this.#failedRead(error);
             return true;
         }
-        return this.#remainsFrom(processes);
+        return this.#remainsFrom(processes, this.#next());
     }
-    /** A failed or deadline-limited reading retains the resource, just as the synchronous exit-hook reading does. */
+    /**
+     * A failed or deadline-limited reading retains the resource, just as the synchronous exit-hook reading does. It may
+     * take a reading begun before it was asked: a group with no process left when the table was read has none left to
+     * start another. Callers asking at once share one reading, and once one of them sees the group gone the others stop
+     * reading.
+     */
     async remainsAsync(deadline) {
         if (this.#retired)
             return false;
-        let processes;
+        let read;
         try {
             checkDeadline(deadline);
-            processes = await this.#readFreshTableAsync(deadline);
+            read = await this.#readFreshTableAsync(deadline);
             checkDeadline(deadline);
         }
         catch (error) {
             this.#failedRead(error);
             return true;
         }
-        return this.#retired ? false : this.#remainsFrom(processes);
+        if (this.#retired || read === undefined)
+            return false;
+        return this.#remainsFrom(read.processes, read.reading.sequence);
     }
-    #remainsFrom(processes) {
-        this.#revision += 1;
+    #remainsFrom(processes, sequence) {
+        this.#newest = Math.max(this.#newest, sequence);
         // A failed first reading never grants signal authority, and an empty ledger is no proof that the launched
         // child ended. Until its pid and group are absent, that unresolved launch continues to hold its resource.
         if (this.#launchIdentity === undefined && processes.some((entry) => running(entry) && (entry.pid === this.#pid || entry.groupId === this.#pid)))
@@ -501,6 +566,30 @@ function checkDeadline(deadline) {
     if (deadline?.signal?.aborted === true || deadline?.reached === true)
         throw new Error('The ownership reading was not confirmed before its deadline ended or was cancelled.');
 }
+// Waits for a reading another caller started until this caller's deadline ends or is cancelled, and leaves the reading
+// running for whoever else waits on it. Its timer holds no process open; the reading itself does while it runs.
+function withinDeadline(work, deadline) {
+    if (deadline === undefined)
+        return work;
+    const { signal } = deadline;
+    if (signal?.aborted === true)
+        return Promise.reject(new Error('The ownership reading was not confirmed before its deadline ended or was cancelled.'));
+    return new Promise((resolve, reject) => {
+        let timer;
+        const settle = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', ended);
+        };
+        function ended() {
+            settle();
+            reject(new Error('The ownership reading was not confirmed before its deadline ended or was cancelled.'));
+        }
+        timer = setTimeout(ended, deadline.waitToEndMs);
+        timer.unref();
+        signal?.addEventListener('abort', ended, { once: true });
+        work.then((value) => { settle(); resolve(value); }, (error) => { settle(); reject(error); });
+    });
+}
 function parseProcessTable(text) {
     const records = [];
     for (const line of text.split('\n')) {

package/dist/store/artifacts.d.ts

@@ -48,6 +48,10 @@ export type ArtifactSpec = {
 } | {
     readonly kind: 'diagnostics';
     readonly identity: RecordIdentity;
+} | {
+    readonly kind: 'download';
+    readonly identity: RecordIdentity;
+    readonly name: string;
 } | {
     readonly kind: 'report';
 };
@@ -65,6 +69,21 @@ export declare const partialSuffix = ".partial";
  * @example artifactPath({ kind: 'screenshot', identity, purpose: 'failure', sequence: 1, format: 'png' }) // 'artifacts/k3v9q0x2mb/web-<hash>/screenshot-failure-1.png'
  */
 export declare function artifactPath(spec: ArtifactSpec): string;
+/**
+ * The folder a session's downloads are saved in, relative to the run folder: the browser writes each one there by its
+ * own id, and Retest renames it to the name `downloadFileName` makes of the name the page suggested.
+ *
+ * @example downloadsFolder(identity) // 'artifacts/k3v9q0x2mb/web-<hash>/downloads'
+ */
+export declare function downloadsFolder(identity: RecordIdentity): string;
+/**
+ * A name a reference may hold, made of the name a page suggested for a download: every run of other characters than
+ * letters, digits, `.`, `_` and `-` becomes one `-`, a leading `.` or `-` goes, and a long name keeps its end, where
+ * its extension is. A name with nothing left is `download`.
+ *
+ * @example downloadFileName('Tasks (May).csv') // 'Tasks-May-.csv'
+ */
+export declare function downloadFileName(suggested: string): string;
 /**
  * The path the media process is given as a recording's `output`, relative to the run folder: the recording's path
  * without its extension, which the process adds once it knows the container. Join it to the run folder with
@@ -229,7 +248,8 @@ export declare function readArtifactFile(runFolder: string, reference: string, l
  */
 export type ArtifactReference = {
     readonly path: string;
-    readonly kind: ArtifactKind;
+    /** What the file is; `download` is a file a page downloaded, which retention never removes. */
+    readonly kind: ArtifactKind | 'download';
     readonly namedBy: string;
     readonly testId?: string;
     readonly attemptId?: string;
@@ -242,7 +262,8 @@ export type ArtifactReference = {
 export declare function recordingArtifactReferences(recording: RecordingRecord, namedBy: string): ArtifactReference[];
 /**
  * The artifacts the events of a run name: failure screenshots (`evidence.captured`), diagnostics artifacts
- * (`diagnostics.finished`) and the screenshots AI checks sent their judges (`evaluation.finished`). Event types this
+ * (`diagnostics.finished`), the screenshots AI checks sent their judges (`evaluation.finished`) and the pictures a failed
+ * screenshot comparison left (`assertion.failed` with `attachments`). Event types this
  * reader does not know name nothing here, so an event type added later must be added to this function. Recordings name
  * videos and partial files; retention removes references unless a later removal failure preserves the file.
  *