@veryfront/ext-bundler-esbuild 0.1.1237 → 0.1.1239

package/esm/esbuild-bundler.d.ts

@@ -1,5 +1,15 @@
 import type { BuildContext, BundleOptions, Bundler, BundleResult, TransformOptions, TransformResult } from "veryfront/extensions/bundler";
 import type { ChildProcess } from "node:child_process";
+/**
+ * Unexpected service-child deaths tolerated before the adapter gives up.
+ *
+ * The child can be killed by something outside the process (OOM-kill, a
+ * container runtime signal). That is recoverable: esbuild respawns the
+ * service once its module state is reset, so it must not poison the process
+ * the way foreign ownership does. The budget keeps a crash-looping binary
+ * from respawning forever.
+ */
+export declare const MAX_SERVICE_RESTARTS = 3;
 /**
  * Keep lifecycle tracking tolerant of Node-compatible child-process shims.
  *
@@ -8,8 +18,12 @@ import type { ChildProcess } from "node:child_process";
  */
 /** The ownership latch is module-wide; tests must clear it between cases. */
 export declare function __resetOwnershipErrorForTests(): void;
+/** Crash-recovery state is module-wide; tests must reset it between cases. */
+export declare function __resetServiceRecoveryForTests(): void;
 /** Exercise the latch without starting a real esbuild service. */
 export declare function __recordOwnershipErrorForTests(cause?: unknown): Error;
+/** Exercise trusted esbuild diagnostic normalization without starting a service. */
+export declare function __markEsbuildSourceDiagnosticForTests(error: unknown): void;
 export declare function isLiveEsbuildServiceProcess(child: Pick<ChildProcess, "killed" | "exitCode" | "signalCode">): boolean;
 /**
  * esbuild-backed {@link Bundler} implementation.

package/esm/esbuild-bundler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"esbuild-bundler.d.ts","sourceRoot":"","sources":["../src/esbuild-bundler.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EAEb,OAAO,EACP,YAAY,EAGZ,gBAAgB,EAChB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAgPvD;;;;;GAKG;AACH,6EAA6E;AAC7E,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAED,kEAAkE;AAClE,wBAAgB,8BAA8B,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,CAErE;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC,GAC9D,OAAO,CAIT;AA6HD;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,OAAO;IACtC,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAsCrD,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAa9D,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAqCtD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAiF5B"}
+{"version":3,"file":"esbuild-bundler.d.ts","sourceRoot":"","sources":["../src/esbuild-bundler.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EAEb,OAAO,EACP,YAAY,EAGZ,gBAAgB,EAChB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAkBvD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAqftC;;;;;GAKG;AACH,6EAA6E;AAC7E,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAED,8EAA8E;AAC9E,wBAAgB,8BAA8B,IAAI,IAAI,CAQrD;AAED,kEAAkE;AAClE,wBAAgB,8BAA8B,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,CAErE;AAED,oFAAoF;AACpF,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE1E;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC,GAC9D,OAAO,CAIT;AA8ID;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,OAAO;IACtC,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAsCrD,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAkB9D,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAiEtD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAsH5B"}

package/esm/esbuild-bundler.js

@@ -16,6 +16,22 @@ import { createRequire } from "node:module";
 import { ensureEsbuildBinary } from "./binary.js";
 import { toEsbuildPlugin } from "./plugin-adapter.js";
 const ESBUILD_STOP_TIMEOUT_MS = 5_000;
+const ESBUILD_SOURCE_DIAGNOSTIC = Symbol.for("veryfront.bundler.esbuild-source-diagnostic");
+const ArrayIsArray = Array.isArray;
+const ObjectDefineProperty = Object.defineProperty;
+const ObjectPrototypeHasOwnProperty = Object.prototype.hasOwnProperty;
+const ReflectApply = Reflect.apply;
+const ReflectGetOwnPropertyDescriptor = Reflect.getOwnPropertyDescriptor;
+/**
+ * Unexpected service-child deaths tolerated before the adapter gives up.
+ *
+ * The child can be killed by something outside the process (OOM-kill, a
+ * container runtime signal). That is recoverable: esbuild respawns the
+ * service once its module state is reset, so it must not poison the process
+ * the way foreign ownership does. The budget keeps a crash-looping binary
+ * from respawning forever.
+ */
+export const MAX_SERVICE_RESTARTS = 3;
 const childProcess = createRequire(globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url)("node:child_process");
 let esbuildModule = null;
 let esbuildService = null;
