@deeeed/metamask-harness 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 0.24.0 - 2026-07-30
+
+### Added
+
+- `metamask.perps.edit_order` drives `PerpsController.editOrder()` on the `core` adapter, verifying that a known resting target was replaced by one new order matching the requested attributes rather than trusting the acknowledgement.
+- `expect_error` asserts that a `core` perps operation is REJECTED with a given typed error instead of succeeding. The comparison is exact and code-only: actions attach the controller's error code as data, and a rejection carrying no code does NOT match, so an unrelated failure whose message happens to mention the code cannot satisfy a refusal proof. Exposed only on the five actions with a real controller-refusal boundary (`place_order`, `edit_order`, `update_position_tpsl`, `close_orders`, `close_positions`); on read, assert and ensure actions every throw is argument validation or a postcondition failure, which can carry no code, so the parameter is not advertised there.
+- `expect_count` on `metamask.perps.assert_orders` and `assert_positions` pins the exact number of matching items, which the default at-least-one check cannot do.
+- Attached TP/SL assertions verify that one parent links to live children of the requested TP/SL family, market, side and trigger price, and record those attributes in evidence.
+- Relative price and size inputs on `place_order` and `update_position_tpsl`: `take_profit_offset_pct` / `stop_loss_offset_pct` derive a price from live mid, and `take_profit_fraction` / `stop_loss_fraction` derive a size from the live position, rounded to the market's size precision. An absolute value still wins when supplied.
+- `notional` on `edit_order` derives a size when the resting order cannot be read.
+
+### Fixed
+
+- Optional params left unset by a recipe template arrive as an empty string; the `core` perps actions treated that as a supplied value, so an order with no TP/SL could be rejected as having an invalid TP/SL size. Empty now means absent and falls through to a supplied alias.
+- Batch order-cancel and position-close failures retain the failed controller result instead of being flattened, including partial failures.
+- `edit_order` accepts only resting `GTC` and `ALO` replacements; `IOC` cannot satisfy its resting-order postcondition.
+- `place_order` no longer discards a `time_in_force` or a stray trigger price on a non-trigger placement. Dropping a field the caller set is wrong on its own terms, and it also hid the controller's refusal of it; both are forwarded and the controller decides.
+- `place_order` and `edit_order` reject a blank or unrecognised `side` instead of treating anything that is not `short` as a long, which let an unset template place a real order on an assumed side.
+
+## 0.23.1 - 2026-07-29
+
+### Fixed
+
+- Mobile recipe evidence no longer triggers Metro Fast Refresh: harness-managed Metro ignores checkout-local `temp` artifacts, and screenshot scratch files stay outside the watched project.
+
 ## 0.23.0 - 2026-07-28
 
 ### Added

package/adapters/manifest.json

@@ -42,6 +42,14 @@
       "inputs": "--target --port --log --pid-file [--workers] [--clear]",
       "outputs": "Metro PID/launch metadata and redirected log; exit 0/1/2"
     },
