@deeeed/metamask-harness 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.49.0 - 2026-09-07
+
+- Simplify Mobile setup and sizing; correct nested-route verification, lifecycle portability, wallet selection, input clearing and token-sort restoration.
+- Keep piped help complete; add platform-scoped recipe guidance, fixture troubleshooting and action descriptions.
+- Consolidate market/limit validation into `perps.release-live-order`; bind balances to their wallet runtime and cleanup to accepted orders, correct sizing/direction checks, and support approved source-dev testnet QA up to $20.
+
 ## 0.48.0 - 2026-09-07
 
 - Consolidate parameterized recipes, move specialized Perps journeys into the team library, and separate short performance checks from full coverage suites.

package/dist/commands/help.js

@@ -3,19 +3,31 @@ import path from "node:path";
 import { detectAdapter } from "../harness.js";
 import { optionString, parseArgs, targetPath } from "./parse-args.js";
 const UNSCOPED_NEXT = "cd into a MetaMask checkout or pass --adapter <mobile|extension|core>";
+function validHelpLine(value) {
+  return typeof value === "string" || Boolean(value && typeof value.text === "string" && Array.isArray(value.adapters) && value.adapters.length > 0 && value.adapters.every((adapter) => ["mobile", "extension", "core"].includes(adapter)));
+}
+function scopedSections(topic, adapter) {
+  const select = (lines) => lines.flatMap((line) => typeof line === "string" ? [line] : line.adapters.includes(adapter) ? [line.text] : []);
+  return topic.sections.map((section) => ({
+    ...section,
+    details: select(section.details),
+    commands: select(section.commands)
+  }));
+}
 function loadRecipeHelp(packageRoot) {
   const file = path.join(packageRoot, "site", "assets", "help-recipes.json");
   const value = JSON.parse(fs.readFileSync(file, "utf8"));
   if (value.schemaVersion !== 1 || value.topic !== "recipes" || typeof value.title !== "string" || typeof value.summary !== "string" || typeof value.capabilities !== "string" || typeof value.scopeNotice !== "string" || typeof value.recipeProtocolVersion !== "string" || typeof value.safety !== "string" || !Array.isArray(value.sections) || value.sections.length !== 8 || value.sections.some(
-    (section) => !section || typeof section.id !== "string" || typeof section.title !== "string" || typeof section.instruction !== "string" || !Array.isArray(section.details) || section.details.some((detail) => typeof detail !== "string") || !Array.isArray(section.commands) || section.commands.some((command) => typeof command !== "string")
+    (section) => !section || typeof section.id !== "string" || typeof section.title !== "string" || typeof section.instruction !== "string" || !Array.isArray(section.details) || section.details.some((detail) => !validHelpLine(detail)) || !Array.isArray(section.commands) || section.commands.some((command) => !validHelpLine(command))
   )) {
     throw new Error(`Invalid recipe help data: ${file}`);
   }
   return value;
 }
 function recipeHelpPayload(topic, harnessVersion, adapter, target) {
-  const commands = Array.from(new Set(topic.sections.flatMap((section) => section.commands)));
-  const discoveryCommands = topic.sections.find((section) => section.id === "discover")?.commands ?? [];
+  const sections = scopedSections(topic, adapter);
+  const commands = Array.from(new Set(sections.flatMap((section) => section.commands)));
+  const discoveryCommands = sections.find((section) => section.id === "discover")?.commands ?? [];
   return {
     schemaVersion: topic.schemaVersion,
     command: "help",
@@ -29,7 +41,7 @@ function recipeHelpPayload(topic, harnessVersion, adapter, target) {
     summary: topic.summary,
     capabilities: topic.capabilities,
     scopeNotice: topic.scopeNotice,
-    sections: topic.sections,
+    sections,
     commands,
     discoveryCommands,
     safety: topic.safety
@@ -45,7 +57,7 @@ function renderRecipeHelp(topic, harnessVersion, adapter) {
     "Visual tutorial: mm-harness tutorial"
   ];
   if (adapter === "unscoped") lines.push(`No MetaMask checkout detected. Next: ${UNSCOPED_NEXT}.`);
-  for (const [index, section] of topic.sections.entries()) {
+  for (const [index, section] of scopedSections(topic, adapter).entries()) {
     lines.push("", `${index + 1}. ${section.title}`, `   ${section.instruction}`);
     for (const detail of section.details) lines.push(`   - ${detail}`);
     for (const command of section.commands) lines.push(`   $ ${command}`);

package/dist/funding-execution-context.js

@@ -36,7 +36,8 @@ const CLAIM_DIFF_FIELDS = [
 ];
 const trustedActionContexts = /* @__PURE__ */ new WeakSet();
 const fundingSources = /* @__PURE__ */ new WeakMap();
-const CURRENT_FUNDING_REGISTRY_SHA256 = "7e79ee2a5f7bdde0a5548208cb2eab55881575cc7d826ee5f7acdbf15d49609c";
+const CURRENT_FUNDING_REGISTRY_SHA256 = "d4416e0e8a812a0e2f1798ae6f901a5820f7ee0b9783cfa5d515d0c7863ea80e";
+const PREVIOUS_FUNDING_REGISTRY_SHA256 = "7e79ee2a5f7bdde0a5548208cb2eab55881575cc7d826ee5f7acdbf15d49609c";
 const FROZEN_G005_FUNDING_REGISTRY_SHA256 = "c2230bc02fa00d6902915d1cb81bcc08389ea7e399ee9618f26fb0d9fc00b291";
 const LIVE_PERPS_TINY_REGISTRY = {
   "live-perps-tiny": {
@@ -58,8 +59,15 @@ const LIVE_PERPS_TINY_REGISTRY = {
 };
 const TRUSTED_FUNDING_REGISTRIES = {
   [CURRENT_FUNDING_REGISTRY_SHA256]: LIVE_PERPS_TINY_REGISTRY,
+  [PREVIOUS_FUNDING_REGISTRY_SHA256]: LIVE_PERPS_TINY_REGISTRY,
   [FROZEN_G005_FUNDING_REGISTRY_SHA256]: LIVE_PERPS_TINY_REGISTRY
 };
+const SOURCE_DEV_TESTNET_BUDGETS = /* @__PURE__ */ new Set([
+  "perps-market-order:usdc-base-units",
+  "perps-limit-order:usdc-base-units",
+  "perps-cancel-order:usdc-base-units",
+  "perps-close-position:usdc-base-units"
+]);
 const OPERATION_ACTION = /* @__PURE__ */ new Map([
   ["perps-market-order", "metamask.perps.place_order"],
   ["perps-limit-order", "metamask.perps.place_order"],
@@ -1002,7 +1010,7 @@ async function validateFundingEvidenceChain(documents, identity) {
     }
     balanceRuntime = currentRuntime;
     const visibleState = requireRecord(evidenceDocument.visibleState, "funding balance evidence visibleState");
-    if (visibleState.perpsAvailableMarginBaseUnits !== actualBaseUnits || visibleBalanceBaseUnits(trace, emittedNodes) !== actualBaseUnits) {
+    if (visibleState.perpsAvailableMarginBaseUnits !== actualBaseUnits || visibleBalanceBaseUnits(trace, emittedNodes, currentRuntime) !== actualBaseUnits) {
       throw new Error("Funding balance actual value does not match its visible trace.");
     }
     if (!exactTerminalPass(recipe, trace, summary, artifactManifest)) {
@@ -1086,11 +1094,17 @@ function extensionOrigin(value, label) {
     throw new Error(`${label} Extension origin is invalid.`);
   }
 }
-function visibleBalanceBaseUnits(trace, emittedNodes) {
+function visibleBalanceBaseUnits(trace, emittedNodes, runtime) {
   const entries = Array.isArray(trace.entries) ? trace.entries : [];
   const matches = entries.filter((entry) => isRecord(entry) && entry.action === "metamask.perps.read_visible_state" && entry.ok === true && isRecord(entry.output) && entry.output.action === entry.action && entry.output.surface === "home" && entry.output.source === "visible-ui" && isRecord(entry.output.balance) && entry.output.balance.visible === true && isRecord(emittedNodes.get(String(entry.nodeId))) && emittedNodes.get(String(entry.nodeId))?.surface === "home");
   const matchEntry = matches.at(-1);
   if (!matchEntry) throw new Error("Funding balance evidence requires a visible Perps Home balance observation.");
+  for (const entry of matches) {
+    const output = requireRecord(entry.output, "funding balance observation");
+    if (output.runtimeSessionId !== runtime.runtimeSessionId || output.cdpPort !== runtime.cdpPort || extensionOrigin(output.targetUrl, "funding balance observation") !== runtime.extensionOrigin) {
+      throw new Error("Funding balance observation is not from its anchored wallet runtime.");
+    }
+  }
   const label = String(matchEntry.output.balance.label ?? "");
   const match = /(?:^|\s)\$([0-9]+(?:\.[0-9]{1,2})?)(?:\s|$)/u.exec(label);
   if (!match) throw new Error("Funding balance evidence visible amount is invalid.");
@@ -1325,7 +1339,8 @@ function validateTrustedFundingRegistry(identity, operations, budgets) {
   for (const [key, aggregate] of requested) {
     const trusted = domain.budgets.get(key);
     const supplied = suppliedBudgets.get(key);
-    if (!trusted || !supplied || BigInt(supplied.maxBaseUnits) > BigInt(trusted.maxBaseUnits) || supplied.maxCount > trusted.maxCount || aggregate.maxAmountBaseUnits > BigInt(trusted.maxBaseUnits) || aggregate.count > trusted.maxCount || aggregate.amountBaseUnits > BigInt(trusted.maxBaseUnits) * BigInt(trusted.maxCount)) {
+    const maximum = BigInt(identity.registrySha256 === CURRENT_FUNDING_REGISTRY_SHA256 && identity.client === "extension" && identity.proofLane === "source-dev" && SOURCE_DEV_TESTNET_BUDGETS.has(key) ? "20000000" : trusted?.maxBaseUnits ?? "0");
+    if (!trusted || !supplied || BigInt(supplied.maxBaseUnits) > maximum || supplied.maxCount > trusted.maxCount || aggregate.maxAmountBaseUnits > maximum || aggregate.count > trusted.maxCount || aggregate.amountBaseUnits > maximum * BigInt(trusted.maxCount)) {
       throw new Error(`Funding operation ${aggregate.operation} is not bounded by the runner-trusted funding registry.`);
     }
   }

package/dist/metamask-action-validation.js

@@ -191,7 +191,8 @@ function validateMetaMaskActionInputs(recipe, adapter, params) {
       }
       if (action === "metamask.perps.close_orders") {
         required("side", /^(?:long|short)$/u, `${action} requires the exact order side`);
-        if (!/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(String(node.limit_price ?? ""))) {
+        const outputPrice = /^\{\{outputs\.[A-Za-z0-9_.-]+\}\}$/u.test(String(node.limit_price ?? ""));
+        if (!outputPrice && (!/^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,6})?$/u.test(String(node.limit_price ?? "")) || !(Number(node.limit_price) > 0))) {
           findings.push({
             severity: "error",
             code: "recipe.invalid_param",
@@ -200,7 +201,7 @@ function validateMetaMaskActionInputs(recipe, adapter, params) {
           });
         }
       }
-      if (action === "metamask.perps.place_order" && String(node.order_type ?? "market") === "limit" && !/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(String(node.limit_price ?? ""))) {
+      if (action === "metamask.perps.place_order" && String(node.order_type ?? "market") === "limit" && (!/^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,6})?$/u.test(String(node.limit_price ?? "")) || !(Number(node.limit_price) > 0))) {
         findings.push({
           severity: "error",
           code: "recipe.invalid_param",

package/dist/mm-harness-cli.js

@@ -826,7 +826,8 @@ for (const command of REAL) {
       process.exit(await handleUpdate(rawArgv.slice(1)));
     }
     if (command.name === "help") {
-      process.exit(handleHelp(rawArgv.slice(1), { packageRoot, harnessVersion: pkgVersion }));
+      process.exitCode = handleHelp(rawArgv.slice(1), { packageRoot, harnessVersion: pkgVersion });
+      return;
     }
     if (command.name === "tutorial") {
       process.exit(handleTutorial(rawArgv.slice(1), { harnessVersion: pkgVersion }));

package/docs/RECIPES.md

@@ -115,8 +115,8 @@ mm-harness run perps.release-market-filters --describe --adapter extension --jso
 | --- | --- |
 | Activity filter routes | `perps.release-activity-filters` |
 | Deposit and withdraw previews without submission | `perps.release-funds-flows` |
-| Resting limit placement and exact cancellation | `perps.release-live-limit-order` |
-| Filled market placement and exact position close | `perps.release-live-market-order` |
+| Resting limit placement and exact cancellation | `perps.release-live-order order_type=limit limit_price='"<price>"'` |
+| Filled market placement and exact position close | `perps.release-live-order order_type=market` |
 | Market header and statistics | `perps.release-market-details` |
 | Market categories | `perps.release-market-filters` |
 | Market text search | `perps.release-market-search` |

package/library/actions/core/perps/_controller.mjs

@@ -1,26 +1,14 @@
+// Load the target checkout's Perps controller and resolve fixture-backed accounts.
+// Share headless selection, signing, formatting and adapter-output helpers.
+
 import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 
-// Importing a runner .ts source signals the live-adapter contract to execute
-// this adapter under the bundled tsx (see commandFor/importsSourceTypescript in
-// src/live-adapter-contract.ts). The core adapter dynamic-imports the perps
-// controller TypeScript at runtime, so it MUST run under tsx, not plain node.
 import { walletFixturePath } from '../../harness-exports.mjs';
 
-// Shared headless instantiation for the MetaMask `core` adapter.
-//
-// Slice 1: read-only. We instantiate @metamask/perps-controller against a
-// resolved MetaMask/core checkout (context.projectRoot) and drive its standalone
-// read path, which talks to HyperLiquid testnet over HTTP — no CDP, no bridge,
-// no UI, no signer. The controller's standalone read methods
-// (getPositions/getOpenOrders/getAccountState with { standalone: true,
-// userAddress }) create their own InfoClient and never touch the messenger, so
-// reads need ZERO external action handlers. Signing/account-resolution through
-// the messenger is Slice 2.
-
 function controllerEntry(projectRoot) {
   return pathToFileURL(path.join(projectRoot, 'packages/perps-controller/src/index.ts')).href;
 }
@@ -590,12 +578,7 @@ export function symbolForItem(item) {
   return normalizeMarketSymbol(item?.symbol ?? item?.coin ?? '');
 }
 
-// Normalize an item's side to the long/short vocabulary the selector uses.
-// Positions report side as long/short already; OPEN ORDERS report it as buy/sell
-// (a resting BUY = long direction, a resting SELL = short). Mapping both onto
-// long/short lets the shared `side` selector filter positions and orders alike —
-// without this, requesting side:"long" silently drops every order (whose side is
-// "buy"), which is the bug this normalization fixes.
+// Orders carry buy/sell sides; Position.size is signed and authoritative.
 function normalizeSide(rawSide) {
   const side = String(rawSide ?? '').toLowerCase();
   if (side === 'buy' || side === 'b') return 'long';
@@ -603,7 +586,14 @@ function normalizeSide(rawSide) {
   return side;
 }
 
-function sideForItem(item) {
+function sideForItem(item, itemType) {
+  if (itemType === 'position') {
+    const rawSize = item?.size ?? item?.szi;
+    if (typeof rawSize !== 'string' && typeof rawSize !== 'number') return '';
+    const size = Number(rawSize);
+    if (!Number.isFinite(size) || size === 0) return '';
+    return size > 0 ? 'long' : 'short';
+  }
   return normalizeSide(item?.side ?? item?.direction ?? '');
 }
 
@@ -646,7 +636,7 @@ export function requireExplicitSelection(input) {
  * vocabulary as the extension perps adapter. With no selector and no
  * mode=all, returns every item (read defaults to showing all live state).
  */
-export function selectedItems(input, items) {
+export function selectedItems(input, items, itemType = 'order') {
   const requested = configuredSymbols(input, items);
   const selector =
     input.node?.selector && typeof input.node.selector === 'object' ? input.node.selector : {};
@@ -655,7 +645,7 @@ export function selectedItems(input, items) {
   const symbols = requested.length > 0 ? new Set(requested) : null;
   return items.filter((item) => {
     if (symbols && !symbols.has(symbolForItem(item))) return false;
-    if (side && sideForItem(item) && sideForItem(item) !== side) return false;
+    if (side && sideForItem(item, itemType) !== side) return false;
     return true;
   });
 }

package/library/actions/core/perps/assert_orders.mjs

@@ -1,3 +1,6 @@
+// Assert selected standalone orders, trigger fields and parent/child protection links.
+// Checks observed state without placing or canceling orders.
+
 import {
   getCoreController,
   isDirectRun,
@@ -8,11 +11,6 @@ import {
   selectedItems,
 } from './_controller.mjs';
 
-// core Assert selected live Perps open orders are present or absent. Pure read
-// over the controller's standalone getOpenOrders path (no signer / provider init
-// needed) — throws on mismatch so the recipe fails loudly. Mirrors
-// assert_positions.mjs.
-//
 // Optional expect_* fields additionally assert the TRIGGER DATA the exchange
 // round-tripped for every matching order: expect_trigger_order_type (the
 // normalized placement type, e.g. stop_market), expect_trigger_price,

package/library/actions/core/perps/assert_positions.mjs

@@ -1,3 +1,5 @@
+// Assert required presence, absence or count of selected standalone Perps positions.
+
 import {
   getCoreController,
   isDirectRun,
@@ -8,10 +10,6 @@ import {
   selectedItems,
 } from './_controller.mjs';
 
-// core Assert selected live Perps positions are present or absent. Pure read
-// over the controller's standalone path (no signer / provider init needed) —
-// throws on mismatch so the recipe fails loudly.
-
 export function expectedOpen(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.assert_positions requires state=open or state=none.');
   const state = String(input.node.state).toLowerCase();
@@ -39,7 +37,7 @@ export async function assertPositions(input, expectOpen = expectedOpen(input)) {
       standalone: true,
       userAddress: accountAddress,
     });
-    matching = selectedItems(input, positions);
+    matching = selectedItems(input, positions, 'position');
     const reached = expectedCount === undefined
       ? matching.length > 0
       : matching.length === Number(expectedCount);

package/library/actions/core/perps/close_orders.mjs

@@ -1,5 +1,9 @@
+// Cancel selected testnet orders by a fixed ID set and verify their absence.
+// Optional expected IDs reject changed selection before signing and dispatch.
+
 import {
   controllerRejection,
+  getCoreController,
   getCoreControllerWithSigner,
   isDirectRun,
   redactOrder,
@@ -10,9 +14,6 @@ import {
   optionalParam,
 } from './_controller.mjs';
 
-// Snapshot selection into exact IDs so dispatch and postcondition checks cannot
-// expand to opposite-side or newly created orders sharing a market symbol.
-
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -46,7 +47,15 @@ export function cancelOrdersFailure(result) {
 
 export async function closeOrders(input) {
   requireExplicitSelection(input);
-  const { controller, accountAddress, network } = await getCoreControllerWithSigner(input);
+  const expectedIds = input.node?.expected_order_ids;
+  if (expectedIds !== undefined && (!Array.isArray(expectedIds) ||
+    expectedIds.some((id) => typeof id !== 'string' || !id.trim()) ||
+    new Set(expectedIds).size !== expectedIds.length)) {
+    throw new Error('expected_order_ids must contain unique non-empty receipt IDs.');
+  }
+  const { controller, accountAddress, network } = await (expectedIds === undefined
+    ? getCoreControllerWithSigner(input)
+    : getCoreController(input));
   const timeoutMs = Number(
     optionalParam(input.node ?? {}, 'timeout_ms', 'timeoutMs') ?? 30000,
   );
@@ -56,6 +65,14 @@ export async function closeOrders(input) {
     userAddress: accountAddress,
   });
   const matching = selectedItems(input, orders);
+  const checkExpectedIds = (selected) => {
+    if (expectedIds === undefined) return;
+    const actual = selected.map((order) => order.orderId);
+    if (actual.length !== expectedIds.length || actual.some((id) => !expectedIds.includes(id))) {
+      throw new Error('CORE_ORDER_RECEIPT_MISMATCH: selected live orders do not match expected_order_ids; cancellation was not dispatched.');
+    }
+  };
+  checkExpectedIds(matching);
   const symbols = Array.from(new Set(matching.map(symbolForItem)));
 
   if (symbols.length === 0) {
@@ -76,6 +93,13 @@ export async function closeOrders(input) {
   if (orderIds.some((id) => typeof id !== 'string' || !id.trim()) || new Set(orderIds).size !== orderIds.length) {
     throw new Error('Selected Core orders require unique non-empty orderId values before cancellation.\nNext: mm-harness actions metamask.perps.read_orders --adapter core --json');
   }
+  if (expectedIds !== undefined) {
+    await getCoreControllerWithSigner(input);
+    checkExpectedIds(selectedItems(input, await controller.getOpenOrders({
+      standalone: true,
+      userAddress: accountAddress,
+    })));
+  }
   const result = await controller.cancelOrders({ orderIds });
   const failure = cancelOrdersFailure(result);
   if (failure !== undefined) {

package/library/actions/core/perps/close_positions.mjs

@@ -1,6 +1,10 @@
+// Close selected testnet positions and verify their absence.
+// Optional receipt guards bind the observed position, reducing side and maximum quantity.
+
 import {
   controllerRejection,
   currentMarketPrice,
+  getCoreController,
   getCoreControllerWithSigner,
   isDirectRun,
   redactPosition,
@@ -11,12 +15,6 @@ import {
   optionalParam,
 } from './_controller.mjs';
 
-// core Close selected live Perps positions on HyperLiquid testnet by driving the
-// headless PerpsController.closePosition() per matching position (full close)
-// through the full signing/provider path (Slice 2). Mirrors the extension
-// adapter: read → close each matching position with a fresh price → verify the
-// selected positions are gone.
-
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -45,7 +43,17 @@ export function closePositionsFailure(results) {
 
 export async function closePositions(input) {
   requireExplicitSelection(input);
-  const { controller, accountAddress, network } = await getCoreControllerWithSigner(input);
+  const expectedPositions = input.node?.expected_positions;
+  if (expectedPositions !== undefined && (!Array.isArray(expectedPositions) || expectedPositions.length > 1 ||
+    expectedPositions.some((position) => !position || typeof position.coin !== 'string' ||
+      !position.coin.trim() || !Number.isFinite(Number(position.size)) || Number(position.size) === 0 ||
+      !Number.isFinite(Number(position.entryPrice)) || Number(position.entryPrice) <= 0) ||
+    new Set(expectedPositions.map((position) => position.coin)).size !== expectedPositions.length)) {
+    throw new Error('expected_positions must contain at most one market with nonzero signed size and positive entryPrice.');
+  }
+  const { controller, accountAddress, network } = await (expectedPositions === undefined
+    ? getCoreControllerWithSigner(input)
+    : getCoreController(input));
   const timeoutMs = Number(
     optionalParam(input.node ?? {}, 'timeout_ms', 'timeoutMs') ?? 30000,
   );
@@ -61,7 +69,20 @@ export async function closePositions(input) {
     standalone: true,
     userAddress: accountAddress,
   });
-  const matching = selectedItems(input, positions);
+  const matching = selectedItems(input, positions, 'position');
+  const checkExpectedPositions = (selected) => {
+    if (expectedPositions === undefined) return;
+    if (selected.length !== expectedPositions.length || selected.some((position) => {
+      const actual = redactPosition(position);
+      const expected = expectedPositions.find((item) => item.coin === actual.coin);
+      return !expected || Number(expected.size) !== Number(actual.size) ||
+        Number(expected.entryPrice) !== Number(actual.entryPrice) ||
+        (expected.side != null && expected.side !== actual.side);
+    })) {
+      throw new Error('CORE_POSITION_RECEIPT_MISMATCH: selected live position size, side or entry price changed; close was not dispatched.');
+    }
+  };
+  checkExpectedPositions(matching);
   const symbols = Array.from(new Set(matching.map(symbolForItem)));
 
   if (symbols.length === 0) {
@@ -80,13 +101,29 @@ export async function closePositions(input) {
 
   const results = [];
   let successCount = 0;
+  if (expectedPositions !== undefined) await getCoreControllerWithSigner(input);
   for (const position of matching) {
     const symbol = symbolForItem(position);
     const currentPrice = await currentMarketPrice(controller, symbol);
-    // Full close: omit size so the provider closes 100% of the position. Pass
-    // live position + fresh price so the provider skips a REST refetch and the
-    // slippage guard has a current anchor.
-    const result = await controller.closePosition({
+    if (expectedPositions !== undefined) {
+      checkExpectedPositions(selectedItems(input, await controller.getPositions({
+        standalone: true,
+        userAddress: accountAddress,
+      }), 'position'));
+    }
+    // Guarded closes keep receipt direction and quantity fixed. A venue position
+    // is netted, so matching fields cannot distinguish an identical replacement.
+    const expected = expectedPositions?.find((item) => item.coin === symbol);
+    const result = expected ? await controller.placeOrder({
+      symbol,
+      isBuy: Number(expected.size) < 0,
+      size: String(Math.abs(Number(expected.size))),
+      orderType: 'market',
+      reduceOnly: true,
+      currentPrice,
+      priceAtCalculation: currentPrice,
+      maxSlippageBps,
+    }) : await controller.closePosition({
       symbol,
       orderType: 'market',
       currentPrice,
@@ -128,6 +165,10 @@ export async function closePositions(input) {
     results,
     positions: stillOpen.map(redactPosition),
     proofPath: 'perps-controller-closePosition',
+    ...(expectedPositions === undefined ? {} : {
+      expectedPositions,
+      proofPath: 'perps-controller-placeOrder-reduce-only-receipt-size',
+    }),
   };
 }
 

package/library/actions/core/perps/edit_order.mjs

@@ -1,3 +1,5 @@
+// Edit a selected resting testnet order and verify its replacement or declared rejection.
+
 import {
   configuredSymbols,
   controllerRejection,

package/library/actions/core/perps/ensure_orders.mjs

@@ -1,12 +1,11 @@
+// Converge selected testnet orders to open or absent state, then assert the result.
+// Reuse an existing matching order instead of placing another.
+
 import { getCoreController, isDirectRun, requireExplicitSelection, runAdapter, selectedItems } from './_controller.mjs';
 import { assertOrders } from './assert_orders.mjs';
 import { closeOrders } from './close_orders.mjs';
 import { placeOrder } from './place_order.mjs';
 
-// core Higher-level wrapper that reads selected open orders, converges them to the
-// requested `state` (open/none) by canceling or placing, then asserts the final
-// order state. Mirrors ensure_positions.mjs.
-
 export async function ensureOrders(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.ensure_orders requires state=open or state=none.');
   requireExplicitSelection(input);

package/library/actions/core/perps/ensure_positions.mjs

@@ -1,12 +1,11 @@
+// Converge selected testnet positions to open or absent state, then assert the result.
+// Open a position only when the selected state requires one.
+
 import { getCoreController, isDirectRun, requireExplicitSelection, runAdapter, selectedItems } from './_controller.mjs';
 import { assertPositions } from './assert_positions.mjs';
 import { closePositions } from './close_positions.mjs';
 import { placeOrder } from './place_order.mjs';
 
-// core Higher-level wrapper that reads selected positions, converges them to the
-// requested `state` (open/none) by placing or closing, then asserts the final
-// state. Mirrors the extension ensure_positions semantics.
-
 export async function ensurePositions(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.ensure_positions requires state=open or state=none.');
   requireExplicitSelection(input);
@@ -26,7 +25,7 @@ export async function ensurePositions(input) {
       userAddress: accountAddress,
     });
     let order = null;
-    if (selectedItems(input, positions).length === 0) {
+    if (selectedItems(input, positions, 'position').length === 0) {
       order = await placeOrder(input);
     }
     const assertion = await assertPositions(input, true);

package/library/actions/core/perps/place_order.mjs

@@ -1,3 +1,6 @@
+// Submit and verify testnet market, limit or trigger orders through the headless controller.
+// Supports declared rejection cases and attached protection parameters.
+
 import {
   configuredSymbols,
   controllerRejection,
@@ -12,24 +15,14 @@ import {
   selectedItems,
 } from './_controller.mjs';
 
-// core Place a real Perps order on HyperLiquid testnet by driving the headless
-// PerpsController.placeOrder() through the full signing/provider path (Slice 2).
-// Mirrors the extension adapter's input vocabulary and notional→size math:
-//   size = (usdAmount * leverage) / currentPrice
-// The HyperLiquidProvider recalculates size from usdAmount internally; we still
-// pass a derived size for the controller's own validation, plus currentPrice/
-// priceAtCalculation so the provider's slippage guard has a fresh anchor.
-//
 // LIMIT orders (orderType=limit) place a RESTING order on the book instead of
 // filling: the provider sends tif=Gtc and uses the provided `price` verbatim
 // (calculateOrderPriceAndSize / buildOrdersArray in core's orderCalculations.ts).
 // The limit price is derived from the live mid by `offset_pct` (e.g. -30 places a
-// BUY 30% below mid that will NOT fill), or supplied absolutely via `limit_price`.
+// BUY 30% below mid), or supplied absolutely via `limit_price`.
 // For a limit order we size from the LIMIT price (not mid) and omit usdAmount so
-// the controller uses our explicit size verbatim — that guarantees the
-// on-exchange notional (size * limitPrice) clears HyperLiquid's ~$10 minimum even
-// though the limit sits far from mid. After placing we verify the resting open
-// order exists (not a filled position).
+// the controller receives an explicit size; venue quantity normalization still
+// applies. After placing we verify the resting open order exists, not a filled position.
 //
 // TRIGGER placements (order_type=stop_market | stop_limit | take_profit_market |
 // take_profit_limit) rest off-book until `trigger_price` is reached, then execute
@@ -567,7 +560,7 @@ export async function placeOrder(input) {
       userAddress: accountAddress,
     });
   }
-  const matchingPositions = selectedItems(input, positions);
+  const matchingPositions = selectedItems(input, positions, 'position');
 
   if (restsOnBook && matchingOrders.length === 0) {
     throw new Error(

package/library/actions/core/perps/read_account.mjs

@@ -1,3 +1,5 @@
+// Read the selected account's Perps balance and margin data through standalone controller APIs.
+
 import {
   getCoreController,
   isDirectRun,

package/library/actions/core/perps/read_orders.mjs

@@ -1,3 +1,5 @@
+// Read standalone Perps orders and return redacted selected data with total/matching counts.
+
 import {
   getCoreController,
   isDirectRun,

package/library/actions/core/perps/read_positions.mjs

@@ -1,3 +1,5 @@
+// Read standalone Perps positions and return redacted selected data with total/matching counts.
+
 import {
   getCoreController,
   isDirectRun,
@@ -12,7 +14,7 @@ export async function readPositions(input) {
     standalone: true,
     userAddress: accountAddress,
   });
-  const matching = selectedItems(input, positions);
+  const matching = selectedItems(input, positions, 'position');
   return {
     action: input.action,
     source: 'perps-controller-standalone',

package/library/actions/core/perps/read_snapshot.mjs

@@ -1,3 +1,6 @@
+// Summarize public Perps market data, account state or both for a headless proof.
+// Retain data-source and account identity metadata alongside redacted results.
+
 import {
   getCoreController,
   isDirectRun,

package/library/actions/core/perps/start_state.mjs

@@ -1,21 +1,10 @@
+// Prepare selected testnet baselines before proof, handling positions before orders.
+// Omitted domains are skipped; this headless action performs no UI navigation.
+
 import { isDirectRun, resolveNetwork, runAdapter } from './_controller.mjs';
 import { ensureOrders } from './ensure_orders.mjs';
 import { ensurePositions } from './ensure_positions.mjs';
 
-// core Headless composite that converges the POSITION and ORDER baselines for the
-// selected market(s) on HyperLiquid testnet before the proof window. Mirrors the
-// extension perps-domain-dispatcher start_state semantics but SKIPS every
-// navigation/page/HUD step — headless core has no UI surface.
-//
-// Params (extension schema, testnet-default): profile, market(s)/symbol(s),
-// positions{state,...}, orders{state,...}, network. The UI-only `page`/`hud`
-// fields are accepted by the schema but intentionally ignored here.
-//
-// A baseline block converges to its `state` by composing the ensure_* helpers; a
-// block set to `false` (or omitted) skips that domain. Position convergence runs
-// first (closing a position also clears its TP/SL orders), then order
-// convergence, so the final order baseline is authoritative.
-
 const BASELINE_KEYS = [
   'market',
   'symbol',