@evomap/evolver-proxy 2.0.0-beta.2 → 2.0.0-beta.5

package/dist/selfUpdate/unixController.d.ts

@@ -0,0 +1,15 @@
+import { type SelfUpdateRecoveryOptions } from './transaction.js';
+export declare const UNIX_RECOVERY_CONTROLLER_ARG = "--evolver-unix-recovery-controller";
+export interface UnixRecoveryControllerOptions extends SelfUpdateRecoveryOptions {
+    argv?: readonly string[];
+    processExecPath?: string;
+    platform?: NodeJS.Platform;
+    confirmationTimeoutMs?: number;
+    pollIntervalMs?: number;
+    stopTimeoutMs?: number;
+    logger?: {
+        write(chunk: string): unknown;
+    };
+}
+export declare function maybeRunUnixRecoveryController(options?: UnixRecoveryControllerOptions): Promise<number | undefined>;
+export declare function runUnixRecoveryController(options?: UnixRecoveryControllerOptions): Promise<number>;

package/dist/selfUpdate/unixController.js

@@ -0,0 +1,186 @@
+import { spawn } from 'node:child_process';
+import { bindStableUnixRecoveryController, inspectDurableSelfUpdate, recoverDurableSelfUpdate, rollbackDurableSelfUpdate, } from './transaction.js';
+import { SELF_UPDATE_FAILURE_CODES } from './failureCodes.js';
+export const UNIX_RECOVERY_CONTROLLER_ARG = '--evolver-unix-recovery-controller';
+const DEFAULT_CONFIRMATION_TIMEOUT_MS = 30_000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+const DEFAULT_STOP_TIMEOUT_MS = 2_000;
+const PENDING_CONTROLLER_STAGES = new Set(['installed', 'restarted', 'health_check_pending']);
+const RECOVER_BEFORE_START_STAGES = new Set([
+    'preparing',
+    'downloaded',
+    'verified',
+    'backed_up',
+    'rolling_back',
+    'rollback_pending',
+]);
+export async function maybeRunUnixRecoveryController(options = {}) {
+    const argv = options.argv ?? process.argv.slice(2);
+    if (argv.length !== 2 || argv[0] !== 'proxy' || argv[1] !== UNIX_RECOVERY_CONTROLLER_ARG)
+        return undefined;
+    if ((options.platform ?? process.platform) === 'win32') {
+        throw new Error('unix_recovery_controller_unsupported_platform');
+    }
+    return runUnixRecoveryController(options);
+}
+export async function runUnixRecoveryController(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const processExecPath = options.processExecPath ?? process.execPath;
+    const logger = options.logger ?? process.stderr;
+    const confirmationTimeoutMs = positiveDuration(options.confirmationTimeoutMs, DEFAULT_CONFIRMATION_TIMEOUT_MS);
+    const pollIntervalMs = positiveDuration(options.pollIntervalMs, DEFAULT_POLL_INTERVAL_MS);
+    const stopTimeoutMs = positiveDuration(options.stopTimeoutMs, DEFAULT_STOP_TIMEOUT_MS);
+    const transactionOptions = { ...options, env, platform, processExecPath };
+    const { targetPath } = await bindStableUnixRecoveryController(transactionOptions, processExecPath);
+    let initial = await inspectDurableSelfUpdate(transactionOptions);
+    if (initial.outcome === 'blocked' || initial.stage === 'install_pending') {
+        logger.write('[evolver-controller] recovery_blocked_before_start\n');
+        return 1;
+    }
+    if (initial.stage !== undefined && RECOVER_BEFORE_START_STAGES.has(initial.stage)) {
+        initial = await recoverDurableSelfUpdate(transactionOptions);
+        if (initial.outcome === 'blocked') {
+            logger.write('[evolver-controller] recovery_blocked_before_start\n');
+            return 1;
+        }
+    }
+    const pendingAtLaunch = isControllerPending(initial);
+    let child;
+    let stoppingSignal;
+    const forwardSignal = (signal) => {
+        stoppingSignal = signal;
+        child?.kill(signal);
+    };
+    const onSigterm = () => { forwardSignal('SIGTERM'); };
+    const onSigint = () => { forwardSignal('SIGINT'); };
+    process.once('SIGTERM', onSigterm);
+    process.once('SIGINT', onSigint);
+    try {
+        const launched = spawn(targetPath, ['proxy'], {
+            env,
+            stdio: 'inherit',
+            windowsHide: true,
+        });
+        child = launched;
+        const childExit = waitForNativeExit(launched);
+        if (!pendingAtLaunch)
+            return exitCode(await childExit);
+        const deadline = Date.now() + confirmationTimeoutMs;
+        for (;;) {
+            const event = await Promise.race([
+                childExit.then((exit) => ({ type: 'exit', exit })),
+                delay(Math.min(pollIntervalMs, Math.max(1, deadline - Date.now())))
+                    .then(() => ({ type: 'poll' })),
+            ]);
+            if (stoppingSignal) {
+                await stopNativeChild(launched, childExit, stopTimeoutMs);
+                let rollback;
+                try {
+                    rollback = await rollbackDurableSelfUpdate(transactionOptions, 'controller_stopped_during_health_check');
+                }
+                catch {
+                    logger.write('[evolver-controller] rollback_blocked\n');
+                    return 1;
+                }
+                if (rollback.outcome !== 'rolled_back' && rollback.outcome !== 'confirmed') {
+                    logger.write('[evolver-controller] rollback_blocked\n');
+                    return 1;
+                }
+                return 128 + signalNumber(stoppingSignal);
+            }
+            let state;
+            try {
+                state = await inspectDurableSelfUpdate(transactionOptions);
+            }
+            catch {
+                if (event.type === 'exit' || Date.now() >= deadline) {
+                    logger.write('[evolver-controller] recovery_state_unavailable\n');
+                }
+                else {
+                    continue;
+                }
+            }
+            if (state?.outcome === 'confirmed')
+                return exitCode(await childExit);
+            if (state?.outcome === 'blocked') {
+                await stopNativeChild(launched, childExit, stopTimeoutMs);
+                return 1;
+            }
+            if (state?.outcome === 'rolled_back') {
+                await stopNativeChild(launched, childExit, stopTimeoutMs);
+                child = spawnTarget(targetPath, env);
+                return exitCode(await waitForNativeExit(child));
+            }
+            if (event.type === 'exit' || Date.now() >= deadline) {
+                await stopNativeChild(launched, childExit, stopTimeoutMs);
+                const rollback = await rollbackDurableSelfUpdate(transactionOptions, event.type === 'exit'
+                    ? SELF_UPDATE_FAILURE_CODES.RESTART_FAILED
+                    : 'health_confirmation_timeout');
+                if (rollback.outcome !== 'rolled_back' && rollback.outcome !== 'confirmed') {
+                    logger.write('[evolver-controller] rollback_blocked\n');
+                    return 1;
+                }
+                if (rollback.outcome === 'confirmed')
+                    return exitCode(await childExit);
+                child = spawnTarget(targetPath, env);
+                return exitCode(await waitForNativeExit(child));
+            }
+        }
+    }
+    finally {
+        process.off('SIGTERM', onSigterm);
+        process.off('SIGINT', onSigint);
+    }
+}
+function isControllerPending(state) {
+    return state.stage !== undefined && PENDING_CONTROLLER_STAGES.has(state.stage);
+}
+function spawnTarget(targetPath, env) {
+    return spawn(targetPath, ['proxy'], {
+        env,
+        stdio: 'inherit',
+        windowsHide: true,
+    });
+}
+function waitForNativeExit(child) {
+    return new Promise((resolve) => {
+        child.once('error', (error) => { resolve({ code: null, signal: null, error }); });
+        child.once('exit', (code, signal) => { resolve({ code, signal }); });
+    });
+}
+async function stopNativeChild(child, exit, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    child.kill('SIGTERM');
+    const stopped = await Promise.race([
+        exit.then(() => true),
+        delay(timeoutMs).then(() => false),
+    ]);
+    if (!stopped) {
+        child.kill('SIGKILL');
+        await exit;
+    }
+}
+function exitCode(exit) {
+    if (exit.error)
+        return 1;
+    if (exit.code !== null)
+        return exit.code;
+    return exit.signal === null ? 1 : 128 + signalNumber(exit.signal);
+}
+function signalNumber(signal) {
+    if (signal === 'SIGINT')
+        return 2;
+    if (signal === 'SIGTERM')
+        return 15;
+    if (signal === 'SIGKILL')
+        return 9;
+    return 1;
+}
+function positiveDuration(value, fallback) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+function delay(ms) {
+    return new Promise((resolve) => { setTimeout(resolve, ms); });
+}