+    {
+      "id": "mobile/metro-config",
+      "entry": "adapters/mobile/metro-config.cjs",
+      "kind": "module",
+      "purpose": "Preserve the product Metro config while excluding harness-owned checkout temp artifacts.",
+      "inputs": "base Metro config; env MM_HARNESS_METRO_PROJECT_ROOT, MM_HARNESS_METRO_BASE_CONFIG",
+      "outputs": "merged Metro config with resolver.blockList for <projectRoot>/temp"
+    },
     {
       "id": "mobile/stop-metro",
       "entry": "adapters/mobile/stop-metro.sh",

package/adapters/mobile/metro-config.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+const fs = require('node:fs');
+const { createRequire } = require('node:module');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function appendBlockList(blockList, pattern) {
+  if (Array.isArray(blockList)) return [...blockList, pattern];
+  return blockList instanceof RegExp ? [blockList, pattern] : [pattern];
+}
+
+function blockListFlags(blockList) {
+  const first = Array.isArray(blockList) ? blockList[0] : blockList;
+  return first instanceof RegExp ? first.flags : '';
+}
+
+function resolveExpoConfigLoader(projectRoot) {
+  const requireFromProject = createRequire(path.join(projectRoot, 'package.json'));
+  let requireUtilsPath;
+  try {
+    requireUtilsPath = requireFromProject.resolve('@expo/require-utils');
+  } catch (error) {
+    if (error?.code !== 'MODULE_NOT_FOUND') throw error;
+    return null;
+  }
+  const { loadModuleSync } = requireFromProject(requireUtilsPath);
+  return typeof loadModuleSync === 'function' ? loadModuleSync : null;
+}
+
+async function loadProductConfig(configPath, baseConfig, projectRoot) {
+  let loaded;
+  const expoConfigLoader = resolveExpoConfigLoader(projectRoot);
+  if (expoConfigLoader) {
+    loaded = expoConfigLoader(configPath);
+  } else {
+    try {
+      loaded = require(configPath);
+    } catch (error) {
+      if (error?.code !== 'ERR_REQUIRE_ESM') throw error;
+      loaded = await import(pathToFileURL(configPath).href);
+    }
+  }
+
+  const moduleValue = await loaded;
+  const exported =
+    moduleValue?.__esModule ||
+    moduleValue?.[Symbol.toStringTag] === 'Module'
+      ? moduleValue.default
+      : moduleValue;
+  const config = await exported;
+  return typeof config === 'function' ? config(baseConfig) : config;
+}
+
+module.exports = async function harnessMetroConfig(baseConfig) {
+  const projectRoot = path.resolve(
+    process.env.MM_HARNESS_METRO_PROJECT_ROOT || process.cwd(),
+  );
+  const productConfigPath = path.resolve(
+    process.env.MM_HARNESS_METRO_BASE_CONFIG ||
+      path.join(projectRoot, 'metro.config.js'),
+  );
+  let productConfig = baseConfig;
+  if (fs.existsSync(productConfigPath)) {
+    productConfig = await loadProductConfig(
+      productConfigPath,
+      baseConfig,
+      projectRoot,
+    );
+  }
+
+  const tempRoot = path.join(projectRoot, 'temp');
+  const existingBlockList =
+    productConfig.resolver?.blockList ?? baseConfig.resolver?.blockList;
+  const tempPattern = new RegExp(
+    `^${escapeRegExp(tempRoot)}(?:${escapeRegExp(path.sep)}|$)`,
+    blockListFlags(existingBlockList),
+  );
+  return {
+    ...productConfig,
+    resolver: {
+      ...productConfig.resolver,
+      blockList: appendBlockList(
+        existingBlockList,
+        tempPattern,
+      ),
+    },
+  };
+};

package/adapters/mobile/start-metro.sh

@@ -49,6 +49,7 @@ fi
 # only ever inspect or signal a Metro listening on $PORT.
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/metro-listener.sh"
+MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID} MM_HARNESS_METRO_PROJECT_ROOT EXPO_OVERRIDE_METRO_CONFIG"
 
 # RECIPE_RUNTIME_DIR (relative, validated) makes runtime state per-run so jobs
 # sharing one checkout do not collide on metro.log / metro.pid / metro.tmux.
@@ -98,6 +99,13 @@ set +a
 export EXPO_NO_TYPESCRIPT_SETUP=1
 export WATCHER_PORT="$(printf '%q' "$PORT")" METRO_PORT="$(printf '%q' "$PORT")"
 export METRO_MAX_WORKERS="$(printf '%q' "$METRO_WORKERS")"
+export MM_HARNESS_METRO_PROJECT_ROOT="$(printf '%q' "$TARGET")"
+if [ -n "\${EXPO_OVERRIDE_METRO_CONFIG:-}" ]; then
+  export MM_HARNESS_METRO_BASE_CONFIG="\$EXPO_OVERRIDE_METRO_CONFIG"
+else
+  export MM_HARNESS_METRO_BASE_CONFIG=$(printf '%q' "$TARGET/metro.config.js")
+fi
+export EXPO_OVERRIDE_METRO_CONFIG="$(printf '%q' "$SCRIPT_DIR/metro-config.cjs")"
 yarn expo start --port "$(printf '%q' "$PORT")"$clear_flag 2>&1 | tee -a "$(printf '%q' "$LOG_FILE")"
 EOF
   chmod +x "$runner"
@@ -184,6 +192,9 @@ if ! start_metro_tmux; then
     export EXPO_NO_TYPESCRIPT_SETUP=1
     export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
     export METRO_MAX_WORKERS="${METRO_WORKERS}"