@@ -23,14 +39,86 @@ let esbuildOwnershipError = null;
 let esbuildShutdownError = null;
 let pluginDisposalError = null;
 let esbuildStopPromise = null;
+let esbuildServiceLost = false;
+let esbuildServiceLostDetail = "";
+let remainingServiceRestarts = MAX_SERVICE_RESTARTS;
+let esbuildServiceRecovery = null;
+let esbuildServiceGeneration = 0;
+let serviceLossSpawnGuard = null;
+let esbuildServiceForeignReplacement = null;
 let activeOperationCount = 0;
 let activeOperationsIdle = Promise.resolve();
 let resolveActiveOperationsIdle = null;
+let stopBarrierCount = 0;
+let stopBarrierIdle = Promise.resolve();
+let resolveStopBarrierIdle = null;
 const operationScopes = new AsyncLocalStorage();
 const OWNERSHIP_ERROR_MESSAGE = "[ext-bundler-esbuild] Cannot own an esbuild service started outside the module-wide adapter; restart the process and use only the Bundler contract";
 const MAX_CAUSE_DETAIL_LENGTH = 200;
 /** Absolute POSIX and Windows paths, reduced to a basename below. */
 const ABSOLUTE_PATH_PATTERN = /(?:[A-Za-z]:)?(?:\/|\\\\)[^\s"']*/g;
+function readOwnDataProperty(value, key) {
+    if (value === null ||
+        (typeof value !== "object" && typeof value !== "function")) {
+        return undefined;
+    }
+    try {
+        const descriptor = ReflectGetOwnPropertyDescriptor(value, key);
+        if (descriptor !== undefined &&
+            ReflectApply(ObjectPrototypeHasOwnProperty, descriptor, ["value"]) === true) {
+            return descriptor.value;
+        }
+    }
+    catch {
+        // A hostile proxy cannot provide trusted diagnostic evidence.
+    }
+    return undefined;
+}
+/**
+ * Read esbuild's own diagnostic collection at the direct package boundary.
+ *
+ * esbuild exposes `errors` through an own accessor. Invoking that accessor is
+ * safe only here, before the failure crosses into framework classification.
+ */
+function readTrustedEsbuildErrors(error) {
+    if (error === null || (typeof error !== "object" && typeof error !== "function")) {
+        return undefined;
+    }
+    try {
+        const descriptor = ReflectGetOwnPropertyDescriptor(error, "errors");
+        if (descriptor === undefined)
+            return undefined;
+        if (ReflectApply(ObjectPrototypeHasOwnProperty, descriptor, ["value"]) === true) {
+            return descriptor.value;
+        }
+        const getter = readOwnDataProperty(descriptor, "get");
+        return typeof getter === "function" ? ReflectApply(getter, error, []) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function markEsbuildSourceDiagnostic(error) {
+    const diagnostics = readTrustedEsbuildErrors(error);
+    if (!ArrayIsArray(diagnostics))
+        return;
+    const length = readOwnDataProperty(diagnostics, "length");
+    if (typeof length !== "number")
+        return;
+    for (let index = 0; index < length; index++) {
+        const diagnostic = readOwnDataProperty(diagnostics, index);
+        const location = readOwnDataProperty(diagnostic, "location");
+        if (typeof location !== "object" || location === null)
+            continue;
+        try {
+            ObjectDefineProperty(error, ESBUILD_SOURCE_DIAGNOSTIC, { value: true });
+        }
+        catch {
+            // Non-extensible failures remain unmarked and classify as infrastructure.
+        }
+        return;
+    }
+}
 /**
  * Reduce a cause to a single redacted line.
  *
@@ -99,10 +187,28 @@ function endOperation() {
     activeOperationsIdle = Promise.resolve();
     resolve?.();
 }
+function enterStopBarrier() {
+    if (stopBarrierCount === 0) {
+        stopBarrierIdle = new Promise((resolve) => {
+            resolveStopBarrierIdle = resolve;
+        });
+    }
+    stopBarrierCount += 1;
+}
+function leaveStopBarrier() {
+    stopBarrierCount -= 1;
+    if (stopBarrierCount !== 0)
+        return;
+    const resolve = resolveStopBarrierIdle;
+    resolveStopBarrierIdle = null;
+    stopBarrierIdle = Promise.resolve();
+    resolve?.();
+}
 function createPluginDisposalBarrier(scope) {
     const callbacks = [];
     let activated = false;
     let holdingOperation = false;
+    let disposalError = null;
     const releaseIfSettled = () => {
         if (!holdingOperation || callbacks.some((callback) => !callback.settled))
             return;
@@ -114,36 +220,52 @@ function createPluginDisposalBarrier(scope) {
         if (callback.settled)
             return;
         callback.settled = true;
+        callback.resolveSettled();
         releaseIfSettled();
     };
     const fail = (callback, error) => {
-        if (!pluginDisposalError) {
-            pluginDisposalError = new Error("[ext-bundler-esbuild] Plugin disposal failed", { cause: error });
+        if (!disposalError) {
+            disposalError = new Error("[ext-bundler-esbuild] Plugin disposal failed", { cause: error });
         }
+        if (!pluginDisposalError)
+            pluginDisposalError = disposalError;
         settle(callback);
     };
+    const start = (state) => {
+        if (state.started || state.settled)
+            return;
+        state.started = true;
+        try {
+            const result = state.callback();
+            if (result !== null &&
+                (typeof result === "object" || typeof result === "function") &&
+                typeof result.then === "function") {
+                void Promise.resolve(result).then(() => settle(state), (error) => fail(state, error));
+            }
+            else {
+                settle(state);
+            }
+        }
+        catch (error) {
+            fail(state, error);
+        }
+    };
     return {
         wrap(callback) {
-            const state = { started: false, settled: false };
+            let resolveSettled = () => { };
+            const settledPromise = new Promise((resolve) => {
+                resolveSettled = resolve;
+            });
+            const state = {
+                callback,
+                started: false,
+                settled: false,
+                settledPromise,
+                resolveSettled,
+            };
             callbacks.push(state);
             return () => {
-                if (state.settled)
-                    return;
-                state.started = true;
-                try {
-                    const result = callback();
-                    if (result !== null &&
-                        (typeof result === "object" || typeof result === "function") &&
-                        typeof result.then === "function") {
-                        void Promise.resolve(result).then(() => settle(state), (error) => fail(state, error));
-                    }
-                    else {
-                        settle(state);
-                    }
-                }
-                catch (error) {
-                    fail(state, error);
-                }
+                start(state);
             };
         },
         activate() {
@@ -167,8 +289,62 @@ function createPluginDisposalBarrier(scope) {
                 releaseIfSettled();
             }, 0);
         },
+        async dispose() {
+            const pending = callbacks.filter((callback) => !callback.settled);
+            for (const callback of pending)
+                start(callback);
+            await Promise.all(pending.map((callback) => callback.settledPromise));
+            if (disposalError)
+                throw disposalError;
+        },
     };
 }
+/**
+ * Recover after the managed service child died unexpectedly (crash, OOM-kill).
+ *
+ * esbuild 0.28 keeps a dead service cached in its module state and rejects
+ * every later call, so the reset must go through its `stop()`, which clears
+ * that state and lets the next API call spawn a fresh child. This path only
+ * runs for a child the adapter itself captured; a service started outside the
+ * adapter is still latched permanently by {@link invokeEsbuild}. Recovery is
+ * single-flight and waits for in-flight operations to drain: they fail with
+ * esbuild's own error for the dead child and must not race the reset.
+ */
+function recoverLostService() {
+    esbuildServiceRecovery ??= (async () => {
+        await activeOperationsIdle;
+        if (!esbuildServiceLost)
+            return;
+        const foreignService = esbuildServiceForeignReplacement ??
+            serviceLossSpawnGuard?.foreignService;
+        if (foreignService) {
+            const error = recordOwnershipError(new Error("esbuild service was replaced outside the module-wide adapter"));
+            uninstallServiceLossSpawnGuard();
+            throw error;
+        }
+        uninstallServiceLossSpawnGuard();
+        if (remainingServiceRestarts <= 0) {
+            throw recordOwnershipError(new Error(`esbuild service exited unexpectedly ${MAX_SERVICE_RESTARTS + 1} times (last: ${esbuildServiceLostDetail})`));
+        }
+        remainingServiceRestarts -= 1;
+        const detail = esbuildServiceLostDetail;
+        const m = esbuildModule;
+        esbuildModule = null;
+        esbuildService = null;
+        esbuildServiceLost = false;
+        try {
+            await m?.stop();
+        }
+        catch {
+            // Best effort: the child is already gone; stop() only resets state.
+        }
+        esbuildServiceGeneration += 1;
+        console.warn(`[ext-bundler-esbuild] esbuild service exited unexpectedly (${detail}); restarting it (${remainingServiceRestarts} restart(s) left)`);
+    })().finally(() => {
+        esbuildServiceRecovery = null;
+    });
+    return esbuildServiceRecovery;
+}
 async function runBundlerOperation(operation, preferredScope) {
     if (esbuildOwnershipError)
         throw esbuildOwnershipError;
@@ -176,22 +352,39 @@ async function runBundlerOperation(operation, preferredScope) {
         throw esbuildShutdownError;
     const inheritedScope = operationScopes.getStore();
     const isReentrant = inheritedScope !== undefined && inheritedScope.activeCount > 0;
+    let stopBarrierEntered = false;
     if (!isReentrant) {
         while (esbuildStopPromise)
             await esbuildStopPromise;
+        enterStopBarrier();
+        stopBarrierEntered = true;
     }
-    // Admission is synchronous after the stop barrier check. This makes a stop
-    // exclusive without serializing independent operations. Work re-entered by
-    // an active plugin shares its live scope so shutdown cannot deadlock on it.
-    const scope = preferredScope ?? (isReentrant ? inheritedScope : { activeCount: 0 });
-    beginOperation();
-    scope.activeCount += 1;
     try {
-        return await operationScopes.run(scope, () => operation(scope));
+        if (!isReentrant) {
+            // A lost service is recovered before admission, so one child death costs
+            // one restart instead of poisoning every later operation. The operation
+            // already holds the stop barrier, so shutdown cannot complete in this
+            // recovery gap and then leave the operation to spawn a new service.
+            while (esbuildServiceLost)
+                await recoverLostService();
+        }
+        // Admission is synchronous after the stop barrier check. This makes a stop
+        // exclusive without serializing independent operations. Work re-entered by
+        // an active plugin shares its live scope so shutdown cannot deadlock on it.
+        const scope = preferredScope ?? (isReentrant ? inheritedScope : { activeCount: 0 });
+        beginOperation();
+        scope.activeCount += 1;
+        try {
+            return await operationScopes.run(scope, () => operation(scope));
+        }
+        finally {
+            scope.activeCount -= 1;
+            endOperation();
+        }
     }
     finally {
-        scope.activeCount -= 1;
-        endOperation();
+        if (stopBarrierEntered)
+            leaveStopBarrier();
     }
 }
 function isEsbuildServiceSpawn(spawnArgs) {
@@ -200,6 +393,66 @@ function isEsbuildServiceSpawn(spawnArgs) {
         args.some((arg) => typeof arg === "string" && arg.startsWith("--service=")) &&
         args.includes("--ping");
 }
+function trackServiceChild(child) {
+    let resolveClosed = () => { };
+    const closed = new Promise((resolve) => {
+        resolveClosed = resolve;
+    });
+    const service = { child, closed, expectedClose: false };
+    const recordUnexpectedLoss = (exitCode, signalCode) => recordUnexpectedManagedServiceLoss(service, exitCode, signalCode);
+    child.once("exit", recordUnexpectedLoss);
+    child.once("close", (exitCode, signalCode) => {
+        recordUnexpectedLoss(exitCode, signalCode);
+        resolveClosed();
+        if (esbuildService === service)
+            esbuildService = null;
+    });
+    return service;
+}
+function recordUnexpectedManagedServiceLoss(service, exitCode, signalCode) {
+    // An unexpected close of a child the adapter owns is a crash, not a
+    // lifecycle violation; mark it recoverable instead of latching the
+    // permanent ownership error.
+    if (service.expectedClose || service.lossRecorded)
+        return;
+    service.lossRecorded = true;
+    esbuildServiceLost = true;
+    esbuildServiceLostDetail = `exit code ${exitCode}, signal ${signalCode}`;
+    installServiceLossSpawnGuard();
+}
+function observeForeignServiceChild(child) {
+    let resolveClosed = () => { };
+    const closed = new Promise((resolve) => {
+        resolveClosed = resolve;
+    });
+    const service = { child, closed, expectedClose: false };
+    child.once("close", () => {
+        resolveClosed();
+    });
+    return service;
+}
+function installServiceLossSpawnGuard() {
+    if (serviceLossSpawnGuard)
+        return;
+    const previous = childProcess.spawn;
+    const guard = ((...spawnArgs) => {
+        const child = Reflect.apply(previous, childProcess, spawnArgs);
+        if (isEsbuildServiceSpawn(spawnArgs)) {
+            const foreignService = observeForeignServiceChild(child);
+            esbuildServiceForeignReplacement = foreignService;
+            serviceLossSpawnGuard.foreignService = foreignService;
+        }
+        return child;
+    });
+    serviceLossSpawnGuard = { guard, previous, foreignService: null };
+    childProcess.spawn = guard;
+}
+function uninstallServiceLossSpawnGuard() {
+    const guard = serviceLossSpawnGuard;
+    serviceLossSpawnGuard = null;
+    if (guard && childProcess.spawn === guard.guard)
+        childProcess.spawn = guard.previous;
+}
 /**
  * Keep lifecycle tracking tolerant of Node-compatible child-process shims.
  *
@@ -210,10 +463,24 @@ function isEsbuildServiceSpawn(spawnArgs) {
 export function __resetOwnershipErrorForTests() {
     esbuildOwnershipError = null;
 }
+/** Crash-recovery state is module-wide; tests must reset it between cases. */
+export function __resetServiceRecoveryForTests() {
+    esbuildOwnershipError = null;
+    esbuildServiceLost = false;
+    esbuildServiceLostDetail = "";
+    esbuildServiceForeignReplacement = null;
+    esbuildServiceGeneration = 0;
+    remainingServiceRestarts = MAX_SERVICE_RESTARTS;
+    uninstallServiceLossSpawnGuard();
+}
 /** Exercise the latch without starting a real esbuild service. */
 export function __recordOwnershipErrorForTests(cause) {
     return recordOwnershipError(cause);
 }
+/** Exercise trusted esbuild diagnostic normalization without starting a service. */
+export function __markEsbuildSourceDiagnosticForTests(error) {
+    markEsbuildSourceDiagnostic(error);
+}
 export function isLiveEsbuildServiceProcess(child) {
     return !child.killed &&
         (child.exitCode === null || child.exitCode === undefined) &&
@@ -233,18 +500,7 @@ function invokeEsbuild(operation) {
     const trackedSpawn = ((...spawnArgs) => {
         const child = Reflect.apply(originalSpawn, childProcess, spawnArgs);
         if (isEsbuildServiceSpawn(spawnArgs)) {
-            let resolveClosed = () => { };
-            const closed = new Promise((resolve) => {
-                resolveClosed = resolve;
-            });
-            const service = { child, closed, expectedClose: false };
-            child.once("close", () => {
-                if (!service.expectedClose)
-                    recordOwnershipError();
-                resolveClosed();
-                if (esbuildService === service)
-                    esbuildService = null;
-            });
+            const service = trackServiceChild(child);
             capturedService = service;
             esbuildService = service;
             if (childProcess.spawn === trackedSpawn)
@@ -262,6 +518,16 @@ function invokeEsbuild(operation) {
     }
     const ownedService = capturedService ?? esbuildService;
     if (!ownedService || !isLiveService(ownedService)) {
+        // A managed child that died out from under this operation is the
+        // recoverable crash case handled by runBundlerOperation, not foreign
+        // ownership; the operation surfaces esbuild's own error for the dead
+        // child instead of latching the permanent one.
+        if (esbuildServiceLost)
+            return result;
+        if (ownedService && ownedService === esbuildService) {
+            recordUnexpectedManagedServiceLoss(ownedService, ownedService.child.exitCode, ownedService.child.signalCode);
+            return result;
+        }
         // Latch synchronously so a concurrent operation cannot pass the admission
         // check in runBundlerOperation and drive esbuild while ownership is already
         // known to be invalid. The rejection handler still supplies the cause: the
@@ -326,8 +592,18 @@ function mapOptions(options, scope) {
     return {
         options: mapped,
         activatePluginDisposals: pluginDisposals.activate,
+        disposePluginGeneration: pluginDisposals.dispose,
     };
 }
+async function finalizePluginDisposals(mapped) {
+    const service = esbuildService;
+    if (esbuildServiceLost ||
+        (service && !service.expectedClose && !isLiveService(service))) {
+        await mapped.disposePluginGeneration();
+        return;
+    }
+    mapped.activatePluginDisposals();
+}
 /**
  * esbuild-backed {@link Bundler} implementation.
  *
@@ -365,7 +641,7 @@ export class EsbuildBundler {
                 };
             }
             finally {
-                mapped.activatePluginDisposals();
+                await finalizePluginDisposals(mapped);
             }
         });
     }
@@ -373,7 +649,10 @@ export class EsbuildBundler {
         return runBundlerOperation(async () => {
             const esbuild = await getEsbuild();
             const { code, ...rest } = options;
-            const result = await invokeEsbuild(() => esbuild.transform(code, rest));
+            const result = await invokeEsbuild(() => esbuild.transform(code, rest)).catch((error) => {
+                markEsbuildSourceDiagnostic(error);
+                throw error;
+            });
             return {
                 code: result.code,
                 map: result.map,
@@ -384,14 +663,38 @@ export class EsbuildBundler {
     async context(options) {
         return runBundlerOperation(async (contextScope) => {
             const esbuild = await getEsbuild();
-            const mapped = mapOptions(options, contextScope);
-            const ctx = await invokeEsbuild(() => esbuild.context(mapped.options)).catch((error) => {
-                mapped.activatePluginDisposals();
+            let mapped = mapOptions(options, contextScope);
+            let ctx = await invokeEsbuild(() => esbuild.context(mapped.options)).catch(async (error) => {
+                await finalizePluginDisposals(mapped);
                 throw error;
             });
+            let contextGeneration = esbuildServiceGeneration;
+            let contextRefresh = null;
+            const currentContext = async () => {
+                if (contextGeneration === esbuildServiceGeneration)
+                    return ctx;
+                contextRefresh ??= (async () => {
+                    if (contextGeneration === esbuildServiceGeneration)
+                        return;
+                    await mapped.disposePluginGeneration();
+                    const nextMapped = mapOptions(options, contextScope);
+                    const currentEsbuild = await getEsbuild();
+                    ctx = await invokeEsbuild(() => currentEsbuild.context(nextMapped.options)).catch(async (error) => {
+                        await finalizePluginDisposals(nextMapped);
+                        mapped = mapOptions(options, contextScope);
+                        throw error;
+                    });
+                    mapped = nextMapped;
+                    contextGeneration = esbuildServiceGeneration;
+                })().finally(() => {
+                    contextRefresh = null;
+                });
+                await contextRefresh;
+                return ctx;
+            };
             return {
                 rebuild: () => runBundlerOperation(async () => {
-                    const result = await ctx.rebuild();
+                    const result = await (await currentContext()).rebuild();
                     return {
                         outputFiles: (result.outputFiles ?? []).map(toOutput),
                         warnings: toMessages(result.warnings),
@@ -400,14 +703,20 @@ export class EsbuildBundler {
                     };
                 }, contextScope),
                 cancel: () => runBundlerOperation(async () => {
-                    await ctx.cancel();
+                    await (await currentContext()).cancel();
                 }, contextScope),
                 dispose: () => runBundlerOperation(async () => {
                     try {
-                        await ctx.dispose();
+                        if (contextGeneration === esbuildServiceGeneration)
+                            await ctx.dispose();
                     }
                     finally {
-                        mapped.activatePluginDisposals();
+                        if (contextGeneration === esbuildServiceGeneration) {
+                            mapped.activatePluginDisposals();
+                        }
+                        else {
+                            await mapped.disposePluginGeneration();
+                        }
                     }
                 }, contextScope),
             };
@@ -422,10 +731,31 @@ export class EsbuildBundler {
             return;
         }
         const stopping = (async () => {
+            await stopBarrierIdle;
             await activeOperationsIdle;
+            if (esbuildServiceLost &&
+                (esbuildServiceForeignReplacement ?? serviceLossSpawnGuard?.foreignService)) {
+                const error = recordOwnershipError(new Error("esbuild service was replaced outside the module-wide adapter"));
+                uninstallServiceLossSpawnGuard();
+                throw error;
+            }
+            if (esbuildServiceLost && remainingServiceRestarts <= 0) {
+                const error = recordOwnershipError(new Error(`esbuild service exited unexpectedly ${MAX_SERVICE_RESTARTS + 1} times (last: ${esbuildServiceLostDetail})`));
+                uninstallServiceLossSpawnGuard();
+                throw error;
+            }
+            let chargedLostService = false;
+            if (esbuildServiceLost) {
+                remainingServiceRestarts -= 1;
+                chargedLostService = true;
+                uninstallServiceLossSpawnGuard();
+            }
             const m = esbuildModule;
             const trackedService = esbuildService;
-            if (trackedService && !trackedService.expectedClose && !isLiveService(trackedService)) {
+            if (trackedService && !trackedService.expectedClose && !isLiveService(trackedService) &&
+                remainingServiceRestarts <= 0 && !chargedLostService) {
+                // A dead managed child within the restart budget is a crash, which a
+                // stop resets anyway; only an exhausted budget still means giving up.
                 recordOwnershipError();
             }
             const ownershipError = esbuildOwnershipError;
@@ -477,6 +807,9 @@ export class EsbuildBundler {
             if (esbuildService === service)
                 esbuildService = null;
             esbuildShutdownError = null;
+            // A clean stop resets esbuild's module state, so a pending crash needs
+            // no recovery pass anymore.
+            esbuildServiceLost = false;
             if (disposalError) {
                 if (pluginDisposalError === disposalError)
                     pluginDisposalError = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veryfront/ext-bundler-esbuild",
-  "version": "0.1.1237",
+  "version": "0.1.1239",
   "description": "Veryfront first-party extension package for ext-bundler-esbuild",
   "keywords": [
     "veryfront",
@@ -50,7 +50,7 @@
     "esbuild": "0.28.1"
   },
   "peerDependencies": {
-    "veryfront": "^0.1.1237"
+    "veryfront": "^0.1.1239"
   },
   "type": "module",
   "types": "./esm/index.d.ts",