@cogcoin/client 0.5.3 → 0.5.4

package/dist/wallet/reset.js

@@ -0,0 +1,781 @@
+import { randomBytes } from "node:crypto";
+import { access, constants, copyFile, mkdir, mkdtemp, readFile, readdir, rename, rm } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { DEFAULT_SNAPSHOT_METADATA } from "../bitcoind/bootstrap/constants.js";
+import { resolveBootstrapPathsForTesting } from "../bitcoind/bootstrap/paths.js";
+import { validateSnapshotFileForTesting } from "../bitcoind/bootstrap/snapshot-file.js";
+import { acquireFileLock } from "./fs/lock.js";
+import { createInternalCoreWalletPassphrase, deriveWalletIdentityMaterial, deriveWalletMaterialFromMnemonic, } from "./material.js";
+import { loadMiningRuntimeStatus } from "./mining/runtime-artifacts.js";
+import { resolveWalletRuntimePathsForTesting } from "./runtime.js";
+import { loadWalletExplicitLock } from "./state/explicit-lock.js";
+import { createDefaultWalletSecretProvider, createWalletRootId, createWalletSecretReference, } from "./state/provider.js";
+import { loadWalletState, saveWalletState } from "./state/storage.js";
+import { confirmTypedAcknowledgement } from "./tx/confirm.js";
+function sanitizeWalletName(walletRootId) {
+    return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
+}
+function isPathWithin(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith("..") && rel !== ".");
+}
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+async function readJsonFileOrNull(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+}
+async function readWalletEnvelope(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+}
+async function loadRawWalletEnvelope(paths) {
+    const primary = await readWalletEnvelope(paths.walletStatePath);
+    if (primary !== null) {
+        return {
+            source: "primary",
+            envelope: primary,
+        };
+    }
+    const backup = await readWalletEnvelope(paths.walletStateBackupPath);
+    if (backup !== null) {
+        return {
+            source: "backup",
+            envelope: backup,
+        };
+    }
+    return null;
+}
+function extractWalletRootIdFromSecretKeyId(keyId) {
+    if (keyId === null) {
+        return null;
+    }
+    const prefix = "wallet-state:";
+    return keyId.startsWith(prefix) ? keyId.slice(prefix.length) : null;
+}
+async function isProcessAlive(pid) {
+    if (pid === null) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return false;
+        }
+        return true;
+    }
+}
+async function waitForProcessExit(pid, timeoutMs = 15_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!await isProcessAlive(pid)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return !await isProcessAlive(pid);
+}
+async function terminateTrackedProcesses(trackedProcesses) {
+    const survivors = new Set();
+    for (const processInfo of trackedProcesses) {
+        try {
+            process.kill(processInfo.pid, "SIGTERM");
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !("code" in error) || error.code !== "ESRCH") {
+                throw error;
+            }
+        }
+    }
+    for (const processInfo of trackedProcesses) {
+        if (!await waitForProcessExit(processInfo.pid, 5_000)) {
+            survivors.add(processInfo.pid);
+        }
+    }
+    for (const pid of survivors) {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !("code" in error) || error.code !== "ESRCH") {
+                throw error;
+            }
+        }
+    }
+    const remaining = new Set();
+    for (const pid of survivors) {
+        if (!await waitForProcessExit(pid, 5_000)) {
+            remaining.add(pid);
+        }
+    }
+    if (remaining.size > 0) {
+        throw new Error("reset_process_shutdown_failed");
+    }
+    return {
+        managedBitcoind: trackedProcesses.filter((processInfo) => processInfo.kind === "managed-bitcoind").length,
+        indexerDaemon: trackedProcesses.filter((processInfo) => processInfo.kind === "indexer-daemon").length,
+        backgroundMining: trackedProcesses.filter((processInfo) => processInfo.kind === "background-mining").length,
+        survivors: 0,
+    };
+}
+async function moveFile(sourcePath, destinationPath) {
+    await mkdir(dirname(destinationPath), { recursive: true });
+    try {
+        await rename(sourcePath, destinationPath);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !("code" in error) || error.code !== "EXDEV") {
+            throw error;
+        }
+        await copyFile(sourcePath, destinationPath);
+        await rm(sourcePath, { force: true });
+    }
+}
+async function stageArtifact(sourcePath, stagingRoot, label) {
+    if (!await pathExists(sourcePath)) {
+        return null;
+    }
+    const stagedPath = join(stagingRoot, label);
+    await moveFile(sourcePath, stagedPath);
+    return {
+        originalPath: sourcePath,
+        stagedPath,
+        restorePath: sourcePath,
+    };
+}
+async function restoreStagedArtifacts(artifacts) {
+    for (const artifact of artifacts) {
+        if (!await pathExists(artifact.stagedPath)) {
+            continue;
+        }
+        await moveFile(artifact.stagedPath, artifact.restorePath);
+    }
+}
+function collectMnemonicDerivedIdentityIndices(state) {
+    const indices = new Set();
+    indices.add(state.fundingIndex);
+    for (const identity of state.identities) {
+        if (identity.status === "funding" || identity.status === "dedicated") {
+            indices.add(identity.index);
+        }
+    }
+    return [...indices].sort((left, right) => left - right);
+}
+function createEntropyRetainedWalletState(previousState, nowUnixMs) {
+    const material = deriveWalletMaterialFromMnemonic(previousState.mnemonic.phrase);
+    const walletRootId = createWalletRootId();
+    const preservedIndices = collectMnemonicDerivedIdentityIndices(previousState);
+    const identities = preservedIndices.map((index) => {
+        if (index === previousState.fundingIndex) {
+            return {
+                index,
+                scriptPubKeyHex: material.funding.scriptPubKeyHex,
+                address: material.funding.address,
+                status: "funding",
+                assignedDomainNames: [],
+            };
+        }
+        const identityMaterial = deriveWalletIdentityMaterial(material.keys.accountXprv, index);
+        return {
+            index,
+            scriptPubKeyHex: identityMaterial.scriptPubKeyHex,
+            address: identityMaterial.address,
+            status: "dedicated",
+            assignedDomainNames: [],
+        };
+    });
+    return {
+        schemaVersion: 1,
+        stateRevision: 1,
+        lastWrittenAtUnixMs: nowUnixMs,
+        walletRootId,
+        network: previousState.network,
+        anchorValueSats: previousState.anchorValueSats,
+        nextDedicatedIndex: previousState.nextDedicatedIndex,
+        fundingIndex: previousState.fundingIndex,
+        mnemonic: {
+            phrase: previousState.mnemonic.phrase,
+            language: previousState.mnemonic.language,
+        },
+        keys: {
+            masterFingerprintHex: material.keys.masterFingerprintHex,
+            accountPath: material.keys.accountPath,
+            accountXprv: material.keys.accountXprv,
+            accountXpub: material.keys.accountXpub,
+        },
+        descriptor: {
+            privateExternal: material.descriptor.privateExternal,
+            publicExternal: material.descriptor.publicExternal,
+            checksum: null,
+            rangeEnd: previousState.descriptor.rangeEnd,
+            safetyMargin: previousState.descriptor.safetyMargin,
+        },
+        funding: {
+            address: material.funding.address,
+            scriptPubKeyHex: material.funding.scriptPubKeyHex,
+        },
+        walletBirthTime: previousState.walletBirthTime,
+        managedCoreWallet: {
+            walletName: sanitizeWalletName(walletRootId),
+            internalPassphrase: createInternalCoreWalletPassphrase(),
+            descriptorChecksum: null,
+            fundingAddress0: null,
+            fundingScriptPubKeyHex0: null,
+            proofStatus: "not-proven",
+            lastImportedAtUnixMs: null,
+            lastVerifiedAtUnixMs: null,
+        },
+        identities,
+        domains: [],
+        miningState: {
+            runMode: "stopped",
+            state: "idle",
+            pauseReason: null,
+            currentPublishState: "none",
+            currentDomain: null,
+            currentDomainId: null,
+            currentDomainIndex: null,
+            currentSenderScriptPubKeyHex: null,
+            currentTxid: null,
+            currentWtxid: null,
+            currentFeeRateSatVb: null,
+            currentAbsoluteFeeSats: null,
+            currentScore: null,
+            currentSentence: null,
+            currentEncodedSentenceBytesHex: null,
+            currentBip39WordIndices: null,
+            currentBlendSeedHex: null,
+            currentBlockTargetHeight: null,
+            currentReferencedBlockHashDisplay: null,
+            currentIntentFingerprintHex: null,
+            liveMiningFamilyInMempool: null,
+            currentPublishDecision: null,
+            replacementCount: 0,
+            currentBlockFeeSpentSats: "0",
+            sessionFeeSpentSats: "0",
+            lifetimeFeeSpentSats: "0",
+            sharedMiningConflictOutpoint: null,
+        },
+        hookClientState: {
+            mining: {
+                mode: "builtin",
+                validationState: "never",
+                lastValidationAtUnixMs: null,
+                lastValidationError: null,
+                validatedLaunchFingerprint: null,
+                validatedFullFingerprint: null,
+                fullTrustWarningAcknowledgedAtUnixMs: null,
+                consecutiveFailureCount: 0,
+                cooldownUntilUnixMs: null,
+            },
+        },
+        proactiveFamilies: [],
+        pendingMutations: [],
+    };
+}
+async function promptHiddenOrVisible(prompter, message) {
+    if (typeof prompter.promptHidden === "function") {
+        return await prompter.promptHidden(message);
+    }
+    return await prompter.prompt(message);
+}
+async function loadWalletForEntropyReset(options) {
+    if (options.wallet.rawEnvelope === null) {
+        throw new Error("reset_wallet_entropy_reset_unavailable");
+    }
+    if (options.wallet.mode === "provider-backed") {
+        try {
+            return {
+                loaded: await loadWalletState({
+                    primaryPath: options.paths.walletStatePath,
+                    backupPath: options.paths.walletStateBackupPath,
+                }, {
+                    provider: options.provider,
+                }),
+                access: {
+                    kind: "provider",
+                    provider: options.provider,
+                },
+            };
+        }
+        catch {
+            throw new Error("reset_wallet_entropy_reset_unavailable");
+        }
+    }
+    if (options.wallet.mode !== "passphrase-wrapped") {
+        throw new Error("reset_wallet_entropy_reset_unavailable");
+    }
+    const passphrase = (await promptHiddenOrVisible(options.prompter, "Wallet-state passphrase: ")).trim();
+    if (passphrase === "") {
+        throw new Error("reset_wallet_passphrase_required");
+    }
+    try {
+        return {
+            loaded: await loadWalletState({
+                primaryPath: options.paths.walletStatePath,
+                backupPath: options.paths.walletStateBackupPath,
+            }, passphrase),
+            access: {
+                kind: "passphrase",
+                passphrase,
+            },
+        };
+    }
+    catch {
+        throw new Error("reset_wallet_access_failed");
+    }
+}
+async function collectTrackedManagedProcesses(paths) {
+    const trackedProcesses = [];
+    const trackedProcessKinds = new Set();
+    const serviceLockPaths = new Set();
+    const runtimeEntries = await readdir(paths.runtimeRoot, { withFileTypes: true }).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    });
+    for (const entry of runtimeEntries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const serviceRoot = join(paths.runtimeRoot, entry.name);
+        const bitcoindStatus = await readJsonFileOrNull(join(serviceRoot, "bitcoind-status.json"));
+        if (bitcoindStatus?.processId != null && await isProcessAlive(bitcoindStatus.processId)) {
+            trackedProcesses.push({
+                kind: "managed-bitcoind",
+                pid: bitcoindStatus.processId,
+            });
+            trackedProcessKinds.add("managed-bitcoind");
+            serviceLockPaths.add(join(serviceRoot, "bitcoind.lock"));
+        }
+    }
+    const indexerEntries = await readdir(paths.indexerRoot, { withFileTypes: true }).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    });
+    for (const entry of indexerEntries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const status = await readJsonFileOrNull(join(paths.indexerRoot, entry.name, "status.json"));
+        if (status?.processId != null && await isProcessAlive(status.processId)) {
+            trackedProcesses.push({
+                kind: "indexer-daemon",
+                pid: status.processId,
+            });
+            trackedProcessKinds.add("indexer-daemon");
+            serviceLockPaths.add(join(paths.runtimeRoot, entry.name, "indexer-daemon.lock"));
+        }
+    }
+    const miningRuntime = await loadMiningRuntimeStatus(paths.miningStatusPath).catch(() => null);
+    if (miningRuntime?.backgroundWorkerPid != null
+        && await isProcessAlive(miningRuntime.backgroundWorkerPid)) {
+        trackedProcesses.push({
+            kind: "background-mining",
+            pid: miningRuntime.backgroundWorkerPid,
+        });
+        trackedProcessKinds.add("background-mining");
+    }
+    const seen = new Set();
+    const deduped = trackedProcesses.filter((processInfo) => {
+        const key = `${processInfo.kind}:${processInfo.pid}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+    return {
+        trackedProcesses: deduped,
+        trackedProcessKinds: [...trackedProcessKinds],
+        serviceLockPaths: [...serviceLockPaths].sort(),
+    };
+}
+function resolveRemovedRoots(paths) {
+    const configRoot = dirname(paths.clientConfigPath);
+    return [...new Set([
+            paths.dataRoot,
+            paths.stateRoot,
+            paths.runtimeRoot,
+            configRoot,
+        ])].sort((left, right) => right.length - left.length);
+}
+async function preflightReset(options) {
+    const rawEnvelope = await loadRawWalletEnvelope(options.paths);
+    const explicitLock = await loadWalletExplicitLock(options.paths.walletExplicitLockPath).catch(() => null);
+    const snapshotPaths = resolveBootstrapPathsForTesting(options.dataDir, DEFAULT_SNAPSHOT_METADATA);
+    const validateSnapshot = options.validateSnapshotFile
+        ?? ((path) => validateSnapshotFileForTesting(path, DEFAULT_SNAPSHOT_METADATA));
+    const hasWalletState = await pathExists(options.paths.walletStatePath) || await pathExists(options.paths.walletStateBackupPath);
+    const hasSnapshot = await pathExists(snapshotPaths.snapshotPath);
+    const hasPartialSnapshot = await pathExists(snapshotPaths.partialSnapshotPath);
+    let snapshotStatus = "not-present";
+    if (hasSnapshot) {
+        try {
+            await validateSnapshot(snapshotPaths.snapshotPath);
+            snapshotStatus = "valid";
+        }
+        catch {
+            snapshotStatus = "invalid";
+        }
+    }
+    else if (hasPartialSnapshot) {
+        snapshotStatus = "invalid";
+    }
+    const tracked = await collectTrackedManagedProcesses(options.paths);
+    const secretProviderKeyId = rawEnvelope?.envelope.secretProvider?.keyId ?? null;
+    return {
+        dataRoot: options.paths.dataRoot,
+        removedRoots: resolveRemovedRoots(options.paths),
+        wallet: {
+            present: hasWalletState,
+            mode: rawEnvelope == null
+                ? (hasWalletState ? "unknown" : "unknown")
+                : rawEnvelope.envelope.secretProvider != null
+                    ? "provider-backed"
+                    : "passphrase-wrapped",
+            envelopeSource: rawEnvelope?.source ?? null,
+            secretProviderKeyId,
+            explicitLock,
+            rawEnvelope,
+        },
+        snapshot: {
+            status: snapshotStatus,
+            path: snapshotPaths.snapshotPath,
+            shouldPrompt: snapshotStatus === "valid",
+            shouldStageForPreserve: snapshotStatus === "valid"
+                && resolveRemovedRoots(options.paths).some((root) => isPathWithin(root, snapshotPaths.snapshotPath)),
+        },
+        trackedProcesses: tracked.trackedProcesses,
+        trackedProcessKinds: tracked.trackedProcessKinds,
+        serviceLockPaths: tracked.serviceLockPaths,
+    };
+}
+async function acquireResetLocks(paths, serviceLockPaths) {
+    const lockPaths = [
+        paths.walletControlLockPath,
+        paths.miningControlLockPath,
+        ...serviceLockPaths,
+    ];
+    const handles = [];
+    try {
+        for (const lockPath of lockPaths) {
+            handles.push(await acquireFileLock(lockPath, {
+                purpose: "wallet-reset",
+                walletRootId: null,
+            }));
+        }
+        return handles;
+    }
+    catch (error) {
+        await Promise.all(handles.map(async (handle) => handle.release().catch(() => undefined)));
+        throw error;
+    }
+}
+async function deleteRemovedRoots(roots) {
+    try {
+        for (const root of roots) {
+            await rm(root, {
+                recursive: true,
+                force: true,
+            });
+        }
+    }
+    catch {
+        throw new Error("reset_data_root_delete_failed");
+    }
+}
+async function resolveResetExecutionDecision(options) {
+    if (!options.prompter.isInteractive) {
+        throw new Error("reset_requires_tty");
+    }
+    await confirmTypedAcknowledgement(options.prompter, {
+        expected: "permanently reset",
+        prompt: "Type \"permanently reset\" to continue: ",
+        errorCode: "reset_typed_ack_required",
+        requiresTtyErrorCode: "reset_requires_tty",
+        typedAckRequiredErrorCode: "reset_typed_ack_required",
+    });
+    let walletChoice = "";
+    let loadedWalletForEntropyReset = null;
+    if (options.preflight.wallet.present) {
+        const answer = (await options.prompter.prompt("Wallet reset choice ([Enter] retain base entropy, \"skip\", or \"delete wallet\"): ")).trim();
+        if (answer !== "" && answer !== "skip" && answer !== "delete wallet") {
+            throw new Error("reset_wallet_choice_invalid");
+        }
+        walletChoice = answer;
+        if (walletChoice === "") {
+            loadedWalletForEntropyReset = await loadWalletForEntropyReset({
+                wallet: options.preflight.wallet,
+                paths: options.paths,
+                provider: options.provider,
+                prompter: options.prompter,
+            });
+        }
+    }
+    let deleteSnapshot = false;
+    if (options.preflight.snapshot.shouldPrompt) {
+        const answer = (await options.prompter.prompt("Delete downloaded 910000 UTXO snapshot too? [y/N]: ")).trim().toLowerCase();
+        deleteSnapshot = answer === "y" || answer === "yes";
+    }
+    return {
+        walletChoice,
+        deleteSnapshot,
+        loadedWalletForEntropyReset,
+    };
+}
+function determineWalletAction(walletPresent, walletChoice) {
+    if (!walletPresent) {
+        return "not-present";
+    }
+    if (walletChoice === "skip") {
+        return "kept-unchanged";
+    }
+    if (walletChoice === "delete wallet") {
+        return "deleted";
+    }
+    return "reset-base-entropy";
+}
+function determineSnapshotResultStatus(options) {
+    if (options.snapshotStatus === "not-present") {
+        return "not-present";
+    }
+    if (options.snapshotStatus === "invalid") {
+        return "invalid-removed";
+    }
+    return options.deleteSnapshot ? "deleted" : "preserved";
+}
+export async function previewResetWallet(options) {
+    const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const preflight = await preflightReset({
+        dataDir: options.dataDir,
+        provider,
+        paths,
+        validateSnapshotFile: options.validateSnapshotFile,
+    });
+    return {
+        dataRoot: preflight.dataRoot,
+        confirmationPhrase: "permanently reset",
+        walletPrompt: preflight.wallet.present
+            ? {
+                defaultAction: "reset-base-entropy",
+                acceptedInputs: ["", "skip", "delete wallet"],
+                entropyRetainingResetAvailable: preflight.wallet.mode !== "unknown",
+                requiresPassphrase: preflight.wallet.mode === "passphrase-wrapped",
+                envelopeSource: preflight.wallet.envelopeSource,
+            }
+            : null,
+        bootstrapSnapshot: {
+            status: preflight.snapshot.status,
+            path: preflight.snapshot.path,
+            defaultAction: preflight.snapshot.status === "valid" ? "preserve" : "delete",
+        },
+        trackedProcessKinds: preflight.trackedProcessKinds,
+        willDeleteOsSecrets: preflight.wallet.secretProviderKeyId !== null,
+        removedPaths: preflight.removedRoots,
+    };
+}
+export async function resetWallet(options) {
+    const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const nowUnixMs = options.nowUnixMs ?? Date.now();
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const preflight = await preflightReset({
+        dataDir: options.dataDir,
+        provider,
+        paths,
+        validateSnapshotFile: options.validateSnapshotFile,
+    });
+    const decision = await resolveResetExecutionDecision({
+        preflight,
+        provider,
+        prompter: options.prompter,
+        paths,
+    });
+    const walletAction = determineWalletAction(preflight.wallet.present, decision.walletChoice);
+    const snapshotResultStatus = determineSnapshotResultStatus({
+        snapshotStatus: preflight.snapshot.status,
+        deleteSnapshot: decision.deleteSnapshot,
+    });
+    const locks = await acquireResetLocks(paths, preflight.serviceLockPaths);
+    await mkdir(dirname(paths.dataRoot), { recursive: true });
+    const stagingRoot = await mkdtemp(join(dirname(paths.dataRoot), ".cogcoin-reset-"));
+    const stagedWalletArtifacts = [];
+    const stagedSnapshotArtifacts = [];
+    let stoppedProcesses = {
+        managedBitcoind: 0,
+        indexerDaemon: 0,
+        backgroundMining: 0,
+        survivors: 0,
+    };
+    let rootsDeleted = false;
+    let committed = false;
+    let newProviderKeyId = null;
+    let secretCleanupStatus = preflight.wallet.secretProviderKeyId === null
+        ? "not-found"
+        : "not-found";
+    const deletedSecretRefs = [];
+    const failedSecretRefs = [];
+    const preservedSecretRefs = [];
+    let walletOldRootId = extractWalletRootIdFromSecretKeyId(preflight.wallet.secretProviderKeyId)
+        ?? preflight.wallet.explicitLock?.walletRootId
+        ?? null;
+    let walletNewRootId = null;
+    try {
+        stoppedProcesses = await terminateTrackedProcesses(preflight.trackedProcesses);
+        if (walletAction === "kept-unchanged" || walletAction === "reset-base-entropy") {
+            const stagedPrimary = await stageArtifact(paths.walletStatePath, stagingRoot, "wallet/wallet-state.enc");
+            const stagedBackup = await stageArtifact(paths.walletStateBackupPath, stagingRoot, "wallet/wallet-state.enc.bak");
+            const stagedExplicitLock = await stageArtifact(paths.walletExplicitLockPath, stagingRoot, "wallet/wallet-explicit-lock.json");
+            if (stagedPrimary !== null) {
+                stagedWalletArtifacts.push(stagedPrimary);
+            }
+            if (stagedBackup !== null) {
+                stagedWalletArtifacts.push(stagedBackup);
+            }
+            if (walletAction === "kept-unchanged" && stagedExplicitLock !== null) {
+                stagedWalletArtifacts.push(stagedExplicitLock);
+            }
+        }
+        if (snapshotResultStatus === "preserved" && preflight.snapshot.shouldStageForPreserve) {
+            const stagedSnapshot = await stageArtifact(preflight.snapshot.path, stagingRoot, "snapshot/utxo-910000.dat");
+            if (stagedSnapshot !== null) {
+                stagedSnapshotArtifacts.push(stagedSnapshot);
+            }
+        }
+        await deleteRemovedRoots(preflight.removedRoots);
+        rootsDeleted = true;
+        if (walletAction === "kept-unchanged") {
+            await restoreStagedArtifacts(stagedWalletArtifacts);
+        }
+        else if (walletAction === "reset-base-entropy") {
+            if (decision.loadedWalletForEntropyReset === null) {
+                throw new Error("reset_wallet_entropy_reset_unavailable");
+            }
+            const nextState = createEntropyRetainedWalletState(decision.loadedWalletForEntropyReset.loaded.state, nowUnixMs);
+            walletOldRootId = decision.loadedWalletForEntropyReset.loaded.state.walletRootId;
+            walletNewRootId = nextState.walletRootId;
+            if (decision.loadedWalletForEntropyReset.access.kind === "provider") {
+                const secretReference = createWalletSecretReference(nextState.walletRootId);
+                newProviderKeyId = secretReference.keyId;
+                await provider.storeSecret(secretReference.keyId, randomBytes(32));
+                await saveWalletState({
+                    primaryPath: paths.walletStatePath,
+                    backupPath: paths.walletStateBackupPath,
+                }, nextState, {
+                    provider,
+                    secretReference,
+                });
+                preservedSecretRefs.push(secretReference.keyId);
+            }
+            else {
+                await saveWalletState({
+                    primaryPath: paths.walletStatePath,
+                    backupPath: paths.walletStateBackupPath,
+                }, nextState, decision.loadedWalletForEntropyReset.access.passphrase);
+            }
+        }
+        if (snapshotResultStatus === "preserved") {
+            await restoreStagedArtifacts(stagedSnapshotArtifacts);
+        }
+        committed = true;
+        if (walletAction === "deleted") {
+            if (preflight.wallet.secretProviderKeyId !== null) {
+                try {
+                    await provider.deleteSecret(preflight.wallet.secretProviderKeyId);
+                    deletedSecretRefs.push(preflight.wallet.secretProviderKeyId);
+                    secretCleanupStatus = "deleted";
+                }
+                catch {
+                    failedSecretRefs.push(preflight.wallet.secretProviderKeyId);
+                    secretCleanupStatus = "failed";
+                    throw new Error("reset_secret_cleanup_failed");
+                }
+            }
+        }
+        else if (walletAction === "reset-base-entropy" && preflight.wallet.secretProviderKeyId !== null) {
+            try {
+                if (preflight.wallet.secretProviderKeyId !== newProviderKeyId) {
+                    await provider.deleteSecret(preflight.wallet.secretProviderKeyId);
+                    deletedSecretRefs.push(preflight.wallet.secretProviderKeyId);
+                    secretCleanupStatus = "deleted";
+                }
+            }
+            catch {
+                failedSecretRefs.push(preflight.wallet.secretProviderKeyId);
+                secretCleanupStatus = "failed";
+                throw new Error("reset_secret_cleanup_failed");
+            }
+        }
+        else if (preflight.wallet.secretProviderKeyId !== null) {
+            preservedSecretRefs.push(preflight.wallet.secretProviderKeyId);
+        }
+        if (preflight.wallet.secretProviderKeyId === null && preflight.wallet.present && preflight.wallet.rawEnvelope === null) {
+            secretCleanupStatus = "unknown";
+        }
+        else if (deletedSecretRefs.length === 0 && failedSecretRefs.length === 0) {
+            secretCleanupStatus = "not-found";
+        }
+        return {
+            dataRoot: preflight.dataRoot,
+            factoryResetReady: true,
+            stoppedProcesses,
+            secretCleanupStatus,
+            deletedSecretRefs,
+            failedSecretRefs,
+            preservedSecretRefs,
+            walletAction,
+            walletOldRootId,
+            walletNewRootId,
+            bootstrapSnapshot: {
+                status: snapshotResultStatus,
+                path: preflight.snapshot.path,
+            },
+            removedPaths: preflight.removedRoots,
+        };
+    }
+    catch (error) {
+        if (!committed && rootsDeleted) {
+            await restoreStagedArtifacts(stagedWalletArtifacts).catch(() => undefined);
+            await restoreStagedArtifacts(stagedSnapshotArtifacts).catch(() => undefined);
+            if (newProviderKeyId !== null) {
+                await provider.deleteSecret(newProviderKeyId).catch(() => undefined);
+            }
+        }
+        throw error;
+    }
+    finally {
+        await rm(stagingRoot, { recursive: true, force: true }).catch(() => undefined);
+        await Promise.all(locks.reverse().map(async (lock) => lock.release().catch(() => undefined)));
+    }
+}