swarm-deploy 0.3.1 → 0.4.2

package/dist/storage/reset.js

@@ -0,0 +1,667 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARCHIVE_LEGACY_MARKER_NAME = exports.ARCHIVE_MARKER_NAME = exports.ARCHIVE_DIRECTORY_NAME = exports.METADATA_DIRECTORIES = void 0;
+exports.inspectStorageReset = inspectStorageReset;
+exports.resetStorage = resetStorage;
+const b4a_1 = __importDefault(require("b4a"));
+const error_code_js_1 = require("../error-code.js");
+const _fs_1 = __importDefault(require("#fs"));
+const _path_1 = __importDefault(require("#path"));
+const _process_1 = __importDefault(require("#process"));
+const sodium_native_1 = __importDefault(require("sodium-native"));
+const errors_js_1 = require("../errors.js");
+const hash_js_1 = require("../tar-protocol/hash.js");
+const atomic_file_js_1 = require("./atomic-file.js");
+const commit_journal_js_1 = require("./commit-journal.js");
+const layout_js_1 = require("./layout.js");
+/** Every private metadata directory a reset archives, in archive order. */
+exports.METADATA_DIRECTORIES = [
+    'staging',
+    'sessions',
+    'commits',
+    'journals',
+    'publications',
+    'links',
+    'trash'
+];
+exports.ARCHIVE_DIRECTORY_NAME = 'archive';
+exports.ARCHIVE_MARKER_NAME = 'reset.json';
+/** Verbatim copy of a version 1 marker, kept when a retry upgrades it to the bounded format. */
+exports.ARCHIVE_LEGACY_MARKER_NAME = 'reset.v1.json';
+const ARCHIVE_LOCKS_NAME = 'locks';
+/** The pending pointer is fixed-size: a kind, a version, and one archive name. */
+const MAX_PENDING_BYTES = 16 * 1024;
+/**
+ * Read bound for archive markers. Version 1 markers listed every lock residue
+ * entry and so grew without limit; the shared metadata bound keeps those
+ * readable while still capping allocation.
+ */
+const MAX_ARCHIVE_MARKER_BYTES = atomic_file_js_1.MAX_SESSION_METADATA_BYTES;
+/**
+ * Write bound for archive markers. The capped fields below keep the worst case
+ * (a 4 KiB root and sixteen fully escaped failures) far inside this, so
+ * reaching it is a programming error, never an operating condition.
+ */
+const MAX_MARKER_WRITE_BYTES = 64 * 1024;
+const MARKER_VERSION = 2;
+/** Newest attempts kept in a marker; the first is the top-level `startedAt`/`pid`. */
+const MAX_ATTEMPTS_KEPT = 16;
+const MAX_FAILURE_CHARS = 256;
+/** Lock residue moves between marker writes; the archive itself is the exact record. */
+const LOCK_PROGRESS_BATCH = 32;
+const MAX_LINK_RECORD_BYTES = 4 * 1024;
+const DEFAULT_POLL_INTERVAL = 250;
+const METADATA_RECORD = /^[0-9a-f]{64}\.json$/;
+const ARCHIVE_NAME = /^reset-[0-9TZ]+-[0-9a-f]+$/;
+/** Lock residue no running server can own: retired tombstones and abandoned candidates. */
+const OBSOLETE_LOCK = /^lock\.(?:retired|candidate)-[0-9a-f]+$/;
+function storageError(message, cause = null) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, message, cause);
+}
+function busyError(message) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, message);
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function randomSuffix(bytes = 4) {
+    const buffer = b4a_1.default.allocUnsafe(bytes);
+    sodium_native_1.default.randombytes_buf(buffer);
+    return b4a_1.default.toString(buffer, 'hex');
+}
+function settle({ storageDir, wait = 0, storage = _fs_1.default.promises, isProcessAlive = layout_js_1.isProcessAlive, clock = Date, pid = _process_1.default.pid, pollInterval = DEFAULT_POLL_INTERVAL, sleep = defaultSleep }) {
+    const layout = (0, layout_js_1.resolveLayout)(storageDir);
+    if (!Number.isSafeInteger(wait) || wait < 0)
+        throw storageError('Invalid reset wait');
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw storageError('Invalid reset PID');
+    if (!Number.isSafeInteger(pollInterval) || pollInterval <= 0) {
+        throw storageError('Invalid reset poll interval');
+    }
+    return { layout, storage, isProcessAlive, clock, pid, wait, pollInterval, sleep };
+}
+/** The root must be a real directory that is neither a filesystem root nor the internal directory. */
+function assertSafeRootPath(root) {
+    if (_path_1.default.dirname(root) === root) {
+        throw storageError(`Refusing to reset a filesystem root: ${root}`);
+    }
+    if (_path_1.default.basename(root) === layout_js_1.INTERNAL_DIRECTORY_NAME) {
+        throw storageError(`Refusing to reset an internal directory as a storage root: ${root}`);
+    }
+}
+async function safeDirectoryOrMissing(directory, storage) {
+    try {
+        await (0, layout_js_1.assertSafeDirectory)(directory, storage);
+        return true;
+    }
+    catch (error) {
+        if ((0, error_code_js_1.isMissing)(error))
+            return false;
+        throw error;
+    }
+}
+async function lstatOrNull(target, storage) {
+    try {
+        return await storage.lstat(target);
+    }
+    catch (error) {
+        if ((0, error_code_js_1.errorCode)(error) === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+async function syncDirectory(directory, storage) {
+    const handle = await storage.open(directory, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function validateLayout(layout, storage) {
+    assertSafeRootPath(layout.root);
+    await (0, layout_js_1.assertSafeDirectory)(layout.root, storage);
+    for (let parent = _path_1.default.dirname(layout.root); _path_1.default.dirname(parent) !== parent; parent = _path_1.default.dirname(parent)) {
+        await (0, layout_js_1.assertSafeDirectory)(parent, storage);
+    }
+    try {
+        await (0, layout_js_1.assertSafeDirectory)(layout.internal, storage);
+    }
+    catch (error) {
+        if (!(0, error_code_js_1.isMissing)(error))
+            throw error;
+        throw storageError(`Not an initialized storage root: ${layout.root}`, error);
+    }
+    // A missing metadata directory is an interrupted reset the server recreates;
+    // a symlink or file at one of these paths is unsafe and fails closed.
+    for (const name of exports.METADATA_DIRECTORIES)
+        await safeDirectoryOrMissing(layout[name], storage);
+}
+async function countEntries(directory, storage) {
+    if (!(await safeDirectoryOrMissing(directory, storage)))
+        return 0;
+    return (await storage.readdir(directory)).length;
+}
+async function inspectCommits(layout, storage) {
+    const result = { records: 0, missingPayloads: [], invalid: 0 };
+    if (!(await safeDirectoryOrMissing(layout.commits, storage)))
+        return result;
+    for (const name of (await storage.readdir(layout.commits)).sort()) {
+        if (!METADATA_RECORD.test(name))
+            continue;
+        let recordName;
+        try {
+            const record = (0, commit_journal_js_1.assertCommitRecord)(await (0, atomic_file_js_1.readJson)(_path_1.default.join(layout.commits, name), storage, commit_journal_js_1.MAX_COMMIT_METADATA_BYTES));
+            if (`${record.transferId}.json` !== name)
+                throw storageError('Foreign commit record');
+            recordName = record.name;
+        }
+        catch {
+            result.invalid++;
+            continue;
+        }
+        result.records++;
+        if ((await lstatOrNull(_path_1.default.join(layout.root, recordName), storage)) === null) {
+            result.missingPayloads.push(recordName);
+        }
+    }
+    return result;
+}
+async function inspectLinks(layout, storage) {
+    const result = { records: 0, invalid: 0 };
+    if (!(await safeDirectoryOrMissing(layout.links, storage)))
+        return result;
+    for (const name of (await storage.readdir(layout.links)).sort()) {
+        if (!METADATA_RECORD.test(name))
+            continue;
+        try {
+            await (0, atomic_file_js_1.readJson)(_path_1.default.join(layout.links, name), storage, MAX_LINK_RECORD_BYTES);
+            result.records++;
+        }
+        catch {
+            result.invalid++;
+        }
+    }
+    return result;
+}
+async function inspectRoot(layout, storage) {
+    const remaining = { payloads: [], symlinks: [], other: [] };
+    for (const name of (await storage.readdir(layout.root)).sort()) {
+        if (name === layout_js_1.INTERNAL_DIRECTORY_NAME)
+            continue;
+        const stat = await lstatOrNull(_path_1.default.join(layout.root, name), storage);
+        if (stat === null)
+            continue;
+        if (stat.isSymbolicLink())
+            remaining.symlinks.push(name);
+        else if (stat.isFile() || stat.isDirectory())
+            remaining.payloads.push(name);
+        else
+            remaining.other.push(name);
+    }
+    return remaining;
+}
+async function archiveStatus(archive, storage) {
+    try {
+        const marker = await (0, atomic_file_js_1.readJson)(_path_1.default.join(archive, exports.ARCHIVE_MARKER_NAME), storage, MAX_ARCHIVE_MARKER_BYTES);
+        if (marker.status === 'completed')
+            return 'completed';
+        if (marker.status === 'in-progress')
+            return 'in-progress';
+    }
+    catch { }
+    return 'unknown';
+}
+const NO_HOLDINGS = { directories: [], locks: [] };
+function summarize(held) {
+    return { directories: held.directories, lockEntries: held.locks.length };
+}
+/**
+ * What an archive physically holds: the metadata directories and lock residue
+ * moved into it. This is the truth about a reset's progress; a marker is only
+ * a record of it that a hard stop can leave behind.
+ */
+async function archiveContents(archive, storage) {
+    const names = new Set(await storage.readdir(archive));
+    const held = {
+        directories: exports.METADATA_DIRECTORIES.filter((name) => names.has(name)),
+        locks: []
+    };
+    if (names.has(ARCHIVE_LOCKS_NAME)) {
+        const locks = _path_1.default.join(archive, ARCHIVE_LOCKS_NAME);
+        if (await safeDirectoryOrMissing(locks, storage)) {
+            held.locks = (await storage.readdir(locks)).sort();
+        }
+    }
+    return held;
+}
+/**
+ * SHA-256 over each sorted lock residue name followed by a newline, so an
+ * operator can verify it with `ls locks | LC_ALL=C sort | sha256sum`.
+ */
+function lockDigest(names) {
+    const hash = new hash_js_1.SodiumSha256();
+    for (const name of names)
+        hash.update(b4a_1.default.from(`${name}\n`));
+    return b4a_1.default.toString(hash.digest(), 'hex');
+}
+async function listArchives(layout, storage) {
+    const directory = _path_1.default.join(layout.internal, exports.ARCHIVE_DIRECTORY_NAME);
+    if (!(await safeDirectoryOrMissing(directory, storage)))
+        return [];
+    const archives = [];
+    for (const name of (await storage.readdir(directory)).sort()) {
+        const full = _path_1.default.join(directory, name);
+        const stat = await lstatOrNull(full, storage);
+        if (stat === null || stat.isSymbolicLink() || !stat.isDirectory())
+            continue;
+        archives.push({
+            name,
+            path: full,
+            status: await archiveStatus(full, storage),
+            held: summarize(await archiveContents(full, storage).catch(() => NO_HOLDINGS))
+        });
+    }
+    return archives;
+}
+/**
+ * Reads the pending-reset marker. `archive` is null when the marker exists but
+ * is not one this version wrote, which every caller must treat as unsafe.
+ */
+async function readPendingReset(layout, storage) {
+    const file = _path_1.default.join(layout.internal, layout_js_1.RESET_PENDING_NAME);
+    if ((await lstatOrNull(file, storage)) === null)
+        return { present: false, archive: null };
+    try {
+        const marker = await (0, atomic_file_js_1.readJson)(file, storage, MAX_PENDING_BYTES);
+        if (marker.kind === 'storage-reset' &&
+            marker.version === 1 &&
+            typeof marker.archive === 'string' &&
+            ARCHIVE_NAME.test(marker.archive)) {
+            return { present: true, archive: marker.archive };
+        }
+    }
+    catch { }
+    return { present: true, archive: null };
+}
+async function lockState(settings) {
+    const { layout, storage, isProcessAlive, clock } = settings;
+    const state = await (0, layout_js_1.inspectStorageLock)(layout, storage);
+    if (state.status !== 'held')
+        return state;
+    const ageMs = Math.max(0, clock.now() - state.startedAt);
+    const alive = isProcessAlive(state.pid);
+    return { status: alive ? 'held' : 'stale', pid: state.pid, ageMs };
+}
+async function inspect(settings) {
+    const { layout, storage } = settings;
+    await validateLayout(layout, storage);
+    const metadata = {};
+    for (const name of exports.METADATA_DIRECTORIES) {
+        metadata[name] = await countEntries(layout[name], storage);
+    }
+    let obsoleteLocks = 0;
+    const unknownInternal = [];
+    for (const name of (await storage.readdir(layout.internal)).sort()) {
+        if (exports.METADATA_DIRECTORIES.includes(name))
+            continue;
+        if (name === _path_1.default.basename(layout.lock) ||
+            name === exports.ARCHIVE_DIRECTORY_NAME ||
+            name === layout_js_1.RESET_PENDING_NAME) {
+            continue;
+        }
+        if (OBSOLETE_LOCK.test(name))
+            obsoleteLocks++;
+        else
+            unknownInternal.push(name);
+    }
+    const remaining = await inspectRoot(layout, storage);
+    const pending = await readPendingReset(layout, storage);
+    return {
+        root: layout.root,
+        applied: false,
+        lock: await lockState(settings),
+        metadata,
+        commits: await inspectCommits(layout, storage),
+        links: await inspectLinks(layout, storage),
+        obsoleteLocks,
+        unknownInternal,
+        archives: await listArchives(layout, storage),
+        remaining,
+        resetPending: pending.present,
+        pendingArchive: pending.archive,
+        freshStart: remaining.payloads.length + remaining.symlinks.length + remaining.other.length === 0,
+        archive: null,
+        resumed: null
+    };
+}
+function lockAge(ageMs) {
+    return `${Math.round(ageMs / 1000)}s`;
+}
+/**
+ * Blocks until no live server holds the lock, then takes it. A live holder is
+ * never signalled: this version cannot prove which process owns the root, so
+ * stopping it is the operator's job and the reset only waits for the release.
+ */
+async function acquireExclusive(settings) {
+    const { layout, storage, clock, pid, wait, isProcessAlive, pollInterval, sleep } = settings;
+    const deadline = clock.now() + wait;
+    for (;;) {
+        const state = await lockState(settings);
+        if (state.status === 'unsafe')
+            throw storageError(`Unsafe storage lock path: ${layout.lock}`);
+        if (state.status === 'held') {
+            if (clock.now() >= deadline) {
+                throw busyError(`Storage is locked by pid ${state.pid} (lock age ${lockAge(state.ageMs)}); ` +
+                    'stop that server and retry, or wait for it with --wait');
+            }
+            await sleep(pollInterval);
+            continue;
+        }
+        if (state.status === 'malformed') {
+            throw busyError('Storage lock is unreadable; stop the server and reconcile its lock before resetting');
+        }
+        for (const name of exports.METADATA_DIRECTORIES) {
+            if (!(await safeDirectoryOrMissing(layout[name], storage))) {
+                await storage.mkdir(layout[name], { mode: 0o700 });
+            }
+        }
+        try {
+            return await (0, layout_js_1.acquireStorageLock)(layout, {
+                pid,
+                storage,
+                isProcessAlive
+            });
+        }
+        catch (error) {
+            if ((0, error_code_js_1.errorCode)(error) !== errors_js_1.ERRORS.FILE_BUSY)
+                throw error;
+            if (clock.now() >= deadline)
+                throw busyError('Storage became locked while resetting');
+            await sleep(pollInterval);
+        }
+    }
+}
+async function releaseExclusive(settings, release) {
+    const { layout, storage, pid } = settings;
+    const own = await (0, layout_js_1.inspectStorageLock)(layout, storage).catch(() => null);
+    await release();
+    // Our own retired tombstone is not operator metadata; drop it so the next
+    // preview does not report lock residue this command created.
+    if (own?.status === 'held' && own.pid === pid) {
+        await storage.rm(`${layout.lock}.retired-${own.token}`, { recursive: true, force: true });
+    }
+}
+function archiveName(now) {
+    const stamp = new Date(now).toISOString().replace(/[-:.]/g, '');
+    return `reset-${stamp}-${randomSuffix()}`;
+}
+function isSafeCount(value, minimum) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum;
+}
+function clip(reason) {
+    return reason.length > MAX_FAILURE_CHARS ? `${reason.slice(0, MAX_FAILURE_CHARS - 3)}...` : reason;
+}
+function parseAttempt(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const { startedAt, pid, failed } = value;
+    if (!isSafeCount(startedAt, 0) || !isSafeCount(pid, 1))
+        return null;
+    if (failed === undefined)
+        return { startedAt, pid };
+    return typeof failed === 'string' ? { startedAt, pid, failed: clip(failed) } : null;
+}
+/**
+ * Reads a marker this tool wrote, in the bounded version 2 shape or the
+ * version 1 shape (whose `moved` list held every lock residue entry and whose
+ * latest failure sat beside `attempts`). Returns null for anything else, which
+ * every caller treats as unsafe. Nothing is carried over except these fields.
+ */
+function parseMarker(raw) {
+    if (raw.version !== 1 && raw.version !== MARKER_VERSION)
+        return null;
+    if (raw.status !== 'in-progress' && raw.status !== 'completed')
+        return null;
+    const { root, startedAt, pid } = raw;
+    if (typeof root !== 'string' || !isSafeCount(startedAt, 0) || !isSafeCount(pid, 1))
+        return null;
+    let attempts;
+    if (raw.attempts === undefined) {
+        attempts = [{ startedAt, pid }];
+    }
+    else {
+        if (!Array.isArray(raw.attempts) || raw.attempts.length === 0)
+            return null;
+        attempts = [];
+        for (const entry of raw.attempts) {
+            const attempt = parseAttempt(entry);
+            if (attempt === null)
+                return null;
+            attempts.push(attempt);
+        }
+    }
+    const last = attempts.length - 1;
+    if (typeof raw.failed === 'string' && attempts[last].failed === undefined) {
+        attempts[last] = { ...attempts[last], failed: clip(raw.failed) };
+    }
+    const attemptCount = raw.attemptCount === undefined ? attempts.length : raw.attemptCount;
+    if (!isSafeCount(attemptCount, attempts.length))
+        return null;
+    return { root, startedAt, pid, attempts: attempts.slice(-MAX_ATTEMPTS_KEPT), attemptCount };
+}
+function nextAttempt(state, attempt) {
+    return {
+        ...state,
+        attempts: [...state.attempts, attempt].slice(-MAX_ATTEMPTS_KEPT),
+        attemptCount: state.attemptCount + 1
+    };
+}
+function failLatest(state, reason) {
+    const last = state.attempts.length - 1;
+    return {
+        ...state,
+        attempts: state.attempts.map((attempt, index) => index === last ? { ...attempt, failed: clip(reason) } : attempt)
+    };
+}
+/**
+ * Writes the bounded marker. `moved` names only the metadata directories, at
+ * most seven; lock residue is summarized by a count and a digest of its names,
+ * which stay physically in the archive's `locks/` directory.
+ */
+async function writeMarker(archive, state, status, held, storage, completedAt) {
+    const bytes = b4a_1.default.from(JSON.stringify({
+        version: MARKER_VERSION,
+        status,
+        root: state.root,
+        startedAt: state.startedAt,
+        pid: state.pid,
+        attemptCount: state.attemptCount,
+        attempts: state.attempts,
+        moved: held.directories,
+        locks: { count: held.locks.length, sha256: lockDigest(held.locks) },
+        ...(completedAt === undefined ? {} : { completedAt })
+    }));
+    if (bytes.byteLength > MAX_MARKER_WRITE_BYTES) {
+        throw storageError('Reset marker exceeds its size bound');
+    }
+    await (0, atomic_file_js_1.writeAtomic)(_path_1.default.join(archive, exports.ARCHIVE_MARKER_NAME), bytes, storage);
+}
+/**
+ * Opens the archive a pending reset names so the retry continues it. The archive
+ * must be a plain directory with a marker this tool wrote; anything else means
+ * an operator changed it and the retry fails closed rather than starting a
+ * second archive that would hide where the first one's data went.
+ */
+async function openPendingArchive(archive, storage) {
+    const name = _path_1.default.basename(archive);
+    let raw;
+    try {
+        await (0, layout_js_1.assertSafeDirectory)(archive, storage);
+        raw = await (0, atomic_file_js_1.readJson)(_path_1.default.join(archive, exports.ARCHIVE_MARKER_NAME), storage, MAX_ARCHIVE_MARKER_BYTES);
+    }
+    catch (error) {
+        throw storageError(`Pending reset archive ${name} is missing or unreadable; restore it or reconcile ` +
+            `${layout_js_1.RESET_PENDING_NAME} by hand before resetting`, error);
+    }
+    const state = parseMarker(raw);
+    if (state === null) {
+        throw storageError(`Pending reset archive ${name} has an unrecognized marker; reconcile it before resetting`);
+    }
+    return { raw, state };
+}
+/** Keeps a version 1 marker's full entry list before the bounded format replaces it. */
+async function preserveLegacyMarker(archive, raw, storage) {
+    if (raw.version !== 1)
+        return;
+    const file = _path_1.default.join(archive, exports.ARCHIVE_LEGACY_MARKER_NAME);
+    if ((await lstatOrNull(file, storage)) !== null)
+        return;
+    await (0, atomic_file_js_1.writeAtomic)(file, b4a_1.default.from(JSON.stringify(raw)), storage);
+}
+/**
+ * Archives the metadata, or resumes the archive an interrupted reset left
+ * pending. Every move is a rename, so after a hard stop each directory is
+ * either still live or already inside the archive; progress is therefore
+ * reconciled from what the archive holds, never trusted from the marker.
+ */
+async function archiveMetadata(settings) {
+    const { layout, storage, clock, pid } = settings;
+    const archives = _path_1.default.join(layout.internal, exports.ARCHIVE_DIRECTORY_NAME);
+    if (!(await safeDirectoryOrMissing(archives, storage))) {
+        await storage.mkdir(archives, { mode: 0o700 });
+    }
+    const pendingFile = _path_1.default.join(layout.internal, layout_js_1.RESET_PENDING_NAME);
+    const pending = await readPendingReset(layout, storage);
+    if (pending.present && pending.archive === null) {
+        throw storageError('Unrecognized pending reset marker; reconcile it before resetting');
+    }
+    const startedAt = clock.now();
+    const attempt = { startedAt, pid };
+    let archive;
+    let state;
+    let held = NO_HOLDINGS;
+    let resumed = null;
+    if (pending.archive !== null) {
+        archive = _path_1.default.join(archives, pending.archive);
+        const prior = await openPendingArchive(archive, storage);
+        held = await archiveContents(archive, storage);
+        resumed = summarize(held);
+        // Refuse before moving anything if the archive and the live directory both hold data.
+        for (const name of exports.METADATA_DIRECTORIES) {
+            if (!held.directories.includes(name))
+                continue;
+            await (0, layout_js_1.assertSafeDirectory)(_path_1.default.join(archive, name), storage);
+            if ((await safeDirectoryOrMissing(layout[name], storage)) &&
+                (await storage.readdir(layout[name])).length > 0) {
+                throw storageError(`Reset archive ${pending.archive} already holds ${name} but the live ${name} ` +
+                    'directory is not empty; reconcile the two by hand before resetting');
+            }
+        }
+        await preserveLegacyMarker(archive, prior.raw, storage);
+        state = nextAttempt(prior.state, attempt);
+        await writeMarker(archive, state, 'in-progress', held, storage);
+    }
+    else {
+        archive = _path_1.default.join(archives, archiveName(startedAt));
+        await storage.mkdir(archive, { mode: 0o700 });
+        state = { root: layout.root, startedAt, pid, attempts: [attempt], attemptCount: 1 };
+        await writeMarker(archive, state, 'in-progress', held, storage);
+        await syncDirectory(archives, storage);
+        await (0, atomic_file_js_1.writeAtomic)(pendingFile, b4a_1.default.from(JSON.stringify({ kind: 'storage-reset', version: 1, archive: _path_1.default.basename(archive) })), storage);
+        await syncDirectory(layout.internal, storage);
+    }
+    const recordProgress = async () => {
+        held = await archiveContents(archive, storage);
+        await writeMarker(archive, state, 'in-progress', held, storage);
+    };
+    try {
+        for (const name of exports.METADATA_DIRECTORIES) {
+            const source = layout[name];
+            let live = await safeDirectoryOrMissing(source, storage);
+            if (live && !held.directories.includes(name)) {
+                await storage.rename(source, _path_1.default.join(archive, name));
+                live = false;
+                await recordProgress();
+            }
+            if (!live)
+                await storage.mkdir(source, { mode: 0o700 });
+            await syncDirectory(layout.internal, storage);
+        }
+        const locks = _path_1.default.join(archive, ARCHIVE_LOCKS_NAME);
+        let sinceRecord = 0;
+        for (const name of (await storage.readdir(layout.internal)).sort()) {
+            if (!OBSOLETE_LOCK.test(name))
+                continue;
+            if (!(await safeDirectoryOrMissing(locks, storage))) {
+                await storage.mkdir(locks, { mode: 0o700 });
+            }
+            await storage.rename(_path_1.default.join(layout.internal, name), _path_1.default.join(locks, name));
+            // Residue is recorded in batches: the archive holds the exact list, so a
+            // marker that lags by one batch after a hard stop is reconciled, not trusted.
+            if (++sinceRecord % LOCK_PROGRESS_BATCH === 0)
+                await recordProgress();
+        }
+        await syncDirectory(layout.internal, storage);
+        held = await archiveContents(archive, storage);
+        await writeMarker(archive, state, 'completed', held, storage, clock.now());
+        await syncDirectory(archive, storage);
+        await storage.unlink(pendingFile);
+        await syncDirectory(layout.internal, storage);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const moved = await archiveContents(archive, storage).catch(() => held);
+        await writeMarker(archive, failLatest(state, reason), 'in-progress', moved, storage).catch(() => { });
+        throw error;
+    }
+    return { archive, resumed };
+}
+/** Read-only inspection of a storage root: never creates, moves, or locks anything. */
+function inspectStorageReset(options) {
+    try {
+        return inspect(settle(options));
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+}
+/**
+ * Archives every private metadata directory of a storage root into
+ * `.swarm-deploy/archive/<reset-stamp>/` and recreates them empty, under the
+ * storage lock. Visible payloads and symlinks in the root are never touched,
+ * and nothing is deleted: the archive is restorable by moving it back.
+ */
+async function resetStorage(options) {
+    const settings = settle(options);
+    const { layout, storage } = settings;
+    const preview = await inspect(settings);
+    if (preview.lock.status === 'unsafe') {
+        throw storageError(`Unsafe storage lock path: ${layout.lock}`);
+    }
+    const release = await acquireExclusive(settings);
+    let result;
+    let before;
+    try {
+        before = await inspect(settings);
+        result = await archiveMetadata(settings);
+    }
+    finally {
+        await releaseExclusive(settings, release);
+    }
+    return {
+        ...before,
+        lock: preview.lock,
+        resetPending: false,
+        pendingArchive: null,
+        applied: true,
+        archives: await listArchives(layout, storage),
+        archive: result.archive,
+        resumed: result.resumed
+    };
+}
+//# sourceMappingURL=reset.js.map