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

package/dist/selfUpdate/executor.d.ts

@@ -1,8 +1,9 @@
 import { ops } from '@evomap/evolver-core';
 import { type SelfUpdateFailureCode } from './failureCodes.js';
+import type { DurableSelfUpdateSession } from './transaction.js';
 type DownloadedArtifact = ops.DownloadedArtifact;
 /** Structured outcome codes — reported to telemetry; the hub sees WHY an update did/didn't apply. */
-export type SelfUpdateOutcome = 'applied' | 'noop' | 'rejected_decision' | 'rejected_verification' | 'download_failed' | 'replace_failed' | 'already_in_progress' | 'disabled';
+export type SelfUpdateOutcome = 'applied' | 'noop' | 'rejected_decision' | 'rejected_verification' | 'download_failed' | 'replace_failed' | 'restart_failed' | 'rollback_failed' | 'already_in_progress' | 'disabled';
 export interface SelfUpdateResult {
     outcome: SelfUpdateOutcome;
     reason: string;
@@ -13,13 +14,15 @@ export interface SelfUpdateResult {
     /**
      * Which download path produced the staged binary: `'binary'` is the normal
      * precompiled-asset happy path, `'tarball'` means the binary download failed
-     * and Channel 1b (release `.tar.gz`) fallback was used. The verifyManifest
+     * and Channel 1b (release `.tar.gz`) fallback was used. The selected-artifact
      * gate ran in BOTH cases, so apply-semantics are identical, but "tarball
      * used in production" is a useful CDN/rate-limit signal for the hub.
      * Persisted into `last_update.json` (lastUpdate.LastUpdatePayload.applied_via)
      * on success so the hub can observe the channel directly.
      */
     appliedVia?: 'binary' | 'tarball';
+    /** Durable installs are not successful until the relaunched daemon completes startup health checks. */
+    confirmationPending?: true;
 }
 /** The hub's force_update directive (inbound message payload). */
 export interface ForceUpdateDirective {
@@ -36,7 +39,7 @@ export interface ForceUpdateDirective {
 export interface DownloadResult {
     /** Where the new version was staged (e.g. a tmp dir). Passed to atomicReplace on success. */
     stagedPath: string;
-    /** The downloaded artifacts (bytes or precomputed sha256) for verifyManifest. */
+    /** Exactly one selected artifact (bytes or precomputed sha256) for verification. */
     artifacts: readonly DownloadedArtifact[];
     /**
      * Which channel actually produced the staged bytes — defaults to `'binary'`
@@ -63,8 +66,10 @@ export interface SelfUpdateDeps {
     download: (targetVersion: string, directive: ForceUpdateDirective) => Promise<DownloadResult>;
     /** Atomically replace the install tree with the staged path (preserving node_modules/.env/etc). Throws on fail. */
     atomicReplace: (stagedPath: string) => Promise<void>;
+    /** Optional durable transaction: cross-process lock + journal + backup + recovery-aware install. */
+    beginTransaction?: (targetVersion: string) => Promise<DurableSelfUpdateSession>;
     /** Signal a restart so the supervisor relaunches the new version. v1 convention: process.exit(78). */
-    restart: () => void;
+    restart: () => void | Promise<void>;
     /** Optional Ed25519 public key (PEM / raw base64). When set, an unsigned/badly-signed manifest is REJECTED. */
     publicKey?: string;
     /** Best-effort telemetry sink for the structured outcome (never throws into the update path). */
@@ -80,7 +85,7 @@ export declare function _resetSelfUpdateMutex(): void;
  *  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`.
+ *  5. verifySelectedManifestArtifact (pure) — THE GATE. Fail → no write, no restart.
  *  6. 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

package/dist/selfUpdate/executor.js

@@ -4,7 +4,8 @@
 // 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.
 //
@@ -12,7 +13,7 @@
 // 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;
+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.
@@ -38,7 +39,7 @@ function report(deps, result) {
  *  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`.
+ *  5. verifySelectedManifestArtifact (pure) — THE GATE. Fail → no write, no restart.
  *  6. 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
@@ -103,13 +104,29 @@ export async function executeForceUpdate(directive, deps) {
     }
     inFlight = true;
     const targetVersion = decision.targetVersion ?? manifest?.version ?? '';
+    let transaction;
     try {
+        if (deps.beginTransaction) {
+            try {
+                transaction = await deps.beginTransaction(targetVersion);
+            }
+            catch (err) {
+                const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED);
+                return report(deps, {
+                    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 {
             dl = await deps.download(targetVersion, effectiveDirective);
         }
         catch (err) {
+            await transaction?.abort(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED).catch(() => { });
             const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
             return report(deps, {
                 outcome: 'download_failed',
@@ -118,9 +135,25 @@ export async function executeForceUpdate(directive, deps) {
                 targetVersion,
             });
         }
+        if (transaction) {
+            try {
+                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 report(deps, {
+                    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] : []));
+        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, {
                 outcome: 'rejected_verification',
@@ -129,9 +162,25 @@ export async function executeForceUpdate(directive, deps) {
                 targetVersion,
             });
         }
+        try {
+            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 report(deps, {
+                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);
+            if (transaction)
+                await transaction.install();
+            else
+                await deps.atomicReplace(dl.stagedPath);
         }
         catch (err) {
             const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.COPY_FAILED);
@@ -147,12 +196,38 @@ 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.
+        try {
+            await transaction?.markRestartRequested();
+            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 report(deps, {
+                    outcome: 'rollback_failed',
+                    reason: rollback.detail,
+                    failureCode: rollback.failureCode,
+                    targetVersion,
+                });
+            }
+            return report(deps, {
+                outcome: 'restart_failed',
+                reason: classified.detail,
+                failureCode: classified.failureCode,
+                targetVersion,
+            });
+        }
         return result;
     }
     finally {
+        await transaction?.release().catch(() => { });
         // 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.
         inFlight = false;

package/dist/selfUpdate/failureCodes.d.ts

@@ -17,6 +17,12 @@ 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";
 }>;
 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,12 @@ 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',
 });
 export class SelfUpdateFailureError extends Error {
     failureCode;

package/dist/selfUpdate/index.d.ts

@@ -2,4 +2,7 @@ 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';

package/dist/selfUpdate/index.js

@@ -2,4 +2,7 @@ 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';

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';
 }

package/dist/selfUpdate/releaseBinary.d.ts

@@ -11,8 +11,18 @@ export interface ReleaseBinaryOptions {
     targetPath?: string;
     processExecPath?: string;
     requireSignedManifest?: boolean;
+    maxPrimaryBinaryBytes?: number;
     maxExtractedTarballBytes?: number;
 }
+/**
+ * Hard ceiling for primary release binaries. The binary is buffered before its
+ * manifest hash is verified, so an unbounded response could exhaust memory
+ * before the verification gate runs. 128MiB leaves headroom above current
+ * single-platform binaries while bounding that pre-verification allocation.
+ */
+export declare const MAX_PRIMARY_BINARY_BYTES: number;
+/** Release metadata is untrusted and buffered before parsing or verification. */
+export declare const MAX_RELEASE_METADATA_BYTES: number;
 /**
  * Hard ceiling for Channel 1b tarball downloads. A compromised/corrupt release
  * could advertise a multi-GB tar.gz and OOM us because tarballBytes is buffered

package/dist/selfUpdate/releaseBinary.js

@@ -8,6 +8,15 @@ import { SELF_UPDATE_FAILURE_CODES, SelfUpdateFailureError, selfUpdateFailure }
 const DEFAULT_RELEASES_URL = 'https://github.com/EvoMap/evolver/releases';
 const SIGNED_MANIFEST_ASSET = 'evolver-update-manifest.json';
 const RELEASE_DOWNLOAD_TIMEOUT_MS = 60_000;
+/**
+ * Hard ceiling for primary release binaries. The binary is buffered before its
+ * manifest hash is verified, so an unbounded response could exhaust memory
+ * before the verification gate runs. 128MiB leaves headroom above current
+ * single-platform binaries while bounding that pre-verification allocation.
+ */
+export const MAX_PRIMARY_BINARY_BYTES = 128 * 1024 * 1024;
+/** Release metadata is untrusted and buffered before parsing or verification. */
+export const MAX_RELEASE_METADATA_BYTES = 256 * 1024;
 /**
  * Hard ceiling for Channel 1b tarball downloads. A compromised/corrupt release
  * could advertise a multi-GB tar.gz and OOM us because tarballBytes is buffered
@@ -75,7 +84,7 @@ export async function downloadGithubReleaseArtifact(targetVersion, directive, op
 }
 async function downloadBinaryAsset(version, assetName, directive, opts) {
     const assetUrl = releaseDownloadUrl(directive.release_url, version, assetName);
-    const bytes = Buffer.from(await fetchBytes(assetUrl, opts.fetchFn));
+    const bytes = Buffer.from(await fetchBytes(assetUrl, opts.fetchFn, resolvedPrimaryBinaryLimit(opts.maxPrimaryBinaryBytes)));
     if (bytes.byteLength === 0) {
         throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_INCOMPLETE, `empty release asset:${assetName}`);
     }
@@ -192,7 +201,7 @@ export async function atomicReplaceExecutable(stagedPath, opts = {}) {
     }
 }
 export function resolveSelfUpdateTarget(opts = {}) {
-    const explicitTarget = opts.targetPath ?? opts.env?.['EVOLVER_SELF_UPDATE_TARGET_PATH'];
+    const explicitTarget = opts.targetPath ?? opts.env?.['EVOLVER_SELF_UPDATE_TARGET_PATH']?.trim();
     if (explicitTarget)
         return { path: explicitTarget, explicit: true };
     const execPath = opts.processExecPath ?? process.execPath;
@@ -207,7 +216,10 @@ function releaseDownloadUrl(releaseUrl, version, assetName) {
         base = new URL(releaseUrl && releaseUrl.trim() ? releaseUrl : DEFAULT_RELEASES_URL);
     }
     catch (err) {
-        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED, errorDetail(err), { cause: err });
+        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED, 'invalid_release_url', { cause: err });
+    }
+    if (base.username || base.password) {
+        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED, 'invalid_release_url_credentials');
     }
     if (base.protocol !== 'https:' || base.hostname !== 'github.com') {
         throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED, 'invalid_release_url_origin');
@@ -242,8 +254,8 @@ async function fetchSignedReleaseManifest(releaseUrl, version, assetName, fetchF
     if (!manifestVersion) {
         throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_INCOMPLETE, 'signed_manifest_invalid_version');
     }
-    if (!ops.currentSatisfiesRequiredVersion(manifestVersion, version)) {
-        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOADED_VERSION_MISMATCH, 'signed_manifest_below_required');
+    if (manifestVersion !== version) {
+        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOADED_VERSION_MISMATCH, 'signed_manifest_version_mismatch');
     }
     const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
     if (!artifacts.some((artifact) => artifact && typeof artifact.path === 'string' && basename(artifact.path) === assetName)) {
@@ -253,7 +265,8 @@ async function fetchSignedReleaseManifest(releaseUrl, version, assetName, fetchF
 }
 async function fetchText(url, fetchFn) {
     const fetched = await fetchWith(url, fetchFn);
-    return readBodyWithTimeout(url, 'text', () => fetched.response.text(), fetched.abort);
+    const bytes = await readBodyWithTimeout(url, 'text', () => readBytesWithLimit(fetched.response, MAX_RELEASE_METADATA_BYTES, fetched.abort), fetched.abort);
+    return Buffer.from(bytes).toString('utf8');
 }
 async function fetchBytes(url, fetchFn, maxBytes) {
     const fetched = await fetchWith(url, fetchFn);
@@ -267,6 +280,12 @@ async function readBytesWithLimit(response, maxBytes, abort) {
         }
         return arr;
     }
+    const declaredBytes = parseContentLength(response.headers.get('content-length'));
+    if (declaredBytes !== undefined && declaredBytes > maxBytes) {
+        abort();
+        await response.body.cancel().catch(() => { });
+        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_INCOMPLETE, `release_body_too_large:${declaredBytes} > ${maxBytes}`);
+    }
     const reader = response.body.getReader();
     const chunks = [];
     let totalBytes = 0;
@@ -297,6 +316,15 @@ async function readBytesWithLimit(response, maxBytes, abort) {
     }
     return out.buffer;
 }
+function parseContentLength(raw) {
+    const trimmed = raw?.trim();
+    if (!trimmed || !/^\d+$/.test(trimmed))
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed))
+        return Number.POSITIVE_INFINITY;
+    return parsed;
+}
 async function fetchWith(url, fetchFn) {
     const fn = fetchFn ?? globalThis.fetch;
     if (!fn)
@@ -472,6 +500,15 @@ function resolvedExtractedTarballLimit(requested) {
         return MAX_EXTRACTED_TARBALL_BYTES;
     return Math.min(Math.floor(requested), MAX_EXTRACTED_TARBALL_BYTES);
 }
+function resolvedPrimaryBinaryLimit(requested) {
+    if (requested === undefined)
+        return MAX_PRIMARY_BINARY_BYTES;
+    if (!Number.isFinite(requested) || requested <= 0)
+        return MAX_PRIMARY_BINARY_BYTES;
+    // Tests may lower the cap without providing a production escape hatch that
+    // could raise or disable the hard safety boundary.
+    return Math.min(Math.floor(requested), MAX_PRIMARY_BINARY_BYTES);
+}
 function readTarString(block, start, length) {
     let end = start;
     const max = start + length;

package/dist/selfUpdate/transaction.d.ts

@@ -0,0 +1,109 @@
+import type { DownloadResult } from './executor.js';
+import { type ReleaseBinaryOptions } from './releaseBinary.js';
+export type SelfUpdateJournalStage = 'preparing' | 'downloaded' | 'verified' | 'backed_up' | 'install_pending' | 'installed' | 'restarted' | 'health_check_pending' | 'rolling_back' | 'rollback_pending' | 'confirmed' | 'rolled_back' | 'rollback_failed';
+export interface SelfUpdateJournal {
+    schema_version: 2;
+    transaction_id: string;
+    stage: SelfUpdateJournalStage;
+    from_version: string;
+    target_version: string;
+    platform: NodeJS.Platform;
+    arch: NodeJS.Architecture;
+    installing_pid: number;
+    created_at: string;
+    updated_at: string;
+    recovery_attempts: number;
+    /** Canonical logical install path: real parent directory plus the target leaf name. */
+    target_path: string;
+    /** Normalized operator-configured spelling used only when its parent can no longer be resolved. */
+    configured_target_path?: string;
+    staged_name?: string;
+    backup_name?: string;
+    failure_code?: string;
+    verified_sha256?: string;
+}
+export interface DurableSelfUpdateSession {
+    adoptDownloaded(download: DownloadResult): Promise<DownloadResult>;
+    markVerified(artifacts: readonly {
+        bytes?: Uint8Array;
+        sha256?: string;
+    }[]): Promise<void>;
+    install(): Promise<void>;
+    markRestartRequested(): Promise<void>;
+    abort(failureCode: string): Promise<void>;
+    rollback(failureCode: string): Promise<void>;
+    release(): Promise<void>;
+}
+export interface SelfUpdateRecoveryResult {
+    outcome: 'none' | 'pending_health' | 'rollback_pending' | 'confirmed' | 'rolled_back' | 'blocked';
+    stage?: SelfUpdateJournalStage;
+    targetVersion?: string;
+    fromVersion?: string;
+    restartRequired?: boolean;
+    failureCode?: string;
+}
+export interface StagedBinaryProbeOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeout: number;
+    windowsHide: boolean;
+    maxBuffer: number;
+}
+export type StagedBinaryProbe = (targetPath: string, args: readonly string[], options: StagedBinaryProbeOptions) => Promise<{
+    stdout: string;
+}>;
+export interface DurableSelfUpdateOptions extends ReleaseBinaryOptions {
+    stateDir?: string;
+    currentVersion: string;
+    platform?: NodeJS.Platform;
+    arch?: NodeJS.Architecture;
+    pid?: number;
+    now?: () => Date;
+    readBackVersion?: (targetPath: string) => Promise<string>;
+    stagedBinaryProbe?: StagedBinaryProbe;
+    /** Test hook invoked after a stale lock generation is observed and before its successor is published. */
+    beforeStaleLockReclaim?: () => void | Promise<void>;
+}
+export type SelfUpdateRecoveryOptions = Omit<DurableSelfUpdateOptions, 'currentVersion'> & {
+    currentVersion?: string;
+    /** Runs after a durable journal is loaded and before recovery changes the journal, target, or managed artifacts. */
+    beforeJournalMutation?: () => void | Promise<void>;
+};
+export interface StableUnixRecoveryControllerOptions extends SelfUpdateRecoveryOptions {
+    platform?: NodeJS.Platform;
+}
+export interface StableWindowsRecoveryControllerOptions extends SelfUpdateRecoveryOptions {
+    platform?: NodeJS.Platform;
+}
+export declare function inspectDurableSelfUpdate(options: SelfUpdateRecoveryOptions): Promise<SelfUpdateRecoveryResult>;
+export declare function resolveStableUnixRecoveryControllerPath(options: StableUnixRecoveryControllerOptions): Promise<string>;
+export declare function stableUnixRecoveryControllerPathForTarget(targetPath: string, stateDir?: string): string;
+/**
+ * Installs an executable copy outside the mutable target path. The transaction
+ * lock and the existing no-follow file primitives keep service installation
+ * from racing an update or copying through a symlink.
+ */
+export declare function provisionStableUnixRecoveryController(options: StableUnixRecoveryControllerOptions): Promise<string>;
+export declare function bindStableUnixRecoveryController(options: StableUnixRecoveryControllerOptions, processExecPath: string): Promise<{
+    controllerPath: string;
+    targetPath: string;
+}>;
+export declare function bindStableWindowsRecoveryController(options: StableWindowsRecoveryControllerOptions, processExecPath: string): Promise<{
+    controllerPath: string;
+    stateDir: string;
+    targetPath: string;
+}>;
+export declare function stableWindowsRecoveryControllerPathForStateDir(stateDir: string): string;
+/**
+ * Provision or refresh the long-lived controller while it is not running.
+ * Service installation stops the Scheduled Task before calling this command;
+ * each self-update only replaces the separate windows-updater worker path.
+ */
+export declare function provisionStableWindowsRecoveryController(options: StableWindowsRecoveryControllerOptions, processExecPath: string): Promise<string>;
+export declare function beginDurableSelfUpdate(targetVersion: string, options: DurableSelfUpdateOptions): Promise<DurableSelfUpdateSession>;
+export declare function recoverDurableSelfUpdate(options: SelfUpdateRecoveryOptions): Promise<SelfUpdateRecoveryResult>;
+export declare function markWindowsInstallApplied(options: SelfUpdateRecoveryOptions): Promise<SelfUpdateRecoveryResult>;
+export declare function confirmDurableSelfUpdate(options: SelfUpdateRecoveryOptions): Promise<SelfUpdateRecoveryResult>;
+export declare function rollbackDurableSelfUpdate(options: SelfUpdateRecoveryOptions, failureCode: string): Promise<SelfUpdateRecoveryResult>;
+export declare function normalizeCanonicalSelfUpdateTargetPath(targetPath: string, platform?: NodeJS.Platform): string;
+export declare function preflightManagedStagedBinary(targetPath: string, expectedVersion: string, probe?: StagedBinaryProbe): Promise<void>;