botmux 3.10.0 → 3.23.1

package/dist/workflows/migration/v2-run-archive.js

@@ -1,1220 +0,0 @@
-/**
- * One-time, read-only-to-the-source archive for retired v2 workflow runs.
- *
- * The archive deliberately stores both the byte-exact legacy tree and the
- * current ops projection.  The legacy replay implementation can be deleted only
- * after `verifyV2RunArchive(..., { sourceRunsDir })` proves that both views
- * still match the live source.
- */
-import { createHash, randomBytes } from 'node:crypto';
-import { chmodSync, closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, linkSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, renameSync, rmSync, unlinkSync, writeSync, } from 'node:fs';
-import { basename, dirname, isAbsolute, join, posix, relative, resolve } from 'node:path';
-import { canonicalJsonStringify } from '../../utils/canonical-json.js';
-import { fsyncDirectorySyncPortable } from '../../utils/fs-durability.js';
-import { withFileLock } from '../../utils/file-lock.js';
-import { parseEvent } from '../events/schema.js';
-import { isValidRunId, readRunSnapshot, } from '../ops-projection.js';
-import { V2_RUN_ARCHIVE_COMMIT_SCHEMA_VERSION, V2_RUN_ARCHIVE_KIND, V2_RUN_ARCHIVE_SCHEMA_VERSION, V2_RUN_RETIREMENT_KIND, V2_RUN_RETIREMENT_SCHEMA_VERSION, archiveDirectoryName, parseV2RunArchiveCommitMarker, parseV2RunArchiveManifest, parseV2RunRetirementReceipt, sha256Ref, v2RunArchiveId, } from './v2-run-archive-schema.js';
-const READ_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0);
-const CREATE_FLAGS = constants.O_WRONLY |
-    constants.O_CREAT |
-    constants.O_EXCL |
-    (constants.O_NOFOLLOW ?? 0);
-const DIRECTORY_FLAGS = constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0);
-const BUFFER_BYTES = 64 * 1024;
-const MANIFEST_FILE = 'manifest.json';
-const COMMIT_FILE = 'COMMITTED';
-const STAGING_PREFIX = '.staging-v2-run-archive-';
-const STAGE_MARKER = 'stage.json';
-const PUBLICATION_LOCK_BASENAME = '.v2-run-archive-publication';
-const RETIREMENT_RECEIPT_PREFIX = 'v2-run-retirement-';
-export class V2RunArchiveError extends Error {
-    code;
-    constructor(code, message) {
-        super(`${code}: ${message}`);
-        this.code = code;
-        this.name = 'V2RunArchiveError';
-    }
-}
-function fail(code, message) {
-    throw new V2RunArchiveError(code, message);
-}
-function assertSafeRelativePath(path, label) {
-    if (!path ||
-        path.length > 4096 ||
-        isAbsolute(path) ||
-        path.includes('\\') ||
-        path.split('/').some((segment) => !segment || segment === '.' || segment === '..')) {
-        fail('UNSAFE_ARCHIVE_PATH', `${label} is not a normalized relative path: ${path}`);
-    }
-}
-function assertPathInside(parent, child, label) {
-    const rel = relative(resolve(parent), resolve(child));
-    if (!rel || rel === '.')
-        return;
-    if (rel.startsWith('..') || isAbsolute(rel)) {
-        fail('PATH_ESCAPE', `${label} escapes ${parent}: ${child}`);
-    }
-}
-function assertPlainDirectory(path, label) {
-    let stat;
-    try {
-        stat = lstatSync(path);
-    }
-    catch (err) {
-        fail('DIRECTORY_UNREADABLE', `${label} ${path}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        fail('UNSAFE_DIRECTORY', `${label} must be a real directory, not a symlink/special entry: ${path}`);
-    }
-    const fd = openSync(path, DIRECTORY_FLAGS);
-    try {
-        const opened = fstatSync(fd);
-        if (!opened.isDirectory() || opened.dev !== stat.dev || opened.ino !== stat.ino) {
-            fail('DIRECTORY_RACED', `${label} changed while opening: ${path}`);
-        }
-    }
-    finally {
-        closeSync(fd);
-    }
-}
-function ensurePrivateDirectory(path) {
-    mkdirSync(path, { recursive: true, mode: 0o700 });
-    assertPlainDirectory(path, 'archive directory');
-    chmodSync(path, 0o700);
-}
-/**
- * Create the dedicated archive base privately, but never chmod a caller-owned
- * existing directory such as /tmp or $HOME. An existing base must already
- * satisfy the private-mode contract or the operator must choose a child path.
- */
-function ensurePrivateArchiveBase(path) {
-    const created = mkdirSync(path, { recursive: true, mode: 0o700 });
-    assertPlainDirectory(path, 'archive base directory');
-    if (created !== undefined)
-        chmodSync(path, 0o700);
-    else
-        assertPrivateMode(path, 0o700, 'archive base directory');
-}
-/**
- * Publication and retirement deliberately share one non-reentrant lock.
- * Keep all callers on this helper so a basename change cannot split the
- * serialization domain and never call it from inside another invocation.
- */
-export function withV2RunArchivePublicationLock(archiveBaseDir, fn) {
-    return withFileLock(join(resolve(archiveBaseDir), PUBLICATION_LOCK_BASENAME), fn);
-}
-function assertPrivateMode(path, wanted, label) {
-    if (process.platform === 'win32')
-        return;
-    const mode = lstatSync(path).mode & 0o777;
-    if (mode !== wanted)
-        fail('ARCHIVE_MODE_MISMATCH', `${label} ${path} mode=${mode.toString(8)}, expected ${wanted.toString(8)}`);
-}
-function readSecureFile(path) {
-    const before = lstatSync(path);
-    if (before.isSymbolicLink() || !before.isFile()) {
-        fail('UNSAFE_SOURCE_ENTRY', `expected regular file: ${path}`);
-    }
-    if (before.nlink !== 1)
-        fail('SOURCE_HARDLINK', `hard-linked source file is not archive-safe: ${path}`);
-    const fd = openSync(path, READ_FLAGS);
-    try {
-        const opened = fstatSync(fd);
-        if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== before.dev || opened.ino !== before.ino)
-            fail('SOURCE_FILE_RACED', `source file changed while opening: ${path}`);
-        const chunks = [];
-        const buffer = Buffer.alloc(BUFFER_BYTES);
-        let total = 0;
-        while (true) {
-            const count = readSync(fd, buffer, 0, buffer.length, null);
-            if (count === 0)
-                break;
-            chunks.push(Buffer.from(buffer.subarray(0, count)));
-            total += count;
-        }
-        const after = fstatSync(fd);
-        if (after.dev !== opened.dev || after.ino !== opened.ino || after.nlink !== 1 ||
-            after.size !== opened.size || after.size !== total || after.mtimeMs !== opened.mtimeMs)
-            fail('SOURCE_FILE_CHANGED', `source file changed while reading: ${path}`);
-        return Buffer.concat(chunks, total);
-    }
-    finally {
-        closeSync(fd);
-    }
-}
-function hashSecureFile(path) {
-    const before = lstatSync(path);
-    if (before.isSymbolicLink() || !before.isFile()) {
-        fail('UNSAFE_SOURCE_ENTRY', `expected regular file: ${path}`);
-    }
-    if (before.nlink !== 1)
-        fail('SOURCE_HARDLINK', `hard-linked file is not archive-safe: ${path}`);
-    const fd = openSync(path, READ_FLAGS);
-    try {
-        const opened = fstatSync(fd);
-        if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== before.dev || opened.ino !== before.ino)
-            fail('SOURCE_FILE_RACED', `file changed while opening: ${path}`);
-        const hash = createHash('sha256');
-        const buffer = Buffer.alloc(BUFFER_BYTES);
-        let bytes = 0;
-        while (true) {
-            const count = readSync(fd, buffer, 0, buffer.length, null);
-            if (count === 0)
-                break;
-            hash.update(buffer.subarray(0, count));
-            bytes += count;
-        }
-        const after = fstatSync(fd);
-        if (after.dev !== opened.dev || after.ino !== opened.ino || after.nlink !== 1 ||
-            after.size !== opened.size || after.size !== bytes || after.mtimeMs !== opened.mtimeMs)
-            fail('SOURCE_FILE_CHANGED', `file changed while hashing: ${path}`);
-        return { bytes, sha256: `sha256:${hash.digest('hex')}` };
-    }
-    finally {
-        closeSync(fd);
-    }
-}
-function writeAll(fd, data) {
-    let offset = 0;
-    while (offset < data.length)
-        offset += writeSync(fd, data, offset, data.length - offset);
-}
-function writeNewPrivateFile(path, data) {
-    assertPathInside(dirname(path), path, 'archive file');
-    const fd = openSync(path, CREATE_FLAGS, 0o600);
-    try {
-        fchmodSync(fd, 0o600);
-        writeAll(fd, data);
-        fsyncSync(fd);
-        const stat = fstatSync(fd);
-        if (!stat.isFile() || stat.nlink !== 1 || stat.size !== data.length) {
-            fail('ARCHIVE_WRITE_INVALID', `new archive file is not a private regular inode: ${path}`);
-        }
-    }
-    finally {
-        closeSync(fd);
-    }
-}
-function copyRegularFileSecure(copy, payloadRoot) {
-    assertSafeRelativePath(copy.archivePath, 'copy destination');
-    const destination = join(payloadRoot, ...copy.archivePath.split('/'));
-    assertPathInside(payloadRoot, destination, 'copy destination');
-    const before = lstatSync(copy.sourcePath);
-    if (before.isSymbolicLink() || !before.isFile()) {
-        fail('UNSAFE_SOURCE_ENTRY', `expected regular source file: ${copy.sourcePath}`);
-    }
-    if (before.nlink !== 1)
-        fail('SOURCE_HARDLINK', `hard-linked source file is not archive-safe: ${copy.sourcePath}`);
-    const sourceFd = openSync(copy.sourcePath, READ_FLAGS);
-    const destinationFd = openSync(destination, CREATE_FLAGS, 0o600);
-    try {
-        fchmodSync(destinationFd, 0o600);
-        const opened = fstatSync(sourceFd);
-        if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== before.dev || opened.ino !== before.ino)
-            fail('SOURCE_FILE_RACED', `source file changed while opening: ${copy.sourcePath}`);
-        const hash = createHash('sha256');
-        const buffer = Buffer.alloc(BUFFER_BYTES);
-        let bytes = 0;
-        while (true) {
-            const count = readSync(sourceFd, buffer, 0, buffer.length, null);
-            if (count === 0)
-                break;
-            hash.update(buffer.subarray(0, count));
-            writeAll(destinationFd, buffer.subarray(0, count));
-            bytes += count;
-        }
-        fsyncSync(destinationFd);
-        const afterSource = fstatSync(sourceFd);
-        const destinationStat = fstatSync(destinationFd);
-        const sha256 = `sha256:${hash.digest('hex')}`;
-        if (afterSource.dev !== opened.dev || afterSource.ino !== opened.ino || afterSource.nlink !== 1 ||
-            afterSource.size !== opened.size || afterSource.size !== bytes || afterSource.mtimeMs !== opened.mtimeMs)
-            fail('SOURCE_FILE_CHANGED', `source file changed while copying: ${copy.sourcePath}`);
-        if (!destinationStat.isFile() || destinationStat.nlink !== 1 || destinationStat.size !== bytes) {
-            fail('ARCHIVE_COPY_INVALID', `destination file identity is unsafe: ${destination}`);
-        }
-        if (bytes !== copy.expected.bytes || sha256 !== copy.expected.sha256) {
-            fail('SOURCE_CHANGED_DURING_ARCHIVE', `source bytes changed after first capture: ${copy.sourcePath}`);
-        }
-    }
-    finally {
-        closeSync(sourceFd);
-        closeSync(destinationFd);
-    }
-}
-function captureDirectoryTree(root) {
-    assertPlainDirectory(root, 'source tree');
-    const directories = [];
-    const files = [];
-    const visit = (directory, relativeDirectory) => {
-        assertPlainDirectory(directory, 'source tree directory');
-        const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
-        for (const entry of entries) {
-            if (entry.name === '.' || entry.name === '..' || entry.name.includes('/') || entry.name.includes('\\')) {
-                fail('UNSAFE_SOURCE_NAME', `unsafe source entry name in ${directory}: ${entry.name}`);
-            }
-            const absolute = join(directory, entry.name);
-            const relativePath = relativeDirectory ? posix.join(relativeDirectory, entry.name) : entry.name;
-            assertSafeRelativePath(relativePath, 'source tree entry');
-            const stat = lstatSync(absolute);
-            if (stat.isSymbolicLink())
-                fail('SOURCE_SYMLINK', `symlinks are forbidden in the archive source: ${absolute}`);
-            if (stat.isDirectory()) {
-                directories.push(relativePath);
-                visit(absolute, relativePath);
-                continue;
-            }
-            if (!stat.isFile())
-                fail('SOURCE_SPECIAL_ENTRY', `special filesystem entry is forbidden: ${absolute}`);
-            if (stat.nlink !== 1)
-                fail('SOURCE_HARDLINK', `hard-linked source file is forbidden: ${absolute}`);
-            const hashed = hashSecureFile(absolute);
-            files.push({ relativePath, sourcePath: absolute, ...hashed });
-        }
-    };
-    visit(root, '');
-    directories.sort();
-    files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
-    return { directories, files };
-}
-function captureTopFile(path, name) {
-    const stat = lstatSync(path);
-    if (stat.isSymbolicLink() || !stat.isFile())
-        fail('SOURCE_SPECIAL_ENTRY', `unsafe top-level entry: ${path}`);
-    if (stat.nlink !== 1)
-        fail('SOURCE_HARDLINK', `hard-linked top-level file is forbidden: ${path}`);
-    const hashed = hashSecureFile(path);
-    return { directories: [], files: [{ relativePath: name, sourcePath: path, ...hashed }] };
-}
-function treeDigest(tree) {
-    return sha256Ref(canonicalJsonStringify({
-        directories: tree.directories,
-        files: tree.files.map(({ relativePath: path, bytes, sha256 }) => ({ path, bytes, sha256 })),
-    }));
-}
-function strictReadJournal(runDir, runId) {
-    const path = join(runDir, 'events.ndjson');
-    const raw = readSecureFile(path).toString('utf-8');
-    if (!raw.endsWith('\n')) {
-        fail('TORN_EVENT_LOG', `${path} has no final newline (possible partial append)`);
-    }
-    const events = [];
-    let lineNumber = 0;
-    const lines = raw.split('\n');
-    lines.pop(); // exactly one final empty segment is required above
-    for (const line of lines) {
-        lineNumber++;
-        if (!line)
-            fail('CORRUPT_EVENT_LOG', `${path}:${lineNumber}: blank journal line`);
-        let value;
-        try {
-            value = JSON.parse(line);
-        }
-        catch (err) {
-            fail('CORRUPT_EVENT_LOG', `${path}:${lineNumber}: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        let event;
-        try {
-            event = parseEvent(value);
-        }
-        catch (err) {
-            fail('CORRUPT_EVENT_LOG', `${path}:${lineNumber}: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        const expectedEventId = `${runId}-${events.length + 1}`;
-        if (event.runId !== runId || event.eventId !== expectedEventId) {
-            fail('RUN_IDENTITY_MISMATCH', `${path}:${lineNumber} expected runId/eventId ${runId}/${expectedEventId}, got ${event.runId}/${event.eventId}`);
-        }
-        events.push(event);
-    }
-    if (events.length === 0)
-        fail('EMPTY_EVENT_LOG', `${path} has no workflow events`);
-    return events;
-}
-function presenceInTree(tree) {
-    const files = new Set(tree.files.map((file) => file.relativePath));
-    const directories = new Set(tree.directories);
-    return {
-        workflowJson: files.has('workflow.json'),
-        chatBindingJson: files.has('chat-binding.json'),
-        attemptsDir: directories.has('attempts'),
-        blobsDir: directories.has('blobs'),
-    };
-}
-function projectionWarnings(snapshot, presence) {
-    const warnings = [];
-    const danglingCount = snapshot.dangling.activities.length +
-        snapshot.dangling.effectAttempted.length +
-        snapshot.dangling.waits.length +
-        snapshot.dangling.cancels.length;
-    const liveTerminals = Object.values(snapshot.attemptIO).filter((item) => item.terminal?.status === 'live').length;
-    if (danglingCount > 0) {
-        warnings.push({
-            code: 'TERMINAL_RUN_HAS_DANGLING_STATE',
-            message: `Terminal run retains ${danglingCount} dangling replay item(s); raw bytes and projection are preserved.`,
-        });
-    }
-    if (liveTerminals > 0) {
-        warnings.push({
-            code: 'TERMINAL_RUN_HAS_LIVE_SIDECAR',
-            message: `Terminal run retains ${liveTerminals} terminal sidecar(s) marked live; treated as historical metadata.`,
-        });
-    }
-    if (!presence.workflowJson) {
-        warnings.push({
-            code: 'WORKFLOW_SNAPSHOT_MISSING',
-            message: 'Historical run has no workflow.json snapshot; the archive preserves all bytes that remain.',
-        });
-    }
-    return warnings;
-}
-function addTreeToPayload(input) {
-    assertSafeRelativePath(input.archiveRoot, 'archive raw root');
-    addDirectoryWithParents(input.directories, input.archiveRoot);
-    for (const sourceDirectory of input.tree.directories) {
-        addDirectoryWithParents(input.directories, posix.join(input.archiveRoot, sourceDirectory));
-    }
-    for (const sourceFile of input.tree.files) {
-        const archivePath = posix.join(input.archiveRoot, sourceFile.relativePath);
-        const expected = { path: archivePath, bytes: sourceFile.bytes, sha256: sourceFile.sha256 };
-        input.files.push(expected);
-        input.copies.push({ sourcePath: sourceFile.sourcePath, archivePath, expected });
-    }
-}
-function addDirectoryWithParents(directories, path) {
-    assertSafeRelativePath(path, 'archive directory');
-    const segments = path.split('/');
-    for (let index = 1; index <= segments.length; index++) {
-        directories.add(segments.slice(0, index).join('/'));
-    }
-}
-async function captureSource(runsDirInput) {
-    const absoluteRunsDir = resolve(runsDirInput);
-    assertPlainDirectory(absoluteRunsDir, 'workflow runs root');
-    const sourceRunsDir = realpathSync(absoluteRunsDir);
-    const runs = [];
-    const residuals = [];
-    const directories = new Set();
-    const files = [];
-    const copies = [];
-    const projections = new Map();
-    const entries = readdirSync(sourceRunsDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-        if (entry.name.includes('/') || entry.name.includes('\\') || entry.name === '.' || entry.name === '..') {
-            fail('UNSAFE_SOURCE_NAME', `unsafe top-level entry name: ${entry.name}`);
-        }
-        const sourcePath = join(sourceRunsDir, entry.name);
-        const stat = lstatSync(sourcePath);
-        if (stat.isSymbolicLink())
-            fail('SOURCE_SYMLINK', `top-level symlink is forbidden: ${sourcePath}`);
-        if (!stat.isDirectory() && !stat.isFile())
-            fail('SOURCE_SPECIAL_ENTRY', `top-level special entry is forbidden: ${sourcePath}`);
-        if (stat.isFile()) {
-            const tree = captureTopFile(sourcePath, entry.name);
-            const rawRoot = posix.join('residual', entry.name, 'raw');
-            addTreeToPayload({ tree, archiveRoot: rawRoot, directories, files, copies });
-            residuals.push({
-                name: entry.name,
-                sourceType: 'file',
-                reason: 'top-level-file',
-                rawRoot,
-                fileCount: tree.files.length,
-                totalBytes: tree.files.reduce((sum, file) => sum + file.bytes, 0),
-                treeSha256: treeDigest(tree),
-            });
-            continue;
-        }
-        const tree = captureDirectoryTree(sourcePath);
-        const hasEvents = tree.files.some((file) => file.relativePath === 'events.ndjson');
-        if (!hasEvents) {
-            const rawRoot = posix.join('residual', entry.name, 'raw');
-            addTreeToPayload({ tree, archiveRoot: rawRoot, directories, files, copies });
-            residuals.push({
-                name: entry.name,
-                sourceType: 'directory',
-                reason: 'directory-without-events',
-                rawRoot,
-                fileCount: tree.files.length,
-                totalBytes: tree.files.reduce((sum, file) => sum + file.bytes, 0),
-                treeSha256: treeDigest(tree),
-            });
-            continue;
-        }
-        if (!isValidRunId(entry.name))
-            fail('INVALID_RUN_ID', `event-bearing directory has unsafe runId '${entry.name}'`);
-        const events = strictReadJournal(sourcePath, entry.name);
-        const snapshot = await readRunSnapshot(sourceRunsDir, entry.name);
-        if (!snapshot)
-            fail('UNPROJECTABLE_RUN', `current ops projection cannot read run ${entry.name}`);
-        if (snapshot.runId !== entry.name || snapshot.run.runId !== entry.name) {
-            fail('RUN_IDENTITY_MISMATCH', `projection identity for ${entry.name} does not match its directory`);
-        }
-        if (snapshot.lastSeq !== events.length) {
-            fail('EVENT_SEQUENCE_MISMATCH', `projection lastSeq=${snapshot.lastSeq}, strict journal count=${events.length} for ${entry.name}`);
-        }
-        if (!['succeeded', 'failed', 'cancelled'].includes(snapshot.run.status)) {
-            fail('NONTERMINAL_RUN', `run ${entry.name} is ${snapshot.run.status}; drain it before archiving`);
-        }
-        const projection = Buffer.from(`${canonicalJsonStringify(snapshot)}\n`, 'utf-8');
-        const projectionPath = posix.join('runs', entry.name, 'projection.json');
-        const projectionFile = { path: projectionPath, bytes: projection.length, sha256: sha256Ref(projection) };
-        const rawRoot = posix.join('runs', entry.name, 'raw');
-        addTreeToPayload({ tree, archiveRoot: rawRoot, directories, files, copies });
-        addDirectoryWithParents(directories, posix.dirname(projectionPath));
-        files.push(projectionFile);
-        projections.set(projectionPath, projection);
-        const presence = presenceInTree(tree);
-        const liveTerminalSidecars = Object.values(snapshot.attemptIO)
-            .filter((item) => item.terminal?.status === 'live').length;
-        runs.push({
-            runId: entry.name,
-            rawRoot,
-            projectionPath,
-            projectionSha256: projectionFile.sha256,
-            presence,
-            missingOptional: [
-                ...(!presence.chatBindingJson ? ['chat-binding.json'] : []),
-                ...(!presence.attemptsDir ? ['attempts'] : []),
-            ],
-            warnings: projectionWarnings(snapshot, presence),
-            verdict: {
-                status: snapshot.run.status,
-                workflowId: snapshot.run.workflowId ?? 'unknown',
-                ...(snapshot.run.revisionId ? { revisionId: snapshot.run.revisionId } : {}),
-                lastSeq: snapshot.lastSeq,
-                updatedAt: snapshot.updatedAt,
-                dangling: {
-                    activities: snapshot.dangling.activities.length,
-                    effectAttempted: snapshot.dangling.effectAttempted.length,
-                    waits: snapshot.dangling.waits.length,
-                    cancels: snapshot.dangling.cancels.length,
-                },
-                liveTerminalSidecars,
-            },
-        });
-    }
-    if (runs.length === 0 && residuals.length === 0) {
-        fail('NO_WORKFLOW_RUNS', `${sourceRunsDir} has no v2 workflow-run bytes to archive`);
-    }
-    runs.sort((a, b) => a.runId.localeCompare(b.runId));
-    residuals.sort((a, b) => a.name.localeCompare(b.name));
-    const payloadDirectories = [...directories].sort();
-    const payloadFiles = files.sort((a, b) => a.path.localeCompare(b.path));
-    assertUnique(payloadDirectories, 'payload directory');
-    assertUnique(payloadFiles.map((file) => file.path), 'payload file');
-    return {
-        sourceRunsDir,
-        content: { runs, residuals, payloadDirectories, payloadFiles },
-        copies: copies.sort((a, b) => a.archivePath.localeCompare(b.archivePath)),
-        projections,
-    };
-}
-function assertUnique(values, label) {
-    const seen = new Set();
-    for (const value of values) {
-        if (seen.has(value))
-            fail('DUPLICATE_ARCHIVE_ENTRY', `duplicate ${label}: ${value}`);
-        seen.add(value);
-    }
-}
-function comparableContent(left, right) {
-    return canonicalJsonStringify(left) === canonicalJsonStringify(right);
-}
-export async function planV2RunArchive(input) {
-    const capture = await captureSource(input.runsDir);
-    return {
-        sourceRunsDir: capture.sourceRunsDir,
-        content: capture.content,
-        runCount: capture.content.runs.length,
-        residualCount: capture.content.residuals.length,
-        totalPayloadBytes: capture.content.payloadFiles.reduce((sum, file) => sum + file.bytes, 0),
-    };
-}
-function materializePayload(payloadRoot, capture) {
-    ensurePrivateDirectory(payloadRoot);
-    for (const directory of capture.content.payloadDirectories) {
-        assertSafeRelativePath(directory, 'payload directory');
-        const absolute = join(payloadRoot, ...directory.split('/'));
-        assertPathInside(payloadRoot, absolute, 'payload directory');
-        mkdirSync(absolute, { recursive: true, mode: 0o700 });
-        chmodSync(absolute, 0o700);
-    }
-    for (const copy of capture.copies)
-        copyRegularFileSecure(copy, payloadRoot);
-    for (const [path, projection] of capture.projections) {
-        const absolute = join(payloadRoot, ...path.split('/'));
-        writeNewPrivateFile(absolute, projection);
-    }
-    for (const directory of [...capture.content.payloadDirectories].sort((a, b) => b.split('/').length - a.split('/').length)) {
-        fsyncDirectorySyncPortable(join(payloadRoot, ...directory.split('/')));
-    }
-    fsyncDirectorySyncPortable(payloadRoot);
-}
-function canonicalFile(value) {
-    return Buffer.from(`${canonicalJsonStringify(value)}\n`, 'utf-8');
-}
-function publishCommitMarker(archiveDir, stageDir, marker) {
-    const path = join(archiveDir, COMMIT_FILE);
-    const bytes = canonicalFile(marker);
-    // Keep the link source outside the immutable archive tree. A process crash
-    // after writing this inode but before link/unlink must not leave an extra
-    // file that makes the content-address target unverifiable forever. The
-    // owned staging transaction is safely reclaimed on the next invocation.
-    const tmp = join(stageDir, `COMMITTED.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
-    try {
-        writeNewPrivateFile(tmp, bytes);
-        try {
-            linkSync(tmp, path);
-            unlinkSync(tmp);
-            fsyncDirectorySyncPortable(archiveDir);
-        }
-        catch (err) {
-            if (err.code !== 'EEXIST')
-                throw err;
-            const existing = readSecureFile(path);
-            if (!existing.equals(bytes))
-                fail('COMMIT_MARKER_CONFLICT', `existing ${path} differs from expected marker`);
-            unlinkSync(tmp);
-        }
-    }
-    finally {
-        try {
-            unlinkSync(tmp);
-        }
-        catch { /* best effort */ }
-    }
-}
-function stageMarkerBytes(sourceRunsDir) {
-    return canonicalFile({
-        schemaVersion: 1,
-        kind: V2_RUN_ARCHIVE_KIND,
-        sourceRunsDir,
-    });
-}
-function cleanOwnedStaging(archiveBaseDir) {
-    for (const entry of readdirSync(archiveBaseDir, { withFileTypes: true })) {
-        if (!entry.name.startsWith(STAGING_PREFIX))
-            continue;
-        const path = join(archiveBaseDir, entry.name);
-        const stat = lstatSync(path);
-        if (stat.isSymbolicLink() || !stat.isDirectory()) {
-            fail('UNSAFE_STAGING_ENTRY', `refusing to clean non-directory staging path ${path}`);
-        }
-        const markerPath = join(path, STAGE_MARKER);
-        let parsed;
-        try {
-            parsed = JSON.parse(readSecureFile(markerPath).toString('utf-8'));
-        }
-        catch (err) {
-            fail('UNKNOWN_STAGING_ENTRY', `staging directory lacks a valid ownership marker: ${path} (${err instanceof Error ? err.message : String(err)})`);
-        }
-        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) ||
-            parsed.schemaVersion !== 1 ||
-            parsed.kind !== V2_RUN_ARCHIVE_KIND)
-            fail('UNKNOWN_STAGING_ENTRY', `staging ownership marker is not recognized: ${path}`);
-        rmSync(path, { recursive: true, force: false });
-        fsyncDirectorySyncPortable(archiveBaseDir);
-    }
-}
-function ensureDisjoint(source, archiveBase) {
-    const sourceToArchive = relative(source, archiveBase);
-    const archiveToSource = relative(archiveBase, source);
-    const inside = (rel) => rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
-    if (inside(sourceToArchive) || inside(archiveToSource)) {
-        fail('ARCHIVE_SOURCE_OVERLAP', `source and archive directories must be disjoint: ${source} <> ${archiveBase}`);
-    }
-}
-/** Resolve a path that may not exist yet without creating any ancestor. */
-function realpathProspective(path) {
-    let cursor = resolve(path);
-    const missing = [];
-    while (true) {
-        try {
-            const stat = lstatSync(cursor);
-            if (stat.isSymbolicLink()) {
-                // realpath below is allowed to resolve existing ancestors, but the
-                // archive base itself must never be a symlink.
-                if (missing.length === 0)
-                    fail('ARCHIVE_BASE_SYMLINK', `archive base must not be a symlink: ${cursor}`);
-                const realAncestor = realpathSync(cursor);
-                if (!lstatSync(realAncestor).isDirectory()) {
-                    fail('ARCHIVE_PARENT_INVALID', `archive symlink ancestor is not a directory: ${cursor}`);
-                }
-                return join(realAncestor, ...missing);
-            }
-            if (!stat.isDirectory())
-                fail('ARCHIVE_PARENT_INVALID', `archive parent is not a directory: ${cursor}`);
-            return join(realpathSync(cursor), ...missing);
-        }
-        catch (err) {
-            if (err instanceof V2RunArchiveError)
-                throw err;
-            if (err.code !== 'ENOENT')
-                throw err;
-            const parent = dirname(cursor);
-            if (parent === cursor)
-                throw err;
-            missing.unshift(basename(cursor));
-            cursor = parent;
-        }
-    }
-}
-export async function commitV2RunArchive(input) {
-    const archiveBaseDir = resolve(input.archiveBaseDir);
-    // Preflight overlap before *any* archive mkdir/chmod/lock write.  Resolve
-    // the nearest existing archive ancestor so a symlinked parent cannot hide
-    // that the requested output actually lives inside the source tree.
-    const sourceInput = resolve(input.runsDir);
-    assertPlainDirectory(sourceInput, 'workflow runs root');
-    const sourceReal = realpathSync(sourceInput);
-    ensureDisjoint(sourceInput, archiveBaseDir);
-    ensureDisjoint(sourceReal, realpathProspective(archiveBaseDir));
-    ensurePrivateArchiveBase(archiveBaseDir);
-    return withV2RunArchivePublicationLock(archiveBaseDir, async () => {
-        cleanOwnedStaging(archiveBaseDir);
-        const first = await captureSource(input.runsDir);
-        ensureDisjoint(first.sourceRunsDir, archiveBaseDir);
-        await input.onPhase?.('after-first-capture');
-        const stageDir = join(archiveBaseDir, `${STAGING_PREFIX}${process.pid}-${randomBytes(8).toString('hex')}`);
-        mkdirSync(stageDir, { mode: 0o700 });
-        chmodSync(stageDir, 0o700);
-        writeNewPrivateFile(join(stageDir, STAGE_MARKER), stageMarkerBytes(first.sourceRunsDir));
-        const payloadRoot = join(stageDir, 'payload');
-        materializePayload(payloadRoot, first);
-        await input.onPhase?.('after-copy');
-        const second = await captureSource(first.sourceRunsDir);
-        if (!comparableContent(first.content, second.content)) {
-            fail('SOURCE_CHANGED_DURING_ARCHIVE', 'source tree or live projection changed between the two captures');
-        }
-        await input.onPhase?.('after-second-capture');
-        const archiveId = v2RunArchiveId(first.content);
-        const manifest = {
-            schemaVersion: V2_RUN_ARCHIVE_SCHEMA_VERSION,
-            kind: V2_RUN_ARCHIVE_KIND,
-            archiveId,
-            createdAt: (input.now ?? new Date()).toISOString(),
-            sourceRunsDir: first.sourceRunsDir,
-            containsSensitiveData: true,
-            content: first.content,
-        };
-        // Validate the exact persisted shape before publication; a path-length or
-        // enum drift must strand only staging bytes, never an unopenable archive.
-        parseV2RunArchiveManifest(manifest);
-        const manifestBytes = canonicalFile(manifest);
-        writeNewPrivateFile(join(payloadRoot, MANIFEST_FILE), manifestBytes);
-        fsyncDirectorySyncPortable(payloadRoot);
-        await input.onPhase?.('after-manifest');
-        const archiveDir = join(archiveBaseDir, archiveDirectoryName(archiveId));
-        let reused = false;
-        try {
-            const existing = lstatSync(archiveDir);
-            if (existing.isSymbolicLink() || !existing.isDirectory()) {
-                fail('ARCHIVE_TARGET_UNSAFE', `content-address target is not a real directory: ${archiveDir}`);
-            }
-            const existingVerification = await verifyV2RunArchive({
-                archiveDir,
-                allowMissingCommitMarker: true,
-            });
-            if (!comparableContent(existingVerification.manifest.content, manifest.content)) {
-                fail('ARCHIVE_TARGET_CONFLICT', `existing content-address target does not match ${archiveId}`);
-            }
-            reused = true;
-        }
-        catch (err) {
-            if (err.code !== 'ENOENT')
-                throw err;
-            renameSync(payloadRoot, archiveDir);
-            fsyncDirectorySyncPortable(archiveBaseDir);
-        }
-        await input.onPhase?.('after-publish');
-        const publishedManifestBytes = readSecureFile(join(archiveDir, MANIFEST_FILE));
-        const marker = {
-            schemaVersion: V2_RUN_ARCHIVE_COMMIT_SCHEMA_VERSION,
-            archiveId,
-            manifestSha256: sha256Ref(publishedManifestBytes),
-        };
-        publishCommitMarker(archiveDir, stageDir, marker);
-        await input.onPhase?.('after-commit-marker');
-        try {
-            rmSync(stageDir, { recursive: true, force: true });
-        }
-        catch { /* committed archive is already durable */ }
-        fsyncDirectorySyncPortable(archiveBaseDir);
-        const verification = await verifyV2RunArchive({
-            archiveDir,
-            sourceRunsDir: first.sourceRunsDir,
-        });
-        return { archiveDir, manifest: verification.manifest, reused, verification };
-    });
-}
-function walkArchiveTree(root) {
-    assertPlainDirectory(root, 'archive root');
-    const directories = [];
-    const files = [];
-    const visit = (dir, relDir) => {
-        assertPlainDirectory(dir, 'archive directory');
-        assertPrivateMode(dir, 0o700, 'archive directory');
-        for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-            if (entry.name.includes('/') || entry.name.includes('\\') || entry.name === '.' || entry.name === '..') {
-                fail('UNSAFE_ARCHIVE_ENTRY', `unsafe archive entry name in ${dir}: ${entry.name}`);
-            }
-            const absolute = join(dir, entry.name);
-            const rel = relDir ? posix.join(relDir, entry.name) : entry.name;
-            assertSafeRelativePath(rel, 'archive entry');
-            const stat = lstatSync(absolute);
-            if (stat.isSymbolicLink())
-                fail('ARCHIVE_SYMLINK', `archive contains symlink: ${absolute}`);
-            if (stat.isDirectory()) {
-                directories.push(rel);
-                visit(absolute, rel);
-            }
-            else if (stat.isFile()) {
-                if (stat.nlink !== 1)
-                    fail('ARCHIVE_HARDLINK', `archive contains hard-linked file: ${absolute}`);
-                assertPrivateMode(absolute, 0o600, 'archive file');
-                files.push(rel);
-            }
-            else {
-                fail('ARCHIVE_SPECIAL_ENTRY', `archive contains special filesystem entry: ${absolute}`);
-            }
-        }
-    };
-    visit(root, '');
-    return { directories: directories.sort(), files: files.sort() };
-}
-function assertProjectionMatchesVerdict(archiveDir, run) {
-    const path = join(archiveDir, ...run.projectionPath.split('/'));
-    let projection;
-    try {
-        projection = JSON.parse(readSecureFile(path).toString('utf-8'));
-    }
-    catch (err) {
-        fail('ARCHIVE_PROJECTION_INVALID', `${path}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (projection.runId !== run.runId || projection.run.runId !== run.runId ||
-        projection.run.status !== run.verdict.status ||
-        (projection.run.workflowId ?? 'unknown') !== run.verdict.workflowId ||
-        projection.lastSeq !== run.verdict.lastSeq || projection.updatedAt !== run.verdict.updatedAt)
-        fail('ARCHIVE_VERDICT_MISMATCH', `projection and manifest verdict disagree for ${run.runId}`);
-}
-function optionalLstat(path) {
-    try {
-        return lstatSync(path);
-    }
-    catch (err) {
-        if (err.code === 'ENOENT')
-            return undefined;
-        throw err;
-    }
-}
-function archiveHex(archiveId) {
-    const match = /^sha256:([0-9a-f]{64})$/.exec(archiveId);
-    if (!match)
-        fail('ARCHIVE_ID_INVALID', `invalid archive id ${archiveId}`);
-    return match[1];
-}
-function quarantinePathFor(sourceRunsDir, archiveId) {
-    return join(dirname(sourceRunsDir), `.${basename(sourceRunsDir)}.retired-${archiveHex(archiveId)}`);
-}
-function retirementReceiptPathFor(archiveBaseDir, archiveId) {
-    return join(resolve(archiveBaseDir), `${RETIREMENT_RECEIPT_PREFIX}${archiveHex(archiveId)}.json`);
-}
-function hasRetirementArtifacts(sourcePath, archiveBaseDir) {
-    const quarantinePrefix = `.${basename(sourcePath)}.retired-`;
-    const sourceParent = dirname(sourcePath);
-    const checks = [
-        { directory: sourceParent, prefix: quarantinePrefix, label: 'quarantine' },
-        { directory: archiveBaseDir, prefix: RETIREMENT_RECEIPT_PREFIX, label: 'receipt' },
-    ];
-    let found = false;
-    for (const check of checks) {
-        const stat = optionalLstat(check.directory);
-        if (!stat)
-            continue;
-        if (stat.isSymbolicLink() || !stat.isDirectory()) {
-            fail('RETIREMENT_PARENT_UNSAFE', `${check.label} parent must be a real directory: ${check.directory}`);
-        }
-        for (const entry of readdirSync(check.directory, { withFileTypes: true })) {
-            if (!entry.name.startsWith(check.prefix))
-                continue;
-            const path = join(check.directory, entry.name);
-            const artifact = lstatSync(path);
-            if (artifact.isSymbolicLink() || (!artifact.isDirectory() && !artifact.isFile())) {
-                fail('RETIREMENT_ARTIFACT_UNSAFE', `unsafe ${check.label} artifact: ${path}`);
-            }
-            found = true;
-        }
-    }
-    return found;
-}
-function expectedRawTree(manifest, rawRoot) {
-    if (!manifest.content.payloadDirectories.includes(rawRoot)) {
-        fail('ARCHIVE_RAW_ROOT_MISSING', `manifest does not contain raw root ${rawRoot}`);
-    }
-    const prefix = `${rawRoot}/`;
-    return {
-        directories: manifest.content.payloadDirectories
-            .filter((path) => path.startsWith(prefix))
-            .map((path) => path.slice(prefix.length))
-            .sort(),
-        files: manifest.content.payloadFiles
-            .filter((file) => file.path.startsWith(prefix))
-            .map((file) => ({
-            relativePath: file.path.slice(prefix.length),
-            bytes: file.bytes,
-            sha256: file.sha256,
-        }))
-            .sort((a, b) => a.relativePath.localeCompare(b.relativePath)),
-    };
-}
-function comparableRawTree(tree) {
-    return canonicalJsonStringify({
-        directories: tree.directories,
-        files: tree.files.map(({ relativePath, bytes, sha256 }) => ({ relativePath, bytes, sha256 })),
-    });
-}
-/**
- * Verify relocated bytes without replaying projections.
- *
- * Historical OutputRef.outputPath values are absolute and intentionally
- * remain byte-exact inside the quarantine. Replaying them after rename would
- * reinterpret those paths relative to the new root and create false drift.
- * The two pre-rename source-aware passes already prove projection parity;
- * post-rename recovery must instead prove the complete raw topology/hashes.
- */
-function verifyRelocatedRawSourceAgainstManifest(sourceDir, manifest) {
-    assertPlainDirectory(sourceDir, 'retired workflow runs root');
-    const expected = new Map();
-    for (const run of manifest.content.runs) {
-        if (expected.has(run.runId))
-            fail('ARCHIVE_SOURCE_TOPOLOGY_MISMATCH', `duplicate source entry ${run.runId}`);
-        expected.set(run.runId, { sourceType: 'directory', rawRoot: run.rawRoot });
-    }
-    for (const residual of manifest.content.residuals) {
-        if (expected.has(residual.name))
-            fail('ARCHIVE_SOURCE_TOPOLOGY_MISMATCH', `duplicate source entry ${residual.name}`);
-        expected.set(residual.name, { sourceType: residual.sourceType, rawRoot: residual.rawRoot });
-    }
-    const actualNames = readdirSync(sourceDir, { withFileTypes: true })
-        .map((entry) => entry.name)
-        .sort();
-    const expectedNames = [...expected.keys()].sort();
-    if (canonicalJsonStringify(actualNames) !== canonicalJsonStringify(expectedNames)) {
-        fail('ARCHIVE_SOURCE_TOPOLOGY_MISMATCH', 'retired source top-level entries differ from manifest');
-    }
-    for (const name of expectedNames) {
-        const spec = expected.get(name);
-        const path = join(sourceDir, name);
-        const stat = lstatSync(path);
-        if (stat.isSymbolicLink())
-            fail('SOURCE_SYMLINK', `retired source contains symlink: ${path}`);
-        let captured;
-        if (spec.sourceType === 'directory') {
-            if (!stat.isDirectory())
-                fail('ARCHIVE_SOURCE_TOPOLOGY_MISMATCH', `${name} must remain a directory`);
-            captured = captureDirectoryTree(path);
-        }
-        else {
-            if (!stat.isFile())
-                fail('ARCHIVE_SOURCE_TOPOLOGY_MISMATCH', `${name} must remain a regular file`);
-            captured = captureTopFile(path, name);
-        }
-        const expectedTree = expectedRawTree(manifest, spec.rawRoot);
-        if (comparableRawTree(captured) !== canonicalJsonStringify(expectedTree)) {
-            fail('ARCHIVE_SOURCE_CHANGED', `retired source bytes/topology differ for ${name}`);
-        }
-    }
-}
-function readRetirementReceipt(path) {
-    const stat = lstatSync(path);
-    if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) {
-        fail('RETIREMENT_RECEIPT_UNSAFE', `receipt must be a single-link regular file: ${path}`);
-    }
-    assertPrivateMode(path, 0o600, 'retirement receipt');
-    try {
-        return parseV2RunRetirementReceipt(JSON.parse(readSecureFile(path).toString('utf-8')));
-    }
-    catch (err) {
-        if (err instanceof V2RunArchiveError)
-            throw err;
-        fail('RETIREMENT_RECEIPT_INVALID', `${path}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-function assertReceiptMatches(receipt, expected) {
-    for (const key of [
-        'schemaVersion',
-        'kind',
-        'archiveId',
-        'manifestSha256',
-        'sourceRunsDir',
-        'quarantineDir',
-    ]) {
-        if (receipt[key] !== expected[key]) {
-            fail('RETIREMENT_RECEIPT_CONFLICT', `receipt ${key} does not match the verified retirement`);
-        }
-    }
-}
-function publishRetirementReceipt(receiptPath, expected, now) {
-    const existing = optionalLstat(receiptPath);
-    if (existing) {
-        const receipt = readRetirementReceipt(receiptPath);
-        assertReceiptMatches(receipt, expected);
-        return { receipt, reused: true };
-    }
-    const receipt = {
-        ...expected,
-        retiredAt: now.toISOString(),
-    };
-    parseV2RunRetirementReceipt(receipt);
-    const bytes = canonicalFile(receipt);
-    const tmp = join(dirname(receiptPath), `.${basename(receiptPath)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
-    try {
-        writeNewPrivateFile(tmp, bytes);
-        try {
-            linkSync(tmp, receiptPath);
-            unlinkSync(tmp);
-            fsyncDirectorySyncPortable(dirname(receiptPath));
-            return { receipt, reused: false };
-        }
-        catch (err) {
-            if (err.code !== 'EEXIST')
-                throw err;
-            unlinkSync(tmp);
-            const raced = readRetirementReceipt(receiptPath);
-            assertReceiptMatches(raced, expected);
-            return { receipt: raced, reused: true };
-        }
-    }
-    finally {
-        try {
-            unlinkSync(tmp);
-        }
-        catch { /* best effort */ }
-    }
-}
-/**
- * Linearize v2 run-source retirement without deleting bytes.
- *
- * The advisory publication lock coordinates Botmux archive/retire commands,
- * but it cannot stop an old daemon from appending to an already-open journal.
- * Therefore non-empty retirement additionally requires an explicit operator
- * acknowledgement that all v2 writers are stopped, verifies source parity
- * twice immediately before rename, and verifies the relocated tree once more.
- */
-export async function retireV2RunSource(input) {
-    const archiveBaseDir = resolve(input.archiveBaseDir);
-    const sourceInput = resolve(input.runsDir);
-    const archiveDir = resolve(input.archiveDir);
-    const initialSourceStat = optionalLstat(sourceInput);
-    if (initialSourceStat && (initialSourceStat.isSymbolicLink() || !initialSourceStat.isDirectory())) {
-        fail('UNSAFE_DIRECTORY', `workflow runs root must be a real directory: ${sourceInput}`);
-    }
-    const initiallyEmpty = !initialSourceStat || readdirSync(sourceInput).length === 0;
-    // A fresh install has no archive contract to verify and retirement should
-    // be a genuine zero-write no-op. Only enter the publication transaction
-    // when live bytes or a prior quarantine/receipt prove there is work.
-    if (initiallyEmpty && !hasRetirementArtifacts(sourceInput, archiveBaseDir)) {
-        return { status: 'nothing_to_retire', sourceRunsDir: realpathProspective(sourceInput) };
-    }
-    ensureDisjoint(sourceInput, archiveBaseDir);
-    ensureDisjoint(realpathProspective(sourceInput), realpathProspective(archiveBaseDir));
-    ensurePrivateArchiveBase(archiveBaseDir);
-    return withV2RunArchivePublicationLock(archiveBaseDir, async () => {
-        const archiveStat = optionalLstat(archiveDir);
-        const sourceStat = optionalLstat(sourceInput);
-        if (sourceStat && (sourceStat.isSymbolicLink() || !sourceStat.isDirectory())) {
-            fail('UNSAFE_DIRECTORY', `workflow runs root must be a real directory: ${sourceInput}`);
-        }
-        if (!archiveStat) {
-            if (!sourceStat || readdirSync(sourceInput).length === 0) {
-                fail('RETIREMENT_STATE_REQUIRES_ARCHIVE', 'found a retirement quarantine/receipt but the referenced committed archive is missing');
-            }
-            fail('RETIREMENT_ARCHIVE_REQUIRED', `non-empty v2 source requires a committed archive: ${archiveDir}`);
-        }
-        if (archiveStat.isSymbolicLink() || !archiveStat.isDirectory()) {
-            fail('ARCHIVE_TARGET_UNSAFE', `retirement archive must be a real directory: ${archiveDir}`);
-        }
-        if (dirname(archiveDir) !== archiveBaseDir) {
-            fail('RETIREMENT_ARCHIVE_OUTSIDE_BASE', `retirement archive must be a direct child of ${archiveBaseDir}`);
-        }
-        const staticVerification = await verifyV2RunArchive({ archiveDir });
-        const manifest = staticVerification.manifest;
-        const expectedSourcePath = realpathProspective(sourceInput);
-        if (expectedSourcePath !== manifest.sourceRunsDir) {
-            fail('ARCHIVE_SOURCE_MISMATCH', `manifest source ${manifest.sourceRunsDir} != requested source ${expectedSourcePath}`);
-        }
-        const quarantineDir = quarantinePathFor(manifest.sourceRunsDir, manifest.archiveId);
-        const receiptPath = retirementReceiptPathFor(archiveBaseDir, manifest.archiveId);
-        const quarantineStat = optionalLstat(quarantineDir);
-        const receiptStat = optionalLstat(receiptPath);
-        if (quarantineStat && (quarantineStat.isSymbolicLink() || !quarantineStat.isDirectory())) {
-            fail('RETIREMENT_QUARANTINE_UNSAFE', `quarantine must be a real directory: ${quarantineDir}`);
-        }
-        if (receiptStat && (receiptStat.isSymbolicLink() || !receiptStat.isFile() || receiptStat.nlink !== 1)) {
-            fail('RETIREMENT_RECEIPT_UNSAFE', `receipt must be a single-link regular file: ${receiptPath}`);
-        }
-        if (sourceStat && quarantineStat) {
-            fail('RETIREMENT_SOURCE_RESURRECTED', `source and quarantine both exist; an old writer may still be active`);
-        }
-        if ((!sourceStat || readdirSync(sourceInput).length === 0) &&
-            !quarantineStat && !receiptStat &&
-            hasRetirementArtifacts(sourceInput, archiveBaseDir)) {
-            fail('RETIREMENT_STATE_REQUIRES_ARCHIVE', 'existing retirement artifacts do not belong to the selected committed archive');
-        }
-        if (sourceStat && readdirSync(sourceInput).length === 0) {
-            if (receiptStat)
-                fail('RETIREMENT_RECEIPT_WITH_LIVE_SOURCE', `receipt exists while source directory is present`);
-            return { status: 'nothing_to_retire', sourceRunsDir: realpathSync(sourceInput) };
-        }
-        if (!sourceStat && !quarantineStat) {
-            if (receiptStat)
-                fail('RETIREMENT_QUARANTINE_MISSING', `receipt exists but quarantine is missing`);
-            return { status: 'nothing_to_retire', sourceRunsDir: expectedSourcePath };
-        }
-        if (!input.daemonStoppedAcknowledged) {
-            fail('DAEMON_STOP_ACK_REQUIRED', 'non-empty v2 retirement requires --ack-daemon-stopped; the archive lock does not exclude old daemon writers');
-        }
-        const manifestSha256 = sha256Ref(readSecureFile(join(archiveDir, MANIFEST_FILE)));
-        const expectedReceipt = {
-            schemaVersion: V2_RUN_RETIREMENT_SCHEMA_VERSION,
-            kind: V2_RUN_RETIREMENT_KIND,
-            archiveId: manifest.archiveId,
-            manifestSha256,
-            sourceRunsDir: manifest.sourceRunsDir,
-            quarantineDir,
-        };
-        if (!sourceStat) {
-            verifyRelocatedRawSourceAgainstManifest(quarantineDir, manifest);
-            chmodSync(quarantineDir, 0o700);
-            fsyncDirectorySyncPortable(dirname(quarantineDir));
-            const published = publishRetirementReceipt(receiptPath, expectedReceipt, input.now ?? new Date());
-            await input.onPhase?.('after-retirement-receipt');
-            return {
-                status: published.reused ? 'already_retired' : 'retired',
-                archiveDir,
-                quarantineDir,
-                receiptPath,
-                receipt: published.receipt,
-                verification: { ...staticVerification, sourceVerified: true },
-            };
-        }
-        if (receiptStat) {
-            fail('RETIREMENT_RECEIPT_WITH_LIVE_SOURCE', `receipt exists while source directory is present`);
-        }
-        await verifyV2RunArchive({
-            archiveDir,
-            sourceRunsDir: sourceInput,
-        });
-        await input.onPhase?.('after-first-source-verification');
-        const secondVerification = await verifyV2RunArchive({
-            archiveDir,
-            sourceRunsDir: sourceInput,
-        });
-        await input.onPhase?.('before-source-rename');
-        renameSync(sourceInput, quarantineDir);
-        fsyncDirectorySyncPortable(dirname(sourceInput));
-        await input.onPhase?.('after-source-rename');
-        chmodSync(quarantineDir, 0o700);
-        verifyRelocatedRawSourceAgainstManifest(quarantineDir, manifest);
-        fsyncDirectorySyncPortable(dirname(quarantineDir));
-        await input.onPhase?.('after-quarantine-verification');
-        const published = publishRetirementReceipt(receiptPath, expectedReceipt, input.now ?? new Date());
-        await input.onPhase?.('after-retirement-receipt');
-        return {
-            status: 'retired',
-            archiveDir,
-            quarantineDir,
-            receiptPath,
-            receipt: published.receipt,
-            verification: secondVerification,
-        };
-    });
-}
-export async function verifyV2RunArchive(input) {
-    const archiveDir = resolve(input.archiveDir);
-    assertPlainDirectory(archiveDir, 'archive root');
-    const manifestPath = join(archiveDir, MANIFEST_FILE);
-    const manifestBytes = readSecureFile(manifestPath);
-    let manifest;
-    try {
-        manifest = parseV2RunArchiveManifest(JSON.parse(manifestBytes.toString('utf-8')));
-    }
-    catch (err) {
-        fail('ARCHIVE_MANIFEST_INVALID', `${manifestPath}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (v2RunArchiveId(manifest.content) !== manifest.archiveId) {
-        fail('ARCHIVE_ID_MISMATCH', `manifest content does not derive ${manifest.archiveId}`);
-    }
-    if (basename(archiveDir) !== archiveDirectoryName(manifest.archiveId)) {
-        fail('ARCHIVE_DIRECTORY_MISMATCH', `archive directory name does not match ${manifest.archiveId}`);
-    }
-    assertUnique(manifest.content.payloadDirectories, 'manifest payload directory');
-    assertUnique(manifest.content.payloadFiles.map((file) => file.path), 'manifest payload file');
-    assertUnique(manifest.content.runs.map((run) => run.runId), 'manifest runId');
-    assertUnique(manifest.content.residuals.map((residual) => residual.name), 'manifest residual name');
-    const tree = walkArchiveTree(archiveDir);
-    const expectedDirectories = [...manifest.content.payloadDirectories].sort();
-    if (canonicalJsonStringify(tree.directories) !== canonicalJsonStringify(expectedDirectories)) {
-        fail('ARCHIVE_DIRECTORY_TOPOLOGY_MISMATCH', 'archive directory topology differs from manifest');
-    }
-    const expectedFiles = [...manifest.content.payloadFiles.map((file) => file.path), MANIFEST_FILE];
-    const hasCommitMarker = tree.files.includes(COMMIT_FILE);
-    if (hasCommitMarker)
-        expectedFiles.push(COMMIT_FILE);
-    if (!hasCommitMarker && !input.allowMissingCommitMarker) {
-        fail('ARCHIVE_NOT_COMMITTED', `${archiveDir} has no ${COMMIT_FILE} marker`);
-    }
-    expectedFiles.sort();
-    if (canonicalJsonStringify(tree.files) !== canonicalJsonStringify(expectedFiles)) {
-        fail('ARCHIVE_FILE_TOPOLOGY_MISMATCH', 'archive file topology differs from manifest');
-    }
-    let totalBytes = 0;
-    for (const expected of manifest.content.payloadFiles) {
-        const absolute = join(archiveDir, ...expected.path.split('/'));
-        assertPathInside(archiveDir, absolute, 'manifest payload file');
-        const actual = hashSecureFile(absolute);
-        if (actual.bytes !== expected.bytes || actual.sha256 !== expected.sha256) {
-            fail('ARCHIVE_FILE_HASH_MISMATCH', `${expected.path} differs from its manifest digest`);
-        }
-        totalBytes += actual.bytes;
-    }
-    for (const run of manifest.content.runs) {
-        const projected = manifest.content.payloadFiles.find((file) => file.path === run.projectionPath);
-        if (!projected || projected.sha256 !== run.projectionSha256) {
-            fail('ARCHIVE_PROJECTION_HASH_MISMATCH', `projection file record is inconsistent for ${run.runId}`);
-        }
-        assertProjectionMatchesVerdict(archiveDir, run);
-    }
-    if (hasCommitMarker) {
-        let marker;
-        try {
-            marker = parseV2RunArchiveCommitMarker(JSON.parse(readSecureFile(join(archiveDir, COMMIT_FILE)).toString('utf-8')));
-        }
-        catch (err) {
-            fail('COMMIT_MARKER_INVALID', `${archiveDir}: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        if (marker.archiveId !== manifest.archiveId || marker.manifestSha256 !== sha256Ref(manifestBytes)) {
-            fail('COMMIT_MARKER_MISMATCH', `${COMMIT_FILE} does not authenticate manifest.json`);
-        }
-    }
-    let sourceVerified = false;
-    if (input.sourceRunsDir) {
-        const live = await captureSource(input.sourceRunsDir);
-        if (live.sourceRunsDir !== manifest.sourceRunsDir) {
-            fail('ARCHIVE_SOURCE_MISMATCH', `manifest source ${manifest.sourceRunsDir} != live source ${live.sourceRunsDir}`);
-        }
-        if (!comparableContent(live.content, manifest.content)) {
-            fail('ARCHIVE_SOURCE_CHANGED', 'live source bytes or current ops projections differ from the archive');
-        }
-        sourceVerified = true;
-    }
-    return {
-        archiveDir,
-        manifest,
-        staticVerified: true,
-        sourceVerified,
-        fileCount: manifest.content.payloadFiles.length,
-        totalBytes,
-    };
-}
-//# sourceMappingURL=v2-run-archive.js.map