@deeeed/metamask-harness 0.38.1 → 0.40.0

package/library/actions/extension/perps/perps.mjs

@@ -1,7 +1,29 @@
 import { pathToFileURL } from 'node:url';
 import { dataTestId, marketSymbol, normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import {
+  assertTrustedExternalMutationTarget,
+  externalMutationNotDispatched,
+  readExternalMutationReceipt,
+  readPriorMutationReceipt,
+  recordExternalMutationCleanupCandidate,
+  runGuardedExternalMutation,
+  trustedExternalMutationBudget,
+  trustedExternalMutationFundingRequirement,
+  trustedExternalMutationIdentity,
+  withExternalMutationRecovery,
+} from './mutation-receipt.mjs';
 import { readSnapshot } from './read_snapshot.mjs';
 import { readPerpsRuntimeStateExpression } from './state.mjs';
+import {
+  orderIdentityMatches,
+  parseOrderCard,
+  parsePositionDetail,
+  parsePositiveBaseUnits,
+  parseUsdBaseUnits,
+  positionIdentityMatches,
+  withinBaseUnitTolerance,
+  waitForStableGlobalPerpsHome,
+} from './visible-mutation-identity.mjs';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -167,37 +189,121 @@ export async function assertOrders(input, expectedOpen) {
 export async function closePositions(input) {
   requireExplicitSelection(input);
   return withExtensionPage(input, async (page) => {
-    const timeoutMs = Number(input.node?.timeout_ms ?? 30000);
     const state = await page.readPositions();
     if (!state.available) throw new Error('Background Perps API unavailable; cannot verify or close live positions.');
     const matching = selectedItems(input, state.positions);
     const symbols = uniqueSymbols(matching.map(symbolForItem));
     if (symbols.length === 0) return { action: input.action, closed: false, matchingCount: 0, symbols, reason: 'no matching open positions' };
-    const closeResult = { success: true, successCount: 0, failureCount: 0, results: [] };
-    for (const position of matching) {
-      const symbol = symbolForItem(position);
-      const currentPrice = await readCurrentMarketPrice(page, symbol);
-      const positionSize = Number(position?.size ?? position?.szi);
-      if (!Number.isFinite(positionSize) || positionSize === 0) {
-        closeResult.success = false;
-        closeResult.failureCount += 1;
-        closeResult.results.push({ symbol, success: false, error: `Invalid position size for ${symbol}: ${String(position?.size ?? position?.szi)}` });
-        continue;
+    throw new Error(
+      'metamask.perps.close_positions cannot dispatch through background state hooks. ' +
+      'Use the exact receipt-bound metamask.perps.close_visible_position action.',
+    );
+  });
+}
+
+async function closeOrderThroughBackground(input, page, timeoutMs) {
+  await requirePerpsTradingContext(input, page);
+  const symbol = marketSymbol(input);
+  const side = String(input.node?.side ?? '').toLowerCase();
+  const amount = String(input.node?.amount ?? '');
+  const leverage = Number(input.node?.leverage);
+  const limitPrice = String(input.node?.limit_price ?? '');
+  const orderId = String(input.node?.order_id ?? '');
+  const roundingToleranceBaseUnits = String(input.node?.identity_rounding_tolerance_base_units ?? '10000');
+  const expected = {
+    market: symbol,
+    side,
+    orderType: 'limit',
+    notionalBaseUnits: `${BigInt(trustedExternalMutationIdentity(input, page, {
+      operation: 'perps-cancel-order',
+      provider: input.node?.provider,
+      network: input.node?.network,
+      market: symbol,
+      side,
+      amount,
+      leverage,
+      orderType: 'limit',
+      positionMode: 'new',
+      limitPrice,
+      offsetPct: input.node?.offset_pct ?? null,
+      partialCloseAmount: null,
+      externalOrderId: orderId,
+      roundingToleranceBaseUnits,
+    }).amountBaseUnits) * BigInt(leverage)}`,
+    limitPriceBaseUnits: parseUsdBaseUnits(limitPrice),
+    roundingToleranceBaseUnits,
+  };
+  const identity = trustedExternalMutationIdentity(input, page, {
+    operation: 'perps-cancel-order',
+    market: symbol,
+    side,
+    provider: input.node?.provider,
+    network: input.node?.network,
+    amount,
+    leverage,
+    orderType: 'limit',
+    positionMode: 'new',
+    limitPrice,
+    offsetPct: input.node?.offset_pct ?? null,
+    partialCloseAmount: null,
+    externalOrderId: orderId,
+    roundingToleranceBaseUnits,
+  });
+  const fundingBalance = await requireCurrentVisibleFundingBalance(input, page, timeoutMs);
+  const existing = await readExternalMutationReceipt(input, identity);
+  const exact = (await readOpenOrders(page))
+    .map(backgroundOrderObservation)
+    .filter((order) => order?.id === orderId && backgroundOrderMatches(order, expected));
+  if (!existing && exact.length !== 1) {
+    throw new Error('Exact authorized background order is unavailable for cancellation.');
+  }
+  if (existing?.record?.facts?.order?.id !== orderId) {
+    if (existing) throw new Error('Background cancellation receipt is not bound to the requested order.');
+  }
+  const order = exact[0] ?? existing?.record?.facts?.order;
+  const mutation = await runGuardedExternalMutation({
+    input,
+    identity,
+    publicationFacts: { order, fundingBalance },
+    dispatch: async () => {
+      try {
+        await requireCurrentVisibleFundingBalance(input, page, timeoutMs, fundingBalance.observedBaseUnits);
+        await requirePerpsTradingContext(input, page);
+        const current = (await readOpenOrders(page))
+          .map(backgroundOrderObservation)
+          .filter((candidate) => candidate?.id === orderId && backgroundOrderMatches(candidate, expected));
+        if (current.length !== 1 || JSON.stringify(current[0]) !== JSON.stringify(order)) {
+          throw new Error('Exact authorized background order changed before cancellation.');
+        }
+        assertTrustedExternalMutationTarget(input, page, identity);
+      } catch (error) {
+        throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
       }
-      const result = await closePositionWithFreshPrice(page, input, position, symbol);
-      const success = result?.success === true;
-      closeResult.results.push({ symbol, success, result });
-      if (success) closeResult.successCount += 1;
-      else {
-        closeResult.success = false;
-        closeResult.failureCount += 1;
+      const result = await requestBackground(page, 'perpsCancelOrder', [{ orderId, symbol }]);
+      if (result?.success === false) throw new Error(result?.error || 'perpsCancelOrder failed.');
+    },
+    observe: async () => {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() <= deadline) {
+        const present = (await readOpenOrders(page))
+          .map(backgroundOrderObservation)
+          .some((candidate) => candidate?.id === orderId);
+        if (!present) return { success: true, canceledOrder: order };
+        await sleep(250);
       }
-    }
-    const after = await waitForPositionsAbsent(page, symbols, timeoutMs);
-    const stillOpen = after.positions.filter((position) => symbols.includes(symbolForItem(position)));
-    if (stillOpen.length > 0) throw new Error(`Expected selected positions to close after perpsClosePosition. Result: ${JSON.stringify(closeResult)}`);
-    return { action: input.action, closed: true, matchingCount: matching.length, symbols, closeResult, proofPath: 'background-perpsClosePosition' };
+      throw new Error('Exact background order did not become absent after cancellation.');
+    },
   });
+  return {
+    action: input.action,
+    canceled: true,
+    matchingCount: 1,
+    symbols: [symbol],
+    order,
+    receipt: mutation.receipt,
+    resumed: mutation.resumed,
+    proofPath: 'background-receipt-bound',
+  };
 }
 
 export async function closeOrders(input) {
@@ -207,75 +313,176 @@ export async function closeOrders(input) {
     const hasBackgroundRequest = await page.evaluate(
       `typeof globalThis.stateHooks?.submitRequestToBackground === 'function'`,
     );
+    if (hasBackgroundRequest) return closeOrderThroughBackground(input, page, timeoutMs);
     if (!hasBackgroundRequest) {
       if (input.node?.confirm_live !== true) {
         throw new Error('metamask.perps.close_orders requires confirm_live=true for visible live cancellation.');
       }
-      const selector = input.node?.selector && typeof input.node.selector === 'object' ? input.node.selector : {};
-      if (input.node?.side != null || selector.side != null) {
-        throw new Error('Visible Perps order cancellation cannot prove an order side. Next: select one market without side or use a runtime with background state hooks.');
-      }
       const symbols = configuredSymbols(input, []);
       if (symbols.length !== 1) {
         throw new Error('Visible Perps order cancellation requires exactly one market.');
       }
       const symbol = symbols[0];
-      await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
-      const orderSelector = '[data-testid^="order-card-"]';
-      await page.waitForSelector(orderSelector, { timeoutMs });
-      let canceled = 0;
-      while (await page.evaluate(`Boolean(document.querySelector(${JSON.stringify(orderSelector)}))`)) {
-        const beforeCount = await page.evaluate(`document.querySelectorAll(${JSON.stringify(orderSelector)}).length`);
-        await page.click(orderSelector);
+      const side = String(input.node?.side ?? '').toLowerCase();
+      const amount = String(input.node?.amount ?? '');
+      const leverage = Number(input.node?.leverage);
+      const limitPrice = String(input.node?.limit_price ?? '');
+      const roundingToleranceBaseUnits = String(input.node?.identity_rounding_tolerance_base_units ?? '10000');
+      if (!/^(?:long|short)$/u.test(side) || !Number.isInteger(leverage)
+        || !/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(limitPrice)) {
+        throw new Error('Visible Perps cancellation requires side, amount, leverage, and explicit limit_price identity.');
+      }
+      const operation = {
+        operation: 'perps-cancel-order',
+        provider: input.node?.provider,
+        network: input.node?.network,
+        market: symbol,
+        side,
+        amount,
+        leverage,
+        orderType: 'limit',
+        positionMode: 'new',
+        limitPrice,
+        offsetPct: input.node?.offset_pct ?? null,
+        partialCloseAmount: null,
+        roundingToleranceBaseUnits,
+      };
+      const priorLookupIdentity = trustedExternalMutationIdentity(input, page, operation);
+      const priorPlace = await readPriorMutationReceipt(
+        input,
+        priorLookupIdentity,
+        'metamask.perps.place_order',
+      );
+      const expectedOrder = {
+        market: symbol,
+        side,
+        orderType: 'limit',
+        notionalBaseUnits: `${BigInt(priorLookupIdentity.amountBaseUnits) * BigInt(leverage)}`,
+        limitPriceBaseUnits: parseUsdBaseUnits(limitPrice),
+        roundingToleranceBaseUnits,
+      };
+      const cleanupCandidate = priorPlace.record?.state === 'observed-policy-violation'
+        ? priorPlace.record.cleanupCandidate
+        : null;
+      const cleanupOrder = cleanupCandidate?.order;
+      const cleanupMode = Boolean(cleanupCandidate)
+        && cleanupCandidate.orderId === cleanupOrder?.id
+        && cleanupCandidate.market === symbol
+        && cleanupCandidate.side === side
+        && cleanupCandidate.orderType === 'limit'
+        && Number(cleanupCandidate.leverage) === leverage
+        && String(cleanupCandidate.limitPriceBaseUnits) === String(expectedOrder.limitPriceBaseUnits)
+        && String(cleanupCandidate.requestedNotionalBaseUnits) === expectedOrder.notionalBaseUnits
+        && BigInt(cleanupCandidate.observedNotionalBaseUnits) > BigInt(expectedOrder.notionalBaseUnits)
+        && BigInt(cleanupCandidate.overageBaseUnits)
+          === BigInt(cleanupCandidate.observedNotionalBaseUnits) - BigInt(expectedOrder.notionalBaseUnits);
+      const priorOrder = cleanupMode ? cleanupOrder : priorPlace.record?.observation?.order;
+      if (!priorOrder?.id || !(cleanupMode || orderIdentityMatches(priorOrder, expectedOrder))) {
+        throw new Error('Prior place receipt has no exact visible limit-order identity to cancel.');
+      }
+      const identity = trustedExternalMutationIdentity(input, page, {
+        ...operation,
+        visibleOrderId: priorOrder.id,
+      });
+      const existingReceipt = await readExternalMutationReceipt(input, identity);
+      let fundingBalance = null;
+      let tradingContext = null;
+      if (!existingReceipt) {
+        fundingBalance = await requireCurrentVisibleFundingBalance(input, page, timeoutMs);
+        tradingContext = await requirePerpsTradingContext(input, page);
+        await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
+        await page.waitForSelector(dataTestId('perps-market-detail-pair'), { timeoutMs });
+        const exact = (await readVisibleOrderCards(page, symbol))
+          .filter((order) => order.id === priorOrder.id && (cleanupMode
+            ? cleanupCandidateIdentityMatches(order, expectedOrder)
+              && String(order.notionalBaseUnits) === String(cleanupCandidate.observedNotionalBaseUnits)
+            : orderIdentityMatches(order, priorOrder)));
+        if (exact.length !== 1) throw new Error('Exact authorized visible order is unavailable for cancellation.');
+        await page.click(`[data-testid=${JSON.stringify(priorOrder.id)}]`);
         await page.waitForSelector(dataTestId('perps-cancel-order-modal'), { timeoutMs });
-        await page.click(dataTestId('perps-cancel-order-button'));
-        canceled += 1;
+      }
+      const mutation = await runGuardedExternalMutation({
+        input,
+        identity,
+        publicationFacts: {
+          order: priorOrder,
+          ...(fundingBalance ? { fundingBalance } : {}),
+          ...(tradingContext ? { tradingContext } : {}),
+          ...(cleanupMode ? { cleanupMode: 'observed-policy-violation', cleanupCandidate } : {}),
+        },
+        dispatch: async () => {
+          let dispatchTarget;
+          try {
+            await requireCurrentVisibleFundingBalance(input, page, timeoutMs, fundingBalance.observedBaseUnits);
+            await requirePerpsTradingContext(input, page);
+            assertTrustedExternalMutationTarget(input, page, identity);
+            await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
+            await page.waitForSelector(dataTestId('perps-market-detail-pair'), { timeoutMs });
+            const exact = (await readVisibleOrderCards(page, symbol))
+              .filter((order) => order.id === priorOrder.id && (cleanupMode
+                ? cleanupCandidateIdentityMatches(order, expectedOrder)
+                  && String(order.notionalBaseUnits) === String(cleanupCandidate.observedNotionalBaseUnits)
+                : orderIdentityMatches(order, priorOrder)));
+            if (exact.length !== 1) throw new Error('Exact authorized visible order changed before cancellation.');
+            await page.click(`[data-testid=${JSON.stringify(priorOrder.id)}]`);
+            await page.waitForSelector(dataTestId('perps-cancel-order-modal'), { timeoutMs });
+            dispatchTarget = await page.evaluate(`(() => {
+              const element = document.querySelector('[data-testid="perps-cancel-order-button"]');
+              if (!element || element.disabled || element.getAttribute('aria-disabled') === 'true') {
+                throw new Error('Visible Perps cancel control is unavailable.');
+              }
+              element.scrollIntoView({ block: 'center', inline: 'center' });
+              const rect = element.getBoundingClientRect();
+              return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+            })()`);
+            assertTrustedExternalMutationTarget(input, page, identity);
+          } catch (error) {
+            throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
+          }
+          await page.session.call('Input.dispatchMouseEvent', {
+            type: 'mousePressed', x: dispatchTarget.x, y: dispatchTarget.y,
+            button: 'left', buttons: 1, clickCount: 1,
+          });
+          await page.session.call('Input.dispatchMouseEvent', {
+            type: 'mouseReleased', x: dispatchTarget.x, y: dispatchTarget.y,
+            button: 'left', buttons: 0, clickCount: 1,
+          });
+        },
+        observe: async () => {
         const deadline = Date.now() + timeoutMs;
+        let absentSince = null;
         while (Date.now() < deadline) {
-          const state = await page.evaluate(`({
-            modal: Boolean(document.querySelector(${JSON.stringify(dataTestId('perps-cancel-order-modal'))})),
-            orders: document.querySelectorAll(${JSON.stringify(orderSelector)}).length,
-          })`);
-          if (!state.modal && state.orders < beforeCount) break;
+          const present = (await readVisibleOrderCards(page, symbol)).some((order) => order.id === priorOrder.id);
+          if (!present) {
+            absentSince ??= Date.now();
+            if (Date.now() - absentSince >= 1_000) {
+              await page.navigateHash('#/perps-home');
+              const cleanup = await waitForStableGlobalPerpsHome(page, { timeoutMs, requireZero: true });
+              return {
+                success: true,
+                canceledOrder: priorOrder,
+                cleanup: { positionCount: 0, orderCount: 0, balanceBaseUnits: cleanup.balanceBaseUnits },
+              };
+            }
+          } else absentSince = null;
           await sleep(250);
         }
-        if (canceled >= 100) throw new Error('Visible Perps order cancellation exceeded 100 orders.');
-      }
+        throw new Error('Exact authorized order did not become stably absent after cancellation.');
+        },
+      });
       return {
         action: input.action,
-        canceled: canceled > 0,
-        matchingCount: canceled,
+        canceled: true,
+        matchingCount: 1,
         symbols: [symbol],
+        order: priorOrder,
+        receipt: mutation.receipt,
+        resumed: mutation.resumed,
+        cleanup: mutation.observation.cleanup,
         proofPath: 'visible-product-controls',
       };
     }
-    const before = await readOpenOrders(page);
-    const matching = selectedItems(input, before);
-    const symbols = uniqueSymbols(matching.map(symbolForItem));
-    if (symbols.length === 0) return { action: input.action, canceled: false, matchingCount: 0, symbols, result: null };
-    const result = { success: true, successCount: 0, failureCount: 0, results: [] };
-    for (const order of matching) {
-      const orderId = order?.orderId ?? order?.id;
-      const symbol = symbolForItem(order);
-      if (!orderId || !symbol) {
-        result.success = false;
-        result.failureCount += 1;
-        result.results.push({ orderId: orderId ?? null, symbol: symbol || null, success: false, error: 'missing orderId or symbol' });
-        continue;
-      }
-      const cancelResult = await requestBackground(page, 'perpsCancelOrder', [{ orderId: String(orderId), symbol }]);
-      const success = cancelResult?.success !== false;
-      result.results.push({ orderId: String(orderId), symbol, success, result: cancelResult });
-      if (success) result.successCount += 1;
-      else {
-        result.success = false;
-        result.failureCount += 1;
-      }
-    }
-    const after = await waitForOrdersAbsent(page, symbols, timeoutMs);
-    const stillOpen = after.filter((order) => symbols.includes(symbolForItem(order)));
-    if (stillOpen.length > 0) throw new Error(`Expected selected Perps orders to cancel, but ${stillOpen.length} are still open.`);
-    return { action: input.action, canceled: true, matchingCount: matching.length, symbols, result, proofPath: 'background-perpsCancelOrder' };
+    throw new Error('Visible Perps cancellation did not return a terminal result.');
   });
 }
 
@@ -290,47 +497,6 @@ async function requestBackground(page, method, args, timeoutMs = 20000) {
   return result;
 }
 
-async function triggerBackground(page, method, args) {
-  return page.evaluate(`(() => {
-    const request = globalThis.stateHooks?.submitRequestToBackground;
-    if (typeof request !== 'function') throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot call ${method}.');
-    const pending = request(${JSON.stringify(method)}, ${JSON.stringify(args)});
-    Promise.resolve(pending).catch(() => {});
-    return { requested: true };
-  })()`);
-}
-
-function isTransientClosePriceError(result) {
-  const message = String(result?.error ?? result?.message ?? '');
-  // Retry local pricing/slippage races only. Provider-level oracle rejections
-  // such as "Price too far from oracle" are surfaced as real market failures.
-  return /IOC_CANCEL|Slippage/i.test(message);
-}
-
-async function closePositionWithFreshPrice(page, input, position, symbol) {
-  const maxAttempts = Number(input.node?.close_attempts ?? 3);
-  const attempts = [];
-  let lastResult = null;
-  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    const currentPrice = await readCurrentMarketPrice(page, symbol, input.node?.current_price);
-    const params = {
-      symbol,
-      size: String(input.node?.size ?? ''),
-      orderType: 'market',
-      priceAtCalculation: currentPrice,
-      maxSlippageBps: Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300),
-      position,
-    };
-    const result = await requestBackground(page, 'perpsClosePosition', [params]);
-    attempts.push({ attempt, currentPrice, result });
-    lastResult = result;
-    if (result?.success === true) return { ...result, attempts, params };
-    if (!isTransientClosePriceError(result) || attempt === maxAttempts) break;
-    await sleep(Number(input.node?.close_retry_delay_ms ?? 1000));
-  }
-  return { ...(lastResult && typeof lastResult === 'object' ? lastResult : { success: false, error: String(lastResult) }), attempts };
-}
-
 async function readCurrentMarketPrice(page, symbol, explicitPrice) {
   if (explicitPrice !== undefined && explicitPrice !== null && explicitPrice !== '') {
     const parsed = Number(String(explicitPrice).replace(/[$,]/g, ''));
@@ -385,6 +551,146 @@ async function readOpenOrders(page) {
   return (await readOpenOrdersState(page)).orders;
 }
 
+function backgroundOrderObservation(order) {
+  const id = String(order?.orderId ?? order?.id ?? '');
+  const market = symbolForItem(order);
+  const side = sideForItem(order);
+  const orderType = String(order?.orderType?.type ?? order?.orderType ?? order?.type ?? '').toLowerCase();
+  const limitPriceBaseUnits = parseUsdBaseUnits(
+    order?.price ?? order?.limitPrice ?? order?.limitPx ?? order?.px,
+  );
+  const size = Number(order?.size ?? order?.sz ?? order?.szi);
+  const price = limitPriceBaseUnits == null ? Number.NaN : Number(limitPriceBaseUnits) / 1_000_000;
+  const notional = size * price;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,180}$/u.test(id)
+    || !market || !/^(?:long|short)$/u.test(side) || orderType !== 'limit'
+    || limitPriceBaseUnits == null || !Number.isFinite(notional) || notional <= 0) return null;
+  return {
+    id,
+    market,
+    side,
+    orderType,
+    limitPriceBaseUnits,
+    notionalBaseUnits: `${Math.round(notional * 1_000_000)}`,
+  };
+}
+
+function backgroundOrderMatches(observed, expected) {
+  return Boolean(observed)
+    && observed.market === expected.market
+    && observed.side === expected.side
+    && observed.orderType === expected.orderType
+    && withinBaseUnitTolerance(
+      observed.notionalBaseUnits,
+      expected.notionalBaseUnits,
+      expected.roundingToleranceBaseUnits,
+    )
+    && withinBaseUnitTolerance(
+      observed.limitPriceBaseUnits,
+      expected.limitPriceBaseUnits,
+      expected.roundingToleranceBaseUnits,
+    );
+}
+
+function backgroundPositionObservation(position) {
+  const market = symbolForItem(position);
+  const side = sideForItem(position);
+  const leverage = Number(position?.leverage?.value ?? position?.leverage ?? position?.lev);
+  const size = Number(position?.size ?? position?.szi);
+  let marginBaseUnits = parseUsdBaseUnits(
+    position?.marginUsed ?? position?.margin ?? position?.marginValue,
+  );
+  if (marginBaseUnits == null) {
+    const positionValueBaseUnits = parseUsdBaseUnits(
+      position?.positionValue ?? position?.notional ?? position?.value,
+    );
+    if (positionValueBaseUnits != null && Number.isInteger(leverage) && leverage > 0) {
+      marginBaseUnits = `${BigInt(positionValueBaseUnits) / BigInt(leverage)}`;
+    }
+  }
+  if (!market || !/^(?:long|short)$/u.test(side) || !Number.isInteger(leverage)
+    || leverage < 1 || !Number.isFinite(size) || size === 0 || marginBaseUnits == null
+    || BigInt(marginBaseUnits) <= 0n) return null;
+  return { market, side, leverage, size: String(position?.size ?? position?.szi), marginBaseUnits };
+}
+
+async function observeBackgroundPlace(page, expected, baselineIds, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    if (expected.orderType === 'limit') {
+      const matches = (await readOpenOrders(page))
+        .map(backgroundOrderObservation)
+        .filter((order) => order && !baselineIds.has(order.id) && backgroundOrderMatches(order, expected));
+      if (matches.length === 1) return { success: true, order: matches[0] };
+      if (matches.length > 1) throw new Error('Background order postcondition matched more than one new order.');
+    } else {
+      const state = await page.readPositions();
+      if (!state.available) throw new Error('Background position postcondition is unavailable.');
+      const matches = state.positions
+        .map(backgroundPositionObservation)
+        .filter((position) => position
+          && position.market === expected.market
+          && position.side === expected.side
+          && position.leverage === expected.leverage
+          && withinBaseUnitTolerance(
+            position.marginBaseUnits,
+            expected.amountBaseUnits,
+            expected.roundingToleranceBaseUnits,
+          ));
+      if (matches.length === 1) return { success: true, position: matches[0] };
+      if (matches.length > 1) throw new Error('Background position postcondition matched more than one position.');
+    }
+    await sleep(250);
+  }
+  throw new Error('Exact background Perps placement postcondition was not proven.');
+}
+
+async function dispatchBackgroundPlace(page, {
+  amount,
+  isBuy,
+  leverage,
+  limitPrice,
+  maxSlippageBps,
+  orderType,
+  resolvedPrice,
+  symbol,
+}) {
+  return page.evaluate(`(async () => {
+    const request = globalThis.stateHooks?.submitRequestToBackground;
+    if (typeof request !== 'function') throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot place live Perps order.');
+    const currentPrice = Number(${JSON.stringify(resolvedPrice)});
+    const usdAmount = ${JSON.stringify(amount)};
+    const leverage = ${JSON.stringify(leverage)};
+    const orderType = ${JSON.stringify(orderType)};
+    const limitPrice = ${JSON.stringify(limitPrice)};
+    const orderParams = orderType === 'limit' ? {
+      symbol: ${JSON.stringify(symbol)},
+      isBuy: ${JSON.stringify(isBuy)},
+      size: ((Number(usdAmount) * Number(leverage)) / Number(limitPrice)).toString(),
+      orderType,
+      price: String(limitPrice),
+      timeInForce: 'GTC',
+      leverage,
+      currentPrice,
+      priceAtCalculation: currentPrice,
+      maxSlippageBps: ${JSON.stringify(maxSlippageBps)},
+    } : {
+      symbol: ${JSON.stringify(symbol)},
+      isBuy: ${JSON.stringify(isBuy)},
+      size: ((Number(usdAmount) * Number(leverage)) / currentPrice).toString(),
+      orderType,
+      leverage,
+      currentPrice,
+      priceAtCalculation: currentPrice,
+      usdAmount,
+      maxSlippageBps: ${JSON.stringify(maxSlippageBps)},
+    };
+    const result = await request('perpsPlaceOrder', [orderParams]);
+    if (!result || result.success !== true) throw new Error(result?.error || 'perpsPlaceOrder failed.');
+    return { success: true };
+  })()`, { awaitPromise: true });
+}
+
 async function readOpenOrdersState(page) {
   const state = await page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
@@ -500,16 +806,369 @@ async function waitForSelectedOrderState(page, input, expectedOpen, timeoutMs) {
   }
 }
 