package/dist/selfUpdate/version.d.ts

@@ -1,2 +1,6 @@
-/** Resolve EVOLVER's own version. Walks up from this module to the nearest package.json named @evomap/evolver-proxy. */
-export declare function getCurrentVersion(): string;
+export interface CurrentVersionOptions {
+    startDir?: string;
+    buildVersion?: string;
+}
+/** Resolve EVOLVER's version from package/git metadata, then the standalone build-time version. */
+export declare function getCurrentVersion(options?: CurrentVersionOptions): string;

package/dist/selfUpdate/version.js

@@ -5,10 +5,12 @@
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { util } from '@evomap/evolver-core';
-/** Resolve EVOLVER's own version. Walks up from this module to the nearest package.json named @evomap/evolver-proxy. */
-export function getCurrentVersion() {
+/** Resolve EVOLVER's version from package/git metadata, then the standalone build-time version. */
+export function getCurrentVersion(options = {}) {
+    const buildVersion = (options.buildVersion ?? process.env.EVOLVER_CLI_VERSION)?.trim();
     return util.resolveRuntimeVersion({
-        startDir: dirname(fileURLToPath(import.meta.url)),
+        startDir: options.startDir ?? dirname(fileURLToPath(import.meta.url)),
         isPackage: (pkg) => pkg.name === '@evomap/evolver-proxy' || pkg.name === '@evomap/evolver',
+        ...(buildVersion && buildVersion !== '0.0.0' ? { fallback: buildVersion } : {}),
     });
 }

package/dist/selfUpdate/windowsController.d.ts

@@ -0,0 +1,23 @@
+import { type ChildProcess } from 'node:child_process';
+import { type SelfUpdateRecoveryOptions } from './transaction.js';
+export declare const WINDOWS_RECOVERY_CONTROLLER_ARG = "--evolver-windows-recovery-controller";
+export declare const WINDOWS_RECOVERY_CONTROLLER_PROVISION_ARG = "--evolver-windows-recovery-controller-provision";
+type RunUpdaterWorker = (workerPath: string, stateDir: string, env: NodeJS.ProcessEnv) => Promise<number>;
+export interface WindowsRecoveryControllerOptions extends SelfUpdateRecoveryOptions {
+    argv?: readonly string[];
+    processExecPath?: string;
+    platform?: NodeJS.Platform;
+    confirmationTimeoutMs?: number;
+    pollIntervalMs?: number;
+    stopTimeoutMs?: number;
+    logger?: {
+        write(chunk: string): unknown;
+    };
+    /** Test-only process adapter; production always uses the fixed target plus the fixed `proxy` argv. */
+    spawnTarget?: (targetPath: string, env: NodeJS.ProcessEnv) => ChildProcess;
+    /** Test-only worker adapter; production executes the fixed updater path with the fixed worker argv. */
+    runUpdaterWorker?: RunUpdaterWorker;
+}
+export declare function maybeRunWindowsRecoveryController(options?: WindowsRecoveryControllerOptions): Promise<number | undefined>;
+export declare function runWindowsRecoveryController(options?: WindowsRecoveryControllerOptions): Promise<number>;
+export {};

package/dist/selfUpdate/windowsController.js

@@ -0,0 +1,274 @@
+import { spawn } from 'node:child_process';
+import { lstat } from 'node:fs/promises';
+import { bindStableWindowsRecoveryController, inspectDurableSelfUpdate, markWindowsInstallApplied, provisionStableWindowsRecoveryController, recoverDurableSelfUpdate, rollbackDurableSelfUpdate, } from './transaction.js';
+import { SELF_UPDATE_FAILURE_CODES } from './failureCodes.js';
+import { bindWindowsManagedExecutable, resolveWindowsUpdaterPaths, WINDOWS_UPDATER_WORKER_ARG, } from './windowsUpdater.js';
+export const WINDOWS_RECOVERY_CONTROLLER_ARG = '--evolver-windows-recovery-controller';
+export const WINDOWS_RECOVERY_CONTROLLER_PROVISION_ARG = '--evolver-windows-recovery-controller-provision';
+const DEFAULT_CONFIRMATION_TIMEOUT_MS = 30_000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+const DEFAULT_STOP_TIMEOUT_MS = 2_000;
+const PENDING_CONTROLLER_STAGES = new Set(['installed', 'restarted', 'health_check_pending']);
+const RECOVER_BEFORE_START_STAGES = new Set([
+    'preparing',
+    'downloaded',
+    'verified',
+    'backed_up',
+    'install_pending',
+    'rolling_back',
+    'rollback_pending',
+]);
+const PENDING_SWAP_JOURNAL_STAGES = new Set([
+    'install_pending',
+    'restarted',
+    'rolling_back',
+    'rollback_pending',
+]);
+export async function maybeRunWindowsRecoveryController(options = {}) {
+    const argv = options.argv ?? process.argv.slice(2);
+    const command = argv.length === 2 && argv[0] === 'proxy' ? argv[1] : undefined;
+    if (command !== WINDOWS_RECOVERY_CONTROLLER_ARG && command !== WINDOWS_RECOVERY_CONTROLLER_PROVISION_ARG) {
+        return undefined;
+    }
+    if ((options.platform ?? process.platform) !== 'win32')
+        return 64;
+    try {
+        if (command === WINDOWS_RECOVERY_CONTROLLER_PROVISION_ARG) {
+            await provisionStableWindowsRecoveryController(options, options.processExecPath ?? process.execPath);
+            return 0;
+        }
+        return await runWindowsRecoveryController(options);
+    }
+    catch {
+        return 1;
+    }
+}
+export async function runWindowsRecoveryController(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const processExecPath = options.processExecPath ?? process.execPath;
+    const logger = options.logger ?? process.stderr;
+    const confirmationTimeoutMs = positiveDuration(options.confirmationTimeoutMs, DEFAULT_CONFIRMATION_TIMEOUT_MS);
+    const pollIntervalMs = positiveDuration(options.pollIntervalMs, DEFAULT_POLL_INTERVAL_MS);
+    const stopTimeoutMs = positiveDuration(options.stopTimeoutMs, DEFAULT_STOP_TIMEOUT_MS);
+    const spawnBoundTarget = options.spawnTarget ?? spawnTarget;
+    const runBoundUpdaterWorker = options.runUpdaterWorker ?? runUpdaterWorker;
+    const bound = await bindStableWindowsRecoveryController({ ...options, env, platform }, processExecPath);
+    const transactionOptions = {
+        ...options,
+        env,
+        platform,
+        processExecPath,
+        stateDir: bound.stateDir,
+        targetPath: bound.targetPath,
+        beforeJournalMutation: async () => {
+            await bindStableWindowsRecoveryController({ ...options, env, platform }, processExecPath);
+        },
+    };
+    let initial = await inspectDurableSelfUpdate(transactionOptions);
+    if (initial.outcome === 'blocked') {
+        logger.write('[evolver-windows-controller] recovery_blocked_before_start\n');
+        return 1;
+    }
+    if (await pendingSwapExists(bound.stateDir)) {
+        if (initial.stage === undefined || !PENDING_SWAP_JOURNAL_STAGES.has(initial.stage)) {
+            logger.write('[evolver-windows-controller] pending_swap_blocked\n');
+            return 1;
+        }
+        const workerExitCode = await executeBoundUpdaterWorker(runBoundUpdaterWorker, bound.stateDir, env);
+        if (workerExitCode !== 0) {
+            let rollback;
+            try {
+                rollback = await rollbackDurableSelfUpdate(transactionOptions, SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED);
+                rollback = await completePreparedRollback(rollback, transactionOptions, bound.stateDir, env, runBoundUpdaterWorker);
+            }
+            catch {
+                logger.write('[evolver-windows-controller] pending_swap_blocked\n');
+                return 1;
+            }
+            if (rollback.outcome !== 'rolled_back') {
+                logger.write('[evolver-windows-controller] pending_swap_blocked\n');
+                return 1;
+            }
+            return launchRestoredTarget(bound.targetPath, env, spawnBoundTarget);
+        }
+        initial = await inspectDurableSelfUpdate(transactionOptions);
+    }
+    if (initial.stage === 'install_pending') {
+        initial = await markWindowsInstallApplied(transactionOptions);
+        if (initial.outcome === 'blocked') {
+            logger.write('[evolver-windows-controller] install_not_applied\n');
+            return 1;
+        }
+    }
+    if (initial.outcome === 'blocked') {
+        logger.write('[evolver-windows-controller] recovery_blocked_before_start\n');
+        return 1;
+    }
+    if (initial.stage !== undefined && RECOVER_BEFORE_START_STAGES.has(initial.stage)) {
+        initial = await recoverAndApplyRollback(transactionOptions, bound.stateDir, env, runBoundUpdaterWorker);
+        if (initial.outcome === 'blocked' || initial.outcome === 'rollback_pending') {
+            logger.write('[evolver-windows-controller] recovery_blocked_before_start\n');
+            return 1;
+        }
+    }
+    const pendingAtLaunch = isControllerPending(initial);
+    const launched = spawnBoundTarget(bound.targetPath, env);
+    const childExit = waitForNativeExit(launched);
+    if (!pendingAtLaunch)
+        return exitCode(await childExit);
+    const deadline = Date.now() + confirmationTimeoutMs;
+    for (;;) {
+        const event = await Promise.race([
+            childExit.then((exit) => ({ type: 'exit', exit })),
+            delay(Math.min(pollIntervalMs, Math.max(1, deadline - Date.now())))
+                .then(() => ({ type: 'poll' })),
+        ]);
+        let state;
+        try {
+            state = await inspectDurableSelfUpdate(transactionOptions);
+        }
+        catch {
+            if (event.type === 'exit' || Date.now() >= deadline) {
+                logger.write('[evolver-windows-controller] recovery_state_unavailable\n');
+            }
+            else {
+                continue;
+            }
+        }
+        if (state?.outcome === 'confirmed')
+            return exitCode(await childExit);
+        if (state?.outcome === 'blocked') {
+            await stopNativeChild(launched, childExit, stopTimeoutMs);
+            return 1;
+        }
+        if (state?.outcome === 'rolled_back') {
+            await stopNativeChild(launched, childExit, stopTimeoutMs);
+            return launchRestoredTarget(bound.targetPath, env, spawnBoundTarget);
+        }
+        if (event.type === 'exit' || Date.now() >= deadline) {
+            await stopNativeChild(launched, childExit, stopTimeoutMs);
+            let rollback;
+            try {
+                rollback = await rollbackDurableSelfUpdate(transactionOptions, event.type === 'exit'
+                    ? SELF_UPDATE_FAILURE_CODES.RESTART_FAILED
+                    : 'health_confirmation_timeout');
+                rollback = await completePreparedRollback(rollback, transactionOptions, bound.stateDir, env, runBoundUpdaterWorker);
+            }
+            catch {
+                logger.write('[evolver-windows-controller] rollback_blocked\n');
+                return 1;
+            }
+            if (rollback.outcome === 'confirmed')
+                return exitCode(await childExit);
+            if (rollback.outcome !== 'rolled_back') {
+                logger.write('[evolver-windows-controller] rollback_blocked\n');
+                return 1;
+            }
+            return launchRestoredTarget(bound.targetPath, env, spawnBoundTarget);
+        }
+    }
+}
+async function recoverAndApplyRollback(options, stateDir, env, runBoundUpdaterWorker) {
+    const recovery = await recoverDurableSelfUpdate(options);
+    return completePreparedRollback(recovery, options, stateDir, env, runBoundUpdaterWorker);
+}
+async function completePreparedRollback(recovery, options, stateDir, env, runBoundUpdaterWorker) {
+    if (recovery.outcome !== 'rollback_pending')
+        return recovery;
+    const workerExitCode = await executeBoundUpdaterWorker(runBoundUpdaterWorker, stateDir, env);
+    if (workerExitCode !== 0) {
+        return { ...recovery, outcome: 'blocked', failureCode: 'rollback_apply_failed' };
+    }
+    return recoverDurableSelfUpdate(options);
+}
+async function pendingSwapExists(stateDir) {
+    const pendingPath = resolveWindowsUpdaterPaths(stateDir).pendingPath;
+    try {
+        const info = await lstat(pendingPath);
+        if (info.isSymbolicLink() || !info.isFile())
+            throw new Error('windows_controller_pending_unsafe');
+        return true;
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return false;
+        throw error;
+    }
+}
+function isControllerPending(state) {
+    return state.stage !== undefined && PENDING_CONTROLLER_STAGES.has(state.stage);
+}
+function spawnTarget(targetPath, env) {
+    return spawn(targetPath, ['proxy'], {
+        env,
+        stdio: 'inherit',
+        windowsHide: true,
+    });
+}
+async function runUpdaterWorker(workerPath, _stateDir, env) {
+    return exitCode(await waitForNativeExit(spawn(workerPath, ['proxy', WINDOWS_UPDATER_WORKER_ARG], {
+        env,
+        stdio: 'inherit',
+        windowsHide: true,
+    })));
+}
+async function executeBoundUpdaterWorker(runner, stateDir, env) {
+    const paths = resolveWindowsUpdaterPaths(stateDir);
+    const bound = await bindWindowsManagedExecutable({
+        stateDir,
+        executablePath: paths.helperPath,
+        relativePath: ['windows-updater', 'updater.exe'],
+        label: 'controller_worker',
+        platform: 'win32',
+    });
+    const workerEnv = { ...env, EVOLVER_SELF_UPDATE_STATE_DIR: bound.stateDir };
+    return runner(bound.executablePath, bound.stateDir, workerEnv);
+}
+async function launchRestoredTarget(targetPath, env, spawnBoundTarget) {
+    return exitCode(await waitForNativeExit(spawnBoundTarget(targetPath, env)));
+}
+function waitForNativeExit(child) {
+    return new Promise((resolve) => {
+        child.once('error', (error) => { resolve({ code: null, signal: null, error }); });
+        child.once('exit', (code, signal) => { resolve({ code, signal }); });
+    });
+}
+async function stopNativeChild(child, exit, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    child.kill('SIGTERM');
+    const stopped = await Promise.race([
+        exit.then(() => true),
+        delay(timeoutMs).then(() => false),
+    ]);
+    if (!stopped) {
+        child.kill('SIGKILL');
+        await exit;
+    }
+}
+function exitCode(exit) {
+    if (exit.error)
+        return 1;
+    if (exit.code !== null)
+        return exit.code;
+    return exit.signal === null ? 1 : 128 + signalNumber(exit.signal);
+}
+function signalNumber(signal) {
+    if (signal === 'SIGINT')
+        return 2;
+    if (signal === 'SIGTERM')
+        return 15;
+    if (signal === 'SIGKILL')
+        return 9;
+    return 1;
+}
+function positiveDuration(value, fallback) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+function delay(ms) {
+    return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+function isErrno(error, code) {
+    return typeof error === 'object' && error !== null && error.code === code;
+}

package/dist/selfUpdate/windowsUpdater.d.ts

@@ -0,0 +1,79 @@
+import { rename } from 'node:fs/promises';
+export declare const WINDOWS_UPDATER_WORKER_ARG = "--evolver-windows-updater-worker";
+export type WindowsUpdaterOperation = 'install' | 'rollback';
+export interface WindowsUpdaterPaths {
+    directory: string;
+    helperPath: string;
+    pendingPath: string;
+    resultPath: string;
+}
+export interface PrepareWindowsUpdaterOptions {
+    operation: WindowsUpdaterOperation;
+    targetPath: string;
+    backupPath: string;
+    stateDir: string;
+    /** Required for install and bound to the signed-manifest digest. */
+    stagedPath?: string;
+    expectedStagedSha256?: string;
+    /** Rollback copies the currently running helper-capable binary by default. */
+    helperSourcePath?: string;
+    processExecPath?: string;
+    platform?: NodeJS.Platform;
+}
+export interface WindowsUpdaterDescriptor {
+    operation: WindowsUpdaterOperation;
+    operationId: string;
+    helperPath: string;
+    pendingPath: string;
+    resultPath: string;
+}
+export interface WindowsUpdaterResult {
+    schema_version: 1;
+    operation: WindowsUpdaterOperation;
+    status: 'completed' | 'failed';
+    failure_code?: string;
+}
+export interface ApplyWindowsUpdaterOptions {
+    stateDir?: string;
+    workerExecPath?: string;
+    platform?: NodeJS.Platform;
+    renameFn?: typeof rename;
+}
+export interface BindWindowsManagedExecutableOptions {
+    stateDir: string;
+    executablePath: string;
+    relativePath: readonly string[];
+    label: string;
+    mismatchLabel?: string;
+    platform?: NodeJS.Platform;
+}
+export interface BoundWindowsManagedExecutable {
+    stateDir: string;
+    executablePath: string;
+}
+/** Paths are fixed so the stable controller never consumes descriptor-supplied executable paths. */
+export declare function resolveWindowsUpdaterPaths(stateDirInput: string): WindowsUpdaterPaths;
+/** Bind a fixed executable below the private state root without following directory links. */
+export declare function bindWindowsManagedExecutable(options: BindWindowsManagedExecutableOptions): Promise<BoundWindowsManagedExecutable>;
+/**
+ * Prepare a launcher-consumed update descriptor. This function never mutates
+ * the live executable and never spawns a competing relaunch process.
+ *
+ * The stable lifecycle controller runs updater.exe before it starts target.
+ * The worker applies pending.json while no target process exists, then removes
+ * pending.json only after an idempotently durable success result is written.
+ */
+export declare function prepareWindowsExecutableSwap(options: PrepareWindowsUpdaterOptions): Promise<WindowsUpdaterDescriptor>;
+/**
+ * Apply the pending operation before the stable controller starts target.
+ * A successful swap is idempotent across crashes after rename: if target
+ * already has source's content, the helper only finalizes result/pending state.
+ */
+export declare function applyPendingWindowsExecutableSwap(options?: ApplyWindowsUpdaterOptions): Promise<WindowsUpdaterResult>;
+/** Return undefined for normal execution, otherwise the launcher helper exit code. */
+export declare function maybeRunWindowsUpdaterWorkerFromArgv(options?: {
+    argv?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    processExecPath?: string;
+}): Promise<number | undefined>;