@black-market/sdk 0.6.4 → 0.7.1

package/dist/lifecycle/simulation.js

@@ -1,8 +1,64 @@
-import { decodeEventLog, decodeFunctionResult, encodeFunctionData, encodeFunctionResult, toHex } from "viem";
-import { launchLifecycleAbi, lifecycleErc20Abi } from "./abi.js";
-import { LifecyclePhase } from "./schema.js";
-import { assertLifecycleBlock, lifecyclePinnedRpc, lifecycleRpc, lifecycleSourceClient, lifecycleStage, nitroArbSys, nitroArbSysAbi, nitroGasInfo, nitroGasInfoAbi, readLifecycleBlock, readNitroPosterGas, resolveLifecycleLimits, rpcHex, rpcObject, rpcQuantity } from "./rpc.js";
+import { decodeErrorResult, decodeEventLog, decodeFunctionResult, encodeFunctionData, encodeFunctionResult, parseAbi, toHex } from "viem";
+import { fixedFeePoolHookV1Abi, launchLifecycleAbi, lifecycleErc20Abi } from "./abi.js";
+import { hashLaunchIdentity, hashLaunchPlan, LifecyclePhase } from "./schema.js";
+import { assertLifecycleBlock, assertLifecycleReadClientOpen, lifecycleFailureReason, lifecyclePinnedRpc, lifecycleRpc, lifecycleSourceClient, lifecycleStage, nitroArbSys, nitroArbSysAbi, nitroGasInfo, nitroGasInfoAbi, readLifecycleBlock, readLifecycleChainId, readNitroPosterGas, resolveLifecycleLimits, rpcHex, rpcObject, rpcQuantity } from "./rpc.js";
 import { LifecyclePlanningError } from "./types.js";