+    export MM_HARNESS_METRO_PROJECT_ROOT="$TARGET"
+    export MM_HARNESS_METRO_BASE_CONFIG="${EXPO_OVERRIDE_METRO_CONFIG:-$TARGET/metro.config.js}"
+    export EXPO_OVERRIDE_METRO_CONFIG="$SCRIPT_DIR/metro-config.cjs"
     launcher_args=(
       --target "$TARGET"
       --port "$PORT"

package/dist/recipe-security.js

@@ -9,7 +9,14 @@ const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.read_orders",
   "metamask.perps.read_account",
   "metamask.perps.assert_positions",
-  "metamask.perps.assert_orders"
+  "metamask.perps.assert_orders",
+  // Both only read the collector's JSONL and export/assert over it.
+  // `metamask.analytics.start_capture` is deliberately NOT listed: it spawns a
+  // detached HTTP listener, so it falls through to 'arbitrary-code' and needs
+  // explicit approval. Classifying a process-spawning action as read-only to
+  // save an approval prompt would defeat the point of this allowlist.
+  "metamask.analytics.read_events",
+  "metamask.analytics.assert_events"
 ]);
 const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.setup",
@@ -18,16 +25,20 @@ const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.close_positions",
   "metamask.perps.close_orders",
   "metamask.perps.place_order",
+  "metamask.perps.edit_order",
   "metamask.perps.update_position_tpsl",
   "metamask.perps.ensure_positions",
   "metamask.perps.ensure_orders",
   "metamask.perps.start_state",
-  "metamask.perps.teardown_state"
+  "metamask.perps.teardown_state",
+  // Flips MetaMetrics consent in the wallet, so app-mutation, not read-only.
+  "metamask.analytics.set_consent"
 ]);
 const EXTERNAL_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.close_positions",
   "metamask.perps.close_orders",
   "metamask.perps.place_order",
+  "metamask.perps.edit_order",
   "metamask.perps.update_position_tpsl",
   "metamask.perps.ensure_positions",
   "metamask.perps.ensure_orders",

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

@@ -618,6 +618,60 @@ export function redactPosition(position) {
   };
 }
 
