@zktx.io/sui-mcp 0.5.0

package/docs/WALLET_CONNECTION.md

@@ -0,0 +1,238 @@
+# Wallet Connection
+
+WalletConnect provides approved Sui mainnet account context and a transport for
+individual wallet requests. It is not login, proof of address ownership, custody, or standing permission to transact. Frontend behavior is defined in
+[Frontend Policy](FRONTEND_POLICY.md); tools are in [MCP Tools](MCP_TOOLS.md).
+
+## Connection and read account
+
+`session.create_wallet_connection` takes an intent: `connect`, `disconnect` or `manage` (the default). A connect-intent card automatically starts one pairing after the View confirms current state with its UI permission, unless a connection or operation already exists. Manage opens connection controls without starting pairing; Connect wallet starts it only after the user clicks. Disconnect opens target-specific confirmation when one connection is available; the user chooses Confirm disconnect or returns with Back. No model-facing call can disconnect or request a signature. Public saved reads never start pairing. QR data stays in UI metadata bound to the exact card, connection and revision; reopening a waiting card preserves that pairing.
+
+Sui MCP uses one wallet connection at a time across all clients sharing a
+data directory. That connection can approve several Sui mainnet addresses; other
+chains are not supported. The same connection rule controls displayed actions,
+restoration, SDK observations and atomic SQLite admission. An unexpired connected wallet, pending approval or pending disconnection
+prevents another pairing, including requests from different cards. A competing
+card retains its own permission and reports the existing connection; it does not
+inherit another card's QR or waiting controls. A failed connection attempt needs
+an explicit retry even if the other connection later ends. If multiple valid connections are saved, none is selected for account use,
+review preparation or signing. The Connect card shows each exact target for
+user-confirmed disconnection. After recorded disconnections leave one valid
+connection and no pending connection operation, that connection becomes usable;
+with none remaining, a new pairing is allowed. Terminal history alone does not
+block it. A failed disconnect remains unconfirmed in the wallet app; its SDK
+session cannot revive the failed product record.
+
+The backend validates accounts, Sui mainnet namespace, methods and expiry before
+recording a connection. A single wallet-approved account can become read context
+from an explicit connection; multiple approved accounts require an explicit
+selection. The active read account is stored in SQLite until changed or cleared.
+SDK restoration and status reads never undo a user clearing that context. The stored selection is separate from its eligibility as a default for current asset reads. Implicit asset reads require a usable current wallet connection for the selected address; disconnection, expiry, pending disconnection, multiple-connection conflict or unavailable wallet state removes that default. Tools with an `account` input may still read an explicit address; connected-account-only tools require connection/account selection or recovery of wallet availability. Explicit-address public reads and saved transaction/activity reads remain available. `session.get_interaction_status.assetReadAccount` supplies that default-account decision alongside `connections` and `walletAvailability`.
+
+| Connection state | Available behavior |
+| --- | --- |
+| Unsubmitted card | Automatic pairing for connect intent; manual Connect wallet for manage intent; address selection and target-specific disconnect when permitted |
+| Multiple valid saved connections | Resolve through target-specific disconnect; no new pairing, address use, review preparation or signature |
+| awaiting_approval | Same private QR and approval observation; Stop connecting |
+| connected | View approved accounts and expiry; a new card may select another operation |
+| rejected / failed / expired / stopped / disconnected | View the recorded outcome; new operations need a new card |
+
+`session.get_interaction_status` reports the last confirmed wallet-service observation and stored connections. SDK events and command checks apply review/request invalidation through the same database owner. An ordinary status read does not wait for a fresh SDK request, change the selected account or start a wallet operation. `walletObservation` identifies the local service run, observation order and check time; it is not proof of the wallet app's current screen or online status. See the [interaction API](MCP_TOOLS.md) for the response contract.
+
+An admitted disconnect is a pending card operation, distinct from the last
+confirmed connection state. The same connection cannot be selected for another
+operation while disconnection is pending. Cards and wait tools observe its
+stored completion or failure; a connected-session update is not completion of
+the disconnect. A restart does not replay an unfinished disconnect or restore
+that connection as usable. The wallet app may still retain the connection.
+
+If the SDK disconnect ends but its local completion write fails, current reads
+settle the operation once storage recovers. An available SDK with no such session
+confirms local disconnection; an unavailable SDK or retained session produces an
+unconfirmed failure and wallet-app guidance. Reading never repeats disconnect.
+Approval storage failure can also leave a connection in the wallet app. Local
+failure or expiry does not prove remote revocation; remove retained connections
+in the wallet app. No fixed cleanup period is promised, and an SDK session alone
+never restores product authority.
+
+Chat navigation and frame recreation are not transitions. Local stopping does
+not claim that a remote wallet dialog closed. A late approval cannot revive a
+stopped connection. An unavailable backend wallet service keeps ordinary reads
+available and makes connection cards unavailable with an explicit explanation.
+
+The product supplies its public WalletConnect project identifier without user
+configuration or an override. Shared Relay service limits can affect connection
+availability across installations. An initialization failure does not establish
+that the user omitted a setting or that a transaction failed. A failure to
+restore saved connections or subscribe to wallet changes disables wallet operations until the wallet service is recovered;
+it cannot leave signing available without account/chain change observation.
+Stored review, request and verified execution facts remain readable through
+session tools and cards as well as ordinary evidence tools. `walletAvailability`
+describes the backend wallet dependency; it is not connection approval or
+transaction authorization. An unavailable dependency does not erase a saved
+result or prove chain failure. Startup diagnostics contain safe failure stages,
+not the project ID, SDK error bodies or wallet credentials.
+
+The wallet SDK runs in a separate child process. The parent retains database
+authority, transaction verification, submission and chain-result observation.
+An unresponsive wallet service does not prevent ordinary reads or access to
+stored results. Normal startup is shown as initialization, not as a wallet
+rejection. No implicit asset account is offered until the current service run
+confirms a usable connection.
+
+There is no card or Settings control for restarting the connection service.
+If the service stops or a disconnection remains unresponsive, fully quit all
+apps using Sui MCP, then reopen them. Closing a non-owning app or only a
+window does not stop the shared backend; another open client may take over.
+Confirm the new service is available before starting a new wallet operation.
+This does not guarantee that a relay responds or that a connection is removed
+in your wallet app. Multiple saved connections are resolved through their
+individual Disconnect controls, not by assuming an app restart clears them.
+
+A new owner records interrupted connection approval as stopped and unconfirmed
+disconnection as failed. It does not repeat either request or restore their
+wallet authority. Already submitted transactions remain readable by their digest.
+Historical service-recovery cards retain their recorded outcomes; they grant
+no new restart input. See [setup troubleshooting](MCP_SETUP.md#wallet-connection-boundary).
+
+An interrupted wallet operation reports `progress.status: "unavailable"` and a
+bounded wait returns `waitOutcome: "unavailable"` with the recorded facts. It does
+not pretend that the operation completed or the wait timed out. A completed
+request returns its saved result immediately. The backend can still verify the
+known digest of an already submitted transaction without WalletConnect. No
+financial request is replayed when reading or recovering results.
+
+A failed disconnect means disconnection was not confirmed. Inspect the connection
+in your wallet app and remove it there if it remains listed. Local service
+recovery does not verify remote removal. A card for an earlier successful
+connection may show that the connection is now unavailable; that is not proof
+that its original pairing failed.
+
+Initialization is described neutrally. A pending card command shows that its
+response has not arrived yet; a pending disconnection can show the app-restart
+procedure without declaring a timeout or failure. These notices do not diagnose a hung service,
+assert admission, or automatically send another command. The same-request check
+takes priority when a signing request's delivery is uncertain. Review messages
+preserve whether preparation was invalidated by wallet selection, a requested
+disconnect, multiple-connection conflict, or service loss. Historical messages
+retain their original cause.
+
+## Transaction approval
+
+A default address is qualified by the connection through which it was selected.
+If that connection ends and another connection approves the same address,
+choose Use address in the remaining connection's card before using it as the
+default or preparing a new review. The saved address remains readable history.
+A restored connection with the same ID retains its selection; a cleared or
+source-less selection is never inferred from matching addresses. New explicit
+connections that approve one address still select it automatically.
+
+The backend publishes the current usable connection and default-address
+eligibility. A recorded connection whose expiry has passed is not an additional
+usable wallet, even before the next SDK observation updates its record.
+Recorded targets remain available for appropriate disconnection; they do not
+block the sole usable connection's address selection or review choices.
+
+A single available wallet/account is displayed without a selection dropdown.
+A permitted live Review card automatically prepares and renews verified conditions for that target. Multiple valid wallet connections block preparation and signing; resolve the conflict in Connect. Several approved addresses inside the single wallet require address selection there. A failed computation offers Retry review rather than repeating automatically. The explicit approval button selects the displayed transaction revision; automatic preparation never requests a signature. Backend
+account, connection, revision and material checks remain authoritative.
+
+An existing review keeps its original account binding. Preparing or updating it
+requires that account to be the selected read account as well as an approved
+account on the chosen connection. If read context changes from A to B, select A
+again to update the same review, or request a new review for B. The card explains
+the current selection restriction separately from saved review messages, which
+can record a preparation failure or connection change. A refused incompatible
+selection starts no preparation and records no failed review. Read context alone does not revoke already verified A signing
+evidence or alter an admitted request.
+
+Preparation execution and its stored outcome are separate. If execution has
+ended but both success and failure writes failed, the next current-state read
+records the failed update once storage recovers. It does not recompute evidence;
+another update requires an explicit user action. A still-running computation is
+not failed merely because its result is not yet available.
+
+Review cards display account-bound verified evidence. Only a current review,
+matching live wallet account and explicit user action may admit a signing
+request. The backend uses `sui_signTransaction` with the stored BCS transaction
+encoded as base64, checks the returned bytes' digest and signature against the
+admitted account, then submits once. No browser signer, sign-and-execute fallback
+or automatic retry is used. A wallet lacking that method cannot sign through
+this path. Actual compatibility requires that wallet's successful normal flow;
+namespace advertising alone does not prove it.
+
+The backend verifies the stored material and rechecks its exact identity,
+review revision, bytes and expiry in the admission transaction. A displayed
+signature choice cannot extend the quote's validity. If the material expires
+before admission, update the review; no signature request is sent. Once admitted,
+the transaction remains fixed and the saved signing deadline applies. Reading
+or recovering an admitted attempt does not require a fresh quote or send it again.
+
+Wallet account/chain selection changes and connection conflicts invalidate affected unadmitted review
+data and pending submission permission in the same connection-change transaction.
+If that write fails, wallet operations are disabled until service recovery; a late
+signature cannot continue under an unrecorded old permission.
+Before submission, an explicit user stop, an SDK connection change and a
+requested disconnect record distinct reasons. A disconnect request does not
+claim completed disconnection. The first terminal reason is retained.
+After submission, connection updates and disconnect requests do not stop
+independent chain observation, including a lookup that has not started yet.
+Only the explicit transaction `stop_waiting` action stops that observation;
+later connection events neither resume it nor extend its deadline. An explicit
+result read can still inspect the same digest. No event resends the transaction.
+Callbacks already dispatched to submit or read a transaction may still record
+verified facts and settle their own pending flags while the same DB owner is
+valid. Wallet failure alone does not end an SDK promise. Server shutdown, owner
+replacement and data-generation changes still reject stale continuations.
+
+A request records one of `awaiting_signature`, `submitting`,
+`awaiting_chain_result`, `stopped`, `request_failed`, `outcome_unknown`, or
+`completed`. Only completed requests contain a separately verified chain
+success/failure result. Timeout, wallet rejection and lost RPC replies do not
+prove chain failure. Result reads observe the same digest. Management requires
+an exact review session and attempt and cannot refresh or sign a new review.
+
+The stored `submitting` state already identifies an admitted submission attempt.
+It remains observable and protected during the original observation window even
+if the post-submission write fails. Observation can finish before the submission
+callback returns. A late callback cannot reopen a completed or unknown outcome,
+extend that window, or submit again. Actual pending callbacks continue to protect
+data replacement even after a result is recorded.
+
+## Ownership and persistence
+
+One backend owns a data directory and its WalletConnect SDK. Authenticated local
+clients share that owner. A second owner is refused even on another port.
+Private SDK connection/session keys reside in an OS-user-only store separate
+from public activity backup. Request history, pending messages and unknown
+resend namespaces are volatile. The SDK storage stays alive until the owner
+process exits; no unsupported complete in-process SDK disposal is assumed.
+
+A new owner preserves completed facts, expires old unsubmitted input, and marks
+interrupted requests outcome_unknown without replaying them. Known approved
+SDK sessions may be reconciled with existing connection records; abandoned
+pairings and financial requests are not replayed. An unknown outcome may later
+be resolved by reading the known transaction digest.
+
+Data replacement is refused while signature/submission callbacks or initial
+chain observation remain unsettled. Removing finished local records cannot
+cancel or reverse an on-chain transaction. Public export/import never restores
+card permissions, SDK secrets, private request authority or live pending work.
+Local data replacement does not revoke the wallet app's connection approval.
+If a connection is no longer present in the product database, remove it in the
+wallet app; see [local data setup](MCP_SETUP.md#local-data-format).
+
+## Balance forms in a swap review
+
+A wallet can hold tokens as coin objects, address balances, or both. The backend
+uses the supported adapter's SDK to construct the transaction and verifies the
+funding form present in the stored material. Review details identify whether gas
+uses SUI coin objects, address balance, or an address-balance reservation with
+coin objects. A reservation is a limit, not a completed debit.
+
+The selected account must fund both the swap and its gas. A positive total wallet
+balance does not by itself prove that a particular withdrawal is covered. Source
+read failures and unsupported funding are not reported as confirmed insufficient
+funds. Balances can change after review; simulation and successful connection do
+not guarantee that the wallet will accept or the chain will execute a transaction.
+Every signature still requires the user's explicit card action and wallet approval.

package/docs/golden-scenarios/BEHAVIOR_MATRIX.md

@@ -0,0 +1,166 @@
+# Behavior Golden Scenarios
+
+These scenarios document expected response classes for manual release review. They are not Claude, Codex, or Cursor execution results.
+
+For current-release intent evidence checks that compare user prompts, preferred tool paths, standard answer clauses, and manual client observations, see `docs/golden-scenarios/INTENT_EVIDENCE_MATRIX.md`.
+
+For the deterministic MCP replay contract behind Korean USD-denominated coverage, total, and shortfall questions, see `docs/golden-scenarios/INTENT_EVIDENCE_GOLDEN_ANSWERS.md`.
+
+Manual client runs should call `read.get_server_status` first and record the package version, `evidencePolicy.version`, and `implementedToolsCount` before running the question rows.
+
+## Current Release Intent Evidence Corpus
+
+These scenarios translate the internal intent corpus into English release-review prompts.
+
+Current-release intent evidence answers can answer evidence questions without creating route recommendations, payment support, portfolio plans, P&L, transaction material, or signing readiness. Account-bound DeepBook review has a separate local transaction-material build path that is not part of these intent evidence answer rows.
+
+For current asset reads, use the connection-qualified default from `assetReadAccount`, or an explicit Sui address supplied by the user. A stored active address alone is insufficient.
+
+`What is 10 SUI worth?`
+Class: `answer_only`.
+Use `read.get_deepbook_mid_price` with a disclosed DeepBook SUI quote pool such as `SUI_USDC`.
+Use `read.list_deepbook_pools` only when the pool is ambiguous.
+Expose DeepBook pool, mid price, quote asset, and `fetchedAt`.
+Do not present this as a global market price, route recommendation, settlement choice, or signing readiness.
+
+`If I sell 10 SUI, how many dollars do I get?`
+Class: `clarify_or_intent_evidence`.
+Do not quote until the user selects a registered DeepBook quote asset or pool, or asks for wallet-scoped USD-denominated intent evidence.
+If the user chooses a pool such as SUI/USDC, call `read.quote_deepbook_display_amount`.
+Expose source input, missing quote-token or pool choice, fiat cash-out boundary, and available intent-evidence path when account context exists.
+Do not silently choose USDC or USDT, infer inverse output-target quotes, use web/finance lookup for USDC/USD, assume the USDC/USD peg, or present fiat cash-out, final min-out, route quality, funding readiness, or signing readiness.
+
+`What can I sell?`
+Class: `wallet_asset_read`.
+Use active account context or explicit address, then call `read.classify_wallet_assets`.
+Expose returned zero/nonzero coin-balance classes, gas asset context, DeepBook token registry matches, and `uninspectedAssetClasses`.
+Do not treat staked, locked, DeepBook manager, LP, vault, NFT, object, unsupported, or unknown classes as zero balances or sellable candidates.
+
+`Sell DEEP for USDC.`
+Class: `clarify_or_quote_context`.
+Ask for a source amount before quoting.
+After source amount and pool are explicit, call `read.quote_deepbook_display_amount`.
+Use `read.classify_wallet_assets` only for scoped wallet context.
+Do not assume amount, choose a route, run inverse quotes, create a review session, or treat DeepBook manager inventory as spendable.
+
+`Make $1000.`
+Class: `intent_evidence_with_choices`.
+Use `read.list_settlement_asset_groups`, then `read.preview_intent_evidence` when active account or explicit address context is available.
+Ask only for choices returned by `responseSummary`.
+Do not silently choose USDC or USDT, treat USDC as fiat USD, choose source assets, rank routes, or prepare signing.
+
+`Can I cover a 1000 dollar payment?`
+Class: `intent_evidence_with_choices`.
+Use `read.list_settlement_asset_groups`, then `read.preview_intent_evidence` with `intentKind: "cover_payment_like_amount"`, `denomination: "dollar"`, and `requiredDisplayAmount: "1000"`.
+Expose `responseSummary`, settlement-asset coverage basis, settlement-asset shortfall when available, required user choices, and unsupported payment/signing boundaries.
+Do not silently choose USDC or USDT, claim fiat USD cash-out, route-dependent payment support, gas readiness, transaction building, or signing readiness.
+
+`Can I pay for this $1000 item?`
+Use the same `intent_evidence_with_choices` path as `Can I cover a 1000 dollar payment?`.
+Do not claim fiat USD cash-out, route-dependent payment support, gas completeness, transaction building, or signing readiness.
+
+`How much are my USD-denominated assets together?`
+Class: `intent_evidence_total_only`.
+Use `read.list_settlement_asset_groups`, then `read.preview_intent_evidence` with `intentKind: "summarize_settlement_asset_group_balance"` and `denomination: "dollar"`.
+Expose `responseSummary.conclusionKind: "current_settlement_asset_total"` and current display total when available.
+Do not invent a target amount, silently choose USDC or USDT, treat the total as fiat USD cash-out, recommend a route, claim payment readiness, produce transaction material, or imply signing readiness.
+
+`Which stablecoin-like asset is highest or lowest?`
+Class: `settlement_asset_group_parity`.
+Use `read.list_settlement_asset_groups`, then `read.summarize_settlement_asset_group_parity` with `denomination: "dollar"`.
+Expose `responseSummary.referenceAssetRole`, min/max/mean/median statistics, and unsupported boundaries.
+Do not treat the reference asset as settlement selection, fiat USD value, peg assumption, payment readiness, route recommendation, transaction material, or signing readiness.
+
+`What is the shortfall?`
+Class: `intent_evidence_with_context_or_clarify`.
+If a target amount was already established, use `read.preview_intent_evidence` with that amount and answer from `responseSummary`.
+If not, ask for the missing target amount.
+Do not guess the missing amount, silently choose a settlement token, choose source assets, rank routes, claim gas readiness, prepare signing, or produce transaction material.
+
+`Make it 100 SUI.`
+Class: `blocked_with_context`.
+Use `read.classify_wallet_assets` only for current coin context when active account or explicit address is available.
+Do not create a portfolio target, rebalance plan, source selection, route recommendation, or review session.
+
+`Keep 100 SUI and convert the rest.`
+Class: `blocked_with_context`.
+Use `read.classify_wallet_assets` only for current coin context when active account or explicit address is available.
+Do not infer gas reserve, sell source, route, reserve policy, transaction material, or signing readiness.
+
+`If USDC is short, sell another token to fill it.`
+Class: `intent_evidence_with_choices`.
+Use `read.preview_intent_evidence` with `targetAssetSymbol: "USDC"` and `targetAssetSelectionSource: "user_explicit"` when active account or explicit address context is available.
+Expose selected target shortfall, `selectedTarget.selectionSource`, settlement-asset candidate conversion evidence or quote-unavailable reasons, and required user choices.
+Do not set target provenance for an AI-inferred target. Do not auto-pick assets to sell, rank routes, merge non-group quote proceeds into coverage, treat uninspected assets as funding sources, or prepare signing.
+
+## General Behavior Scenarios
+
+`What is 1 SUI worth?`
+Class: `answer_only`.
+Call `read.get_deepbook_mid_price` with `poolKey: "SUI_USDC"` for Sui MCP verified context.
+Answer as DeepBook SUI/USDC mid price at `fetchedAt`, not as the global market price.
+Do not use external web data unless the user explicitly asks for non-product market context.
+Do not ask for a wallet or push a review session.
+
+`If I sell 10 SUI, how many dollars do I get?`
+Class: `clarify_or_intent_evidence`.
+Say Sui MCP cannot turn "dollars" into fiat USD or silently choose USDC/USDT.
+Ask whether the user wants a specific DeepBook USD-denominated quote token/pool or wallet-scoped settlement-asset-group evidence.
+If the user chooses SUI/USDC, answer as a DeepBook SUI/USDC quote at `fetchedAt`.
+Do not convert USDC to fiat USD cash-out, assume the USDC/USD peg, or use web/finance lookup unless the user explicitly asks for outside product market context.
+Do not present it as a global USD price, route recommendation, price-impact calculation, final min-out, funding readiness, or signing readiness.
+
+`How much do I have?`
+Class: `clarify`.
+Check `session.get_interaction_status.assetReadAccount`. If no usable default is available, ask for a Sui address for tools that accept `account`. Open Connect only when the user requests connection.
+
+`Connect my wallet.`
+Class: `tool_wait`.
+Call `session.create_wallet_connection` with `intent: connect` and present the internal Connect card. Its authenticated View starts one pairing after checking current state; the ordinary tool call or wait does not. Read or wait using its cardId. A connection is account context, not transaction approval or login.
+Use `session.get_interaction_status.assetReadAccount` before announcing a usable default address. Resolve `connectionConflict` through user-confirmed targeted disconnection; never pick a wallet silently.
+On `timed_out`, say the wallet connection is still pending, not failed.
+
+`I want to buy $10 worth of SUI.`
+Class: `present_options`.
+Do not claim a supported buy flow or provide investment advice.
+Explain that dollar-denominated intent needs a supported stablecoin and amount unit.
+Offer read-only DeepBook quote options and disclose that signing remains blocked.
+
+`Sell a little.`
+Class: `clarify`.
+Ask for a concrete amount and provide examples.
+Do not map vague quantity words to a fixed percent.
+
+`Sell half.`
+Class: `clarify`.
+Explain that balance-relative swap amounts are unsupported and ask for an explicit source amount. Do not promise a spendable-balance calculation or start pairing to resolve that unsupported input.
+
+`5`
+Class: `clarify`.
+Ask which unit the user means: SUI, another asset, or a USD-denominated amount.
+If they mean dollars or stablecoins, use settlement-asset-group evidence before asking for a specific token.
+
+`Keep it from getting expensive.`
+Class: `clarify`.
+Ask for a price/slippage limit or explain the default only when a supported action flow applies.
+
+`Is this transaction safe?`
+Class: `redirect_unsupported`.
+Do not guarantee safety.
+Summarize concrete review facts or say a review is blocked/unavailable.
+
+`Tell me when the price drops.`
+Class: `redirect_unsupported`.
+Say alerts are unsupported and offer a one-time read.
+
+`Let's buy Bitcoin too.`
+Class: `redirect_unsupported`.
+Say only Sui mainnet surfaces are exposed.
+
+`What happened to the thing from before?`
+Class: `clarify`.
+Ask for the `reviewSessionId` unless a recent-session feature exists.
+
+## Manual Client Results
+
+No client observations are recorded in this matrix. Release checks can record Claude, Codex, or Cursor observations in an ignored local result file and promote durable failures to `docs/golden-scenarios/INTENT_EVIDENCE_MATRIX.md`, product docs, tests, or code.

package/docs/golden-scenarios/INTENT_EVIDENCE_GOLDEN_ANSWERS.md

@@ -0,0 +1,161 @@
+# Intent Evidence Golden Answers
+
+This document records the expected answer reference for the deterministic intent-evidence replay scenarios. It is a release-review reference for AI clients, not a transcript of live Claude, Codex, Cursor, or other client runs.
+
+The deterministic source of truth is `test/fixtures/intentEvidenceScenarios.ts`.
+
+It owns:
+
+- exact prompts;
+- MCP tool path;
+- tool input;
+- expected evidence fields;
+- forbidden claims.
+
+Korean prompt text is stored there with Unicode escapes. That keeps repo-visible test prose in English while the Korean dollar-word alias remains covered by tests.
+
+## Required Status Check
+
+Before judging any client answer, call `read.get_server_status` and record these fields:
+
+| Field | Required meaning |
+| --- | --- |
+| `packageName` | The client is connected to the expected Sui MCP package. |
+| `version` | The package build under observation. |
+| `evidencePolicy.version` | The evidence policy version used for the answer. |
+| `network` | Must be `mainnet`. |
+| `implementedToolsCount` | The server-provided implemented tool count; do not hand-count tools. |
+
+If the status call is missing `evidencePolicy.version`, the observation is not valid release evidence.
+
+## Deterministic Replay Scenarios
+
+Each row uses this tool path:
+
+1. `read.get_server_status`
+2. `read.list_settlement_asset_groups`
+3. `read.preview_intent_evidence`
+
+`korean_dollar_payment_coverage`
+Category: Korean USD-denominated payment coverage.
+Input: `intentKind: "cover_payment_like_amount"`, Korean dollar alias, and `requiredDisplayAmount: "1000"`.
+Expected status: `responseSummary.conclusionKind: "covered_by_settlement_asset_balance"`.
+Answer shape: say the current settlement-asset wallet coin-balance snapshot covers the requested display amount. Ask only for `responseSummary.requiredUserChoices`.
+
+`korean_dollar_balance_total`
+Category: Korean USD-denominated balance total.
+Input: `intentKind: "summarize_settlement_asset_group_balance"` with Korean dollar alias.
+Expected status: `responseSummary.conclusionKind: "current_settlement_asset_total"`.
+Answer shape: report the current settlement-asset total only. Do not invent a payment target or settlement token.
+
+`korean_dollar_shortfall_with_prior_target`
+Category: Korean USD-denominated shortfall with a prior target amount.
+Input: `intentKind: "cover_payment_like_amount"`, Korean dollar alias, and `requiredDisplayAmount: "1000"` from prior conversation context.
+Expected status: `responseSummary.conclusionKind: "shortfall_in_settlement_asset_balance"`.
+Answer shape: report `responseSummary.shortfallDisplayAmount` as the settlement-asset shortfall. Ask only for `responseSummary.requiredUserChoices`.
+
+`quote_detour_shortfall_guard`
+Category: USD-denominated payment coverage after extra SUI/NS quote calls.
+Input: `read.preview_intent_evidence` for a 1000 dollar target, then separate SUI/USDC and NS/USDC quote calls.
+Expected status: `responseSummary.currentDisplayAmount: "278.890119"` and `responseSummary.shortfallDisplayAmount: "721.109881"`.
+
+Allowed conclusion:
+Use only the `responseSummary` result:
+
+- current settlement-asset amount `278.890119`;
+- required amount `1000`;
+- settlement-asset shortfall `721.109881`.
+
+Forbidden conclusions:
+
+- Do not conclude that other assets were considered.
+- Do not conclude that everything can be converted.
+- Do not conclude that quote outputs can be combined.
+- Do not conclude that the account is still short after adding quote outputs.
+- Do not use `569.01226` or another quote-combined amount as the shortfall.
+
+Required evidence fields:
+
+- `responseSummary.answerCompleteness.requiredAnswerFields`
+- `responseSummary.doNotCallQuoteToolsForThisQuestion`
+- `responseSummary.separateQuoteOutputs`
+- `quantitySemantics.doNotCombineWithPaymentAnswer`
+- `userAnswerUse.followUp.answerFields: ["responseSummary"]`
+
+Answer shape: use `responseSummary` for the current amount and shortfall. Treat the SUI/NS quote outputs as separate price estimates because the required evidence fields say they are not used for the payment amount or shortfall amount.
+
+`explicit_usdc_shortfall`
+Category: user-explicit selected target shortfall.
+Input: `intentKind: "cover_payment_like_amount"`, `denomination: "dollar"`, established `requiredDisplayAmount`, `targetAssetSymbol: "USDC"`, and `targetAssetSelectionSource: "user_explicit"` or `"prior_user_explicit_context"`.
+Expected status: `responseEvidence.mode: "selected_target_context"` and `selectedTarget.selectionSource` matches the input source.
+Answer shape: distinguish `selectedTarget.shortfallDisplayAmount` from the settlement-asset aggregate shortfall. Ask only for returned `requiredUserChoices`.
+
+## Required Evidence Fields
+
+For these settlement-asset answers without a selected target settlement asset, `responseEvidence.mode` must be `settlement_asset_only`.
+
+`responseEvidence.primaryEvidenceFields` must be exactly:
+
+- `responseSummary`
+
+The user-facing response should use `responseSummary` only. Other packet fields may be source or diagnostic evidence, but they must not become a settlement-token choice, a route, or signing readiness.
+
+When the response includes `userAnswerUse`, `userAnswerUse.answerFields` is the response-local copy of this answer path.
+
+Selected-target answers are allowed only when the user explicitly selected the target settlement asset.
+
+For selected-target answers, use the fields listed in `userAnswerUse.answerFields`, including `responseSummary`, `selectedTarget`, `candidateConversions`, and `requiredUserChoices`.
+
+Direct pool quote evidence is part of a selected-target answer only when the same response lists `direct_pool_quote_evidence` in `responseEvidence.supportedResponseClaims` and `direct_pool_quote_evidence_for_user_selected_target` in `userAnswerUse.canAnswer`.
+
+`targetAssetSymbol` without `targetAssetSelectionSource` must fail or remain unselected.
+
+Clients must not use `targetAssetSelectionSource` for an AI-inferred target.
+
+Separate quote tool results from SUI, WAL, RWA, or other non-group assets must not be counted as payment coverage or shortfall evidence.
+
+## Standard Clauses
+
+Use equivalent wording with the same meaning:
+
+| Evidence result | Standard clause |
+| --- | --- |
+| `responseSummary.conclusionKind: "covered_by_settlement_asset_balance"` | Based on the current settlement-asset wallet coin-balance snapshot, the requested display amount is covered. |
+| `responseSummary.conclusionKind: "shortfall_in_settlement_asset_balance"` | Based on the current settlement-asset wallet coin-balance snapshot, the settlement-asset shortfall is `<shortfallDisplayAmount>`. |
+| `responseSummary.conclusionKind: "current_settlement_asset_total"` | The current settlement-asset wallet coin-balance total is `<currentDisplayAmount>` display units. |
+| Any settlement-asset answer | This is pre-transaction intent evidence only, not payment execution readiness, gas readiness, transaction building, or signing readiness. |
+| Returned `responseSummary.requiredUserChoices` | Ask only for the missing decisions returned by the evidence report. |
+
+## Forbidden Claims
+
+Client answers for these rows must not claim or imply:
+
+- USDC, USDT, or any other settlement-token selection unless the user selected that target asset.
+- USDC equals fiat USD or a fiat USD cash-out estimate.
+- Best route, route quality, route-dependent payment support, or venue comparison.
+- Gas readiness, payment execution readiness, transaction building, signing data, or signing readiness.
+- P&L, profit, tax, performance, or cost-basis calculations.
+- Source-asset selection for filling a shortfall.
+
+## Manual Client Observation
+
+Manual Claude/Codex observations should reuse the deterministic replay scenarios and record whether the client followed the expected answer reference. A release observation row should include:
+
+| Field | Required content |
+| --- | --- |
+| Client | Client name and version when available. |
+| Date | Observation date. |
+| Status fields | `packageName`, `version`, `evidencePolicy.version`, `network`, and `implementedToolsCount`. |
+| Prompt | The exact prompt category or fixture scenario id. |
+| Tool path used | Tools called by the client, in order. |
+| Response evidence | Whether the answer used only `responseEvidence.primaryEvidenceFields` for the conclusion. |
+| Forbidden claim check | Any settlement-token, fiat USD, route, P&L, transaction-building, or signing-readiness leakage. |
+| Follow-up | Whether the fix belongs in evidence report fields, MCP/API docs, agent behavior docs, or the client prompt. |
+
+Do not treat a manual observation as stronger than the deterministic MCP replay test. Manual observations show client behavior for a specific client build; the replay test guards the product evidence policy.
+
+Current manual observation status: no Claude, Codex, Cursor, or other AI-client observation rows are recorded for this deterministic policy yet.
+
+Until such rows are recorded, release review should treat manual client behavior as unobserved.
+
+The deterministic MCP replay test can still satisfy the product evidence policy. A separate manual observation is needed only before claiming that a specific AI client build followed the policy unaided.