@deeeed/metamask-harness 0.51.8 → 0.51.9

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.51.9 - 2026-09-16
+
+### Changed
+
+- Recipe guidance states how Perps testnet account state is handled: on an account or market the task owns, the proof converges the positions and orders it needs (team library `perps.ensure-market-state` / `perps.clean-market-testnet`, or Mobile/Core `ensure_positions` / `ensure_orders` with `mode=all` for strays) instead of refusing on a pre-existing position; Extension `ensure_*` stay assertion-only. `help`, `docs/RECIPES.md`, and the Perps mutation action descriptions say so. Mainnet stays read-only.
+
 ## 0.51.8 - 2026-09-15
 
 ### Fixed

package/docs/RECIPES.md

@@ -192,10 +192,26 @@ transitions must use an explicitly funded leaf action.
 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.
+That confirmation does not reserve the market. Plan first and execute with
+actual task ownership; on an account or market the task owns, converge the
+state the proof needs (see Testnet account state) instead of refusing.
 Planning or calling a recipe never weakens those gates.
 
+### Testnet account state
+
+On a testnet account or market the task owns for its run (the slot's fixture
+account, or one reserved with `exclusive_testnet_market=true`), converging is an
+explicit, ownership-scoped setup choice, not a violation. Use the team library's
+`perps.ensure-market-state` or `perps.clean-market-testnet`, or on Mobile and
+Core `metamask.perps.ensure_positions` / `metamask.perps.ensure_orders`
+(`mode=all` for strays), record what was closed in the trace, then prove. A
+pre-existing position or order on an account the task owns is never a reason to
+block, skip, or refuse; a fixture that demands an empty account must converge
+rather than refuse. Extension `ensure_*` and `teardown_state` only assert, so
+converge there through an explicitly funded leaf action. Never broaden cleanup
+onto an account or market the task does not own; obtain an owned one instead
+of blocking. Mainnet is read-only.
+
 ### Mobile advanced-order setup
 
 These recipes belong to the Perps team library. Register it once:
@@ -389,9 +405,11 @@ 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.
+testnet ownership. Its initial assertions refuse non-flat state rather than
+clearing it, so a task proof converges its owned account first (see Testnet
+account state). 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.

package/library/manifests/core.action-manifest.json