+/**
+ * Wrap a controller rejection so its typed code survives as data.
+ *
+ * `expect_error` used to match by substring against the message, which meant a
+ * message that merely mentioned a code — or contained a longer code with the
+ * expected one as a prefix — matched wrongly. Carrying the code on the error
+ * lets the comparison be exact.
+ *
+ * @param params - Rejection details.
+ * @param params.action - Action name, for the message.
+ * @param params.detail - Human context for the message.
+ * @param params.code - The controller's typed error code.
+ * @returns An error carrying `perpsErrorCode`.
+ */
+export function controllerRejection(params) {
+  const { action, detail, code } = params;
+  const error = new Error(`${action} was rejected: ${code}${detail ? ` (${detail})` : ''}`);
+  error.perpsErrorCode = code;
+  return error;
+}
+
+/**
+ * Read an optional node param, treating an unset template as absent.
+ *
+ * Recipes are static JSON, so an optional parameter that a caller leaves at its
+ * default arrives as an empty string rather than being omitted. Passing that
+ * through as a set-but-empty value is how a plain order ends up carrying an
+ * empty TP/SL size, which the controller then rejects as invalid. Whitespace is
+ * trimmed for the same reason.
+ *
+ * @param node - The recipe node.
+ * @param snake - snake_case param name.
+ * @param camel - camelCase alias.
+ * @returns The value as a string, or undefined when the node did not set it.
+ */
+export function optionalParam(node, snake, camel) {
+  const normalize = (value) => {
+    if (value === undefined || value === null) {
+      return undefined;
+    }
+    const text = String(value).trim();
+    return text.length === 0 ? undefined : text;
+  };
+  return normalize(node?.[snake]) ?? normalize(node?.[camel]);
+}
+
+export function optionalBooleanParam(node, snake, camel) {
+  const value = optionalParam(node, snake, camel);
+  if (value === undefined) return undefined;
+  if (value.toLowerCase() === 'true') return true;
+  if (value.toLowerCase() === 'false') return false;
+  throw new Error(`${snake} must be true or false; got ${value}.`);
+}
+
 export function redactOrder(order) {
   return {
     coin: order.coin ?? order.symbol ?? null,
@@ -691,16 +745,95 @@ async function disconnectController(exitCode) {
   }
 }
 
+/**
+ * Read the rejection a node expects, if any.
+ *
+ * @param input - Adapter input (node.expect_error / node.expectError).
+ * @returns The expected error token, or undefined when the node expects success.
+ */
+function expectedErrorFor(input) {
+  const node = input?.node ?? {};
+  for (const key of ['expect_error', 'expectError']) {
+    const value = node[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Run a Core perps adapter, honouring an expected rejection.
+ *
+ * Most nodes assert that an operation succeeds. A controller's refusals are part
+ * of its contract too — that a partial size below the asset's precision, or a
+ * TP/SL linkage the venue cannot express, is rejected with a typed error and
+ * before any side effect. Without `expect_error` those can only be proven by a
+ * bespoke script, because every action here throws on failure.
+ *
+ * With `expect_error` set, a throw whose message carries the expected token is
+ * the passing outcome: the rejection is written out as evidence and the process
+ * exits 0. Anything else fails — a different error, or the operation succeeding
+ * when it should have been refused. The success case is checked explicitly
+ * rather than left to fall through, so a contract that silently stops rejecting
+ * is caught rather than reported as a pass.
+ *
+ * Actions surface a controller's `{ success: false, error }` result by throwing
+ * with the code in the message (see place_order.mjs), so a substring match
+ * covers both that shape and a genuine throw.
+ *
+ * When the param is absent this is byte-identical to the previous behaviour.
+ *
+ * @param callback - The adapter body, receiving the loaded input.
+ */
 export async function runAdapter(callback) {
   const input = await loadInput();
+  const expectedError = expectedErrorFor(input);
   let exitCode = 0;
   try {
-    await writeOutput(input, await callback(input));
+    const output = await callback(input);
+    if (expectedError) {
+      // Not thrown: a rejection asserted here must not be satisfied by the
+      // message this branch would itself produce.
+      exitCode = 1;
+      process.stderr.write(
+        `[core/perps] ${input.action} expected rejection ${expectedError}, but it succeeded.\n`,
+      );
+    } else {
+      await writeOutput(input, output);
+    }
   } catch (error) {
-    exitCode = 1;
-    // Surface the failure; still tear down so a half-open WebSocket from a
-    // failed write doesn't leave the process wedged open.
-    process.stderr.write(`[core/perps] adapter failed: ${fmtError(error)}\n`);
+    const message = error?.message ?? String(error);
+    // A typed proof requires the code as data. Matching on the message was a
+    // weaker check wearing the same name: an adapter's own error, or any text
+    // that merely mentioned a code, could satisfy it. Only a rejection the
+    // action tagged with the controller's code counts, compared exactly — so a
+    // proof cannot pass on a failure the controller never issued.
+    const code = error?.perpsErrorCode;
+    if (expectedError && code === expectedError) {
+      await writeOutput(input, {
+        action: input.action,
+        source: 'expect_error',
+        rejected: true,
+        matched: true,
+        matchedOn: 'code',
+        expectedError,
+        actualErrorCode: code,
+        actualError: message,
+      });
+    } else {
+      exitCode = 1;
+      if (expectedError) {
+        process.stderr.write(
+          code === undefined
+            ? `[core/perps] ${input.action} expected rejection ${expectedError}, but the failure carries no controller error code — it did not come from the controller.\n`
+            : `[core/perps] ${input.action} expected rejection ${expectedError}, but the controller rejected with ${code}.\n`,
+        );
+      }
+      // Surface the failure; still tear down so a half-open WebSocket from a
+      // failed write doesn't leave the process wedged open.
+      process.stderr.write(`[core/perps] adapter failed: ${fmtError(error)}\n`);
+    }
   } finally {
     await disconnectController(exitCode);
   }

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

@@ -1,6 +1,7 @@
 import {
   getCoreController,
   isDirectRun,
+  optionalParam,
   redactOrder,
   requireExplicitSelection,
   runAdapter,
@@ -19,6 +20,123 @@ import {
 // expect_size (proves a partial TP/SL quantity). They use the controller's own
 // field names (triggerOrderType, triggerPrice, orderType, reduceOnly, size).
 
+// A count proves only how many orders exist, never that one is the linked TP/SL
+// the caller asked for: two unrelated orders satisfy `expect_count: 2` just as
+// well as a parent and its child. So assert the LINK the controller exposes —
+// the parent's own takeProfitOrderId / stopLossOrderId — and that the id it
+// names is really resting as a reduce-only trigger.
+export function expectedChildLinks(input) {
+  const node = input.node ?? {};
+  const wanted = [];
+  const truthy = (value) =>
+    value !== undefined && value !== null && String(value).trim() !== '' &&
+    String(value).toLowerCase() !== 'false';
+  if (truthy(optionalParam(node, 'expect_take_profit_child', 'expectTakeProfitChild'))) {
+    wanted.push({ label: 'take profit', idField: 'takeProfitOrderId' });
+  }
+  if (truthy(optionalParam(node, 'expect_stop_loss_child', 'expectStopLossChild'))) {
+    wanted.push({ label: 'stop loss', idField: 'stopLossOrderId' });
+  }
+  return wanted;
+}
+
+export function assertChildLinks(matching, allOrders, wanted) {
+  const resolved = [];
+  if (wanted.length === 0) return resolved;
+
+  const hasLink = (order, idField) =>
+    order[idField] !== undefined && String(order[idField]).trim() !== '';
+  const parent = matching.find((order) =>
+    wanted.every(({ idField }) => hasLink(order, idField)),
+  );
+  if (!parent) {
+    throw new Error(
+      `Expected one matching order to expose ${wanted.map(({ idField }) => idField).join(' and ')}, but none did. Matching orders: ${JSON.stringify(matching.map((order) => ({ id: order.orderId, takeProfitOrderId: order.takeProfitOrderId, stopLossOrderId: order.stopLossOrderId })))}.`,
+    );
+  }
+
+  const normalizedSide = (order) => {
+    const value = String(order.side ?? order.dir ?? '').toLowerCase();
+    if (value === 'buy' || value === 'b' || value.includes('long')) return 'buy';
+    if (value === 'sell' || value === 'a' || value.includes('short')) return 'sell';
+    return undefined;
+  };
+  const parentSymbol = parent.symbol ?? parent.coin;
+  const parentSide = normalizedSide(parent);
+
+  for (const { label, idField } of wanted) {
+    const isTakeProfit = idField === 'takeProfitOrderId';
+    const priceField = isTakeProfit ? 'takeProfitPrice' : 'stopLossPrice';
+    const triggerFamily = isTakeProfit ? 'take_profit_' : 'stop_';
+    const childId = String(parent[idField]);
+    const child = allOrders.find(
+      (order) => String(order.orderId ?? order.oid) === childId,
+    );
+    if (!child) {
+      throw new Error(
+        `Order ${parent.orderId} names ${idField}=${childId} as its ${label} child, but no such order is live — the child was dropped after being linked.`,
+      );
+    }
+    if (child.reduceOnly !== true) {
+      throw new Error(
+        `The ${label} child ${childId} is live but not reduce-only, so it would open exposure rather than close it.`,
+      );
+    }
+    if (child.isTrigger !== true) {
+      throw new Error(
+        `The ${label} child ${childId} is live but is not a trigger order, so it cannot fire as a ${label}.`,
+      );
+    }
+    const childType = String(child.triggerOrderType ?? '').toLowerCase();
+    if (!childType.startsWith(triggerFamily)) {
+      throw new Error(
+        `The ${label} child ${childId} has triggerOrderType=${JSON.stringify(child.triggerOrderType)}, expected the ${triggerFamily} family.`,
+      );
+    }
+    const childSymbol = child.symbol ?? child.coin;
+    if (parentSymbol === undefined || childSymbol !== parentSymbol) {
+      throw new Error(
+        `The ${label} child ${childId} is on ${childSymbol ?? 'an unknown market'}, expected ${parentSymbol ?? 'the parent market'}.`,
+      );
+    }
+    const childSide = normalizedSide(child);
+    if (
+      parentSide === undefined ||
+      childSide === undefined ||
+      childSide === parentSide
+    ) {
+      throw new Error(
+        `The ${label} child ${childId} has side=${child.side ?? child.dir ?? 'unknown'}, expected the opposite of parent side=${parent.side ?? parent.dir ?? 'unknown'}.`,
+      );
+    }
+    const parentPrice = parent[priceField];
+    const childPrice = child.triggerPrice ?? child.triggerPx;
+    if (
+      parentPrice === undefined ||
+      childPrice === undefined ||
+      Number(parentPrice) !== Number(childPrice)
+    ) {
+      throw new Error(
+        `The ${label} child ${childId} has triggerPrice=${JSON.stringify(childPrice)}, expected the parent's ${priceField}=${JSON.stringify(parentPrice)}.`,
+      );
+    }
+    resolved.push({
+      link: idField,
+      parentOrderId: String(parent.orderId ?? parent.oid),
+      childOrderId: childId,
+      child: {
+        symbol: childSymbol,
+        side: childSide,
+        triggerOrderType: child.triggerOrderType,
+        triggerPrice: childPrice,
+        size: child.size ?? child.sz,
+        reduceOnly: child.reduceOnly,
+      },
+    });
+  }
+  return resolved;
+}
+
 export function expectedOpen(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.assert_orders requires state=open or state=none.');
   const state = String(input.node.state).toLowerCase();
@@ -40,23 +158,42 @@ export function expectedOpen(input) {
  * @returns True when only trigger orders should be considered.
  */
 export function onlyTriggerOrders(input) {
-  const value = input.node?.only_trigger_orders ?? input.node?.onlyTriggerOrders;
+  const value = optionalParam(
+    input.node ?? {},
+    'only_trigger_orders',
+    'onlyTriggerOrders',
+  );
   return value === true || String(value).toLowerCase() === 'true';
 }
 
 export function expectedTriggerData(input) {
   const node = input.node ?? {};
+  const pick = (snake, camel) => {
+    const normalize = (value) =>
+      typeof value === 'string' && value.trim().length === 0
+        ? undefined
+        : value ?? undefined;
+    return normalize(node[snake]) ?? normalize(node[camel]);
+  };
   const expectations = {
-    triggerOrderType:
-      node.expect_trigger_order_type ?? node.expectTriggerOrderType,
-    triggerPrice: node.expect_trigger_price ?? node.expectTriggerPrice,
-    orderType: node.expect_execution ?? node.expectExecution,
-    reduceOnly: node.expect_reduce_only ?? node.expectReduceOnly,
-    size: node.expect_size ?? node.expectSize,
+    triggerOrderType: pick(
+      'expect_trigger_order_type',
+      'expectTriggerOrderType',
+    ),
+    triggerPrice: pick('expect_trigger_price', 'expectTriggerPrice'),
+    orderType: pick('expect_execution', 'expectExecution'),
+    reduceOnly: pick('expect_reduce_only', 'expectReduceOnly'),
+    size: pick('expect_size', 'expectSize'),
   };
+  // A blank expectation is an unset recipe template, not a demand that the
+  // value equal ''. Keeping it turned an unused param into an assertion against
+  // an empty string — which for a price compares as 0.
   return Object.fromEntries(
     Object.entries(expectations).filter(
-      ([, value]) => value !== undefined && value !== null,
+      ([, value]) =>
+        value !== undefined &&
+        value !== null &&
+        !(typeof value === 'string' && value.trim().length === 0),
     ),
   );
 }
@@ -103,8 +240,15 @@ export function assertTriggerData(orders, expectations) {
 export async function assertOrders(input, expectOpen = expectedOpen(input)) {
   requireExplicitSelection(input);
   const { controller, accountAddress, network } = await getCoreController(input);
-  const timeoutMs = Number(input.node?.timeout_ms ?? 0);
+  const timeoutMs = Number(
+    optionalParam(input.node ?? {}, 'timeout_ms', 'timeoutMs') ?? 0,
+  );
   const deadline = Date.now() + Math.max(0, timeoutMs);
+  const expectedCount = optionalParam(
+    input.node ?? {},
+    'expect_count',
+    'expectCount',
+  );
   let orders;
   let matching;
   while (true) {
@@ -118,7 +262,13 @@ export async function assertOrders(input, expectOpen = expectedOpen(input)) {
       // applied to an unrelated parent order resting alongside them.
       matching = matching.filter((order) => order.isTrigger === true);
     }
-    if (expectOpen ? matching.length > 0 : matching.length === 0) break;
+    // When an exact count is demanded, stopping at the first positive result
+    // reads a mid-replace moment as final: the previous order may not have been
+    // swept yet, or the new one not yet placed. Wait for the count itself.
+    const reached = expectedCount === undefined
+      ? matching.length > 0
+      : matching.length === Number(expectedCount);
+    if (expectOpen ? reached : matching.length === 0) break;
     if (Date.now() >= deadline) break;
     await new Promise((resolve) =>
       setTimeout(resolve, Math.min(500, Math.max(1, deadline - Date.now()))),
@@ -130,9 +280,20 @@ export async function assertOrders(input, expectOpen = expectedOpen(input)) {
     throw new Error('Expected at least one matching open Perps order, but found none.');
   }
 
+  // "at least one" cannot distinguish a clean replace from one that added a
+  // second order beside the first, so a caller can pin the exact count.
+  if (expectedCount !== undefined && matching.length !== Number(expectedCount)) {
+    throw new Error(
+      `Expected exactly ${expectedCount} matching open Perps order(s), but found ${matching.length}.`,
+    );
+  }
+
   const triggerExpectations = expectedTriggerData(input);
+  const childLinks = expectedChildLinks(input);
+  let resolvedChildLinks = [];
   if (expectOpen) {
     assertTriggerData(matching, triggerExpectations);
+    resolvedChildLinks = assertChildLinks(matching, orders, childLinks);
   }
   if (!expectOpen && hasOrder) {
     throw new Error(`Expected no matching open Perps orders, but found ${matching.length}.`);
@@ -146,7 +307,10 @@ export async function assertOrders(input, expectOpen = expectedOpen(input)) {
     expectedOpen: expectOpen,
     expectedTrigger:
       Object.keys(triggerExpectations).length === 0 ? null : triggerExpectations,
+    expectedChildLinks: childLinks.map((link) => link.idField),
+    resolvedChildLinks,
     matchingCount: matching.length,
+    expectedCount: expectedCount === undefined ? null : Number(expectedCount),
     orders: matching.map(redactOrder),
     proofPath: 'perps-controller-getOpenOrders',
   };

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

@@ -2,6 +2,7 @@ import {
   getCoreController,
   isDirectRun,
   redactPosition,
+  optionalParam,
   requireExplicitSelection,
   runAdapter,
   selectedItems,
@@ -22,8 +23,15 @@ export function expectedOpen(input) {
 export async function assertPositions(input, expectOpen = expectedOpen(input)) {
   requireExplicitSelection(input);
   const { controller, accountAddress, network } = await getCoreController(input);
-  const timeoutMs = Number(input.node?.timeout_ms ?? 0);
+  const timeoutMs = Number(
+    optionalParam(input.node ?? {}, 'timeout_ms', 'timeoutMs') ?? 0,
+  );
   const deadline = Date.now() + Math.max(0, timeoutMs);
+  const expectedCount = optionalParam(
+    input.node ?? {},
+    'expect_count',
+    'expectCount',
+  );
   let positions;
   let matching;
   while (true) {
@@ -32,7 +40,10 @@ export async function assertPositions(input, expectOpen = expectedOpen(input)) {
       userAddress: accountAddress,
     });
     matching = selectedItems(input, positions);
-    if (expectOpen ? matching.length > 0 : matching.length === 0) break;
+    const reached = expectedCount === undefined
+      ? matching.length > 0
+      : matching.length === Number(expectedCount);
+    if (expectOpen ? reached : matching.length === 0) break;
     if (Date.now() >= deadline) break;
     await new Promise((resolve) =>
       setTimeout(resolve, Math.min(500, Math.max(1, deadline - Date.now()))),
@@ -43,6 +54,12 @@ export async function assertPositions(input, expectOpen = expectedOpen(input)) {
   if (expectOpen && !hasPosition) {
     throw new Error('Expected at least one matching open Perps position, but found none.');
   }
+
+  if (expectedCount !== undefined && matching.length !== Number(expectedCount)) {
+    throw new Error(
+      `Expected exactly ${expectedCount} matching open Perps position(s), but found ${matching.length}.`,
+    );
+  }
   if (!expectOpen && hasPosition) {
     throw new Error(`Expected no matching open Perps positions, but found ${matching.length}.`);
   }
@@ -54,6 +71,7 @@ export async function assertPositions(input, expectOpen = expectedOpen(input)) {
     account: accountAddress,
     expectedOpen: expectOpen,
     matchingCount: matching.length,
+    expectedCount: expectedCount === undefined ? null : Number(expectedCount),
     positions: matching.map(redactPosition),
     proofPath: 'perps-controller-getPositions',
   };