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

package/dist/selfUpdate/executor.js

@@ -4,15 +4,16 @@
 // shells out or touches a real install tree by accident.
 //
 // THE HARD GATE (verify-before-apply, non-negotiable): after download and BEFORE any filesystem write or restart,
-// the executor calls the PURE core verifyManifest. If verification fails — bad sha256, missing/invalid signature
+// the executor calls the PURE core verifySelectedManifestArtifact. If verification fails — bad sha256,
+// missing/invalid signature
 // when a key is configured, anything — the executor writes NOTHING, restarts NOTHING, and returns a structured
 // failure. The old version stays intact and runnable. A compromised hub cannot turn this channel into fleet RCE.
 //
 // Concurrency: a process-level mutex guarantees that concurrent force_update messages execute the update EXACTLY
 // once. The second caller short-circuits with `already_in_progress` and performs no I/O.
 import { ops } from '@evomap/evolver-core';
-import { SELF_UPDATE_FAILURE_CODES, classifySelfUpdateError, codeForDecisionReject, } from './failureCodes.js';
-const { decideUpdate, verifyManifest } = ops;
+import { SELF_UPDATE_FAILURE_CODES, classifySelfUpdateError, codeForDecisionReject, selfUpdateFailure, } from './failureCodes.js';
+const { decideUpdate, verifySelectedManifestArtifact } = ops;
 // Process-level mutex. Module scope is correct: there is one daemon per process, and v1's _forceUpdateInFlight had
 // the same lifetime. Guards against two force_update envelopes (or a heartbeat-driven + mailbox-driven trigger)
 // racing the same upgrade and replacing files twice / double-restarting.