@@ -1157,7 +1157,7 @@
       ]
     },
     "metamask.perps.close_positions": {
-      "description": "core Close selected live Perps positions on HyperLiquid testnet by driving the headless perps controller closePosition() through the full signing/provider path. Testnet only.",
+      "description": "core Close selected live Perps positions on HyperLiquid testnet by driving the headless perps controller closePosition() through the full signing/provider path. Testnet only. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -1427,7 +1427,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_positions": {
-      "description": "core Higher-level wrapper that reads selected positions, places or closes via the headless controller as needed, then asserts the final position state. Testnet only.",
+      "description": "core Higher-level wrapper that reads selected positions, places or closes via the headless controller as needed, then asserts the final position state. Testnet only. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -1580,7 +1580,7 @@
       ]
     },
     "metamask.perps.close_orders": {
-      "description": "Core Perps cancellation selects current orders by market/side or mode=all, then dispatches and verifies those exact order IDs. Missing or duplicate selected IDs fail before dispatch. Requires authorized signing and task-owned selection; defaults to testnet.",
+      "description": "Core Perps cancellation selects current orders by market/side or mode=all, then dispatches and verifies those exact order IDs. Missing or duplicate selected IDs fail before dispatch. Requires authorized signing and task-owned selection; defaults to testnet. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -1914,7 +1914,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_orders": {
-      "description": "core Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested.Higher-level wrapper that reads selected orders, cancels when needed, then asserts final order state.",
+      "description": "core Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested.Higher-level wrapper that reads selected orders, cancels when needed, then asserts final order state. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {

package/library/manifests/extension.action-manifest.json

@@ -4018,7 +4018,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.close_orders": {
-      "description": "extension Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders.",
+      "description": "extension Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action. Mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -4595,7 +4595,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_positions": {
-      "description": "Read and assert the selected Extension Perps position state without creating or closing a position. Use an explicitly funded leaf action for any transition.",
+      "description": "Read and assert the selected Extension Perps position state without creating or closing a position. Use an explicitly funded leaf action for any transition. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action. Mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -4724,7 +4724,7 @@
       ]
     },
     "metamask.perps.ensure_orders": {
-      "description": "Read and assert the selected Extension Perps order state without creating or canceling an order. Use an explicitly funded leaf action for any transition.",
+      "description": "Read and assert the selected Extension Perps order state without creating or canceling an order. Use an explicitly funded leaf action for any transition. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action. Mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {

package/library/manifests/mobile.action-manifest.json

@@ -2395,7 +2395,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.close_positions": {
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Close selected live Perps positions. Use selector/mode params to close matching symbols or all positions.",
+      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Close selected live Perps positions. Use selector/mode params to close matching symbols or all positions. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2486,7 +2486,7 @@
       "execution_capabilities": ["app-mutation", "external-mutation"]
     },
     "metamask.perps.close_orders": {
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders.",
+      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2886,7 +2886,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_positions": {
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Higher-level wrapper that reads selected positions, closes or places when needed, then asserts final position state.",
+      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Higher-level wrapper that reads selected positions, closes or places when needed, then asserts final position state. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -3002,7 +3002,7 @@
       "execution_capabilities": ["app-mutation", "external-mutation"]
     },
     "metamask.perps.ensure_orders": {
-      "description": "mobile Converge selected testnet orders to open or absent, then independently assert the final state. Creating an open state uses a resting limit order.",
+      "description": "mobile Converge selected testnet orders to open or absent, then independently assert the final state. Creating an open state uses a resting limit order. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.51.8",
+  "version": "0.51.9",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"

package/site/assets/help-recipes.json

@@ -191,12 +191,15 @@
         "Performance: define a measured window, exclude setup, and compare equivalent builds, devices, and lifecycle conditions; action duration alone is not app latency.",
         {
           "text": "For Extension timing, inspect app.performance_capture/app.network_capture and the installed recipe-performance capture-extension-window.mjs helper before writing a collector. If LavaMoat blocks an observation API, capture its reference before initialization via Page.addScriptToEvaluateOnNewDocument during explicit setup, not inside the measured window. Keep domain predicates in the team recipe; see docs/RECIPES.md#extension-timing-observation.",
-          "adapters": ["extension"]
+          "adapters": [
+            "extension"
+          ]
         },
         "Retain samples and declared limits when a measurement fails. For memory growth, compare an equal-duration idle control before attributing it to navigation; do not raise the budget to make the run pass.",
         "Analytics: verify the collection destination and existing consent before capture. Changing participation or marketing consent requires operator approval and restoration of the prior settings; a recipe's hardcoded opt-in is not permission. Missing collection prerequisites are not missing product events.",
         "Flake risk: wait on observable state instead of sleeping, keep device and runtime identity explicit, and never overwrite a prior run's artifacts.",
-        "Mutation: require an independent state assertion and identity-bound receipt. Bind activity to that operation's accepted ID; an old row or nonzero count is insufficient. Opening and closing orders have different IDs. Schedule authorized cleanup in teardown, verify its result, and report any residue. Testnet cleanup must not cancel another task's orders or close its positions.",
+        "Mutation: require an independent state assertion and identity-bound receipt. Bind activity to that operation's accepted ID; an old row or nonzero count is insufficient. Opening and closing orders have different IDs. Schedule authorized cleanup in teardown, verify its result, and report any residue. Testnet cleanup closes what the task opened and never silently undoes another task's live proof on a reserved account or market.",
+        "Testnet account state: on a testnet account or market the task owns for its run (the slot's fixture account, or one reserved with exclusive_testnet_market=true), converging is an explicit, ownership-scoped setup choice, not a violation. Use the team library's perps.ensure-market-state or perps.clean-market-testnet, or on Mobile and Core metamask.perps.ensure_positions / metamask.perps.ensure_orders (mode=all for strays), record what was closed in the trace, then prove. A pre-existing position or order on an account the task owns is never a reason to block, skip, or refuse, and a fixture that demands an empty account must converge rather than refuse. Extension ensure_* and teardown_state only assert; converge there through an explicitly funded leaf action. Never broaden cleanup onto an account or market the task does not own; obtain an owned one instead of blocking. Mainnet is read-only.",
         {
           "text": "An accepted order can fill before the UI updates. Preserve its receipt even when the expected resting-order assertion fails; one empty read does not prove cleanup. Check the read API's cache and freshness options before adding polling. Reconcile returned margin against the pre-placement balance. A successful close does not turn the original failed proof into a pass.",
           "adapters": [