mixdog 0.7.1

package/scripts/stress-atomic-write.mjs

@@ -0,0 +1,1028 @@
+// Cross-process stress harness for atomic-write + advisory-lock.
+// Usage:
+//   node scripts/stress-atomic-write.mjs              # run all scenarios
+//   node scripts/stress-atomic-write.mjs s1 s4        # run subset
+// Internal:
+//   node scripts/stress-atomic-write.mjs --worker <mode> <target> <content> <timeoutMs>
+import {
+    mkdtempSync, writeFileSync, readFileSync, existsSync,
+    rmSync, readdirSync, statSync, appendFileSync,
+} from 'fs';
+import { tmpdir } from 'os';
+import { join, dirname, basename } from 'path';
+import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
+import { performance } from 'perf_hooks';
+import { createHash } from 'crypto';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const repoRoot = dirname(__dirname);
+
+const atomicModUrl = 'file://' + join(repoRoot, 'src/agent/orchestrator/tools/builtin/atomic-write.mjs').replace(/\\/g, '/');
+const lockModUrl = 'file://' + join(repoRoot, 'src/agent/orchestrator/tools/builtin/advisory-lock.mjs').replace(/\\/g, '/');
+
+function lockFileFor(targetPath) {
+    return join(dirname(targetPath), '.' + basename(targetPath) + '.mixdog-lock');
+}
+
+function listLeftovers(dir) {
+    try {
+        return readdirSync(dir).filter((n) =>
+            n.endsWith('.mixdog-lock') || n.includes('.mixdog-tmp-')
+        );
+    } catch { return []; }
+}
+
+function snapshot(p) {
+    try {
+        const s = statSync(p);
+        return { exists: true, size: s.size, mtimeMs: s.mtimeMs, ino: s.ino };
+    } catch { return { exists: false }; }
+}
+
+// ============================================================
+// Worker mode (child process = one operation)
+// ============================================================
+if (process.argv[2] === '--worker') {
+    const mode = process.argv[3];
+    const target = process.argv[4];
+    const content = process.argv[5];
+    const timeoutMs = Number(process.argv[6] || 5000);
+
+    const { atomicWrite } = await import(atomicModUrl);
+    const { acquireAdvisoryLock } = await import(lockModUrl);
+
+    function resolveContent(c) {
+        if (typeof c === 'string' && c.startsWith('@file:')) {
+            return readFileSync(c.slice('@file:'.length), 'utf8');
+        }
+        return c;
+    }
+
+    const wantHistory = process.env.STRESS_HISTORY === '1';
+    function appendHistory(targetPath, payload) {
+        // Lock-protected — caller holds the advisory lock for targetPath.
+        const histFile = targetPath + '.history';
+        const tag = payload.length > 60 ? payload.slice(0, 30) + '...' + payload.length : payload;
+        appendFileSync(histFile, process.pid + '|' + tag + '\n');
+    }
+
+    const t0 = performance.now();
+    try {
+        if (mode === 'single') {
+            const handle = await acquireAdvisoryLock(target, { timeoutMs });
+            try {
+                const resolved = resolveContent(content);
+                await atomicWrite(target, resolved, { expectedTargetSnapshot: snapshot(target) });
+                if (wantHistory) appendHistory(target, resolved);
+            } finally { handle.release(); }
+            const dt = +(performance.now() - t0).toFixed(2);
+            process.stdout.write(JSON.stringify({ ok: true, mode, dt, pid: process.pid }) + '\n');
+        } else if (mode === 'batch') {
+            const targets = target.split('|');
+            // Replicate withAdvisoryLocks ordering: sort + dedupe lower-case on win32
+            const seen = new Set();
+            const ordered = [];
+            for (const p of targets) {
+                const k = process.platform === 'win32' ? p.toLowerCase() : p;
+                if (seen.has(k)) continue;
+                seen.add(k); ordered.push(p);
+            }
+            ordered.sort();
+            const handles = [];
+            try {
+                for (const p of ordered) handles.push(await acquireAdvisoryLock(p, { timeoutMs }));
+                for (const p of targets) {
+                    const payload = content + ':' + basename(p) + '|END';
+                    await atomicWrite(p, payload, { expectedTargetSnapshot: snapshot(p) });
+                    if (wantHistory) appendHistory(p, payload);
+                }
+            } finally {
+                for (let i = handles.length - 1; i >= 0; i -= 1) {
+                    try { handles[i].release(); } catch { /* best-effort */ }
+                }
+            }
+            const dt = +(performance.now() - t0).toFixed(2);
+            process.stdout.write(JSON.stringify({ ok: true, mode, dt, pid: process.pid }) + '\n');
+        } else if (mode === 'read') {
+            // Deadline loop with 5ms sleep — tight setImmediate spin starves
+            // the Windows rename retry-loop (reader keeps an open handle,
+            // writer gets EBUSY/EACCES and never lands until reader exits).
+            // Strict integrity checks:
+            //   - tail must be `|END`
+            //   - zero-length file = torn (e.g., visible during rename split)
+            //   - if EXPECTED_SIZE set: buf.length must equal it
+            //   - if EXPECTED_PREFIX set: head bytes must equal it
+            const deadlineMs = Number(content) > 0 ? Number(content) : 800;
+            const deadline = Date.now() + deadlineMs;
+            const expectedSize = process.env.EXPECTED_SIZE ? Number(process.env.EXPECTED_SIZE) : null;
+            const expectedPrefix = process.env.EXPECTED_PREFIX || null;
+            const expectedHash = process.env.EXPECTED_HASH || null;
+            const sizes = new Set();
+            let reads = 0;
+            const reportTorn = (reason, len, detail) => {
+                process.stdout.write(JSON.stringify({
+                    ok: false, mode, torn: true, reason, len, detail, pid: process.pid,
+                }) + '\n');
+                process.exit(2);
+            };
+            while (Date.now() < deadline) {
+                try {
+                    const buf = readFileSync(target);
+                    sizes.add(buf.length);
+                    if (buf.length === 0) reportTorn('zero-length', 0, '');
+                    const tail = buf.subarray(Math.max(0, buf.length - 4)).toString();
+                    if (tail !== '|END') reportTorn('tail', buf.length, tail);
+                    if (expectedSize !== null && buf.length !== expectedSize) {
+                        reportTorn('size', buf.length, `expected=${expectedSize}`);
+                    }
+                    if (expectedPrefix !== null) {
+                        const head = buf.subarray(0, expectedPrefix.length).toString();
+                        if (head !== expectedPrefix) reportTorn('prefix', buf.length, head);
+                    }
+                    if (expectedHash !== null) {
+                        // Mid-body byte-flip detection: anything between prefix
+                        // and tail can still slip past size+prefix+tail checks.
+                        const h = createHash('sha256').update(buf).digest('hex');
+                        if (h !== expectedHash) reportTorn('hash', buf.length, h.slice(0, 16));
+                    }
+                } catch (err) {
+                    if (err.code !== 'ENOENT') throw err;
+                }
+                reads += 1;
+                await new Promise(r => setTimeout(r, 5));
+            }
+            const dt = +(performance.now() - t0).toFixed(2);
+            process.stdout.write(JSON.stringify({
+                ok: true, mode, dt, reads, distinctSizes: sizes.size, pid: process.pid,
+            }) + '\n');
+        } else if (mode === 'sleep-hold') {
+            const holdMs = Number(content);
+            const handle = await acquireAdvisoryLock(target, { timeoutMs: 1000 });
+            try {
+                process.stdout.write(JSON.stringify({
+                    ok: true, mode, event: 'acquired', pid: process.pid,
+                }) + '\n');
+                await new Promise(r => setTimeout(r, holdMs));
+                await atomicWrite(target, 'SLOW-WRITER|END', {
+                    expectedTargetSnapshot: snapshot(target),
+                });
+            } finally { handle.release(); }
+            const dt = +(performance.now() - t0).toFixed(2);
+            process.stdout.write(JSON.stringify({
+                ok: true, mode, event: 'released', dt, pid: process.pid,
+            }) + '\n');
+        } else if (mode === 'lock-prove') {
+            // One-shot: acquire lock, hold for holdMs, release. Emits exact
+            // acquireTs/lockedAt/releasedAt timestamps so the driver can prove
+            // intervals are disjoint across concurrent workers (real lock
+            // serialisation) or overlap (broken/no-op lock).
+            const holdMs = Number(content) > 0 ? Number(content) : 100;
+            const acquireTs = Date.now();
+            const handle = await acquireAdvisoryLock(target, { timeoutMs });
+            const lockedAt = Date.now();
+            try {
+                await new Promise(r => setTimeout(r, holdMs));
+            } finally {
+                handle.release();
+            }
+            const releasedAt = Date.now();
+            const dt = +(performance.now() - t0).toFixed(2);
+            process.stdout.write(JSON.stringify({
+                ok: true, mode, dt, holdMs, acquireTs, lockedAt, releasedAt, pid: process.pid,
+            }) + '\n');
+        } else if (mode === 'locked-read') {
+            // Acquire advisory lock, do MULTIPLE reads under one lock, release;
+            // repeat. If the lock actually serialises writers, every read in
+            // one lock-held window must see the same byte length. If a writer
+            // slips past the lock, sizesInHold.size > 1 → lockInconsistencies.
+            const deadlineMs = Number(content) > 0 ? Number(content) : 500;
+            const deadline = Date.now() + deadlineMs;
+            const READS_PER_HOLD = 5;
+            const expectedSize = process.env.EXPECTED_SIZE ? Number(process.env.EXPECTED_SIZE) : null;
+            const expectedPrefix = process.env.EXPECTED_PREFIX || null;
+            const expectedHash = process.env.EXPECTED_HASH || null;
+            const sizes = new Set();
+            let reads = 0;
+            let lockInconsistencies = 0;
+            const reportTorn = (reason, len, detail) => {
+                process.stdout.write(JSON.stringify({
+                    ok: false, mode, torn: true, reason, len, detail, pid: process.pid,
+                }) + '\n');
+                process.exit(2);
+            };
+            while (Date.now() < deadline) {
+                const handle = await acquireAdvisoryLock(target, { timeoutMs });
+                try {
+                    const sizesInHold = new Set();
+                    for (let k = 0; k < READS_PER_HOLD; k += 1) {
+                        const buf = readFileSync(target);
+                        sizesInHold.add(buf.length);
+                        if (buf.length === 0) reportTorn('zero-length', 0, '');
+                        const tail = buf.subarray(Math.max(0, buf.length - 4)).toString();
+                        if (tail !== '|END') reportTorn('tail', buf.length, tail);
+                        if (expectedSize !== null && buf.length !== expectedSize) {
+                            reportTorn('size', buf.length, `expected=${expectedSize}`);
+                        }
+                        if (expectedPrefix !== null) {
+                            const head = buf.subarray(0, expectedPrefix.length).toString();
+                            if (head !== expectedPrefix) reportTorn('prefix', buf.length, head);
+                        }
+                        if (expectedHash !== null) {
+                            const h = createHash('sha256').update(buf).digest('hex');
+                            if (h !== expectedHash) reportTorn('hash', buf.length, h.slice(0, 16));
+                        }
+                        // Yield so a broken lock has a chance to lose the race.
+                        await new Promise(r => setImmediate(r));
+                    }
+                    if (sizesInHold.size > 1) lockInconsistencies += 1;
+                    // Track first observed size from this hold-window.
+                    sizes.add([...sizesInHold][0]);
+                } finally { handle.release(); }
+                reads += 1;
+                await new Promise(r => setTimeout(r, 5));
+            }
+            const dt = +(performance.now() - t0).toFixed(2);
+            process.stdout.write(JSON.stringify({
+                ok: true, mode, dt, reads, distinctSizes: sizes.size,
+                lockInconsistencies, pid: process.pid,
+            }) + '\n');
+        } else {
+            throw new Error('unknown worker mode: ' + mode);
+        }
+        process.exit(0);
+    } catch (err) {
+        const dt = +(performance.now() - t0).toFixed(2);
+        process.stdout.write(JSON.stringify({
+            ok: false, mode, code: err.code, msg: String(err.message).slice(0, 200), dt, pid: process.pid,
+        }) + '\n');
+        process.exit(1);
+    }
+}
+
+// ============================================================
+// Driver
+// ============================================================
+function spawnWorker(mode, target, content, timeoutMs = 5000, extraEnv = {}) {
+    // LIVE multi-instance load can make 15-30s lock timeouts insufficient
+    // (800+ child processes contending). Boost only "lock-contention" timeouts
+    // (>1s); s6-style short adversarial timeouts (<=1s) stay as-is.
+    const effectiveTimeoutMs = LIVE && timeoutMs > 1000
+        ? Math.max(timeoutMs, 60000)
+        : timeoutMs;
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [
+            __filename, '--worker', mode, target, String(content), String(effectiveTimeoutMs),
+        ], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, ...extraEnv },
+        });
+        let out = '';
+        let err = '';
+        child.stdout.on('data', (d) => { out += d; });
+        child.stderr.on('data', (d) => { err += d; });
+        child.on('close', (exitCode) => {
+            const lines = out.trim().split('\n').filter(Boolean);
+            try {
+                const last = JSON.parse(lines[lines.length - 1]);
+                resolve({ ...last, exitCode, stderr: err.slice(0, 200) });
+            } catch {
+                resolve({ ok: false, exitCode, raw: out.slice(-200), stderr: err.slice(0, 200) });
+            }
+        });
+    });
+}
+
+// Strict success: both JSON ok flag AND exitCode 0.
+function isOk(r) { return r && r.ok === true && r.exitCode === 0; }
+
+// STRESS_LIVE=1 relaxes timing-sensitive invariants (maxDistinct overlap,
+// EAGAIN counter, sustained ops tolerance) that are reliable on a quiet box
+// but flake under heavy multi-instance / parallel-process load. Correctness
+// invariants (torn=no, finalOk, ok counts, lock proof) stay strict in both.
+const LIVE = process.env.STRESS_LIVE === '1';
+
+const results = [];
+function record(name, ok, detail = {}) {
+    const tag = ok ? 'PASS' : 'FAIL';
+    const det = Object.entries(detail).map(([k, v]) => `${k}=${typeof v === 'object' ? JSON.stringify(v) : v}`).join(' ');
+    console.log(`[${tag}] ${name}${det ? '  ' + det : ''}`);
+    // Detail keys must not shadow the invariant `ok` flag — every scenario's
+    // detail object happens to include a value-typed `ok` field (counts like
+    // "32/32" or numbers like 0) which previously overwrote the boolean ok
+    // via spread ordering, silently flipping PASS→fail in the summary.
+    results.push({ ...detail, name, ok });
+    if (!ok) process.exitCode = 1;
+}
+
+function tempDir(label) {
+    return mkdtempSync(join(tmpdir(), 'stress-atomic-' + label + '-'));
+}
+
+// Pre-stage a pool of fixture files with mixed sizes (small/mid/big/huge).
+// Each file has a sentinel-terminated payload so torn-read detection works.
+function buildFixturePool(dir, count = 8) {
+    const sizes = [1024, 32 * 1024, 256 * 1024, 1572864]; // 1KB, 32KB, 256KB, 1.5MB
+    const pool = [];
+    for (let i = 0; i < count; i += 1) {
+        const sz = sizes[i % sizes.length];
+        const prefix = 'POOL-' + i + '-';
+        const tail = '|END';
+        const fillerLen = Math.max(0, sz - prefix.length - tail.length);
+        const content = prefix + 'x'.repeat(fillerLen) + tail;
+        const p = join(dir, 'pool-' + i + '.dat');
+        writeFileSync(p, content);
+        const hash = createHash('sha256').update(content).digest('hex');
+        pool.push({ path: p, size: content.length, index: i, prefix, hash });
+    }
+    return pool;
+}
+
+// ============================================================
+// S1: 32 concurrent writers, single file
+// ============================================================
+async function s1() {
+    const N = 32;
+    const dir = tempDir('s1');
+    try {
+        const target = join(dir, 'target.txt');
+        writeFileSync(target, 'INITIAL|END');
+
+        const t0 = performance.now();
+        const tasks = [];
+        for (let i = 0; i < N; i += 1) {
+            tasks.push(spawnWorker('single', target, `W${i}|END`, 15000, { STRESS_HISTORY: '1' }));
+        }
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+
+        const okCount = out.filter(isOk).length;
+        const final = readFileSync(target, 'utf8');
+        const isValid = /^W\d+\|END$/.test(final);
+        const leftovers = listLeftovers(dir);
+
+        // History invariant: each ok worker appended exactly one line under the
+        // same advisory lock that protected its atomicWrite, so the file must
+        // have N entries and the last entry's payload must equal final.
+        let histLines = [];
+        let lastPayload = null;
+        try {
+            histLines = readFileSync(target + '.history', 'utf8').trim().split('\n').filter(Boolean);
+            const last = histLines[histLines.length - 1];
+            lastPayload = last.slice(last.indexOf('|') + 1);
+        } catch { /* missing history => fail below */ }
+        const histOk = histLines.length === N && lastPayload === final;
+
+        // LIVE: heavy load can timeout a worker → ok=N-1, history=N-1,
+        // and final = last ok worker (lastMatch typically still holds, but
+        // an appendHistory failure after a successful atomicWrite is also
+        // tolerated). Strict mode keeps full N + lastMatch invariants.
+        const okStrict = LIVE ? okCount >= N - 1 : okCount === N;
+        const histStrict = LIVE
+            ? histLines.length >= N - 1
+            : histLines.length === N && lastPayload === final;
+        record('s1: 32 concurrent writers — history-strict',
+            okStrict && isValid && leftovers.length === 0 && histStrict, {
+            ok: `${okCount}/${N}`, wallMs, final: final.slice(0, 20),
+            histLines: histLines.length, lastMatch: histOk, leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// S13: lock serialization proved by interval disjointness.
+// N workers each acquire→hold→release once. Real advisory lock must
+// produce disjoint [lockedAt, releasedAt] intervals across workers. A
+// broken/no-op lock lets all workers hold concurrently → intervals
+// overlap and total elapsed << N × holdMs.
+async function s13() {
+    const dir = tempDir('s13');
+    try {
+        const target = join(dir, 'lock-prove.txt');
+        writeFileSync(target, 'INITIAL|END');
+        const N = 4;
+        const HOLD = 100;
+        const tasks = [];
+        for (let i = 0; i < N; i += 1) {
+            tasks.push(spawnWorker('lock-prove', target, String(HOLD), 10000));
+        }
+        const t0 = performance.now();
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+        const okCount = out.filter(isOk).length;
+
+        const intervals = out.filter(isOk)
+            .map(x => ({ start: x.lockedAt, end: x.releasedAt, pid: x.pid }))
+            .sort((a, b) => a.start - b.start);
+        // No two locked intervals may overlap.
+        let noOverlap = true;
+        for (let i = 1; i < intervals.length; i += 1) {
+            if (intervals[i].start < intervals[i - 1].end) { noOverlap = false; break; }
+        }
+        // Diagnostic dump for race investigation when overlap is detected.
+        if (!noOverlap) {
+            console.log('[s13 diag] overlap intervals (sorted by start):');
+            intervals.forEach((x, idx) => {
+                console.log('  #' + idx + ' pid=' + x.pid + ' start=' + x.start
+                    + ' end=' + x.end + ' dur=' + (x.end - x.start) + 'ms');
+            });
+            // Find the offending pair.
+            for (let i = 1; i < intervals.length; i += 1) {
+                if (intervals[i].start < intervals[i - 1].end) {
+                    const overlapMs = intervals[i - 1].end - intervals[i].start;
+                    console.log('  OVERLAP #' + (i - 1) + '↔#' + i + ' by ' + overlapMs + 'ms');
+                }
+            }
+        }
+        // Serialization sanity: total span >= 90% of N × HOLD.
+        const totalMs = intervals.length > 0
+            ? intervals[intervals.length - 1].end - intervals[0].start
+            : 0;
+        const serializedTime = totalMs >= N * HOLD * 0.9;
+        const leftovers = listLeftovers(dir);
+
+        const okStrict13 = LIVE ? okCount >= N - 1 : okCount === N;
+        record('s13: lock serialization (interval disjointness)',
+            okStrict13 && noOverlap && serializedTime && leftovers.length === 0, {
+            workers: `${okCount}/${N}`, wallMs, noOverlap,
+            totalMs, minExpected: N * HOLD * 0.9, leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// ============================================================
+// S2: multi-file batch race (shuffled orderings, deadlock check)
+// ============================================================
+async function s2() {
+    const N = 16;
+    const FILES = 4;
+    const dir = tempDir('s2');
+    try {
+        const targets = [];
+        for (let i = 0; i < FILES; i += 1) {
+            const p = join(dir, 'tgt' + i + '.txt');
+            writeFileSync(p, 'INIT:tgt' + i + '.txt|END');
+            targets.push(p);
+        }
+        function shuffle(arr, seed) {
+            const a = arr.slice();
+            let s = seed >>> 0;
+            for (let i = a.length - 1; i > 0; i -= 1) {
+                s = (s * 1664525 + 1013904223) >>> 0;
+                const j = s % (i + 1);
+                [a[i], a[j]] = [a[j], a[i]];
+            }
+            return a;
+        }
+
+        const t0 = performance.now();
+        const tasks = [];
+        for (let i = 0; i < N; i += 1) {
+            const order = shuffle(targets, i + 1);
+            tasks.push(spawnWorker('batch', order.join('|'), `W${i}`, 30000, { STRESS_HISTORY: '1' }));
+        }
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+
+        const okCount = out.filter(isOk).length;
+        let allValid = true;
+        for (const p of targets) {
+            const c = readFileSync(p, 'utf8');
+            if (!/^W\d+:tgt\d+\.txt\|END$/.test(c)) { allValid = false; }
+        }
+        const leftovers = listLeftovers(dir);
+
+        // Per-file history invariant: each worker writes each file exactly once.
+        let allHistOk = true;
+        for (const p of targets) {
+            let lines = [];
+            try {
+                lines = readFileSync(p + '.history', 'utf8').trim().split('\n').filter(Boolean);
+            } catch { allHistOk = false; break; }
+            if (lines.length !== N) { allHistOk = false; break; }
+            const last = lines[lines.length - 1];
+            const lastPayload = last.slice(last.indexOf('|') + 1);
+            const finalC = readFileSync(p, 'utf8');
+            if (lastPayload !== finalC) { allHistOk = false; break; }
+        }
+
+        const okStrict2 = LIVE ? okCount >= N - 2 : okCount === N;
+        const histStrict2 = LIVE ? true : allHistOk;
+        record('s2: 16 workers × 4-file batch — history-strict',
+            okStrict2 && allValid && leftovers.length === 0 && histStrict2, {
+            ok: `${okCount}/${N}`, wallMs, allValid, histOk: allHistOk, leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// ============================================================
+// S3: torn-read detection (streamed write >1MB, concurrent readers)
+// ============================================================
+async function s3() {
+    const dir = tempDir('s3');
+    try {
+        const target = join(dir, 'big.txt');
+        const filler = 'x'.repeat(1024 * 1024 + 16);
+        writeFileSync(target, 'INITIAL-' + filler.slice(0, 1024) + '|END');
+
+        const READERS = 8;
+        const WRITES = 6;
+        // Reader window: 2000ms — covers reader cold-start + driver pre-write
+        // delay + writer cold-start + the active write fan-out (~500ms total
+        // since cold start dominates), with margin.
+        const READ_WINDOW_MS = 2000;
+
+        const payloadPaths = [];
+        for (let i = 0; i < WRITES; i += 1) {
+            const p = join(dir, 'payload-' + i + '.bin');
+            writeFileSync(p, 'BIG' + i + '-' + filler + '|END');
+            payloadPaths.push(p);
+        }
+        // Spawn readers first so they observe INITIAL before any BIG write;
+        // child startup is ~150ms so without staggering the readers tend to
+        // land after the writers have all settled (maxDistinctSizes=1).
+        const readerTasks = [];
+        for (let i = 0; i < READERS; i += 1) {
+            readerTasks.push(spawnWorker('read', target, String(READ_WINDOW_MS), 30000));
+        }
+        await new Promise(r => setTimeout(r, 200));
+        const writerTasks = [];
+        for (let i = 0; i < WRITES; i += 1) {
+            writerTasks.push(spawnWorker('single', target, '@file:' + payloadPaths[i], 30000));
+        }
+        const t0 = performance.now();
+        const [w, r] = await Promise.all([
+            Promise.all(writerTasks),
+            Promise.all(readerTasks),
+        ]);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+
+        const writersOk = w.filter(isOk).length;
+        const readersOk = r.filter(isOk).length;
+        const tornReader = r.find(x => x.torn === true);
+        // Overlap proof: at least one reader observed >=2 distinct sizes
+        // (INITIAL small + a BIG payload). If every reader saw a single
+        // size, they did not overlap with active writes.
+        const maxDistinctSizes = Math.max(0, ...r.map(x => x.distinctSizes ?? 0));
+        // LIVE: overlap timing is fragile under 10-instance load.
+        const overlapProved = LIVE ? true : maxDistinctSizes >= 2;
+        const leftovers = listLeftovers(dir);
+        if (!overlapProved) {
+            // Diagnostic dump when overlap fails.
+            console.log('[s3 diag] readers:', r.map(x => ({
+                reads: x.reads, distinctSizes: x.distinctSizes, dt: x.dt, ok: x.ok, code: x.code,
+            })));
+        }
+
+        const writersStrict = LIVE ? writersOk >= WRITES - 1 : writersOk === WRITES;
+        record('s3: torn-read free + overlap proved',
+            !tornReader && writersStrict && readersOk === READERS && overlapProved && leftovers.length === 0, {
+            writers: `${writersOk}/${WRITES}`, readers: `${readersOk}/${READERS}`, torn: tornReader ? 'YES' : 'no',
+            maxDistinctSizes, wallMs, leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// ============================================================
+// S4: stale lock pile-up (dead PID lockfile)
+// ============================================================
+async function s4() {
+    const dir = tempDir('s4');
+    try {
+        const target = join(dir, 'target.txt');
+        writeFileSync(target, 'INITIAL|END');
+        const lockFile = lockFileFor(target);
+        writeFileSync(lockFile, '999999.deadbeefdeadbeef');
+
+        const N = 8;
+        const t0 = performance.now();
+        const tasks = [];
+        for (let i = 0; i < N; i += 1) {
+            tasks.push(spawnWorker('single', target, `W${i}|END`, 15000));
+        }
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+
+        const okCount = out.filter(isOk).length;
+        const final = readFileSync(target, 'utf8');
+        const isValid = /^W\d+\|END$/.test(final);
+        const stillLocked = existsSync(lockFile);
+        const leftovers = listLeftovers(dir);
+
+        const okStrict4 = LIVE ? okCount >= N - 1 : okCount === N;
+        record('s4: 8 contenders clean up stale lock + write',
+            okStrict4 && isValid && !stillLocked && leftovers.length === 0, {
+            ok: `${okCount}/${N}`, wallMs, lockGone: !stillLocked, leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// ============================================================
+// S5: sustained throughput + leak check
+// ============================================================
+async function s5() {
+    const ROUNDS = Number(process.env.STRESS_S5_ROUNDS) || 25;
+    const PARALLEL = Number(process.env.STRESS_S5_PARALLEL) || 8;
+    const dir = tempDir('s5');
+    try {
+        const target = join(dir, 'target.txt');
+        writeFileSync(target, 'INITIAL|END');
+
+        let okTotal = 0; let failTotal = 0;
+        const t0 = performance.now();
+        for (let r = 0; r < ROUNDS; r += 1) {
+            const tasks = [];
+            for (let i = 0; i < PARALLEL; i += 1) {
+                tasks.push(spawnWorker('single', target, `R${r}W${i}|END`, 30000));
+            }
+            const out = await Promise.all(tasks);
+            okTotal += out.filter(isOk).length;
+            failTotal += out.filter(x => !isOk(x)).length;
+        }
+        const wallMs = +(performance.now() - t0).toFixed(1);
+        const ops = ROUNDS * PARALLEL;
+        const opsPerSec = (ops / (wallMs / 1000)).toFixed(1);
+        const leftovers = listLeftovers(dir);
+
+        // Under heavy multi-instance load, very-rare EAGAIN can fire even at
+        // 30s lock timeout. LIVE mode tolerates up to 2/200 EAGAIN.
+        const opsOk = LIVE ? okTotal >= ops - 2 : okTotal === ops;
+        record('s5: sustained throughput leak check', opsOk && leftovers.length === 0, {
+            ops, ok: okTotal, fail: failTotal, wallMs, opsPerSec, leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// ============================================================
+// S6: adversarial short-timeout
+// ============================================================
+async function s6() {
+    const dir = tempDir('s6');
+    try {
+        const target = join(dir, 'target.txt');
+        writeFileSync(target, 'INITIAL|END');
+
+        // Hold long enough to absorb contender cold-start variance under
+        // heavy multi-instance load (was 300ms, became starvation-free on
+        // a quiet box but contenders spawned post-release under load).
+        const slowChild = spawn(process.execPath, [
+            __filename, '--worker', 'sleep-hold', target, '1500', '8000',
+        ], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let slowOut = '';
+        slowChild.stdout.on('data', d => { slowOut += d; });
+        const slowExit = new Promise(res => slowChild.on('close', code => res(code)));
+
+        const deadline = Date.now() + 3000;
+        while (!/"acquired"/.test(slowOut) && Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, 10));
+        }
+        if (!/"acquired"/.test(slowOut)) {
+            record('s6: slow holder did not acquire', false, { slowOut: slowOut.slice(0, 100) });
+            try { slowChild.kill(); } catch { /* */ }
+            return;
+        }
+
+        const N = 8;
+        const tasks = [];
+        for (let i = 0; i < N; i += 1) {
+            tasks.push(spawnWorker('single', target, `IMP${i}|END`, 80));
+        }
+        const t0 = performance.now();
+        const out = await Promise.all(tasks);
+        const slowExitCode = await slowExit;
+        const wallMs = +(performance.now() - t0).toFixed(1);
+
+        // EAGAIN must come with exitCode 1 (worker error path).
+        const eagain = out.filter(r => r.code === 'EAGAIN' && r.exitCode === 1).length;
+        const ok = out.filter(isOk).length;
+        // Every fast contender must be either a clean OK or a clean EAGAIN —
+        // any other outcome (silent failure, parse error, unexpected exit) is
+        // a real bug, not a graceful timeout.
+        const accountedFor = ok + eagain;
+        const final = readFileSync(target, 'utf8');
+        const finalOk = /^(SLOW-WRITER|IMP\d+)\|END$/.test(final);
+        const leftovers = listLeftovers(dir);
+
+        // EAGAIN>=1 is timing-sensitive: under heavy load contender spawn can
+        // land past holder release, making all contenders cleanly acquire.
+        // LIVE mode relaxes to "no unexplained failures" (accountedFor === N).
+        const eagainOk = LIVE ? true : eagain >= 1;
+        record('s6: short-timeout adversarial',
+            eagainOk && accountedFor === N && finalOk && slowExitCode === 0 && leftovers.length === 0, {
+            ok, eagain, accountedFor: `${accountedFor}/${N}`, slowExit: slowExitCode,
+            wallMs, final: final.slice(0, 30), leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// ============================================================
+// Run
+// ============================================================
+// === New parallel scenarios (s7-s12) with shared fixture-pool fixtures ===
+
+// S7: pure read scale on stable fixtures (no writer)
+async function s7() {
+    const dir = tempDir('s7');
+    try {
+        const pool = buildFixturePool(dir, 8);
+        const READERS = 16;
+        const t0 = performance.now();
+        const tasks = [];
+        for (let i = 0; i < READERS; i += 1) {
+            const f = pool[i % pool.length];
+            tasks.push(spawnWorker('read', f.path, '500', 30000, {
+                EXPECTED_SIZE: String(f.size),
+                EXPECTED_PREFIX: f.prefix,
+                EXPECTED_HASH: f.hash,
+            }));
+        }
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+        const okCount = out.filter(isOk).length;
+        const torn = out.find(x => x.torn === true);
+        const totalReads = out.reduce((a, x) => a + (x.reads || 0), 0);
+        const minReads = Math.min(...out.map(x => x.reads ?? 0));
+        record('s7: pure read scale on stable pool',
+            okCount === READERS && !torn && minReads >= 1, {
+            ok: `${okCount}/${READERS}`, totalReads, minReads, wallMs, torn: torn ? 'YES' : 'no',
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// S8: R+W on independent files (no contention)
+async function s8() {
+    const dir = tempDir('s8');
+    try {
+        const pool = buildFixturePool(dir, 8);
+        const writeTargets = pool.slice(0, 4);
+        const readTargets = pool.slice(4, 8);
+        const t0 = performance.now();
+        const tasks = [];
+        for (let i = 0; i < writeTargets.length; i += 1) {
+            tasks.push(spawnWorker('single', writeTargets[i].path, `S8W${i}|END`, 15000));
+        }
+        for (let i = 0; i < readTargets.length; i += 1) {
+            const f = readTargets[i];
+            tasks.push(spawnWorker('read', f.path, '500', 30000, {
+                EXPECTED_SIZE: String(f.size),
+                EXPECTED_PREFIX: f.prefix,
+                EXPECTED_HASH: f.hash,
+            }));
+        }
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+        const okCount = out.filter(isOk).length;
+        const torn = out.find(x => x.torn === true);
+        const leftovers = listLeftovers(dir);
+        // Each write target must hold its expected final payload.
+        let writeFinalsOk = true;
+        for (let i = 0; i < writeTargets.length; i += 1) {
+            const c = readFileSync(writeTargets[i].path, 'utf8');
+            if (c !== `S8W${i}|END`) { writeFinalsOk = false; break; }
+        }
+        // Each read target must remain byte-identical to the original fixture.
+        let readUnchangedOk = true;
+        for (const f of readTargets) {
+            const c = readFileSync(f.path, 'utf8');
+            if (c.length !== f.size || !c.startsWith(f.prefix) || !c.endsWith('|END')) {
+                readUnchangedOk = false; break;
+            }
+        }
+        record('s8: R+W on independent files',
+            okCount === tasks.length && !torn && writeFinalsOk && readUnchangedOk && leftovers.length === 0, {
+            workers: `${okCount}/${tasks.length}`, writeFinalsOk, readUnchangedOk,
+            wallMs, torn: torn ? 'YES' : 'no', leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// S9: same-file R+W high contention
+async function s9() {
+    const dir = tempDir('s9');
+    try {
+        const target = join(dir, 'hot.txt');
+        writeFileSync(target, 'INITIAL|END');
+        const R = 6, W = 8;
+        const tasks = [];
+        for (let i = 0; i < R; i += 1) {
+            tasks.push(spawnWorker('read', target, '1500', 30000));
+        }
+        await new Promise(r => setTimeout(r, 150));
+        for (let i = 0; i < W; i += 1) {
+            tasks.push(spawnWorker('single', target, `S9W${i}|END`, 15000));
+        }
+        const t0 = performance.now();
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+        const okCount = out.filter(isOk).length;
+        const torn = out.find(x => x.torn === true);
+        const maxDistinct = Math.max(0, ...out.map(x => x.distinctSizes ?? 0));
+        const final = readFileSync(target, 'utf8');
+        // Writers expected to land → final must be a S9W payload (no INITIAL).
+        const finalOk = /^S9W\d+\|END$/.test(final);
+        const leftovers = listLeftovers(dir);
+        // Overlap detection (maxDistinct>=2) is timing-sensitive: under heavy
+        // multi-instance load reader cold-start drifts past writer activity.
+        // LIVE mode keeps only correctness invariants (no torn, finalOk, ok).
+        const overlapOk = LIVE ? true : maxDistinct >= 2;
+        record('s9: same-file R+W contention',
+            okCount === (R + W) && !torn && overlapOk && finalOk && leftovers.length === 0, {
+            workers: `${okCount}/${R + W}`, wallMs, maxDistinct, torn: torn ? 'YES' : 'no',
+            final: final.slice(0, 20), leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// S10: rapid replacement read-survival
+async function s10() {
+    const dir = tempDir('s10');
+    try {
+        const target = join(dir, 'rapid.txt');
+        writeFileSync(target, 'INITIAL|END');
+        const READERS = 4, WRITES = 12;
+        const tasks = [];
+        for (let i = 0; i < READERS; i += 1) {
+            // 1500ms deadline — covers reader cold start + driver pre-write
+            // delay even under parallel-stage OS pressure (setTimeout drift).
+            tasks.push(spawnWorker('read', target, '1500', 30000));
+        }
+        await new Promise(r => setTimeout(r, 100));
+        for (let i = 0; i < WRITES; i += 1) {
+            tasks.push(spawnWorker('single', target, `S10W${i}|END`, 15000));
+        }
+        const t0 = performance.now();
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+        const okCount = out.filter(isOk).length;
+        const torn = out.find(x => x.torn === true);
+        const maxDistinct = Math.max(0, ...out.map(x => x.distinctSizes ?? 0));
+        const final = readFileSync(target, 'utf8');
+        const finalOk = /^S10W\d+\|END$/.test(final);
+        const leftovers = listLeftovers(dir);
+        const overlapOk = LIVE ? true : maxDistinct >= 2;
+        record('s10: rapid replacement read-survival',
+            okCount === (READERS + WRITES) && !torn && overlapOk && finalOk && leftovers.length === 0, {
+            workers: `${okCount}/${READERS + WRITES}`, wallMs, maxDistinct,
+            torn: torn ? 'YES' : 'no', final: final.slice(0, 20), leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// S11: mixed pool 50/50 R/W (workers pick random pool target)
+async function s11() {
+    const dir = tempDir('s11');
+    try {
+        // 4-file pool with 16 workers in alternating W/R pairing →
+        // file = pool[floor(i/2) % 4] ensures same pool file gets a writer
+        // (even i) AND a reader (odd i) per pair, so each file has 2 writers
+        // and 2 readers TARGETING IT (real R/W contention on same file).
+        const pool = buildFixturePool(dir, 4);
+        const N = 16;
+        const tasks = [];
+        let writeCount = 0;
+        for (let i = 0; i < N; i += 1) {
+            const file = pool[Math.floor(i / 2) % pool.length];
+            const isWrite = i % 2 === 0;
+            if (isWrite) {
+                tasks.push(spawnWorker('single', file.path, `S11W${i}-p${file.index}|END`, 15000));
+                writeCount += 1;
+            } else {
+                // No EXPECTED_SIZE — same pool file may be mid-write, size legitimately varies.
+                tasks.push(spawnWorker('read', file.path, '500', 30000));
+            }
+        }
+        const t0 = performance.now();
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+        const okCount = out.filter(isOk).length;
+        const torn = out.find(x => x.torn === true);
+        const leftovers = listLeftovers(dir);
+        // Strict per-file final state: each pool[k] is written by writers
+        // i in {2k, 2k+8} (k = floor(i/2) % 4 with i even). Final must be
+        // one of those two writers' payloads — NOT some other file's writer.
+        let perFileOk = true;
+        for (const f of pool) {
+            const k = f.index;
+            const allowedWriters = [2 * k, 2 * k + 8];
+            const allowedFinals = new Set(allowedWriters.map(w => `S11W${w}-p${k}|END`));
+            const c = readFileSync(f.path, 'utf8');
+            if (!allowedFinals.has(c)) { perFileOk = false; break; }
+        }
+        record('s11: mixed pool 50/50 R/W',
+            okCount === N && writeCount === N / 2 && !torn && perFileOk && leftovers.length === 0, {
+            workers: `${okCount}/${N}`, writes: writeCount, reads: N - writeCount,
+            wallMs, perFileOk, torn: torn ? 'YES' : 'no', leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// S12: lock-protected reader vs writer (verifies advisory lock serializes R/W)
+async function s12() {
+    const dir = tempDir('s12');
+    try {
+        const target = join(dir, 'locked.txt');
+        writeFileSync(target, 'INITIAL|END');
+        const READERS = 4, WRITERS = 4;
+        const tasks = [];
+        for (let i = 0; i < READERS; i += 1) {
+            tasks.push(spawnWorker('locked-read', target, '600', 15000));
+        }
+        for (let i = 0; i < WRITERS; i += 1) {
+            tasks.push(spawnWorker('single', target, `S12W${i}|END`, 15000));
+        }
+        const t0 = performance.now();
+        const out = await Promise.all(tasks);
+        const wallMs = +(performance.now() - t0).toFixed(1);
+        const okCount = out.filter(isOk).length;
+        const torn = out.find(x => x.torn === true);
+        const final = readFileSync(target, 'utf8');
+        // Writers expected to land → final must be a S12W payload (no INITIAL).
+        const finalOk = /^S12W\d+\|END$/.test(final);
+        const leftovers = listLeftovers(dir);
+        // Lock proof: every locked-read worker reported lockInconsistencies===0
+        // (size never changed INSIDE a single lock-held window). If a broken/
+        // no-op lock let a writer slip in, sizesInHold.size>1 → fail.
+        const lockedReaders = out.filter(x => x.mode === 'locked-read');
+        const lockBroken = lockedReaders.find(x => (x.lockInconsistencies || 0) > 0);
+        // Writer-actually-wrote proof: at least one locked-read worker
+        // observed >=2 distinct sizes ACROSS its lock-held windows (initial
+        // size + post-write size).
+        const maxAcrossSizes = Math.max(0, ...lockedReaders.map(x => x.distinctSizes ?? 0));
+        const workersStrict12 = LIVE ? okCount >= (READERS + WRITERS) - 2 : okCount === (READERS + WRITERS);
+        // LIVE: locked-reader observing writer activity (maxAcrossSizes>=2)
+        // is timing-sensitive under 10-instance load; final regex already
+        // proves a writer landed, and !lockBroken proves lock semantics.
+        const sizeChangeOk = LIVE ? true : maxAcrossSizes >= 2;
+        record('s12: lock-protected reader vs writer',
+            workersStrict12 && !torn && finalOk
+            && !lockBroken && sizeChangeOk && leftovers.length === 0, {
+            workers: `${okCount}/${READERS + WRITERS}`, wallMs, torn: torn ? 'YES' : 'no',
+            lockBroken: lockBroken ? 'YES' : 'no', maxAcrossSizes,
+            final: final.slice(0, 20), leftovers: leftovers.length,
+        });
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+// === Main runner: heavy sequential + new parallel stage ===
+const want = new Set(process.argv.slice(2).filter(a => !a.startsWith('-')));
+const HEAVY = { s1, s2, s3, s4, s5, s6 };
+const PARALLEL = { s7, s8, s9, s10, s11, s12, s13 };
+const ALL = { ...HEAVY, ...PARALLEL };
+const toRun = want.size === 0 ? Object.keys(ALL) : Object.keys(ALL).filter(k => want.has(k));
+const heavyToRun = toRun.filter(k => k in HEAVY);
+const parallelToRun = toRun.filter(k => k in PARALLEL);
+
+console.log(`stress-atomic-write: heavy=[${heavyToRun.join(',')}] parallel=[${parallelToRun.join(',')}] node=${process.version} platform=${process.platform}`);
+const grandT0 = performance.now();
+
+for (const name of heavyToRun) {
+    try { await HEAVY[name](); }
+    catch (err) { record(name + ': harness error', false, { err: String(err.message).slice(0, 200) }); }
+}
+
+if (parallelToRun.length > 0) {
+    console.log(`-- parallel stage: ${parallelToRun.length} scenarios concurrent --`);
+    const parT0 = performance.now();
+    await Promise.all(parallelToRun.map(async (name) => {
+        try { await PARALLEL[name](); }
+        catch (err) { record(name + ': harness error', false, { err: String(err.message).slice(0, 200) }); }
+    }));
+    console.log(`-- parallel stage done: ${((performance.now() - parT0) / 1000).toFixed(2)}s --`);
+}
+
+const grandWall = ((performance.now() - grandT0) / 1000).toFixed(2);
+const passed = results.filter(r => r.ok).length;
+const failed = results.length - passed;
+console.log(`\n=== ${passed}/${results.length} passed, ${failed} failed, total=${grandWall}s ===`);
+if (process.env.STRESS_DEBUG === '1' || failed > 0) {
+    console.log('=== debug results ===');
+    results.forEach((r, i) => {
+        console.log('  #' + i + ' ok=' + r.ok + ' name=' + r.name);
+    });
+}