@@ -31,22 +32,28 @@ function report(deps, result) {
     return result;
 }
 /**
- * Execute a force_update directive end to end: decide → (mutex) → download → VERIFY → atomic replace → restart.
+ * Execute a force_update directive end to end: fast exits → lease → resolve/decide → download → VERIFY → replace → restart.
  *
  * Order is load-bearing:
- *  1. policy off → do nothing (the default-off risk gate; a half-built channel must not auto-apply).
- *  2. decideUpdate (pure): reject bad manifests, NOOP when already satisfied (no download, no restart).
- *  3. mutex: exactly one execution; concurrent callers get `already_in_progress` and touch no disk.
- *  4. download the staged release.
- *  5. verifyManifest (pure) — THE GATE. Fail → no write, no restart, `rejected_verification`.
- *  6. atomicReplace, then restart(). Only reached after verification passed.
+ *  1. policy off → do nothing (explicit opt-out; auto is hard-gated upstream by supervisor + public key).
+ *  2. reject malformed/already-satisfied required versions without acquiring the lifecycle owner lease.
+ *  3. mutex + lifecycle owner lease: exactly one executor may resolve or mutate release state.
+ *  4. resolve and decideUpdate (pure): reject bad manifests or NOOP under the held lease.
+ *  5. download the staged release.
+ *  6. verifySelectedManifestArtifact (pure) — THE GATE. Fail → no write, no restart.
+ *  7. atomicReplace, then restart(). Only reached after verification passed.
  *
  * Never throws: every failure becomes a structured SelfUpdateResult so the daemon can report it and keep running
  * on the old (intact) version.
  */
 export async function executeForceUpdate(directive, deps) {
+    let selectedResult;
+    const finish = (result) => {
+        selectedResult = result;
+        return report(deps, result);
+    };
     if (deps.policy !== 'auto') {
-        return report(deps, {
+        return finish({
             outcome: 'disabled',
             reason: deps.policy === 'prompt' ? 'self_update_policy_prompt_requires_approval' : 'self_update_policy_off',
         });
@@ -55,87 +62,202 @@ export async function executeForceUpdate(directive, deps) {
         ? ops.normalizeRequiredVersion(directive.required_version)
         : undefined;
     if (directive.required_version !== undefined && !requiredFloor) {
-        return report(deps, {
+        return finish({
             outcome: 'rejected_decision',
             reason: 'required_version_invalid',
             failureCode: SELF_UPDATE_FAILURE_CODES.BAD_REQUIRED_VERSION,
         });
     }
     if (requiredFloor && ops.currentSatisfiesRequiredVersion(deps.currentVersion, requiredFloor)) {
-        return report(deps, { outcome: 'noop', reason: 'already_satisfied', targetVersion: requiredFloor });
+        return finish({ outcome: 'noop', reason: 'already_satisfied', targetVersion: requiredFloor });
     }
-    let manifest = directive.manifest;
-    if (deps.resolveManifest && shouldResolveManifest(directive, manifest, Boolean(deps.publicKey))) {
-        try {
-            manifest = await deps.resolveManifest(directive, deps.currentVersion);
-        }
-        catch (err) {
-            const targetVersion = ops.normalizeRequiredVersion(directive.required_version);
-            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
-            return report(deps, {
-                outcome: 'download_failed',
-                reason: `manifest_resolve_failed: ${classified.detail}`,
-                failureCode: classified.failureCode,
-                ...(targetVersion ? { targetVersion } : {}),
-            });
-        }
-    }
-    const effectiveDirective = { ...directive, manifest };
-    const decision = decideUpdate({
-        current: deps.currentVersion,
-        ...(requiredFloor ? { required: requiredFloor } : {}),
-        manifest,
-    });
-    if (decision.action === 'reject') {
-        return report(deps, {
-            outcome: 'rejected_decision',
-            reason: decision.reason,
-            failureCode: codeForDecisionReject(decision.reason),
-            ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}),
-        });
-    }
-    if (decision.action === 'noop') {
-        return report(deps, { outcome: 'noop', reason: decision.reason, ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}) });
-    }
-    // action === 'proceed'. Take the mutex; a concurrent force_update short-circuits here with NO I/O.
+    // The mutex and lifecycle lease precede manifest resolution, which is release I/O too.
+    // Policy, malformed required-version, and already-satisfied fast exits remain lock-free.
     if (inFlight) {
-        return report(deps, { outcome: 'already_in_progress', reason: 'another_update_in_flight' });
+        return finish({ outcome: 'already_in_progress', reason: 'another_update_in_flight' });
     }
     inFlight = true;
-    const targetVersion = decision.targetVersion ?? manifest?.version ?? '';
+    let targetVersion = requiredFloor ?? '';
+    let lifecycleLease;
+    let transaction;
+    const assertLifecycleLease = async () => {
+        try {
+            await lifecycleLease?.assertOwned();
+        }
+        catch (error) {
+            const classified = classifySelfUpdateError(error, SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED);
+            throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED, `self_update_lifecycle_owner_lease_lost:${classified.detail}`, { cause: error });
+        }
+    };
     try {
+        if (deps.acquireLifecycleLease) {
+            try {
+                lifecycleLease = await deps.acquireLifecycleLease();
+                await assertLifecycleLease();
+            }
+            catch (err) {
+                const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED);
+                return finish({
+                    outcome: classified.failureCode === SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED
+                        ? 'already_in_progress'
+                        : 'replace_failed',
+                    reason: classified.detail,
+                    failureCode: classified.failureCode,
+                    ...(targetVersion ? { targetVersion } : {}),
+                });
+            }
+        }
+        let manifest = directive.manifest;
+        if (deps.resolveManifest && shouldResolveManifest(directive, manifest, Boolean(deps.publicKey))) {
+            try {
+                await assertLifecycleLease();
+                manifest = await deps.resolveManifest(directive, deps.currentVersion);
+            }
+            catch (err) {
+                const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
+                if (classified.failureCode === SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED) {
+                    return finish({
+                        outcome: 'replace_failed',
+                        reason: classified.detail,
+                        failureCode: classified.failureCode,
+                        ...(targetVersion ? { targetVersion } : {}),
+                    });
+                }
+                return finish({
+                    outcome: 'download_failed',
+                    reason: `manifest_resolve_failed: ${classified.detail}`,
+                    failureCode: classified.failureCode,
+                    ...(targetVersion ? { targetVersion } : {}),
+                });
+            }
+        }
+        const effectiveDirective = { ...directive, manifest };
+        const decision = decideUpdate({
+            current: deps.currentVersion,
+            ...(requiredFloor ? { required: requiredFloor } : {}),
+            manifest,
+        });
+        if (decision.action === 'reject') {
+            return finish({
+                outcome: 'rejected_decision',
+                reason: decision.reason,
+                failureCode: codeForDecisionReject(decision.reason),
+                ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}),
+            });
+        }
+        if (decision.action === 'noop') {
+            return finish({
+                outcome: 'noop',
+                reason: decision.reason,
+                ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}),
+            });
+        }
+        targetVersion = decision.targetVersion ?? manifest?.version ?? '';
+        if (deps.beginTransaction) {
+            try {
+                await assertLifecycleLease();
+                transaction = await deps.beginTransaction(targetVersion);
+            }
+            catch (err) {
+                const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED);
+                return finish({
+                    outcome: classified.failureCode === SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED ? 'already_in_progress' : 'replace_failed',
+                    reason: classified.detail,
+                    failureCode: classified.failureCode,
+                    targetVersion,
+                });
+            }
+        }
         // 4. Download the staged release.
         let dl;
         try {
+            await assertLifecycleLease();
             dl = await deps.download(targetVersion, effectiveDirective);
         }
         catch (err) {
             const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
-            return report(deps, {
+            await transaction?.abort(classified.failureCode).catch(() => { });
+            if (classified.failureCode === SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED) {
+                return finish({
+                    outcome: 'replace_failed',
+                    reason: classified.detail,
+                    failureCode: classified.failureCode,
+                    targetVersion,
+                });
+            }
+            return finish({
                 outcome: 'download_failed',
                 reason: classified.detail,
                 failureCode: classified.failureCode,
                 targetVersion,
             });
         }
+        if (transaction) {
+            try {
+                await assertLifecycleLease();
+                dl = await transaction.adoptDownloaded(dl);
+            }
+            catch (err) {
+                await transaction.abort(SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED).catch(() => { });
+                const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED);
+                return finish({
+                    outcome: 'replace_failed',
+                    reason: classified.detail,
+                    failureCode: classified.failureCode,
+                    targetVersion,
+                });
+            }
+        }
         // 5. THE GATE: verify the downloaded bytes against the (optionally signed) manifest BEFORE any write.
-        const verification = verifyManifest(manifest, dl.artifacts, ...(deps.publicKey ? [deps.publicKey] : []));
+        try {
+            await assertLifecycleLease();
+        }
+        catch (err) {
+            await transaction?.abort(SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED).catch(() => { });
+            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED);
+            return finish({
+                outcome: 'replace_failed',
+                reason: classified.detail,
+                failureCode: classified.failureCode,
+                targetVersion,
+            });
+        }
+        const verification = verifySelectedManifestArtifact(manifest, dl.artifacts, ...(deps.publicKey ? [deps.publicKey] : []));
         if (!verification.ok) {
+            await transaction?.abort(SELF_UPDATE_FAILURE_CODES.REJECTED_VERIFICATION).catch(() => { });
             // Verification failed → write NOTHING, restart NOTHING. Old version stays intact and runnable.
-            return report(deps, {
+            return finish({
                 outcome: 'rejected_verification',
                 reason: verification.reason,
                 failureCode: SELF_UPDATE_FAILURE_CODES.REJECTED_VERIFICATION,
                 targetVersion,
             });
         }
+        try {
+            await assertLifecycleLease();
+            await transaction?.markVerified(dl.artifacts);
+        }
+        catch (err) {
+            await transaction?.abort(SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED).catch(() => { });
+            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED);
+            return finish({
+                outcome: 'replace_failed',
+                reason: classified.detail,
+                failureCode: classified.failureCode,
+                targetVersion,
+            });
+        }
         // 6. Verified. Atomic replace, then signal restart. A replace failure leaves the old version intact.
         try {
-            await deps.atomicReplace(dl.stagedPath);
+            await assertLifecycleLease();
+            if (transaction)
+                await transaction.install();
+            else
+                await deps.atomicReplace(dl.stagedPath);
         }
         catch (err) {
             const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.COPY_FAILED);
-            return report(deps, {
+            return finish({
                 outcome: 'replace_failed',
                 reason: classified.detail,
                 failureCode: classified.failureCode,
@@ -147,17 +269,70 @@ export async function executeForceUpdate(directive, deps) {
             reason: 'verified_and_replaced',
             targetVersion,
             appliedVia: dl.appliedVia ?? 'binary',
+            ...(transaction ? { confirmationPending: true } : {}),
         };
-        report(deps, result);
-        deps.restart(); // v1 convention: exit(78) → supervisor relaunches the new version.
+        finish(result);
+        try {
+            await assertLifecycleLease();
+            await transaction?.markRestartRequested();
+            await assertLifecycleLease();
+            await deps.restart(); // v1 convention: exit(78) → supervisor relaunches the new version.
+        }
+        catch (err) {
+            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.RESTART_FAILED);
+            try {
+                await transaction?.rollback(classified.failureCode);
+            }
+            catch (rollbackError) {
+                const rollback = classifySelfUpdateError(rollbackError, SELF_UPDATE_FAILURE_CODES.ROLLBACK_FAILED);
+                return finish({
+                    outcome: 'rollback_failed',
+                    reason: rollback.detail,
+                    failureCode: rollback.failureCode,
+                    targetVersion,
+                });
+            }
+            return finish({
+                outcome: 'restart_failed',
+                reason: classified.detail,
+                failureCode: classified.failureCode,
+                targetVersion,
+            });
+        }
         return result;
     }
     finally {
-        // Released so a later legitimate update (after a failed attempt) can proceed. On the success path the process
-        // is exiting anyway; releasing is harmless and keeps the mutex honest if restart() is a test fake that returns.
+        await transaction?.release().catch(() => { });
+        if (lifecycleLease) {
+            try {
+                await lifecycleLease.release();
+            }
+            catch (error) {
+                if (selectedResult) {
+                    selectedResult.cleanupWarning = boundedCleanupWarning(error);
+                    if (selectedResult.outcome === 'applied') {
+                        selectedResult.reason = 'verified_and_replaced_lifecycle_lease_release_unconfirmed';
+                    }
+                    try {
+                        deps.onCleanupWarning?.(selectedResult.cleanupWarning, selectedResult);
+                    }
+                    catch {
+                        // Cleanup reporting must not replace the primary update outcome.
+                    }
+                }
+            }
+        }
         inFlight = false;
     }
 }
+function boundedCleanupWarning(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const normalized = raw
+        .replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return (normalized || 'self_update_lifecycle_owner_lease_release_failed').slice(0, 512);
+}
 function shouldResolveManifest(directive, manifest, signatureRequired) {
     if (manifest === undefined)
         return true;

package/dist/selfUpdate/failureCodes.d.ts

@@ -17,6 +17,16 @@ export declare const SELF_UPDATE_FAILURE_CODES: Readonly<{
     readonly FALLBACK_DOWNLOAD_FAILED: "fallback_download_failed";
     readonly FALLBACK_EXTRACT_FAILED: "fallback_extract_failed";
     readonly FALLBACK_MISSING_BINARY: "fallback_missing_binary";
+    readonly UPDATE_LOCKED: "update_locked";
+    readonly RECOVERY_REQUIRED: "recovery_required";
+    readonly UNSAFE_UPDATE_PATH: "unsafe_update_path";
+    readonly RESTART_FAILED: "restart_failed";
+    readonly READ_BACK_FAILED: "read_back_failed";
+    readonly ROLLBACK_FAILED: "rollback_failed";
+    readonly MIGRATION_DOWNLOAD_FAILED: "migration_download_failed";
+    readonly MIGRATION_VERIFY_FAILED: "migration_verify_failed";
+    readonly MIGRATION_INSTALL_FAILED: "migration_install_failed";
+    readonly MIGRATION_REGISTER_FAILED: "migration_register_failed";
 }>;
 export type SelfUpdateFailureCode = typeof SELF_UPDATE_FAILURE_CODES[keyof typeof SELF_UPDATE_FAILURE_CODES];
 export interface ClassifiedSelfUpdateError {

package/dist/selfUpdate/failureCodes.js

@@ -22,6 +22,19 @@ export const SELF_UPDATE_FAILURE_CODES = Object.freeze({
     FALLBACK_DOWNLOAD_FAILED: 'fallback_download_failed',
     FALLBACK_EXTRACT_FAILED: 'fallback_extract_failed',
     FALLBACK_MISSING_BINARY: 'fallback_missing_binary',
+    UPDATE_LOCKED: 'update_locked',
+    RECOVERY_REQUIRED: 'recovery_required',
+    UNSAFE_UPDATE_PATH: 'unsafe_update_path',
+    RESTART_FAILED: 'restart_failed',
+    READ_BACK_FAILED: 'read_back_failed',
+    ROLLBACK_FAILED: 'rollback_failed',
+    // One-time npm/JS → standalone binary migration (migration.ts). Append-only:
+    // these surface in attempt-marker detail strings and operator messages so
+    // telemetry can attribute first-run migration failures by phase.
+    MIGRATION_DOWNLOAD_FAILED: 'migration_download_failed',
+    MIGRATION_VERIFY_FAILED: 'migration_verify_failed',
+    MIGRATION_INSTALL_FAILED: 'migration_install_failed',
+    MIGRATION_REGISTER_FAILED: 'migration_register_failed',
 });
 export class SelfUpdateFailureError extends Error {
     failureCode;

package/dist/selfUpdate/index.d.ts

@@ -2,4 +2,8 @@ export * from './executor.js';
 export * from './version.js';
 export * from './policy.js';
 export * from './releaseBinary.js';
-export * from './failureCodes.js';
+export * from './transaction.js';
+export * from './failureCodes.js';
+export * from './unixController.js';
+export * from './windowsController.js';
+export * from './bootstrapReadiness.js';

package/dist/selfUpdate/index.js

@@ -2,4 +2,8 @@ export * from './executor.js';
 export * from './version.js';
 export * from './policy.js';
 export * from './releaseBinary.js';
-export * from './failureCodes.js';
+export * from './transaction.js';
+export * from './failureCodes.js';
+export * from './unixController.js';
+export * from './windowsController.js';
+export * from './bootstrapReadiness.js';

package/dist/selfUpdate/lastUpdate.d.ts

@@ -1,5 +1,6 @@
 import { mailbox } from '@evomap/evolver-core';
 import type { ForceUpdateDirective, SelfUpdateResult } from './executor.js';
+import type { SelfUpdateRecoveryResult } from './transaction.js';
 type MailboxStore = mailbox.MailboxStore;
 type LastUpdateStatus = 'success' | 'failed' | 'skipped' | 'pending';
 export interface LastUpdatePayload {
@@ -12,7 +13,7 @@ export interface LastUpdatePayload {
     /**
      * Which download channel produced the bytes that got applied: `'binary'` is
      * the precompiled-asset happy path, `'tarball'` means Channel 1b fallback
-     * (release `.tar.gz`) was used. Persisted on success so the hub can see
+     * (release `.tar.gz`) was used. Persisted while confirmation is pending and on success so the hub can see
      * "primary CDN is degraded — fallback carrying production" without having
      * to mine telemetry. Absent on non-success or when the executor predates
      * the appliedVia field.
@@ -36,6 +37,7 @@ export declare function reportPendingSelfUpdateLastUpdate(store: MailboxStore, d
     fromVersion: string;
     now?: number;
 }): boolean;
+export declare function finalizeSelfUpdateRecoveryLastUpdate(store: MailboxStore, recovery: SelfUpdateRecoveryResult, now?: number): boolean;
 export declare function lastUpdateFromSelfUpdateResult(directive: ForceUpdateDirective, result: SelfUpdateResult, opts: {
     fromVersion: string;
     now: number;

package/dist/selfUpdate/lastUpdate.js

@@ -86,6 +86,37 @@ export function reportPendingSelfUpdateLastUpdate(store, directive, opts = { fro
         ...(directive.directive_id ? { directive_id: String(directive.directive_id) } : {}),
     }, now);
 }
+export function finalizeSelfUpdateRecoveryLastUpdate(store, recovery, now = Date.now()) {
+    if (recovery.outcome !== 'confirmed'
+        && recovery.outcome !== 'rolled_back'
+        && recovery.outcome !== 'blocked')
+        return false;
+    const toVersion = concreteVersion(recovery.targetVersion);
+    const fromVersion = concreteVersion(recovery.fromVersion);
+    if (!toVersion)
+        return false;
+    const current = readPendingLastUpdate(store, now);
+    if (current && current.to_version !== toVersion)
+        return false;
+    const common = {
+        to_version: toVersion,
+        finished_at: Math.max(now, FINISHED_AT_MIN_MS),
+        ...(current?.directive_id ? { directive_id: current.directive_id } : {}),
+        ...(current?.from_version ? { from_version: current.from_version } : fromVersion ? { from_version: fromVersion } : {}),
+    };
+    if (recovery.outcome === 'confirmed') {
+        return writeLastUpdate(store, {
+            ...common,
+            status: 'success',
+            ...(current?.applied_via ? { applied_via: current.applied_via } : {}),
+        }, now);
+    }
+    return writeLastUpdate(store, {
+        ...common,
+        status: 'failed',
+        error: clampString(hubNs.redactString(`${recovery.failureCode ?? 'self_update_recovery_failed'}: ${recovery.outcome}`), LAST_UPDATE_ERROR_MAX),
+    }, now);
+}
 export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
     if (result.outcome === 'already_in_progress' || result.outcome === 'disabled')
         return undefined;
@@ -94,11 +125,11 @@ export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
         return undefined;
     const base = {
         to_version: toVersion,
-        status: statusForOutcome(result.outcome),
+        status: statusForResult(result),
         finished_at: Math.max(opts.now, FINISHED_AT_MIN_MS),
         ...(directive.directive_id ? { directive_id: String(directive.directive_id) } : {}),
     };
-    if (base.status === 'success') {
+    if (base.status === 'success' || base.status === 'pending') {
         return {
             ...base,
             from_version: clampString(opts.fromVersion, LAST_UPDATE_FROM_VERSION_MAX),
@@ -114,10 +145,10 @@ export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
     }
     return base;
 }
-function statusForOutcome(outcome) {
-    if (outcome === 'applied')
-        return 'success';
-    if (outcome === 'noop')
+function statusForResult(result) {
+    if (result.outcome === 'applied')
+        return result.confirmationPending ? 'pending' : 'success';
+    if (result.outcome === 'noop')
         return 'skipped';
     return 'failed';
 }