+import { decodeAbyssLifecycleMarketConfig, decodePoolBoundV4LifecycleMarketConfig, decodeV4LifecycleMarketConfig, isPoolBoundV4ConfigVersion } from "./markets.js";
+function committedPositionCount(plan) {
+    let count = 0;
+    for (const market of plan.markets) {
+        if (market.configVersion === 1)
+            count += decodeAbyssLifecycleMarketConfig(market.config).positions.length;
+        else if (market.configVersion === 4)
+            count += decodeV4LifecycleMarketConfig(market.config).positions.length;
+        else if (isPoolBoundV4ConfigVersion(market.configVersion))
+            count += decodePoolBoundV4LifecycleMarketConfig(market.config, market.configVersion).positions.length;
+        else
+            throw new LifecyclePlanningError("UNSUPPORTED_CONFIG_VERSION", "Activation requires a supported committed position schema");
+    }
+    return count;
+}
+const executionGuardErrors = [
+    ...fixedFeePoolHookV1Abi.filter((item) => item.type === "error"),
+    ...parseAbi([
+        "error WrongDomain()", "error PlanMismatch()", "error LaunchAlreadyExists()", "error InvalidMode()",
+        "error InvalidPhase()", "error InvalidPreparationOrder()", "error DeadlineExpired()", "error InvalidBinding()",
+        "error InvalidMarket()", "error InsufficientEscrow()", "error InvalidPositions()", "error InvalidPlan()",
+        "error InvalidFunding()", "error InvalidFeePolicy()", "error InvalidBuy()", "error DuplicateMarket()",
+        "error IneligibleImplementation()", "error QuoteDebtForbidden()", "error SlippageExceeded()", "error FeeBelowMinimum()",
+        "error DeploymentFailed()", "error Error(string reason)", "error Panic(uint256 code)",
+    ]),
+];
+function executionFailure(returnData, error) {
+    const native = error !== null && typeof error === "object" && !Array.isArray(error) ? error : undefined;
+    let nativeData = native?.data;
+    for (let depth = 0; depth < 3 && nativeData !== null && typeof nativeData === "object" && !Array.isArray(nativeData); depth += 1)
+        nativeData = nativeData.data;
+    const nativeErrorDataBytes = typeof nativeData === "string" && /^0x(?:[0-9a-fA-F]{2})*$/.test(nativeData) ? (nativeData.length - 2) / 2 : undefined;
+    const nativeErrorCode = typeof native?.code === "number" && Number.isSafeInteger(native.code) ? native.code : undefined;
+    const message = typeof native?.message === "string" ? native.message : "";
+    const nativeGasCapped = message.endsWith(" (gas limit was capped by the RPC server's global gas cap)");
+    // Native eth_simulateV1 uses -32015 for VM errors; -32000 is also used by RPC clients.
+    // Empty data and an explicit OOG report are required. Malformed data or proximity is not proof.
+    const outOfGas = (returnData === undefined || returnData === "0x") && (native?.data === undefined || nativeErrorDataBytes === 0) &&
+        (nativeErrorCode === -32015 || nativeErrorCode === -32000) && /^out of gas\b/i.test(message);
+    const nativeErrorKind = native === undefined ? "missing" : outOfGas ? "out-of-gas" : nativeErrorCode === 3 ? "execution-reverted" : nativeErrorCode === -32015 ? "vm-error" : "other";
+    const diagnostic = { nativeErrorCode, nativeErrorKind, nativeErrorDataBytes, nativeGasCapped };
+    const data = returnData === undefined || returnData === "0x" ? nativeData : returnData;
+    if (typeof data === "string" && /^0x(?:[0-9a-fA-F]{2}){4,}$/.test(data)) {
+        try {
+            const { errorName } = decodeErrorResult({ abi: executionGuardErrors, data: data });
+            return { ...diagnostic, failureCategory: errorName === "DeploymentFailed" ? "opaque" : "semantic", decodedError: errorName, error: `Execution reverted (${errorName})` };
+        }
+        catch {
+            return { ...diagnostic, failureCategory: "opaque", error: "Execution reverted without a reviewed error" };
+        }
+    }
+    if (outOfGas)
+        return { ...diagnostic, failureCategory: nativeGasCapped ? "source" : "capacity", error: nativeGasCapped ? "Native execution ran out of gas under the reported RPC gas cap" : "Native execution ran out of gas" };
+    return { ...diagnostic, failureCategory: "opaque", error: nativeErrorKind === "execution-reverted" ? "Native execution reverted without a reviewed error" : "Execution failed without a reviewed error" };
+}
+const nitroProofsByInvocation = new WeakMap();
 function conditionRequest(condition, planned) {
     if (condition.kind === "allowance")
         return {
@@ -93,9 +149,8 @@ async function simulateRpcPass(client, planned, block, transactions, gasLimits,
             throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Simulated gas use is outside the exact requested envelope");
         const returnData = rpcHex(call.returnData, "simulated return data");
         const success = rpcQuantity(call.status, "simulated status") === 1n;
-        let error;
-        if (!success)
-            error = call.error === undefined ? `Execution reverted: ${returnData}` : JSON.stringify(call.error);
+        const failureDiagnostic = success ? undefined : executionFailure(returnData, call.error);
+        let error = failureDiagnostic?.error;
         if (success) {
             try {
                 // Verification reads must not become synthetic transactions that consume creator nonce/fees.
@@ -120,8 +175,9 @@ async function simulateRpcPass(client, planned, block, transactions, gasLimits,
                 else if (transaction.kind === "atomic" || transaction.kind === "activate") {
                     const functionName = transaction.kind === "atomic" ? "launchAtomic" : "activateLaunch";
                     const receipt = decodeFunctionResult({ abi: launchLifecycleAbi, functionName, data: returnData });
-                    if (receipt.planHash.toLowerCase() !== planned.planHash.toLowerCase() || receipt.launchId.toLowerCase() !== planned.launchId.toLowerCase() || receipt.token.toLowerCase() !== planned.predictedToken.toLowerCase() || receipt.marketCount !== planned.plan.markets.length || receipt.quoteSpent.length !== planned.plan.buys.length || receipt.tokenOut.length !== planned.plan.buys.length || !events.some((event) => event.eventName === "LaunchActivated" && event.args.planHash.toLowerCase() === planned.planHash.toLowerCase() && event.args.token.toLowerCase() === planned.predictedToken.toLowerCase()))
-                        throw new LifecyclePlanningError("POSTCONDITION_FAILED", "Simulation did not atomically complete the committed launch");
+                    const positionCount = committedPositionCount(planned.plan);
+                    if (receipt.planHash.toLowerCase() !== planned.planHash.toLowerCase() || receipt.launchId.toLowerCase() !== planned.launchId.toLowerCase() || receipt.token.toLowerCase() !== planned.predictedToken.toLowerCase() || receipt.marketCount !== planned.plan.markets.length || receipt.positionCount !== positionCount || receipt.quoteSpent.length !== planned.plan.buys.length || receipt.tokenOut.length !== planned.plan.buys.length || !events.some((event) => event.eventName === "LaunchActivated" && event.args.launchId.toLowerCase() === planned.launchId.toLowerCase() && event.args.planHash.toLowerCase() === planned.planHash.toLowerCase() && event.args.token.toLowerCase() === planned.predictedToken.toLowerCase() && event.args.marketCount === planned.plan.markets.length && event.args.positionCount === positionCount))
+                        throw new LifecyclePlanningError("POSTCONDITION_FAILED", "Simulation did not atomically complete every committed market, position and ordered buy");
                     for (let buyIndex = 0; buyIndex < planned.plan.buys.length; buyIndex += 1) {
                         const buy = planned.plan.buys[buyIndex];
                         if (buy === undefined || (receipt.quoteSpent[buyIndex] ?? buy.quoteAmountIn + 1n) > buy.quoteAmountIn || (receipt.tokenOut[buyIndex] ?? 0n) < buy.minTokenOut)
@@ -134,21 +190,38 @@ async function simulateRpcPass(client, planned, block, transactions, gasLimits,
                     throw new LifecyclePlanningError("POSTCONDITION_FAILED", "Funding approval returned failure");
             }
             catch (failure) {
-                error = failure instanceof Error ? failure.message : String(failure);
+                error = failure instanceof LifecyclePlanningError ? failure.message : "Simulation returned an invalid committed postcondition";
             }
         }
-        steps.push({ transactionId: transaction.id, success: success && error === undefined, gasUsed, gasRequired, gasLimit: gasLimits[index], returnData, error });
+        steps.push({ transactionId: transaction.id, success: success && error === undefined, gasUsed, gasRequired, gasLimit: gasLimits[index], returnData, error, ...failureDiagnostic, ...(success && error !== undefined ? { failureCategory: "postcondition" } : {}) });
         if (!success || error !== undefined)
             break;
     }
     return steps;
 }
-/** A failure that consumed nearly the whole limit is treated as possible gas-envelope
- *  exhaustion (EIP-150 retention starves forwarded sub-calls; the surfaced revert bytes
- *  may be a wrapped inner bubble rather than empty). Discovery is safe: a genuine
- *  business revert also fails at the exact ceiling, so it can never be masked. */
+/** A decoded semantic refusal or opaque deployment wrapper is never gas evidence. */
 function looksGasExhausted(step, gasLimit) {
-    return !step.success && step.gasUsed !== undefined && step.gasUsed >= gasLimit - gasLimit / 64n;
+    return !step.success && step.failureCategory === "capacity" && step.gasUsed !== undefined && step.gasUsed >= gasLimit - gasLimit / 64n;
+}
+function simulationFailureKind(failure) {
+    for (let depth = 0; depth < 8 && failure !== null && typeof failure === "object"; depth += 1) {
+        const error = failure;
+        if (error.name === "AbortError")
+            return "abort";
+        const status = error.status ?? error.statusCode;
+        if (typeof status === "number" && status >= 400 && status <= 599)
+            return "source";
+        const message = typeof error.details === "string" ? error.details : typeof error.message === "string" ? error.message : "";
+        const execution = executionFailure(undefined, { ...error, message });
+        if (execution.nativeErrorKind === "out-of-gas" && execution.nativeGasCapped)
+            return "source";
+        if (execution.failureCategory === "capacity")
+            return "out-of-gas";
+        if (error.code === 3 || error.code === -32000 && /^execution (?:failed|reverted)\b/i.test(message))
+            return "execution";
+        failure = error.cause;
+    }
+    return "source";
 }
 async function waitForkReceipt(client, transactionHash, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
@@ -232,7 +305,7 @@ async function simulateForkPass(fork, planned, block, transactions, gasLimits, g
                     const activated = events.filter((event) => event.eventName === "LaunchActivated");
                     const buys = events.filter((event) => event.eventName === "InitialBuyExecuted");
                     if (activated.length !== 1 || !activated.some((event) => event.eventName === "LaunchActivated" && event.args.launchId.toLowerCase() === planned.launchId.toLowerCase() && event.args.planHash.toLowerCase() === planned.planHash.toLowerCase() && event.args.token.toLowerCase() === planned.predictedToken.toLowerCase()) ||
-                        progress.phase !== LifecyclePhase.Active || progress.planHash.toLowerCase() !== planned.planHash.toLowerCase() || progress.token.toLowerCase() !== planned.predictedToken.toLowerCase() ||
+                        progress.phase !== LifecyclePhase.Active || progress.planHash.toLowerCase() !== planned.planHash.toLowerCase() || progress.token.toLowerCase() !== planned.predictedToken.toLowerCase() || progress.marketCount !== planned.plan.markets.length || progress.positionCount !== committedPositionCount(planned.plan) ||
                         buys.length !== planned.plan.buys.length)
                         throw new LifecyclePlanningError("POSTCONDITION_FAILED", "Actual fork activation differs from the exact committed launch");
                     const quoteSpent = [];
@@ -261,7 +334,7 @@ async function simulateForkPass(fork, planned, block, transactions, gasLimits, g
                 steps.push({ transactionId: transaction.id, success: true, gasUsed, gasLimit: gas, gasRequired, returnData });
             }
             catch (failure) {
-                steps.push({ transactionId: transaction.id, success: false, gasLimit: gas, error: failure instanceof Error ? failure.message : String(failure) });
+                steps.push({ transactionId: transaction.id, success: false, gasLimit: gas, error: lifecycleFailureReason(failure) });
                 break;
             }
         }
@@ -278,98 +351,223 @@ async function simulateForkPass(fork, planned, block, transactions, gasLimits, g
         }
     }
 }
-/** Internal one-shot continuation. Only SDK reads can produce its context; callers
- * cannot supply resolved policy or account/chain observations as authority. */
+function observedFields(value) {
+    const keys = Object.keys(value);
+    const values = keys.map((key) => value[key]);
+    return () => keys.length === Object.keys(value).length && keys.every((key, index) => value[key] === values[index]);
+}
+/** Internal continuation owned by one SDK read invocation. Only its positive
+ * capability proof is reused; every candidate executes its entire economic sequence. */
 export function prepareLaunchSimulation(options, block, hasTransactions = true) {
-    const { client, planned } = options;
-    const sourceClient = lifecycleSourceClient(client);
-    const blockNumber = block.number, blockHash = block.hash;
-    const context = { client, account: planned.account, orchestrator: planned.plan.orchestrator, block, chainId: planned.chainId };
+    const { client, planned, fork } = options;
+    const signal = options.signal;
+    if (signal?.aborted)
+        throw Object.assign(new Error("Lifecycle simulation cancelled"), { name: "AbortError" });
+    const sourceClient = lifecycleSourceClient(client), sourceRequest = sourceClient.request;
+    const sourceBatching = sourceClient.supportsReadBatching;
+    const reusable = assertLifecycleReadClientOpen(client);
+    const plan = planned.plan, planHash = planned.planHash, launchId = planned.launchId;
+    const optionsLimits = options.limits, plannedLimits = planned.limits;
+    const policy = optionsLimits === undefined ? plannedLimits : optionsLimits;
+    const blockMatches = observedFields(block);
+    const forkMatches = fork === undefined ? undefined : observedFields(fork);
+    const forkRequest = fork?.client.request;
+    const plannedMatches = observedFields(planned);
+    const context = Object.freeze({ client, account: planned.account, orchestrator: plan.orchestrator, block: Object.freeze({ ...block }), chainId: planned.chainId });
+    let closed = false, active = false, consumed = false, capabilityProved = false;
+    let capabilityPending;
+    const assertContext = () => {
+        if (closed)
+            throw new LifecyclePlanningError("INVALID_SIMULATION", "Prepared simulation continuation has closed");
+        if (signal?.aborted)
+            throw Object.assign(new Error("Lifecycle simulation cancelled"), { name: "AbortError" });
+        assertLifecycleReadClientOpen(client);
+        if (options.client !== client || options.planned !== planned || options.limits !== optionsLimits || options.fork !== fork || options.signal !== signal ||
+            lifecycleSourceClient(client) !== sourceClient || sourceClient.request !== sourceRequest || !plannedMatches() || !blockMatches() ||
+            sourceClient.supportsReadBatching !== sourceBatching ||
+            planned.plan !== plan || planned.account !== context.account || plan.orchestrator !== context.orchestrator || planned.chainId !== context.chainId ||
+            planned.limits !== plannedLimits || forkMatches !== undefined && !forkMatches() || fork?.client.request !== forkRequest) {
+            throw new LifecyclePlanningError("LIMIT_CONTEXT_MISMATCH", "Prepared simulation differs from its source/account/core/plan/header/policy context");
+        }
+        if (hashLaunchPlan(plan).toLowerCase() !== planHash.toLowerCase() || hashLaunchIdentity(plan).toLowerCase() !== launchId.toLowerCase()) {
+            throw new LifecyclePlanningError("PLAN_MUTATED", "Economic plan changed after its simulation context was bound");
+        }
+    };
     const pending = (async () => {
-        if (options.fork !== undefined && lifecycleSourceClient(options.fork.client) === sourceClient)
+        if (fork !== undefined && lifecycleSourceClient(fork.client) === sourceClient)
             throw new LifecyclePlanningError("UNSAFE_FORK", "Source RPC must never receive controlled simulation transactions/snapshots/resets");
         return lifecycleStage(client, "simulation.context", () => Promise.all([
-            resolveLifecycleLimits(context, options.limits === undefined ? planned.limits : options.limits),
-            lifecycleRpc(client, "eth_chainId"),
-            lifecyclePinnedRpc(client, "eth_getCode", [context.account, toHex(block.number)], block),
+            resolveLifecycleLimits(context, policy),
+            readLifecycleChainId(client),
+            lifecyclePinnedRpc(client, "eth_getCode", [context.account, toHex(context.block.number)], context.block),
             hasTransactions ? lifecycleRpc(client, "eth_gasPrice") : undefined,
         ]));
     })().then((observations) => ({ observations }), (failure) => ({ failure }));
-    // Attach the failure handler before input validation can refuse or throw.
-    // Preparation is read-only; no probe, measurement, replay or fork work starts.
-    let consumed = false;
-    return async (transactions) => {
-        if (consumed)
-            throw new LifecyclePlanningError("INVALID_SIMULATION", "Prepared simulation context is invocation-local and may only be consumed once");
+    // Refused inputs may discard this read-only preparation before it settles.
+    // Its rejection is handled immediately; no capability or economic work starts.
+    const run = async (transactions, diagnostic, nextEnvelope) => {
+        if (active || consumed && !reusable || !hasTransactions && transactions.length !== 0) {
+            closed = true;
+            throw new LifecyclePlanningError("INVALID_SIMULATION", "Prepared candidates require sequential consumption by their SDK invocation owner");
+        }
+        active = true;
         consumed = true;
-        const result = await pending;
-        if ("failure" in result)
-            throw result.failure;
-        if (options.client !== client || options.planned !== planned || context.client !== client || context.block !== block || lifecycleSourceClient(client) !== sourceClient ||
-            planned.account !== context.account || planned.plan.orchestrator !== context.orchestrator || planned.chainId !== context.chainId ||
-            block.number !== blockNumber || block.hash !== blockHash)
-            throw new LifecyclePlanningError("LIMIT_CONTEXT_MISMATCH", "Prepared simulation context differs from the bound source/chain/account/core/block");
-        return simulateLaunchTransactionsWithContext(options, transactions, context, result.observations);
+        try {
+            assertContext();
+            const envelopeMatches = nextEnvelope === undefined ? undefined : observedFields(nextEnvelope);
+            const candidates = transactions.map((transaction) => ({
+                transaction, matches: observedFields(transaction),
+                dependencies: [...transaction.dependencies],
+                conditions: transaction.postconditions.map((condition) => ({ condition, matches: observedFields(condition) })),
+            }));
+            const result = await pending;
+            if ("failure" in result)
+                throw result.failure;
+            const assertCurrent = () => {
+                assertContext();
+                result.observations[0].assertCurrent();
+                if (envelopeMatches !== undefined && !envelopeMatches())
+                    throw new LifecyclePlanningError("INVALID_SIMULATION", "Reviewed gas envelope changed during its complete economic proof");
+                if (transactions.length !== candidates.length || candidates.some(({ transaction, matches, dependencies, conditions }, index) => transactions[index] !== transaction || !matches() || transaction.dependencies.length !== dependencies.length ||
+                    dependencies.some((dependency, ordinal) => transaction.dependencies[ordinal] !== dependency) ||
+                    transaction.postconditions.length !== conditions.length || conditions.some(({ condition, matches: conditionMatches }, ordinal) => transaction.postconditions[ordinal] !== condition || !conditionMatches()))) {
+                    throw new LifecyclePlanningError("INVALID_SIMULATION", "Candidate transactions changed during their complete economic proof");
+                }
+            };
+            assertCurrent();
+            const proveBackend = async (limits, gasPrice) => {
+                assertCurrent();
+                if (capabilityProved)
+                    return;
+                if (capabilityPending === undefined) {
+                    const key = JSON.stringify([context.chainId.toString(), context.account.toLowerCase(), context.orchestrator.toLowerCase(), context.block.number.toString(), context.block.hash.toLowerCase(), context.block.timestamp.toString(), context.block.gasLimit.toString(), limits.arbOSVersion?.toString(), limits.maxTxComputeGas?.toString(), limits.maxBlockComputeGas?.toString(), limits.executionGasCeiling.toString(), limits.maxSimulationGas?.toString(), gasPrice.toString()]);
+                    let proofs = reusable ? nitroProofsByInvocation.get(client) : undefined;
+                    if (reusable && proofs === undefined) {
+                        proofs = new Map();
+                        nitroProofsByInvocation.set(client, proofs);
+                    }
+                    const ownedProofs = proofs;
+                    let nativeProof = ownedProofs?.get(key);
+                    if (nativeProof === undefined) {
+                        nativeProof = lifecycleStage(client, "simulation.nitro", () => proveNitroBackend(client, planned, context.block, limits, gasPrice));
+                        ownedProofs?.set(key, nativeProof);
+                        const pending = nativeProof;
+                        void pending.catch(() => { if (ownedProofs?.get(key) === pending)
+                            ownedProofs?.delete(key); });
+                    }
+                    const proof = nativeProof.then(() => {
+                        assertContext();
+                        result.observations[0].assertCurrent();
+                        capabilityProved = true;
+                    });
+                    capabilityPending = proof;
+                    void proof.then(() => { if (capabilityPending === proof)
+                        capabilityPending = undefined; }, () => { if (capabilityPending === proof)
+                        capabilityPending = undefined; });
+                }
+                await capabilityPending;
+                assertCurrent();
+            };
+            const simulation = await simulateLaunchTransactionsWithContext(options, transactions, context, result.observations, proveBackend, assertCurrent, diagnostic, nextEnvelope);
+            assertCurrent();
+            return simulation;
+        }
+        catch (failure) {
+            closed = true;
+            capabilityProved = false;
+            capabilityPending = undefined;
+            throw failure;
+        }
+        finally {
+            active = false;
+        }
     };
+    const simulate = Object.assign((transactions, nextEnvelope) => run(transactions, false, nextEnvelope), { measure: (transactions) => run(transactions, true),
+        close() { closed = true; capabilityProved = false; capabilityPending = undefined; } });
+    return simulate;
 }
-export async function simulateLaunchTransactions(options, transactions, pinnedBlock) {
+export async function simulateLaunchTransactions(options, transactions, pinnedBlock, nextEnvelope) {
     // Standalone calls always produce fresh context, including live chain and fees.
     if (options.fork !== undefined && lifecycleSourceClient(options.fork.client) === lifecycleSourceClient(options.client))
         throw new LifecyclePlanningError("UNSAFE_FORK", "Source RPC must never receive controlled simulation transactions/snapshots/resets");
     const block = pinnedBlock ?? await readLifecycleBlock(options.client);
-    return prepareLaunchSimulation(options, block, transactions.length !== 0)(transactions);
+    const prepared = prepareLaunchSimulation(options, block, transactions.length !== 0);
+    try {
+        return await prepared(transactions, nextEnvelope);
+    }
+    finally {
+        prepared.close();
+    }
 }
-async function simulateLaunchTransactionsWithContext(options, transactions, context, observations) {
+async function simulateLaunchTransactionsWithContext(options, transactions, context, observations, proveBackend, assertCurrent, diagnostic, nextEnvelope) {
     const { client, planned } = options;
     const sourceClient = lifecycleSourceClient(client);
     const { block } = context;
     const [{ limits, configuration }, chainId, accountCodeValue, gasPriceValue] = observations;
     const base = { confidence: "stateful", executionProof: "failed", protocolFit: "unknown", transportPreflight: "not-requested", blockNumber: block.number, blockHash: block.hash, account: planned.account, chainId: planned.chainId, limits };
-    if (rpcQuantity(chainId, "chain ID") !== planned.chainId)
+    if (chainId !== planned.chainId)
         throw new LifecyclePlanningError("CHAIN_MISMATCH", "RPC chain changed before sequential simulation");
     const accountCode = rpcHex(accountCodeValue, "account code");
-    if (accountCode !== "0x")
+    if (accountCode !== "0x") {
+        await assertLifecycleBlock(client, block, planned.chainId);
         return { ...base, confidence: "provisional", executionProof: "unavailable", backend: "unavailable", admitted: false, steps: [], reason: "Direct EOA transaction simulation cannot prove smart-account signature/execution behavior" };
+    }
     for (const transaction of transactions) {
         if (transaction.from.toLowerCase() !== planned.account.toLowerCase() || BigInt(transaction.chainId) !== planned.chainId)
             throw new LifecyclePlanningError("ACCOUNT_MISMATCH", "Simulation transaction differs from the committed chain/account");
-        if (limits.maxCalldataBytes !== undefined && (transaction.data.length - 2) / 2 > limits.maxCalldataBytes)
-            return { ...base, executionProof: "unavailable", protocolFit: "failed", backend: "unavailable", admitted: false, steps: [], failedTransactionId: transaction.id, reason: "Exact calldata exceeds the supplied chain/account/RPC byte cap" };
+        if (limits.maxCalldataBytes !== undefined && (transaction.data.length - 2) / 2 > limits.maxCalldataBytes) {
+            await assertLifecycleBlock(client, block, planned.chainId);
+            return { ...base, executionProof: "unavailable", protocolFit: "failed", backend: "unavailable", admitted: false, steps: [], failedTransactionId: transaction.id, failureCategory: "capacity", capacityConstraint: "calldata", reason: "Exact calldata exceeds the supplied chain/account/RPC byte cap" };
+        }
     }
     if (transactions.length === 0) {
         await assertLifecycleBlock(client, block, planned.chainId);
         return { ...base, executionProof: "proved", protocolFit: "proved", backend: "unavailable", admitted: true, steps: [] };
     }
-    const gasPrice = rpcQuantity(gasPriceValue, "gas price");
+    const recommendedGasPrice = rpcQuantity(gasPriceValue, "gas price");
+    if (recommendedGasPrice >= 1n << 256n)
+        throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Recommended gas price must be a uint256 quantity");
+    // Initial construction reserves twice the pinned base fee if the quote lags.
+    // Reviewed fees are not new recommendations: native replay must accept them
+    // under natural child fees, with no base-fee override or silent fee increase.
+    const baseFeeEnvelope = (block.baseFeePerGas ?? 0n) * 2n;
+    const gasPrice = nextEnvelope?.gasPrice ?? (recommendedGasPrice > baseFeeEnvelope ? recommendedGasPrice : baseFeeEnvelope);
     if (gasPrice >= 1n << 256n)
         throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Gas price must be a uint256 quantity");
+    if (nextEnvelope !== undefined && (typeof nextEnvelope.gas !== "bigint" || nextEnvelope.gas <= 0n || nextEnvelope.gas >= 1n << 64n ||
+        typeof nextEnvelope.gasPrice !== "bigint" || nextEnvelope.gasPrice < 0n || nextEnvelope.gasPrice >= 1n << 256n)) {
+        throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Reviewed gas and gas price must be exact positive uint64 gas and nonnegative uint256 price");
+    }
     const buffer = (gas) => (gas * BigInt(10000 + limits.headroomBps) + 9999n) / 10000n;
     const computeCeiling = limits.transactionGasCeiling !== undefined && limits.transactionGasCeiling < limits.executionGasCeiling ? limits.transactionGasCeiling : limits.executionGasCeiling;
-    const capGas = transactions.map(() => computeCeiling);
-    let parallelMeasurement;
+    // Nonnegative poster gas cannot make this complete discovery request smaller.
+    // A generic controlled fork retains the existing RPC-to-fork fallback.
+    if (limits.maxSimulationGas !== undefined && BigInt(transactions.length) * computeCeiling > limits.maxSimulationGas &&
+        (limits.protocol === "nitro" || options.fork === undefined)) {
+        assertCurrent();
+        await assertLifecycleBlock(client, block, planned.chainId);
+        return { ...base, confidence: "provisional", executionProof: "unavailable", backend: "unavailable", admitted: false, steps: [], failureCategory: "capacity", capacityConstraint: "simulation-gas", reason: `Stateful sequential RPC simulation unavailable: Sequential request exceeds the current RPC aggregate simulation gas cap; use an isolated controlled fork. ${limits.protocol === "nitro" ? "Generic Anvil/Hardhat forks cannot prove ArbOS compute/poster metering." : "Dependent eth_call estimates are not proof."}` };
+    }
     const posterGas = [];
     if (limits.protocol === "nitro") {
-        // The isolated capability probe, poster quote and permissive cap measurement
-        // have no data dependency. Only an actually batching source overlaps all three.
-        const nitroEvidence = Promise.all([
-            lifecycleStage(client, "simulation.nitro", () => proveNitroBackend(client, planned, block, limits, gasPrice)),
-            lifecycleStage(client, "simulation.poster", () => Promise.all(transactions.map(async (transaction) => buffer((await readNitroPosterGas(transaction, context)).posterGas)))),
-        ]);
-        if (sourceClient.supportsReadBatching === true) {
-            // Handle settlement immediately so a failed measurement cannot escape while
-            // the independent metering evidence is still pending. It is never admission.
-            parallelMeasurement = lifecycleStage(client, "simulation.measure", () => simulateRpcPass(client, planned, block, transactions, capGas, limits, gasPrice, false))
-                .then((steps) => ({ steps }), (failure) => ({ failure }));
-        }
+        // Lightweight poster reads may overlap the isolated capability request.
+        // Economic work is not even queued until both prerequisites have succeeded.
         try {
-            const [, estimates] = await nitroEvidence;
+            const [, estimates] = await Promise.all([
+                proveBackend(limits, gasPrice),
+                lifecycleStage(client, "simulation.poster", () => Promise.all(transactions.map(async (transaction) => buffer((await readNitroPosterGas(transaction, context)).posterGas)))),
+            ]);
             posterGas.push(...estimates);
         }
         catch (failure) {
+            if (simulationFailureKind(failure) === "abort")
+                throw failure;
+            assertCurrent();
             await assertLifecycleBlock(client, block, planned.chainId);
-            return { ...base, confidence: "provisional", executionProof: "unavailable", backend: "unavailable", admitted: false, steps: [], reason: `Native Nitro compute/poster proof unavailable: ${failure instanceof Error ? failure.message : String(failure)}. Generic Anvil/Hardhat forks cannot prove ArbOS metering.` };
+            return { ...base, confidence: "provisional", executionProof: "unavailable", backend: "unavailable", admitted: false, steps: [], reason: `Native Nitro compute/poster proof unavailable: ${lifecycleFailureReason(failure)}. Generic Anvil/Hardhat forks cannot prove ArbOS metering.` };
         }
     }
+    assertCurrent();
     // The poster quote allocates gas only. The native exact replay enforces actual
     // compute hold; subtracting this approximate budget from gasUsed would not.
     const discoveryGas = transactions.map((_, index) => {
@@ -381,45 +579,53 @@ async function simulateLaunchTransactionsWithContext(options, transactions, cont
     });
     let backend = "eth_simulateV1";
     let measured;
-    // Permissive cap measurement is not proof; only the exact-gas validated replay admits a plan.
+    // A permissive measurement needs the legal complete compute + poster envelope.
+    // It is not proof: fixed compute/headroom checks and exact validated replay still follow.
     try {
-        if (parallelMeasurement === undefined)
-            measured = await lifecycleStage(client, "simulation.measure", () => simulateRpcPass(client, planned, block, transactions, capGas, limits, gasPrice, false));
-        else {
-            const observation = await parallelMeasurement;
-            if ("failure" in observation)
-                throw observation.failure;
-            measured = observation.steps;
-        }
+        measured = await lifecycleStage(client, "simulation.measure", () => simulateRpcPass(client, planned, block, transactions, discoveryGas, limits, gasPrice, false));
     }
     catch (failure) {
+        if (simulationFailureKind(failure) === "abort")
+            throw failure;
+        assertCurrent();
         if (options.fork === undefined || limits.protocol === "nitro") {
             await assertLifecycleBlock(client, block, planned.chainId);
-            return { ...base, confidence: "provisional", executionProof: "unavailable", backend: "unavailable", admitted: false, steps: [], reason: `Stateful sequential RPC simulation unavailable: ${failure instanceof Error ? failure.message : String(failure)}. ${limits.protocol === "nitro" ? "Generic Anvil/Hardhat forks cannot prove ArbOS compute/poster metering." : "Dependent eth_call estimates are not proof."}` };
+            return { ...base, confidence: "provisional", executionProof: "unavailable", backend: "unavailable", admitted: false, steps: [], reason: `Stateful sequential RPC simulation unavailable: ${lifecycleFailureReason(failure)}. ${limits.protocol === "nitro" ? "Generic Anvil/Hardhat forks cannot prove ArbOS compute/poster metering." : "Dependent eth_call estimates are not proof."}` };
         }
         backend = "controlled-fork";
-        measured = await simulateForkPass(options.fork, planned, block, transactions, capGas, gasPrice, true, limits.headroomBps);
+        measured = await simulateForkPass(options.fork, planned, block, transactions, discoveryGas, gasPrice, true, limits.headroomBps);
     }
+    assertCurrent();
     const failed = measured.find((step) => !step.success);
     if (failed !== undefined) {
         await assertLifecycleBlock(client, block, planned.chainId);
-        return { ...base, backend, admitted: false, steps: measured, reason: failed.error, failedTransactionId: failed.transactionId };
+        return { ...base, backend, admitted: false, steps: measured, reason: failed.error, failedTransactionId: failed.transactionId, failureCategory: failed.failureCategory ?? "opaque", capacityConstraint: failed.failureCategory === "capacity" ? "compute" : undefined };
+    }
+    if (diagnostic) {
+        await assertLifecycleBlock(client, block, planned.chainId);
+        return { ...base, backend, admitted: false, executionProof: "unavailable", steps: measured };
     }
-    const computeGas = measured.map((step) => buffer(step.gasRequired ?? step.gasUsed ?? computeCeiling));
-    const gasLimits = computeGas.map((gas, index) => gas + (posterGas[index] ?? 0n));
+    // Padding belongs to new envelopes. A reviewed envelope may consume its
+    // original margin; only exact replay at its held gas/price proves it still fits.
+    const computeGas = measured.map((step, index) => {
+        const required = step.gasRequired ?? step.gasUsed ?? computeCeiling;
+        return nextEnvelope !== undefined && index === 0 ? required : buffer(required);
+    });
+    const gasLimits = computeGas.map((gas, index) => nextEnvelope !== undefined && index === 0 ? nextEnvelope.gas : gas + (posterGas[index] ?? 0n));
     const exceeds = gasLimits.findIndex((gas, index) => gas <= 0n || gas >= 1n << 64n || (computeGas[index] ?? 0n) > limits.executionGasCeiling || limits.transactionGasCeiling !== undefined && gas > limits.transactionGasCeiling);
     if (exceeds >= 0) {
         await assertLifecycleBlock(client, block, planned.chainId);
-        return { ...base, executionProof: "unavailable", protocolFit: "failed", backend, admitted: false, steps: measured, reason: "Execution compute/headroom or complete poster gas envelope is outside positive uint64 gas and current protocol/known transaction limits", failedTransactionId: transactions[exceeds]?.id };
+        return { ...base, executionProof: "unavailable", protocolFit: "failed", backend, admitted: false, steps: measured, failureCategory: "capacity", capacityConstraint: (computeGas[exceeds] ?? 0n) > limits.executionGasCeiling ? "compute" : "gas-envelope", reason: "Execution compute/headroom or complete poster gas envelope is outside positive uint64 gas and current protocol/known transaction limits", failedTransactionId: transactions[exceeds]?.id };
     }
-    // Replay from the same initial state with exact headroom limits: gasUsed alone is not an EIP-150/gasleft proof.
-    // eth_simulateV1 with validation raises an RPC error on any revert (a generic
-    // -32000 "execution failed" carries no gasUsed/returnData), so a validated
-    // replay failure surfaces as a thrown error here. Route it through envelope
-    // discovery too: EIP-150 retention can starve a forwarded sub-call below the
-    // buffered limit while the true envelope still fits the execution ceiling.
+    // Envelope discovery may enlarge future unfinished steps, never the reviewed
+    // immediate one. Every retry still executes the entire sequence at held price.
+    const envelopeDiscoveryGas = nextEnvelope === undefined ? discoveryGas : discoveryGas.map((gas, index) => index === 0 ? nextEnvelope.gas : gas);
+    // Replay the complete sequence from its original state at the exact buffered
+    // limits. Only explicit native OOG can discover one larger legal envelope;
+    // semantic, opaque and transport failures cannot authorize a capacity retry.
     let verified;
     let validatedReplayError;
+    assertCurrent();
     try {
         if (backend === "eth_simulateV1")
             verified = await lifecycleStage(client, "simulation.replay", () => simulateRpcPass(client, planned, block, transactions, gasLimits, limits, gasPrice, true));
@@ -430,73 +636,128 @@ async function simulateLaunchTransactionsWithContext(options, transactions, cont
         }
     }
     catch (failure) {
-        const message = failure instanceof Error ? failure.message : String(failure);
+        const kind = simulationFailureKind(failure);
+        if (kind === "abort")
+            throw failure;
+        assertCurrent();
+        const message = lifecycleFailureReason(failure);
         if (backend !== "eth_simulateV1") {
             await assertLifecycleBlock(client, block, planned.chainId);
             return { ...base, backend, admitted: false, steps: [], reason: `Exact-gas validated replay failed: ${message}` };
         }
+        if (kind !== "out-of-gas") {
+            await assertLifecycleBlock(client, block, planned.chainId);
+            return { ...base, backend: "unavailable", confidence: "provisional", executionProof: "unavailable", admitted: false, steps: measured, failureCategory: kind === "source" ? "source" : "opaque", reason: `Exact-gas validated replay unavailable: ${message}` };
+        }
         validatedReplayError = message;
         verified = [];
     }
+    assertCurrent();
     let verifiedSteps = verified;
     let admittedGasLimits = gasLimits;
     let finalFailure = verifiedSteps.find((step) => !step.success);
+    let finalFailureReason;
     if (finalFailure === undefined && validatedReplayError !== undefined) {
+        if (!envelopeDiscoveryGas.some((gas, index) => gas > (gasLimits[index] ?? gas))) {
+            await assertLifecycleBlock(client, block, planned.chainId);
+            return { ...base, backend, admitted: false, steps: measured, reason: `Validated execution at the exact current gas ceiling failed: ${validatedReplayError}` };
+        }
         // The buffered validated replay threw before yielding steps. Attempt one
         // explicit envelope-discovery replay at the exact execution ceiling on the
         // same pinned block; headroom is never silently raised — the carried gas is
         // the validated envelope itself.
+        assertCurrent();
         try {
-            const ceilingLimits = discoveryGas;
+            const ceilingLimits = envelopeDiscoveryGas;
             const retried = backend === "eth_simulateV1"
                 ? await lifecycleStage(client, "simulation.envelope", () => simulateRpcPass(client, planned, block, transactions, ceilingLimits, limits, gasPrice, true))
                 : options.fork === undefined ? undefined : await simulateForkPass(options.fork, planned, block, transactions, ceilingLimits, gasPrice, false, limits.headroomBps);
-            if (retried === undefined || retried.some((step) => !step.success)) {
+            const retryFailureIndex = retried?.findIndex((step) => !step.success) ?? -1;
+            const retryFailure = retried?.[retryFailureIndex];
+            if (retried === undefined) {
                 await assertLifecycleBlock(client, block, planned.chainId);
-                return { ...base, backend, admitted: false, steps: measured, reason: `Validated execution at the exact current gas ceiling still failed: ${retried?.find((step) => !step.success)?.error ?? validatedReplayError}; final mint/lock/all-buys/public-opening is indivisible and will not be partitioned`, failedTransactionId: transactions[0]?.id };
+                return { ...base, backend, admitted: false, steps: measured, reason: `Validated execution at the exact current gas ceiling still failed: ${validatedReplayError}` };
             }
             admittedGasLimits = ceilingLimits;
             verifiedSteps = retried;
-            finalFailure = undefined;
+            finalFailure = retryFailure;
             validatedReplayError = undefined;
+            if (retryFailure !== undefined) {
+                const kind = transactions[retryFailureIndex]?.kind;
+                const indivisible = kind === "activate" || kind === "atomic";
+                finalFailureReason = `Validated execution at the exact current gas ceiling still failed: ${retryFailure.error ?? "Execution reverted"}${indivisible ? "; final mint/lock/all-buys/public-opening is indivisible and will not be partitioned" : ""}`;
+            }
         }
-        catch {
+        catch (failure) {
+            const kind = simulationFailureKind(failure);
+            if (kind === "abort")
+                throw failure;
+            assertCurrent();
             await assertLifecycleBlock(client, block, planned.chainId);
-            return { ...base, backend, admitted: false, steps: measured, reason: `Validated buffered replay failed (${validatedReplayError}) and envelope discovery at the exact gas ceiling was rejected by the simulation backend; final mint/lock/all-buys/public-opening is indivisible`, failedTransactionId: transactions[0]?.id };
+            if (kind !== "out-of-gas")
+                return { ...base, backend: "unavailable", confidence: "provisional", executionProof: "unavailable", admitted: false, steps: measured, failureCategory: kind === "source" ? "source" : "opaque", reason: `Legal-envelope validated replay unavailable after buffered execution refusal: ${lifecycleFailureReason(failure)}` };
+            return { ...base, backend, admitted: false, steps: measured, reason: `Validated buffered replay failed (${validatedReplayError}) and execution at the exact gas ceiling still reverted; final mint/lock/all-buys/public-opening is indivisible` };
         }
     }
-    if (finalFailure !== undefined) {
+    else if (finalFailure !== undefined) {
         const failedIndex = verifiedSteps.findIndex((step) => !step.success);
         const bufferedLimit = gasLimits[failedIndex];
         const failedTransaction = transactions[failedIndex];
-        if (bufferedLimit !== undefined && failedTransaction !== undefined && looksGasExhausted(finalFailure, bufferedLimit) && (discoveryGas[failedIndex] ?? 0n) > bufferedLimit) {
+        if (bufferedLimit !== undefined && failedTransaction !== undefined && (nextEnvelope === undefined || failedIndex !== 0) &&
+            looksGasExhausted(finalFailure, bufferedLimit) && (envelopeDiscoveryGas[failedIndex] ?? 0n) > bufferedLimit) {
             // Buffered replay returned an exhaustion-shaped failed step; learn the true
             // validated envelope with one explicit replay at the exact execution ceiling.
+            assertCurrent();
             try {
-                const ceilingLimits = discoveryGas;
+                const ceilingLimits = envelopeDiscoveryGas;
                 const retried = backend === "eth_simulateV1"
-                    ? await simulateRpcPass(client, planned, block, transactions, ceilingLimits, limits, gasPrice, true)
+                    ? await lifecycleStage(client, "simulation.envelope", () => simulateRpcPass(client, planned, block, transactions, ceilingLimits, limits, gasPrice, true))
                     : options.fork === undefined ? undefined : await simulateForkPass(options.fork, planned, block, transactions, ceilingLimits, gasPrice, false, limits.headroomBps);
-                if (retried !== undefined) {
-                    const retryFailure = retried.find((step) => !step.success);
-                    if (retryFailure === undefined) {
-                        admittedGasLimits = ceilingLimits;
-                        verifiedSteps = retried;
-                        finalFailure = undefined;
-                    }
-                    else {
-                        const indivisible = failedTransaction.kind === "activate" || failedTransaction.kind === "atomic";
-                        await assertLifecycleBlock(client, block, planned.chainId);
-                        return { ...base, backend, admitted: false, steps: measured, reason: `Validated execution at the exact current gas ceiling still failed: ${retryFailure.error ?? "the true gas envelope exceeds the current execution limit"}${indivisible ? "; final mint/lock/all-buys/public-opening is indivisible and will not be partitioned" : ""}`, failedTransactionId: failedTransaction.id };
-                    }
+                if (retried === undefined) {
+                    await assertLifecycleBlock(client, block, planned.chainId);
+                    return { ...base, backend, admitted: false, steps: measured, reason: "Validated execution at the exact current gas ceiling omitted transaction results" };
+                }
+                const retryFailureIndex = retried.findIndex((step) => !step.success);
+                const retryFailure = retried[retryFailureIndex];
+                admittedGasLimits = ceilingLimits;
+                verifiedSteps = retried;
+                finalFailure = retryFailure;
+                if (retryFailure !== undefined) {
+                    const kind = transactions[retryFailureIndex]?.kind;
+                    const indivisible = kind === "activate" || kind === "atomic";
+                    finalFailureReason = `Validated execution at the exact current gas ceiling still failed: ${retryFailure.error ?? "Execution reverted"}${indivisible ? "; final mint/lock/all-buys/public-opening is indivisible and will not be partitioned" : ""}`;
                 }
             }
-            catch { /* Envelope discovery unavailable; report the original buffered-limit failure unchanged. */ }
+            catch (failure) {
+                const kind = simulationFailureKind(failure);
+                if (kind === "abort")
+                    throw failure;
+                assertCurrent();
+                if (kind !== "out-of-gas") {
+                    await assertLifecycleBlock(client, block, planned.chainId);
+                    return { ...base, backend: "unavailable", confidence: "provisional", executionProof: "unavailable", admitted: false, steps: measured, reason: `Legal-envelope validated replay unavailable: ${lifecycleFailureReason(failure)}` };
+                }
+                await assertLifecycleBlock(client, block, planned.chainId);
+                return { ...base, backend, admitted: false, steps: measured, reason: `Validated buffered replay failed (${finalFailure?.error ?? "Execution reverted"}) and execution at the exact gas ceiling still reverted: ${lifecycleFailureReason(failure)}` };
+            }
+        }
+    }
+    assertCurrent();
+    if (nextEnvelope !== undefined && finalFailure === undefined) {
+        const currentMinimum = verifiedSteps[0]?.gasRequired ?? verifiedSteps[0]?.gasUsed ?? nextEnvelope.gas;
+        if (nextEnvelope.gas < currentMinimum) {
+            await assertLifecycleBlock(client, block, planned.chainId);
+            return { ...base, backend, admitted: false, executionProof: "proved", protocolFit: "failed", steps: verifiedSteps,
+                failureCategory: "capacity", capacityConstraint: "gas-envelope", failedTransactionId: transactions[0]?.id,
+                reason: "Exact reviewed replay exceeds the held gas envelope" };
         }
     }
     const estimates = [];
-    const balance = rpcQuantity(await lifecyclePinnedRpc(client, "eth_getBalance", [planned.account, toHex(block.number)], block), "creator native balance");
-    let remainingBalance = balance;
+    // A definitive returned replay failure already refuses execution. Retain its
+    // fee observations without inventing a balance or doing redundant payer work.
+    let remainingBalance = finalFailure === undefined
+        ? rpcQuantity(await lifecyclePinnedRpc(client, "eth_getBalance", [planned.account, toHex(block.number)], block), "creator native balance")
+        : undefined;
     let affordabilityFailure;
     const feeContext = configuration.estimateDataFee === undefined || sourceClient === client ? context : { ...context, client: sourceClient };
     for (let index = 0; index < verifiedSteps.length; index += 1) {
@@ -505,7 +766,7 @@ async function simulateLaunchTransactionsWithContext(options, transactions, cont
         const gasLimit = admittedGasLimits[index];
         if (step === undefined || transaction === undefined || gasLimit === undefined)
             throw new LifecyclePlanningError("INVALID_SIMULATION", "Missing verified fee context");
-        const dataFee = limits.protocol === "nitro" ? 0n : configuration.estimateDataFee === undefined ? undefined : await configuration.estimateDataFee({ ...transaction, gas: gasLimit }, feeContext);
+        const dataFee = limits.protocol === "nitro" ? 0n : configuration.estimateDataFee === undefined ? undefined : await configuration.estimateDataFee({ ...transaction, gas: gasLimit, gasPrice }, feeContext);
         if (dataFee !== undefined && (typeof dataFee !== "bigint" || dataFee < 0n || dataFee >= 1n << 256n))
             throw new LifecyclePlanningError("INVALID_DATA_FEE", "Data-fee oracle must return a nonnegative uint256 bigint amount");
         // Nitro gas includes poster charges. Never add the quoted poster fee again.
@@ -513,13 +774,15 @@ async function simulateLaunchTransactionsWithContext(options, transactions, cont
         const required = transaction.value + executionFee + (dataFee ?? 0n);
         if (required >= 1n << 256n)
             throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Transaction value and fee envelope exceed uint256");
-        if (required > remainingBalance && affordabilityFailure === undefined)
-            affordabilityFailure = "Creator native balance cannot fund the remaining transaction value and execution/data fee envelopes";
-        remainingBalance -= required;
+        if (remainingBalance !== undefined) {
+            if (required > remainingBalance && affordabilityFailure === undefined)
+                affordabilityFailure = "Creator native balance cannot fund the remaining transaction value and execution/data fee envelopes";
+            remainingBalance -= required;
+        }
         const poster = posterGas[index];
         estimates.push({ ...step, estimate: { gasUsed: step.gasUsed ?? 0n, gasLimit, gasPrice, executionFee, dataFee, posterGas: poster, posterFee: poster === undefined ? undefined : poster * gasPrice, dataFeeIncludedInGas: limits.protocol === "nitro", totalFee: dataFee === undefined ? undefined : executionFee + dataFee, feeConfidence: dataFee === undefined ? "execution-only" : "execution-and-data" } });
     }
     await assertLifecycleBlock(client, block, planned.chainId);
-    return { ...base, backend, executionProof: finalFailure === undefined ? "proved" : "failed", protocolFit: finalFailure === undefined ? "proved" : "unknown", admitted: finalFailure === undefined && affordabilityFailure === undefined, steps: estimates, reason: finalFailure?.error ?? affordabilityFailure, failedTransactionId: finalFailure?.transactionId };
+    return { ...base, backend, executionProof: finalFailure === undefined ? "proved" : "failed", protocolFit: finalFailure === undefined ? "proved" : "unknown", admitted: finalFailure === undefined && affordabilityFailure === undefined, steps: estimates, reason: finalFailureReason ?? finalFailure?.error ?? affordabilityFailure, failedTransactionId: finalFailure?.transactionId, failureCategory: finalFailure?.failureCategory ?? (affordabilityFailure === undefined ? undefined : "affordability"), capacityConstraint: finalFailure?.failureCategory === "capacity" ? "compute" : undefined };
 }
 //# sourceMappingURL=simulation.js.map