@deeeed/metamask-harness 0.47.4 → 0.49.0

package/docs/RECIPES.md

@@ -32,7 +32,7 @@ task proof and may call other recipes.
   "paramsSchema": {
     "type": "object",
     "properties": {
-      "account": { "type": "string", "default": "Account 1" }
+      "timeout_ms": { "type": "integer", "minimum": 1, "default": 15000 }
     },
     "additionalProperties": false
   },
@@ -41,6 +41,7 @@ task proof and may call other recipes.
     "nodes": {
       "unlock": {
         "action": "metamask.wallet.ensure_unlocked",
+        "timeout_ms": "{{params.timeout_ms}}",
         "intent": "Make the fixture-backed wallet ready for use",
         "next": "done"
       },
@@ -54,8 +55,8 @@ Defaults are applied before validation. Root values use `key=value`; a nested
 recipe call uses `action: "call"`, `ref`, and `params`.
 
 ```bash
-mm-harness run recipe.json account="Account 2" --plan
-mm-harness run recipe.json account="Account 2"
+mm-harness run recipe.json timeout_ms=20000 --plan
+mm-harness run recipe.json timeout_ms=20000
 ```
 
 Use the shared wallet setup recipe on either Mobile or Extension. `auto`
@@ -76,24 +77,53 @@ fixture. Secret values are redacted from commands and evidence. Visible imports
 default to MetaMetrics off and skip Mobile's optional interests; password terms
 are required and always accepted by the action.
 
+### Retained-memory measurements
+
+Budget failures retain their samples and limits in a private JSON report linked
+from the failed node's error. Inspect that report before attributing growth or
+changing a budget; it is supporting evidence, not a passing measurement.
+
+Use `performance.navigation-memory` for one screen in an unlocked Extension.
+Choose its current route/marker, sample count, and growth bounds before running:
+
+```sh
+mm-harness run performance.navigation-memory \
+  'screen_hash=#/settings' screen_test_id=settings-tab-bar-grouped --hud hide
+```
+
+`performance.navigation-memory-suite` retains the full eight-screen audit,
+detached-DOM check, and idle-control comparison. A one-screen slope does not
+prove those broader claims. Check the suite's reference markers against the
+tested build before running it.
+
 ### Extension Perps release recipes
 
 Discover these identifiers with `run --list --adapter extension --json` and
 inspect the exact graph with `run <id> --describe --adapter extension --json`:
 
+Market/activity filters, visible consistency, funds previews, order-form cases,
+live order journeys, watchlist and source-dev snapshot consistency are owned by the
+[Perps team library](https://github.com/MetaMask/experimental-metamask-recipe-perps).
+Register the library checkout to discover and compose those unchanged names:
+
+```sh
+export RECIPE_LIBRARY_PATH="perps=/path/to/experimental-metamask-recipe-perps"
+mm-harness run perps.release-market-filters --describe --adapter extension --json
+```
+
 | Behavior | Canonical recipe |
 | --- | --- |
 | 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` |
-| Long/Short and Market/Limit entry controls | `perps.release-order-entry` |
-| Amount, leverage, keyboard, auto-close, and TP/SL validation | `perps.release-order-validation` |
+| Long/Short and Market/Limit entry controls | `perps.release-order-entry case=configuration` |
+| Amount, leverage, keyboard, auto-close, and TP/SL validation | `perps.release-order-entry case=validation` |
 | Official-build rendered market/activity consistency | `perps.release-visible-consistency` |
-| Favorite persistence and cleanup | `perps.release-watchlist` |
+| Favorite add/remove persistence and observed-baseline restoration | `perps.release-watchlist` |
 | Hook-backed controller snapshot consistency | `perps.source-dev-snapshot-consistency` |
 
 The source-development snapshot recipe is compatibility evidence only and must
@@ -102,11 +132,22 @@ Extension-scoped because their semantic actions are not shared release
 capabilities. Keep ticket-specific orchestration task-local and compose these
 identifiers with `call` instead of copying their graphs.
 
-Order-entry and order-validation callers must supply a market with no existing
+Watchlist proof requires a visible market-bound favorite baseline before any
+toggle. Unknown is not false. Restoration is verified on the audited Extension
+runtime; the audited Mobile reader cannot establish that baseline, so it must
+stop before mutation rather than infer identity from unrelated market text.
+
+The order-form recipe is in the registered Perps team library. Both cases require a market with no existing
 position; the product exposes Modify/Close instead of New Long/Short for an
-already-open market. Source-development snapshot callers may opt into a
+already-open market. Validation prices and leverage must match the selected
+market's current rules; the examples are not universal defaults. Give each
+composed case a distinct `capture_path`.
+Source-development snapshot callers may opt into a
 positive `minimum_changed_market_count`; the default does not require a price
 tick, while typed-history and visible-activity agreement remain strict.
+Use the snapshot recipe's `history` object to bound existing record dates and
+`capture_path` to separate evidence when composing calls. Market sampling does
+not repeatedly fetch history.
 
 The two live recipes require explicit `confirm_live=true`. The trusted runner
 must also verify the exact consented funding request, preflight, release proof,
@@ -126,15 +167,56 @@ using a generic UI press invalidates the cached identity proof; a fresh visible
 `ensure_positions`, `ensure_orders`, and `teardown_state` only observe and assert
 state that already exists; their schemas reject creation and cleanup inputs.
 Extension does not expose `start_state`, readiness claims, multi-position
-background closure, or the mutating `runner.action-validation` recipe. Financial
+background closure. The former `runner.action-validation` is now a repository-only
+maintainer exercise at `scripts/qa/mobile-action-validation.recipe.json`, outside
+the installed catalog. It requires explicit disposable setup and reserved testnet
+account/market inputs; it is not a full action audit or a normal task recipe. Financial
 transitions must use an explicitly funded leaf action.
-The shared `perps.clean-market-testnet` convergence recipe is therefore Mobile-
-only: Extension discovery omits it and a direct Extension plan fails statically.
+The Perps team library owns `perps.clean-market-testnet` for Mobile and Core,
+not Extension. Register that library before discovery or execution.
+They require explicit `account`, `market` and `exclusive_testnet_market=true`.
+That confirmation does not reserve the market or authorize deleting someone
+else's trades. Plan first and execute only with actual task ownership.
 Planning or calling a recipe never weakens those gates.
 
+### Mobile advanced-order setup
+
+These recipes belong to the Perps team library. Register it once:
+
+```sh
+export RECIPE_LIBRARY_PATH="perps=/path/to/experimental-metamask-recipe-perps"
+```
+
+`perps.pro-order-setup` preserves existing orders, positions, and strategies by
+default. Its Scale, Chase, and TWAP placement callers inherit that policy.
+When a proof requires a clean testnet market, reserve the account/market and
+compose explicit setup with `trading_state=clean_selected_testnet_market`.
+This parameter never authorizes cleanup of another task's trades.
+
+`perps.scale-assert-orders` checks the complete market order count before
+capturing three visible rows. The generic `assert_output` action compares a
+prior node's structured field, for example `$.matchingCount` with `eq` and
+`{{params.orders}}`; it is not limited to command output. Count and visibility
+still need task-owned submission IDs to prove a specific ladder.
+
+### Fixed and Max quotes
+
+`swap-bridge.release-quote` uses one graph for both amount modes. It defaults to
+a fixed 0.0001 ETH-to-WETH quote on Ethereum with a 60-second transition budget.
+Max ignores `amount` and uses the selected asset's available balance. Neither
+mode submits a transaction.
+
+```sh
+mm-harness run swap-bridge.release-quote amount=0.0001
+mm-harness run swap-bridge.release-quote amount_mode=max
+```
+
+Set `capture_path` to a distinct filename when composing multiple quotes in
+one run. Pair, chain, asset identity, and timeout inputs remain explicit options.
+
 ### Extension submission boundary
 
-Extension currently exposes read-only Assets and Swap/Bridge evidence plus send
+Extension currently exposes non-submitting Assets and Swap/Bridge evidence plus send
 preparation/review, quote, Max, and slippage actions. It does not expose
 `metamask.assets.finish_send`, `metamask.swap_bridge.submit_transaction`, or
 generic `ui.activate_and_observe`. Those operations remain unavailable until a
@@ -178,12 +260,13 @@ as supporting stills.
 
 ### Perps loading lifecycle validation
 
-One platform-neutral recipe owns the reusable Perps lifecycle proof. The
-harness adapter supplies Android or iOS behavior; the graph and lifecycle
-parameters remain identical. Run it with an explicit device pin:
+The Mobile loading recipe shares one graph across Android and iOS. It requires
+the product's source-dev instrumentation; platform parity still needs live
+validation. Register the Perps team library, then pin the device:
 
 ```bash
 mm-harness run perps.performance \
+  --library perps=/path/to/experimental-metamask-recipe-perps \
   --device <android-serial-or-ios-udid> \
   account=<fixture-account-name> \
   content_variant=trending \
@@ -196,10 +279,10 @@ The Mobile recipe HUD is shown by default, including during performance
 validation. Use `--hud hide` only when a specific opaque/release proof requires
 an unobstructed product surface; do not hide it merely to collect timings.
 
-Supported lifecycle values are `navigate_return`, `cold_disk_cache`,
-`cold_no_cache`, `background_short`, `background_reconnect`, `account_switch`,
-and `network_switch`. The shared graph uses an existing fixture position and
-never fabricates exchange state inside the measurement. It proves native
+Declared lifecycle values are `navigate_return`, `cold_no_cache`,
+`background_short`, `background_reconnect`, `account_switch`, and
+`network_switch`. The graph requires an existing position or an account with
+no positions or orders; it never trades to create either prerequisite. It checks native
 visible content with `ui.wait_for`, captures production `[PerpsLoadProof]` and
 WebSocket milestones, and leaves detailed TTC/DFD to the app's Sentry traces.
 It never relabels Metro, fixture, or process-start duration as TTC.
@@ -207,6 +290,12 @@ The recipe does not label a checkout as main or candidate; pin and record the
 exact checkout commit externally, then use captured source milestones to verify
 which data path actually ran.
 
+Warm return and short resume require resident-content milestones. The other
+lifecycles also require live positions, orders and account streams. Each group
+shares one capture ending, with the lifecycle and content identity preserved.
+Cold preparation clears Perps disk/controller caches and disconnects its
+channels before capture; an explicit process restart begins the proof.
+
 Rules:
 
 - Validate with `--plan` before side effects.
@@ -237,8 +326,9 @@ Locators, labels, routes, and screen structure can legitimately change, so a
 failed recipe is not by itself evidence of either recipe drift or a product
 regression.
 
-1. Reproduce the failing node and compare it with authoritative acceptance
-   criteria, product contracts, or known-good evidence.
+1. Preserve the first failure and compare it with authoritative acceptance
+   criteria, product contracts, or known-good evidence. Reproduce only after
+   confirming the action is safe to repeat.
 2. Inspect the current product surface and resolved recipe source, then classify
    the cause as product regression, recipe drift, fixture/runtime drift, or
    harness defect.
@@ -268,6 +358,23 @@ If changing a value would violate the recipe's postcondition, keep it as a
 documented recipe invariant rather than a parameter. Add a shared action only
 when repeated direct access has a stable cross-task contract.
 
+Core actions construct isolated controllers. Pass account and network into
+each action; a separate initialization node cannot prepare the next process.
+Skip setup that does no work, while retaining the independent read assertions.
+Signing requires a non-empty fixture account name. Address-only inputs support
+reads; they must not silently choose the default signing account.
+
+The Perps team library's `perps.trading-lifecycle` combines the Core long market
+and limit examples. The harness retains read-only `perps.smoke` and
+`perps.snapshot` examples; trading policy belongs to the team library.
+It requires an explicit fixture account, market, and confirmation of exclusive
+testnet ownership. Initial assertions refuse non-flat state rather than clearing
+it. Failure-path cleanup is guarded by completed initial assertions and remains
+market-scoped, so it cannot safely share that account/market with another task.
+The limit branch uses the original 30%-below-mid offset; it must prove the order
+rests rather than assume it cannot fill. These trading paths still require live
+validation with a reserved funded testnet account.
+
 The protocol is authoritative:
 <https://farmslot.io/docs/reference/recipe-protocol-v1>.
 
@@ -307,7 +414,11 @@ mm-harness run onboarding.smoke --plan
 Use `--library wallet=/path/to/library` for one command. The alias is the
 source name; without one, the directory name is used. Resolution follows the
 explicit library order, then bundled MetaMask. Adapter-specific variants are
-selected deterministically from `recipes/<adapter>/<domain>/`. Legacy
+selected deterministically from `recipes/<adapter>/<domain>/`. Identical
+cross-adapter graphs live once in `recipes/shared/<domain>/`; an adapter-specific
+variant takes precedence. Both resolve as `<domain>.<recipe>`, without a platform
+or `shared` prefix. Keep domains below `core`, `extension`, `mobile`, or `shared`.
+Legacy
 `*.<adapter>.recipe.json` paths remain readable during migration, but new and
 migrated libraries use the adapter-first layout. A file cannot declare its
 adapter through both forms. Every run records the root recipe, exact resolved

package/docs/RELEASE-QA-CAPABILITY-MAP.md

@@ -22,8 +22,9 @@ and trusted SHA-256. mm-harness never discovers or downloads a release.
 
 For Extension, `runtime-launch` verifies the ZIP digest and manifest version,
 extracts it safely, records archive and tree provenance, copies the exact tree
-to an isolated runtime directory, resets only the selected Chrome profile, and
-launches without building or patching the checkout.
+to an isolated runtime directory, preserves the selected Chrome profile, and
+launches without building or patching the checkout. A profile reset requires
+explicit `--reset-profile`; an ordinary launch does not apply a wallet fixture.
 
 For Android, `runtime-launch` requires one physical-device serial, verifies the
 local APK digest, package ID, version name, and version code, installs it, and

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;
 }
@@ -498,6 +486,16 @@ function registerSignerHandlers(rootMessenger, childMessenger, account) {
  * @returns { controller, projectRoot, network, accountAddress, signerAddress }.
  */
 export async function getCoreControllerWithSigner(input) {
+  const requestedName = input.node?.account_name ?? input.node?.account;
+  if (requestedName !== undefined && (
+    typeof requestedName !== 'string' || !requestedName.trim() ||
+    /^0x[0-9a-fA-F]{40}$/u.test(requestedName.trim())
+  )) {
+    throw new Error(
+      'Core signing requires a non-empty fixture account name, not an address.\n' +
+      'Next: pass account=<reserved-fixture-name>; use addresses only for read-only actions.',
+    );
+  }
   const base = await getCoreController(input);
   const { controller, messenger: childMessenger, rootMessenger, accountAddress } = base;
   if (!rootMessenger || !childMessenger) {
@@ -580,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';
@@ -593,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 ?? '');
 }
 
@@ -636,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 : {};
@@ -645,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,21 +14,11 @@ import {
   optionalParam,
 } from './_controller.mjs';
 
-// core Cancel selected live Perps open orders on HyperLiquid testnet by driving
-// the headless PerpsController.cancelOrders() through the full signing/provider
-// path (Slice 2). Mirrors close_positions.mjs: read open orders → cancel the
-// selected subset via the controller → verify the selected orders are gone.
-//
-// cancelOrders() resolves the concrete orders to cancel via the ACTIVE provider's
-// getOpenOrders() (PerpsController wires getOpenOrders: () => this.getOpenOrders()
-// into the cancel context) and then batch-cancels by symbol. We pass the selected
-// symbols; with mode=all (no explicit market) we cancel every open order.
-
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function waitForOrdersAbsent(controller, accountAddress, symbols, timeoutMs) {
+async function waitForOrdersAbsent(controller, accountAddress, orderIds, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let orders = [];
   for (;;) {
@@ -32,7 +26,7 @@ async function waitForOrdersAbsent(controller, accountAddress, symbols, timeoutM
       standalone: true,
       userAddress: accountAddress,
     });
-    const remaining = orders.filter((order) => symbols.includes(symbolForItem(order)));
+    const remaining = orders.filter((order) => orderIds.includes(order.orderId));
     if (remaining.length === 0) return orders;
     if (Date.now() >= deadline) return orders;
     await sleep(1000);
@@ -53,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,
   );
@@ -63,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) {
@@ -79,20 +89,29 @@ export async function closeOrders(input) {
     };
   }
 
-  // Cancel by the selected symbols. cancelOrders() filters the active provider's
-  // open orders to these symbols and batch-cancels them on the exchange.
-  const result = await controller.cancelOrders({ symbols });
+  const orderIds = matching.map((order) => order.orderId);
+  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) {
     throw controllerRejection({
       action: 'core cancelOrders',
-      detail: `${JSON.stringify(symbols)}: ${JSON.stringify(result)}`,
+      detail: `${JSON.stringify(orderIds)}: ${JSON.stringify(result)}`,
       code: failure,
     });
   }
 
-  const after = await waitForOrdersAbsent(controller, accountAddress, symbols, timeoutMs);
-  const stillOpen = after.filter((order) => symbols.includes(symbolForItem(order)));
+  const after = await waitForOrdersAbsent(controller, accountAddress, orderIds, timeoutMs);
+  const stillOpen = after.filter((order) => orderIds.includes(order.orderId));
   if (stillOpen.length > 0) {
     throw new Error(
       `Expected selected orders to cancel, but ${stillOpen.length} remain: ${JSON.stringify(result)}`,
@@ -109,6 +128,7 @@ export async function closeOrders(input) {
     successCount: result.successCount,
     failureCount: result.failureCount,
     symbols,
+    orderIds,
     results: result.results,
     orders: stillOpen.map(redactOrder),
     proofPath: 'perps-controller-cancelOrders',

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,