+async function readVisiblePositionIdentity(page) {
+  const raw = await page.evaluate(`(() => {
+    const read = (testId) => {
+      const element = document.querySelector('[data-testid="' + testId + '"]');
+      if (!element) return null;
+      const rect = element.getBoundingClientRect();
+      const style = getComputedStyle(element);
+      if (rect.width <= 0 || rect.height <= 0 || style.display === 'none' || style.visibility === 'hidden') return null;
+      return String(element.innerText || '').replace(/\\s+/gu, ' ').trim().slice(0, 200);
+    };
+    return {
+      pair: read('perps-market-detail-pair'),
+      direction: read('perps-position-leverage'),
+      margin: read('perps-position-margin-value'),
+      size: read('perps-position-size-value'),
+    };
+  })()`);
+  return parsePositionDetail(raw);
+}
+
+async function readVisibleOrderCards(page, market) {
+  const rows = await page.evaluate(`(() => [...document.querySelectorAll('[data-testid^="order-card-"]')]
+    .filter((element) => {
+      const rect = element.getBoundingClientRect();
+      const style = getComputedStyle(element);
+      return rect.width > 0 && rect.height > 0 && style.display !== 'none' && style.visibility !== 'hidden';
+    })
+    .slice(0, 100)
+    .map((element) => ({ id: element.getAttribute('data-testid'), text: String(element.innerText || '').slice(0, 1000) })))()`);
+  return rows.map((row) => parseOrderCard(row, market)).filter(Boolean);
+}
+
+function cleanupCandidateIdentityMatches(order, expected) {
+  return Boolean(order)
+    && String(order.market).toUpperCase() === String(expected.market).toUpperCase()
+    && String(order.side).toLowerCase() === String(expected.side).toLowerCase()
+    && String(order.orderType).toLowerCase() === 'limit'
+    && BigInt(order.limitPriceBaseUnits) === BigInt(expected.limitPriceBaseUnits)
+    && BigInt(order.notionalBaseUnits) > BigInt(expected.notionalBaseUnits);
+}
+
+async function observePolicyViolationCleanupCandidate(page, expected, receipt, timeoutMs) {
+  const baselineIds = Array.isArray(receipt?.facts?.baselineOrderIds) ? receipt.facts.baselineOrderIds : null;
+  if (!baselineIds || baselineIds.length !== 0) return null;
+  const deadline = Date.now() + Math.min(timeoutMs, 10_000);
+  let stableCandidate = null;
+  let stableSince = 0;
+  while (Date.now() < deadline) {
+    const candidates = (await readVisibleOrderCards(page, expected.market))
+      .filter((order) => cleanupCandidateIdentityMatches(order, expected));
+    if (candidates.length > 1) throw new Error('More than one visible over-cap order matches the cleanup identity.');
+    if (candidates.length === 1) {
+      const key = JSON.stringify(candidates[0]);
+      if (key !== stableCandidate) {
+        stableCandidate = key;
+        stableSince = Date.now();
+      } else if (Date.now() - stableSince >= 1_000) {
+        const order = candidates[0];
+        const observedNotionalBaseUnits = String(order.notionalBaseUnits);
+        const requestedNotionalBaseUnits = String(expected.notionalBaseUnits);
+        return {
+          orderId: order.id,
+          order,
+          market: expected.market,
+          side: expected.side,
+          orderType: 'limit',
+          leverage: expected.leverage,
+          limitPriceBaseUnits: String(expected.limitPriceBaseUnits),
+          observedNotionalBaseUnits,
+          requestedNotionalBaseUnits,
+          overageBaseUnits: `${BigInt(observedNotionalBaseUnits) - BigInt(requestedNotionalBaseUnits)}`,
+        };
+      }
+    } else {
+      stableCandidate = null;
+    }
+    await sleep(250);
+  }
+  return null;
+}
+
+async function observeExactVisibleOrderResult(page, expected, receipt, timeoutMs) {
+  await page.navigateHash(`#/perps/market/${encodeURIComponent(expected.market)}`);
+  await page.waitForSelector(dataTestId('perps-market-detail-pair'), { timeoutMs: 20_000 });
+  const deadline = Date.now() + timeoutMs;
+  let stableIdentity = null;
+  let stableSince = 0;
+  let lastObserved = null;
+  while (Date.now() < deadline) {
+    if (expected.orderType === 'market') {
+      const position = await readVisiblePositionIdentity(page);
+      let observedNotionalBaseUnits = null;
+      if (position) {
+        const size = Number(String(position.size).replace(/,/gu, '').match(/[0-9]+(?:\.[0-9]+)?/u)?.[0]);
+        const price = await readCurrentMarketPrice(page, expected.market);
+        if (Number.isFinite(size) && size > 0) {
+          observedNotionalBaseUnits = `${Math.round(size * price * 1_000_000)}`;
+          if (BigInt(observedNotionalBaseUnits) > BigInt(expected.maximumNotionalBaseUnits)) {
+            throw new Error('Visible Perps position notional exceeds the runner-verified operation budget.');
+          }
+        }
+      }
+      lastObserved = {
+        position: position ? {
+          market: String(position.market).slice(0, 20),
+          side: String(position.side).slice(0, 10),
+          leverage: Number(position.leverage),
+          marginBaseUnits: /^-?\d{1,30}$/u.test(String(position.marginBaseUnits))
+            ? String(position.marginBaseUnits)
+            : null,
+          positiveSize: /[1-9]/u.test(String(position.size).replace(/[^0-9]/gu, '')),
+          observedNotionalBaseUnits,
+        } : null,
+      };
+      if (observedNotionalBaseUnits && positionIdentityMatches(position, expected)) {
+        const key = JSON.stringify(position);
+        if (key !== stableIdentity) {
+          stableIdentity = key;
+          stableSince = Date.now();
+        } else if (Date.now() - stableSince >= 1_000) {
+          return {
+            success: true,
+            position,
+            observedNotionalBaseUnits,
+            maximumNotionalBaseUnits: expected.maximumNotionalBaseUnits,
+            order: null,
+            orderId: null,
+          };
+        }
+      } else {
+        stableIdentity = null;
+      }
+    } else {
+      const baselineIds = new Set(Array.isArray(receipt?.facts?.baselineOrderIds) ? receipt.facts.baselineOrderIds : []);
+      const orders = await readVisibleOrderCards(page, expected.market);
+      lastObserved = {
+        orders: orders.slice(0, 10).map((order) => ({
+          id: /^[A-Za-z0-9:_-]{1,128}$/u.test(String(order.id)) ? String(order.id) : null,
+          market: String(order.market).slice(0, 20),
+          side: String(order.side).slice(0, 10),
+          orderType: String(order.orderType).slice(0, 10),
+          notionalBaseUnits: /^\d{1,30}$/u.test(String(order.notionalBaseUnits))
+            ? String(order.notionalBaseUnits)
+            : null,
+          limitPriceBaseUnits: /^\d{1,30}$/u.test(String(order.limitPriceBaseUnits))
+            ? String(order.limitPriceBaseUnits)
+            : null,
+        })),
+      };
+      const matching = orders
+        .filter((order) => !baselineIds.has(order.id) && orderIdentityMatches(order, expected));
+      if (matching.length > 1) throw new Error('More than one new visible order matches the authorized identity.');
+      if (matching.length === 1) {
+        const key = JSON.stringify(matching[0]);
+        if (key !== stableIdentity) {
+          stableIdentity = key;
+          stableSince = Date.now();
+        } else if (Date.now() - stableSince >= 1_000) {
+          return { success: true, position: null, order: matching[0], orderId: matching[0].id };
+        }
+      } else {
+        stableIdentity = null;
+      }
+    }
+    await sleep(250);
+  }
+  const identity = expected.orderType === 'market' && expected.matchMargin === false
+    ? 'market/side/leverage'
+    : 'market/side/amount';
+  throw new Error(`matching ${expected.orderType} ${identity} identity was not stably visible before timeout; last observed: ${JSON.stringify(lastObserved)}`);
+}
+
+async function placeOrderThroughBackground(input, page, {
+  amount,
+  expected,
+  identity,
+  isBuy,
+  leverage,
+  limitPrice,
+  orderType,
+  positionMode,
+  resolvedPrice,
+  submitAttempts,
+  symbol,
+}) {
+  if (positionMode !== 'new' || submitAttempts !== 1) {
+    throw new Error('Background Perps placement requires position_mode=new and submit_attempts=1.');
+  }
+  const fundingBalance = await requireCurrentVisibleFundingBalance(
+    input,
+    page,
+    Number(input.node?.timeout_ms ?? 30_000),
+  );
+  const existing = await readExternalMutationReceipt(input, identity);
+  let baselineIds = new Set();
+  if (existing?.record?.facts?.baselineOrderIds) {
+    baselineIds = new Set(existing.record.facts.baselineOrderIds.map(String));
+  } else if (!existing) {
+    if (orderType === 'limit') {
+      baselineIds = new Set((await readOpenOrders(page))
+        .map((order) => String(order?.orderId ?? order?.id ?? ''))
+        .filter(Boolean));
+    } else {
+      const state = await page.readPositions();
+      if (!state.available) throw new Error('Background position baseline is unavailable.');
+      const matching = state.positions
+        .map(backgroundPositionObservation)
+        .filter((position) => position
+          && position.market === symbol && position.side === expected.side);
+      if (matching.length !== 0) {
+        throw new Error('Background Perps placement requires no pre-existing matching position.');
+      }
+    }
+  }
+  const mutation = await runGuardedExternalMutation({
+    input,
+    identity,
+    publicationFacts: { baselineOrderIds: [...baselineIds], fundingBalance },
+    dispatch: async () => {
+      try {
+        await requireCurrentVisibleFundingBalance(
+          input,
+          page,
+          Number(input.node?.timeout_ms ?? 30_000),
+          fundingBalance.observedBaseUnits,
+        );
+        await requirePerpsTradingContext(input, page);
+        assertTrustedExternalMutationTarget(input, page, identity);
+      } catch (error) {
+        throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
+      }
+      return dispatchBackgroundPlace(page, {
+        amount,
+        isBuy,
+        leverage,
+        limitPrice,
+        maxSlippageBps: Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300),
+        orderType,
+        resolvedPrice,
+        symbol,
+      });
+    },
+    observe: async () => observeBackgroundPlace(
+      page,
+      expected,
+      baselineIds,
+      Number(input.node?.timeout_ms ?? 30_000),
+    ),
+  });
+  return {
+    action: input.action,
+    market: symbol,
+    side: expected.side,
+    orderType,
+    positionMode,
+    amount,
+    leverage,
+    limitPrice,
+    submitted: true,
+    submitAttempts,
+    receipt: mutation.receipt,
+    resumed: mutation.resumed,
+    outcome: mutation.observation,
+    proofPath: 'background-receipt-bound',
+  };
+}
+
+export async function requirePerpsTradingContext(input, page) {
+  const provider = String(input.node?.provider ?? '').toLowerCase();
+  const network = String(input.node?.network ?? '').toLowerCase();
+  if (!/^[a-z][a-z0-9_-]{0,31}$/u.test(provider) || !/^(?:mainnet|testnet)$/u.test(network)) {
+    throw new Error('Perps mutation requires explicit provider and network inputs.');
+  }
+  const state = await readPerpsRuntimeState(page);
+  if (!state.available || !state.networkKnown) {
+    throw new Error('Perps mutation cannot verify the current provider and network.');
+  }
+  const actualProvider = String(state.activeProvider || '').toLowerCase();
+  const actualNetwork = state.isTestnet === true ? 'testnet' : 'mainnet';
+  if (actualProvider !== provider || actualNetwork !== network) {
+    throw new Error(
+      `Perps mutation expected ${provider}/${network}, got ${actualProvider || 'unknown'}/${actualNetwork}.`,
+    );
+  }
+  return { provider, network };
+}
+
+export async function requireCurrentVisibleFundingBalance(input, page, timeoutMs, expectedBaseUnits) {
+  const requirement = trustedExternalMutationFundingRequirement(input);
+  await page.navigateHash('#/perps-home');
+  const home = await waitForStableGlobalPerpsHome(page, {
+    timeoutMs,
+    stableMs: Math.min(1_000, Math.max(0, timeoutMs - 250)),
+    requireZero: false,
+  });
+  if (BigInt(home.balanceBaseUnits) < BigInt(requirement.minBaseUnits)) {
+    throw new Error('Current visible Perps balance is below the runner-trusted funding minimum.');
+  }
+  if (expectedBaseUnits != null && home.balanceBaseUnits !== expectedBaseUnits) {
+    throw new Error('Current visible Perps balance changed after receipt publication.');
+  }
+  return {
+    source: 'visible-perps-home',
+    requirementId: `${requirement.kind}:${requirement.id}`,
+    minimumBaseUnits: requirement.minBaseUnits,
+    evidenceActualBaseUnits: requirement.actualBaseUnits,
+    observedBaseUnits: home.balanceBaseUnits,
+  };
+}
+
+async function requireCurrentOrderEntryFundingBalance(input, page, expectedBaseUnits) {
+  const requirement = trustedExternalMutationFundingRequirement(input);
+  const visible = await page.evaluate(`(() => {
+    const row = document.querySelector('[data-testid="amount-input-available-to-trade-row"]');
+    if (!row) return null;
+    const rect = row.getBoundingClientRect();
+    return {
+      text: String(row.innerText || '').replace(/\\s+/gu, ' ').trim().slice(0, 200),
+      visible: rect.width > 0 && rect.height > 0,
+    };
+  })()`);
+  const visibleAmount = visible?.visible
+    ? /([0-9][0-9,]*(?:\.[0-9]{1,6})?)\s*USDC/iu.exec(String(visible.text))?.[1]
+    : null;
+  const observedBaseUnits = visibleAmount ? parseUsdBaseUnits(visibleAmount) : null;
+  if (observedBaseUnits == null) {
+    throw new Error('Current visible Perps order-entry balance is unavailable.');
+  }
+  if (BigInt(observedBaseUnits) < BigInt(requirement.minBaseUnits)) {
+    throw new Error('Current visible Perps balance is below the runner-trusted funding minimum.');
+  }
+  if (observedBaseUnits !== expectedBaseUnits) {
+    throw new Error('Current visible Perps balance changed after receipt publication.');
+  }
+  return {
+    source: 'visible-perps-order-entry',
+    requirementId: `${requirement.kind}:${requirement.id}`,
+    minimumBaseUnits: requirement.minBaseUnits,
+    evidenceActualBaseUnits: requirement.actualBaseUnits,
+    observedBaseUnits,
+  };
+}
+
 export async function placeOrder(input) {
   requirePlaceOrderInputs(input);
   const symbol = marketSymbol(input);
   const side = String(input.node.side).toLowerCase();
   const amount = String(input.node.amount ?? input.node.notional);
-  const leverage = Number(input.node?.leverage ?? 3);
+  const leverage = Number(input.node?.leverage ?? 1);
   const isBuy = side !== 'short';
   const orderType = resolveOrderType(input);
   const positionMode = String(input.node?.position_mode ?? 'new').toLowerCase();
   const submitAttempts = Number(input.node?.submit_attempts ?? 1);
+  const roundingToleranceBaseUnits = String(input.node?.identity_rounding_tolerance_base_units ?? '10000');
+  if (!/^(?:0|[1-9][0-9]{0,6})$/u.test(roundingToleranceBaseUnits)
+    || BigInt(roundingToleranceBaseUnits) > 1_000_000n) {
+    throw new Error(`${input.action} identity_rounding_tolerance_base_units must be 0..1000000.`);
+  }
+  const explicitLimitPrice = input.node?.limit_price ?? input.node?.limitPrice ?? input.node?.price;
+  if (orderType === 'limit' && (explicitLimitPrice == null || String(explicitLimitPrice) === '')) {
+    throw new Error('Funded visible limit orders require an explicit limit_price so resume cannot recompute a changed offset price.');
+  }
+  const stableLimitPrice = orderType === 'limit' ? String(explicitLimitPrice) : null;
   if (positionMode !== 'new' && positionMode !== 'modify') {
     throw new Error(`${input.action} received unsupported position_mode: ${positionMode}.`);
   }
@@ -517,17 +1176,165 @@ export async function placeOrder(input) {
     throw new Error(`${input.action} submit_attempts must be 1 or 2.`);
   }
   return withExtensionPage(input, async (page) => {
+    const identity = trustedExternalMutationIdentity(input, page, {
+      operation: orderType === 'limit' ? 'perps-limit-order' : 'perps-market-order',
+      provider: input.node?.provider,
+      network: input.node?.network,
+      market: symbol,
+      side,
+      amount,
+      leverage,
+      orderType,
+      positionMode,
+      limitPrice: stableLimitPrice,
+      offsetPct: input.node?.offset_pct ?? input.node?.offsetPct ?? null,
+      partialCloseAmount: null,
+      roundingToleranceBaseUnits,
+    });
+    const requestedNotionalBaseUnits = BigInt(identity.amountBaseUnits) * BigInt(leverage);
+    const placementBudget = trustedExternalMutationBudget(input, identity.operation);
+    if (requestedNotionalBaseUnits > BigInt(placementBudget.maxBaseUnits)) {
+      throw new Error('Requested Perps order exposure exceeds the runner-trusted operation cap.');
+    }
+    const expectedVisibleIdentity = {
+      market: symbol,
+      side,
+      leverage,
+      orderType,
+      amountBaseUnits: identity.amountBaseUnits,
+      notionalBaseUnits: `${requestedNotionalBaseUnits}`,
+      limitPriceBaseUnits: stableLimitPrice == null ? null : parseUsdBaseUnits(stableLimitPrice),
+      roundingToleranceBaseUnits,
+      ...(orderType === 'market' ? { matchMargin: false } : {}),
+      ...(orderType === 'market' ? {
+        maximumNotionalBaseUnits: placementBudget.maxBaseUnits,
+      } : {}),
+    };
+    const hasBackgroundRequest = await page.evaluate(
+      `typeof globalThis.stateHooks?.submitRequestToBackground === 'function'`,
+    );
+    if (hasBackgroundRequest) {
+      await requirePerpsTradingContext(input, page);
+      const resolvedPrice = await readCurrentMarketPrice(
+        page,
+        symbol,
+        input.node?.current_price ?? input.node?.currentPrice,
+      );
+      const backgroundLimitPrice = orderType === 'limit'
+        ? resolveLimitPrice(input, isBuy, resolvedPrice)
+        : null;
+      return placeOrderThroughBackground(input, page, {
+        amount,
+        expected: {
+          ...expectedVisibleIdentity,
+          limitPriceBaseUnits: backgroundLimitPrice == null ? null : parseUsdBaseUnits(backgroundLimitPrice),
+        },
+        identity,
+        isBuy,
+        leverage,
+        limitPrice: backgroundLimitPrice,
+        orderType,
+        positionMode,
+        resolvedPrice,
+        submitAttempts,
+        symbol,
+      });
+    }
+    const existingReceipt = await readExternalMutationReceipt(input, identity);
+    if (existingReceipt) {
+      return withExternalMutationRecovery(existingReceipt, async () => {
+        await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
+        await page.waitForSelector(dataTestId('perps-market-detail-pair'), { timeoutMs: 20_000 });
+        if (positionMode !== 'new') {
+          throw new Error('resumed funded position modification requires manual visible inspection');
+        }
+        let cleanupReceipt = existingReceipt;
+        if (existingReceipt.record?.state === 'outcome-unknown' && orderType === 'limit') {
+          const cleanupCandidate = await observePolicyViolationCleanupCandidate(
+            page,
+            expectedVisibleIdentity,
+            existingReceipt.record,
+            Number(input.node?.timeout_ms ?? 45000),
+          );
+          if (cleanupCandidate) {
+            cleanupReceipt = await recordExternalMutationCleanupCandidate(input, existingReceipt, cleanupCandidate);
+          }
+        }
+        if (cleanupReceipt.record?.state === 'observed-policy-violation') {
+          return {
+            action: input.action,
+            market: symbol,
+            side,
+            orderType,
+            positionMode,
+            amount,
+            leverage,
+            limitPrice: stableLimitPrice,
+            submitted: false,
+            submitAttempts,
+            receipt: {
+              path: cleanupReceipt.relativePath,
+              sha256: cleanupReceipt.sha256,
+              state: cleanupReceipt.record.state,
+            },
+            resumed: true,
+            policyViolation: true,
+            cleanupCandidate: cleanupReceipt.record.cleanupCandidate,
+            proofPath: 'visible-product-controls',
+          };
+        }
+        const mutation = await runGuardedExternalMutation({
+          input,
+          identity,
+          dispatch: async () => {
+            throw new Error('resumed order must not dispatch');
+          },
+          observe: async ({ receipt }) => observeExactVisibleOrderResult(
+            page,
+            expectedVisibleIdentity,
+            receipt,
+            Number(input.node?.timeout_ms ?? 45000),
+          ),
+        });
+        return {
+          action: input.action,
+          market: symbol,
+          side,
+          orderType,
+          positionMode,
+          amount,
+          leverage,
+          limitPrice: stableLimitPrice,
+          submitted: true,
+          submitAttempts,
+          receipt: mutation.receipt,
+          resumed: true,
+          recovery: mutation.recovery,
+          initialOpenOrderCount: null,
+          initialGlobalPositionCount: null,
+          initialGlobalOrderCount: null,
+          openOrderCount: mutation.observation.order ? 1 : null,
+          configured: null,
+          outcome: mutation.observation,
+          proofPath: 'visible-product-controls',
+        };
+      });
+    }
+    await page.navigateHash('#/perps-home');
+    const initialClean = await waitForStableGlobalPerpsHome(page, {
+      timeoutMs: Number(input.node?.timeout_ms ?? 45_000),
+      requireZero: true,
+    });
+    const fundingBalance = await requireCurrentVisibleFundingBalance(
+      input,
+      page,
+      Number(input.node?.timeout_ms ?? 45_000),
+      initialClean.balanceBaseUnits,
+    );
+    const tradingContext = await requirePerpsTradingContext(input, page);
+    const balanceBeforeBaseUnits = fundingBalance.observedBaseUnits;
     await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
     await page.waitForSelector(dataTestId('perps-market-detail-pair'), { timeoutMs: 20_000 });
-    await page.evaluate(`(async () => {
-      const request = globalThis.stateHooks?.submitRequestToBackground;
-      if (typeof request !== 'function') return;
-      const state = globalThis.stateHooks?.store?.getState?.()?.metamask;
-      if (state && state.isTestnet === false) {
-        await request('perpsToggleTestnet', []);
-        await new Promise((resolve) => setTimeout(resolve, 2000));
-      }
-    })()`, { awaitPromise: true });
     const resolvedPrice = await readCurrentMarketPrice(
       page,
       symbol,
@@ -536,21 +1343,26 @@ export async function placeOrder(input) {
     const limitPrice = orderType === 'limit'
       ? resolveLimitPrice(input, isBuy, resolvedPrice)
       : null;
-    const initialPositionSize = positionMode === 'modify'
-      ? await page.evaluate(`document.querySelector('[data-testid="perps-position-size-value"]')?.textContent?.trim() ?? null`)
-      : null;
-    const initialOpenOrderCount = orderType === 'limit'
-      ? await page.evaluate(`document.querySelectorAll('[data-testid^="order-card-"]').length`)
-      : null;
+    const baselineOrderIds = orderType === 'limit'
+      ? (await readVisibleOrderCards(page, symbol)).map((order) => order.id)
+      : [];
+    const initialOpenOrderCount = baselineOrderIds.length;
     await page.navigateHash(`#/perps/trade/${encodeURIComponent(symbol)}?direction=${encodeURIComponent(side)}&mode=${positionMode}`);
     await page.waitForSelector(dataTestId('perps-order-entry-page'), { timeoutMs: 20000 });
-    const hasBackgroundRequest = await page.evaluate(
+    const lateBackgroundRequest = await page.evaluate(
       `typeof globalThis.stateHooks?.submitRequestToBackground === 'function'`,
     );
-    if (!hasBackgroundRequest) {
+    if (lateBackgroundRequest) {
+      throw new Error('Background Perps placement appeared after visible setup; refusing an ambiguous dispatch.');
+    }
+    if (!lateBackgroundRequest) {
       if (input.node?.confirm_live !== true) {
         throw new Error('metamask.perps.place_order requires confirm_live=true for visible live submission.');
       }
+      let configured = null;
+      if (submitAttempts !== 1) {
+        throw new Error('Visible funded Perps submission requires submit_attempts=1.');
+      }
       await page.setInput(`${dataTestId('amount-input-field')} input`, amount);
       await page.setInput(`${dataTestId('leverage-input')} input`, String(leverage));
       if (orderType === 'limit') {
@@ -560,103 +1372,86 @@ export async function placeOrder(input) {
         await page.setInput(limitInput, String(limitPrice));
       }
       const configuredDeadline = Date.now() + 10_000;
-      let configured;
       while (Date.now() < configuredDeadline) {
-        configured = await page.evaluate(`(() => {
-          const value = (testId) => document.querySelector('[data-testid="' + testId + '"] input')?.value ?? null;
-          const limit = document.querySelector('[data-testid="limit-price-input"] input')?.value ?? null;
-          const submit = document.querySelector('[data-testid="submit-order-button"]');
-          return {
-            amount: value('amount-input-field'),
-            leverage: value('leverage-input'),
-            limitPrice: limit,
-            limitSelected: document.querySelector('[data-testid="order-type-limit"]')?.getAttribute('aria-pressed') === 'true',
-            submitEnabled: Boolean(submit && !submit.disabled && submit.getAttribute('aria-disabled') !== 'true'),
-            validation: [...document.querySelectorAll('[role="alert"], [data-testid$="validation-error"], [data-testid$="warning"]')]
-              .map((element) => String(element.innerText || '').replace(/\\s+/gu, ' ').trim())
-              .filter(Boolean)
-              .slice(0, 20),
-          };
-        })()`);
-        if (configured.submitEnabled) break;
-        await sleep(250);
+          configured = await page.evaluate(`(() => {
+            const value = (testId) => document.querySelector('[data-testid="' + testId + '"] input')?.value ?? null;
+            const limit = document.querySelector('[data-testid="limit-price-input"] input')?.value ?? null;
+            const submit = document.querySelector('[data-testid="submit-order-button"]');
+            return {
+              amount: value('amount-input-field'),
+              leverage: value('leverage-input'),
+              limitPrice: limit,
+              limitSelected: document.querySelector('[data-testid="order-type-limit"]')?.getAttribute('aria-pressed') === 'true',
+              submitEnabled: Boolean(submit && !submit.disabled && submit.getAttribute('aria-disabled') !== 'true'),
+            };
+          })()`);
+          if (configured.submitEnabled) break;
+          await sleep(250);
       }
       if (Number(configured.amount) !== Number(amount) || Number(configured.leverage) !== leverage) {
-        throw new Error(`Visible Perps order inputs did not retain the requested values: ${JSON.stringify(configured)}.`);
+        throw new Error('Visible Perps order inputs did not retain the requested values.');
       }
       if (orderType === 'limit' && (!configured.limitSelected || Number(configured.limitPrice) !== limitPrice)) {
-        throw new Error(`Visible Perps limit inputs did not retain the requested values: ${JSON.stringify(configured)}.`);
-      }
-      if (!configured.submitEnabled) {
-        throw new Error(`Visible Perps order is not submittable: ${JSON.stringify(configured)}.`);
-      }
-      const submitTarget = await page.evaluate(`(() => {
-        const element = document.querySelector('[data-testid="submit-order-button"]');
-        if (!element) throw new Error('Visible Perps submit control disappeared.');
-        element.scrollIntoView({ block: 'center', inline: 'center' });
-        const rect = element.getBoundingClientRect();
-        return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
-      })()`);
-      for (let attempt = 0; attempt < submitAttempts; attempt += 1) {
-        await page.session.call('Input.dispatchMouseEvent', {
-          type: 'mousePressed',
-          x: submitTarget.x,
-          y: submitTarget.y,
-          button: 'left',
-          buttons: 1,
-          clickCount: 1,
-        });
-        await page.session.call('Input.dispatchMouseEvent', {
-          type: 'mouseReleased',
-          x: submitTarget.x,
-          y: submitTarget.y,
-          button: 'left',
-          buttons: 0,
-          clickCount: 1,
-        });
-      }
-      const resultSelector = orderType === 'limit'
-        ? '[data-testid^="order-card-"]'
-        : dataTestId('perps-position-size-value');
-      const resultDeadline = Date.now() + Number(input.node?.timeout_ms ?? 45000);
-      let outcome;
-      while (Date.now() < resultDeadline) {
-        outcome = await page.evaluate(`(() => ({
-          success: ${JSON.stringify(positionMode)} === 'modify'
-            ? String(location.hash).startsWith(${JSON.stringify(`#/perps/market/${symbol}`)}) &&
-              String(document.querySelector('[data-testid="perps-position-size-value"]')?.textContent || '').trim() !== ${JSON.stringify(initialPositionSize)}
-            : Boolean(document.querySelector(${JSON.stringify(resultSelector)})),
-          route: String(location.hash),
-          submit: (() => {
-            const element = document.querySelector('[data-testid="submit-order-button"]');
-            return element ? {
-              label: String(element.innerText || '').replace(/\\s+/gu, ' ').trim(),
-              enabled: !element.disabled && element.getAttribute('aria-disabled') !== 'true',
-            } : null;
-          })(),
-          errors: [...document.querySelectorAll('[data-testid="perps-order-submit-error"], [role="alert"]')]
-            .map((element) => String(element.innerText || '').replace(/\\s+/gu, ' ').trim())
-            .filter(Boolean)
-            .slice(0, 20),
-        }))()`);
-        if (outcome.success) break;
-        if (outcome.errors.length > 0) {
-          throw new Error(`Visible Perps order submission failed: ${outcome.errors.join(' | ')}`);
-        }
-        await sleep(250);
-      }
-      if (!outcome?.success) {
-        throw new Error(`Visible Perps order submission did not produce ${resultSelector}; observed ${JSON.stringify(outcome)}.`);
+        throw new Error('Visible Perps limit inputs did not retain the requested values.');
       }
+      if (!configured.submitEnabled) throw new Error('Visible Perps order is not submittable.');
+      const mutation = await runGuardedExternalMutation({
+        input,
+        identity,
+        publicationFacts: { balanceBeforeBaseUnits, baselineOrderIds, fundingBalance, tradingContext },
+        dispatch: async () => {
+          let dispatchTarget;
+          try {
+            await requireCurrentOrderEntryFundingBalance(input, page, fundingBalance.observedBaseUnits);
+            await requirePerpsTradingContext(input, page);
+            const currentConfiguration = await page.evaluate(`(() => {
+              const value = (testId) => document.querySelector('[data-testid="' + testId + '"] input')?.value ?? null;
+              const limitSelected = document.querySelector('[data-testid="order-type-limit"]')?.getAttribute('aria-pressed') === 'true';
+              const element = document.querySelector('[data-testid="submit-order-button"]');
+              if (!element || element.disabled || element.getAttribute('aria-disabled') === 'true') {
+                throw new Error('Visible Perps submit control is unavailable.');
+              }
+              element.scrollIntoView({ block: 'center', inline: 'center' });
+              const rect = element.getBoundingClientRect();
+              return {
+                amount: value('amount-input-field'),
+                leverage: value('leverage-input'),
+                limitPrice: value('limit-price-input'),
+                orderType: limitSelected ? 'limit' : 'market',
+                target: { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
+              };
+            })()`);
+            if (currentConfiguration.amount !== amount
+              || currentConfiguration.leverage !== String(leverage)
+              || currentConfiguration.orderType !== orderType
+              || (orderType === 'limit' && currentConfiguration.limitPrice !== String(limitPrice))
+              || (orderType === 'market' && currentConfiguration.limitPrice != null)) {
+              throw new Error('Visible Perps order inputs changed before dispatch.');
+            }
+            dispatchTarget = currentConfiguration.target;
+            assertTrustedExternalMutationTarget(input, page, identity);
+          } catch (error) {
+            throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
+          }
+          await page.session.call('Input.dispatchMouseEvent', {
+            type: 'mousePressed', x: dispatchTarget.x, y: dispatchTarget.y,
+            button: 'left', buttons: 1, clickCount: 1,
+          });
+          await page.session.call('Input.dispatchMouseEvent', {
+            type: 'mouseReleased', x: dispatchTarget.x, y: dispatchTarget.y,
+            button: 'left', buttons: 0, clickCount: 1,
+          });
+        },
+        observe: async ({ receipt }) => observeExactVisibleOrderResult(
+          page,
+          expectedVisibleIdentity,
+          receipt,
+          Number(input.node?.timeout_ms ?? 45000),
+        ),
+      });
       let openOrderCount = null;
       if (orderType === 'limit') {
-        await sleep(2_000);
-        await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
-        await page.waitForSelector(dataTestId('perps-market-detail-pair'), { timeoutMs: 20_000 });
-        openOrderCount = await page.evaluate(`document.querySelectorAll('[data-testid^="order-card-"]').length`);
-        if (openOrderCount !== initialOpenOrderCount + 1) {
-          throw new Error(`Perps limit submission created an unexpected open-order count: before=${initialOpenOrderCount}, after=${openOrderCount}.`);
-        }
+        openOrderCount = mutation.observation.order ? 1 : null;
       }
       return {
         action: input.action,
@@ -669,62 +1464,20 @@ export async function placeOrder(input) {
         limitPrice,
         submitted: true,
         submitAttempts,
+        receipt: mutation.receipt,
+        resumed: mutation.resumed,
+        recovery: mutation.recovery,
         initialOpenOrderCount,
+        initialGlobalPositionCount: initialClean.positionCount,
+        initialGlobalOrderCount: initialClean.orderCount,
         openOrderCount,
         configured,
-        outcome,
+        outcome: mutation.observation,
+        balanceBeforeBaseUnits,
         proofPath: 'visible-product-controls',
       };
     }
-    let order;
-    try {
-      order = await page.evaluate(`(async () => {
-      const request = globalThis.stateHooks?.submitRequestToBackground;
-      if (typeof request !== 'function') throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot place live Perps order.');
-      const currentPrice = Number(${JSON.stringify(resolvedPrice)});
-      if (!Number.isFinite(currentPrice) || currentPrice <= 0) throw new Error('Unable to determine current Perps price for order placement.');
-      const usdAmount = ${JSON.stringify(amount)};
-      const leverage = ${JSON.stringify(leverage)};
-      const orderType = ${JSON.stringify(orderType)};
-      const limitPrice = ${JSON.stringify(limitPrice)};
-      const orderParams = orderType === 'limit' ? {
-        symbol: ${JSON.stringify(symbol)},
-        isBuy: ${JSON.stringify(isBuy)},
-        size: ((Number(usdAmount) * Number(leverage)) / Number(limitPrice)).toString(),
-        orderType,
-        price: String(limitPrice),
-        timeInForce: 'GTC',
-        leverage,
-        currentPrice,
-        priceAtCalculation: currentPrice,
-        maxSlippageBps: ${JSON.stringify(Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300))},
-      } : {
-        symbol: ${JSON.stringify(symbol)},
-        isBuy: ${JSON.stringify(isBuy)},
-        size: ((Number(usdAmount) * Number(leverage)) / currentPrice).toString(),
-        orderType,
-        leverage,
-        currentPrice,
-        priceAtCalculation: currentPrice,
-        usdAmount,
-        maxSlippageBps: ${JSON.stringify(Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300))},
-      };
-      const result = await request('perpsPlaceOrder', [orderParams]);
-      if (!result || result.success !== true) {
-        throw new Error(result?.error || 'perpsPlaceOrder failed.');
-      }
-      return { result, orderParams };
-    })()`, { awaitPromise: true });
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`${message} (resolvedPrice=${resolvedPrice})`);
-    }
-    if (orderType === 'limit') {
-      await waitForSelectedOrderState(page, input, true, Number(input.node?.timeout_ms ?? 30000));
-    } else {
-      await waitForPositionPresent(page, symbol, Number(input.node?.timeout_ms ?? 30000));
-    }
-    return { action: input.action, market: symbol, side, orderType, positionMode, amount, leverage, limitPrice, submitted: true, order, proofPath: 'background-perpsPlaceOrder' };
+    throw new Error('Visible Perps placement did not return a terminal result.');
   });
 }
 
@@ -733,16 +1486,9 @@ export async function ensurePositions(input) {
   requireExplicitSelection(input);
   const state = String(input.node.state).toLowerCase();
   if (state === 'none' || state === 'closed' || state === 'absent') {
-    const close = await closePositions(input);
-    return { ...(await assertPositions(input, false)), close };
+    return assertPositions(input, false);
   }
   if (state === 'open' || state === 'present') {
-    const current = await withExtensionPage(input, async (page) => {
-      const stateResult = await page.readPositions();
-      if (!stateResult.available) throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot ensure live Perps positions.');
-      return positionSelectionState(input, stateResult.positions);
-    });
-    if (!current.hasMatching) await placeOrder(input);
     return assertPositions(input, true);
   }
   throw new Error(`metamask.perps.ensure_positions received unsupported state: ${state}`);
@@ -753,18 +1499,10 @@ export async function ensureOrders(input) {
   requireExplicitSelection(input);
   const state = String(input.node.state).toLowerCase();
   if (state === 'none' || state === 'closed' || state === 'absent') {
-    const close = await closeOrders(input);
-    return { ...(await assertOrders(input, false)), close };
+    return assertOrders(input, false);
   }
   if (state === 'open' || state === 'present') {
-    const current = await withExtensionPage(input, async (page) => ({
-      orders: await readOpenOrders(page),
-    }));
-    let order = null;
-    if (selectedItems(input, current.orders).length === 0) {
-      order = await placeOrder({ ...input, node: { ...input.node, order_type: 'limit' } });
-    }
-    return { ...(await assertOrders(input, true)), order };
+    return assertOrders(input, true);
   }
   throw new Error(`metamask.perps.ensure_orders received unsupported state: ${state}`);
 }
@@ -794,56 +1532,6 @@ function paramsForState(input) {
   return { ...nested, ...input.node };
 }
 
-function profileDefaults(profile) {
-  const selected = String(profile ?? 'clean_market_testnet');
-  if (selected === 'clean_market_testnet') {
-    return {
-      provider: 'hyperliquid',
-      network: 'testnet',
-      page: 'market',
-      positions: { state: 'none', mode: 'matching' },
-      orders: { state: 'none', mode: 'matching' },
-    };
-  }
-  if (selected === 'open_position_testnet') {
-    return {
-      provider: 'hyperliquid',
-      network: 'testnet',
-      page: 'market',
-      positions: { state: 'open', mode: 'matching' },
-      orders: { state: 'none', mode: 'matching' },
-    };
-  }
-  if (selected === 'open_order_testnet') {
-    return {
-      provider: 'hyperliquid',
-      network: 'testnet',
-      page: 'market',
-      positions: false,
-      orders: { state: 'open', mode: 'matching' },
-    };
-  }
-  if (selected === 'provider_mainnet_readonly') {
-    return {
-      provider: 'hyperliquid',
-      network: 'mainnet',
-      page: 'home',
-      positions: false,
-      orders: false,
-    };
-  }
-  if (selected === 'clean_market_mainnet') {
-    return {
-      provider: 'hyperliquid',
-      network: 'mainnet',
-      page: 'market',
-      positions: { state: 'none', mode: 'matching' },
-      orders: { state: 'none', mode: 'matching' },
-    };
-  }
-  return {};
-}
-
 function mergeStateConfig(defaults, params) {
   return {
     ...defaults,
@@ -923,28 +1611,10 @@ async function ensureNetwork(input, config) {
     if (!before.available) throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot enforce Perps network.');
     if (!before.networkKnown) throw new Error('Unable to read the current Perps network from persisted controller state.');
     if (Boolean(before.isTestnet) === expectedTestnet) return { requested: config.network, isTestnet: before.isTestnet, changed: false };
-    // The toggle request can remain pending after the controller state changes.
-    // Convergence is proved by the bounded state poll below, not request completion.
-    const result = await triggerBackground(page, 'perpsToggleTestnet', []);
-    const after = await waitForNetworkState(page, expectedTestnet, Number(input.node?.timeout_ms ?? 30000));
-    if (Boolean(after.isTestnet) !== expectedTestnet) {
-      throw new Error(`Expected Perps network ${config.network}, got isTestnet=${after.isTestnet}.`);
-    }
-    return { requested: config.network, isTestnet: after.isTestnet, changed: true, result };
+    throw new Error(`Expected Perps network ${config.network}, got isTestnet=${before.isTestnet}. Automatic background network toggles are forbidden without a durable receipt; select the network through a supported visible action before running.`);
   });
 }
 
-async function waitForNetworkState(page, expectedTestnet, timeoutMs) {
-  const deadline = Date.now() + timeoutMs;
-  let last = await readPerpsRuntimeState(page);
-  while (Date.now() < deadline) {
-    last = await readPerpsRuntimeState(page);
-    if (Boolean(last.isTestnet) === expectedTestnet) return last;
-    await sleep(500);
-  }
-  return last;
-}
-
 async function assertReadyToTrade(input, config) {
   if (config.readyToTrade === undefined || config.readyToTrade === false) return { skipped: true };
   return withExtensionPage(input, async (page) => {
@@ -976,9 +1646,8 @@ async function assertBalance(input, config) {
 
 export async function startState(input) {
   const params = paramsForState(input);
-  const config = mergeStateConfig(profileDefaults(params.profile), params);
-  // Enter the Perps surface first so its stream bridge/controller API exists
-  // before provider, network, order, or position convergence begins.
+  const config = mergeStateConfig({}, params);
+  // Enter the Perps surface first so its stream bridge/controller API exists.
   const navigation = await applyStateNavigation(input, config);
   const provider = await ensureProvider(input, config);
   const network = await ensureNetwork(input, config);
@@ -988,7 +1657,6 @@ export async function startState(input) {
   const positions = await applyPositionsState(input, config.positions);
   return {
     action: input.action,
-    profile: config.profile ?? params.profile ?? 'clean_market_testnet',
     phase: 'start_state',
     provider,
     network,
@@ -1028,12 +1696,10 @@ const DIRECT_ACTIONS = new Map([
   ['metamask.perps.read_snapshot', readSnapshot],
   ['metamask.perps.read_positions', readPositions],
   ['metamask.perps.read_orders', readOrders],
-  ['metamask.perps.close_positions', closePositions],
   ['metamask.perps.close_orders', closeOrders],
   ['metamask.perps.place_order', placeOrder],
   ['metamask.perps.ensure_positions', ensurePositions],
   ['metamask.perps.ensure_orders', ensureOrders],
-  ['metamask.perps.start_state', startState],
   ['metamask.perps.teardown_state', teardownState],
 ]);