@zktx.io/sui-mcp 0.7.0 → 0.8.1

package/docs/AGENT_BEHAVIOR.md

@@ -20,7 +20,7 @@ It is not the contributor rulebook and it is not enforcement. Development rules
 | Transaction material and execution | Verified supported swaps under user control | Stored mainnet material is used only after review and wallet approval. External proposals stay non-signable. Fiat cash-out, P&L, tax, cost-basis, route ranking and automatic settlement choice remain unsupported. |
 | Private-key custody, autonomous trading, fiat USD peg claims, and quote-only coverage or readiness claims | Unsupported safety and correctness boundary | Do not custody funds, hold private keys, or autonomously trade. Do not treat settlement assets as fiat USD, bank cash-out amounts, or peg guarantees. Do not turn quote-only conversion candidates into payment coverage, funding readiness, payment execution readiness, or signing readiness. |
 | Silent settlement-token selection and route ranking | Out of scope by current design | Do not silently choose USDC, USDT, or another settlement token for the user. Do not rank venues, choose routes, or make best-price recommendations. |
-| Other chains, autonomous trading, alerts, arbitrary Move calls, investment advice | Unsupported | Say the request is unsupported and redirect to available Sui mainnet read or review capabilities. |
+| Other-chain financial actions, autonomous trading, alerts, arbitrary Move calls, investment advice | Unsupported | Ethereum and Solana address management does not add other-chain asset reads, signing or execution. Say financial requests outside Sui are unsupported and redirect to available Sui mainnet read or review capabilities. |
 | Payment execution | Not a current capability | Intent evidence is separate from execution and does not build or execute payments. Do not describe payment execution as available. |
 | Lending, staking, relative balance actions | Unsupported | Do not describe executable actions for these categories as available product functionality. |
 
@@ -299,28 +299,62 @@ For common USD-denominated evidence questions:
 
 Describe an active wallet account as read context, not login, proof of
 ownership, standing signature approval or custody. Explicit public-address
-reads do not set that context. Account clearing does not disconnect a wallet.
-
-- For current asset reads with no address supplied by the user, read `session_get_interaction_status` and use `assetReadAccount.account` only when its status is `available`. If that default is unavailable and the requested tool accepts `account`, ask for a Sui address in chat. For `read_summarize_deepbook_account_inventory`, a typed address is unsupported: follow its connection/account-selection guidance instead. Do not copy a remembered or stored active address into an explicit argument to bypass this condition. Explicit user-provided addresses remain public reads without a connected wallet. A stored active account is not proof of a current connection.
-- If a different saved connection remains after disconnection, matching addresses do not carry the old default selection into it. The user can choose Use address in Connect. Use the returned `assetReadAccount`, not a count of recorded connections or an address match, to describe the default. A stored connection past its expiry is not a current usable choice or proof of remote removal.
-- Before opening a connection card, use the same status response's `connections`, `connectionConflict` when present, and `walletAvailability`. For a connect request, if the requested wallet is already connected, report that fact without opening another card. For a disconnect request, if no connection is recorded and wallet state is available, report that there is no connection to disconnect. Unavailable wallet state does not prove no connection. Do not ask for another pairing when one is pending.
+reads do not set that context. Account clearing does not disconnect a wallet. Activity tools with an optional
+`account` use saved read context when it exists. If it is absent or cleared, ask
+for an explicit Sui address for that read; do not ask for a wallet connection
+merely to restore a read filter.
+
+- For current asset reads with no address supplied by the user, read `session_get_interaction_status` and use `assetReadAccount.account` only when its status is `available`. If that default is unavailable and the requested tool accepts `account`, ask for a Sui address in chat. For `read_summarize_deepbook_account_inventory`, a typed address is unsupported: follow its current connection or read-address-clearing guidance instead. Do not copy a remembered or stored active address into an explicit argument to bypass this condition. Explicit user-provided addresses remain public reads without a connected wallet. A stored active account is not proof of a current connection.
+- One current connection supplies one fixed address per approved chain. Other wallet/account/address choices require disconnecting and reconnecting. Never propose Add connection or a default-account switch. A stored expired record is not proof of remote removal.
+- Before opening a connection card, read `session_get_interaction_status.connection`, `requestedChains`, `canDisconnect` and `walletAvailability`. An already connected wallet needs no additional pairing. Missing/unavailable observation does not prove absence. Pending work must use its existing card and operation, not another pairing.
 - Collect a missing account address or transaction hash in chat before opening an Account or Receipt card. Use a hash already supplied for the requested transaction; do not ask for it again. If a tool returns `input_required`, ask for its named input without retrying or claiming a failure. These cards have no input forms.
 
-For a connected-account-only read, use `session_get_interaction_status` to distinguish an unavailable wallet service, pending operations, and missing connection/selection. Report wallet-service unavailability and recovery guidance without proposing another pairing. If an operation is pending, use its existing cardId with the connection get/wait tools. Otherwise, explain that the user must request connection or account selection to continue; do not start that operation automatically.
-
-1. `account_get_active_account` reports the stored selection, with `source` and `setAt`. For current assets without a user-provided address, use `session_get_interaction_status.assetReadAccount` to check whether that selection is a usable default. If not, request an address only for tools that accept `account`; connected-account-only tools require the connection/account-selection flow. Do not infer current connection from the stored selection.
-2. An explicit connect/reconnect/disconnect/account replacement request opens an internal
-   Connect card with `session_open_wallet_connection_card`: use `intent: connect` for requested pairing, `intent: disconnect` for requested disconnection, and `intent: manage` for inspection or account selection. The model must not call app-only actions on the user's behalf.
-For "disconnect my wallet", when the wallet service is available and the target is connected, open `session_open_wallet_connection_card` with `intent: disconnect`. For one connected target the card shows Confirm disconnect or Back directly; Back only returns to the connection view; it does not submit Cancel review or disconnect. The card starts no pairing. Do not substitute the Settings action to clear the default read address, claim disconnection is unsupported merely because there is no direct model-facing disconnect tool, or equate disconnection with revoking onchain permissions. If disconnection is already pending, read or wait on that exact card instead of opening another operation.
+For a connected-account-only read, distinguish unavailable service, pending work,
+missing connection and explicit read-address clearing. Use the existing operation's
+cardId for get/wait while it is pending. Otherwise follow the user's connection
+request; do not initiate pairing automatically. Clearing read context is not a
+wallet disconnection or an invitation to bypass the read guard with a remembered address.
+
+1. `account_get_active_account` reports stored Sui read context, with its source
+   and time. Use `session_get_interaction_status.assetReadAccount` for current
+   asset eligibility. Tools with an `account` input accept a user-provided address;
+   connected-account-only tools do not. Stored context alone proves no connection.
+2. For an explicit connect request, open `session_open_wallet_connection_card`
+   with empty input. For disconnection, open `session_open_wallet_disconnection_card`.
+   The latter fixes the current exact session and shows Confirm disconnect and
+   Cancel. Cancel ends that card without disconnecting. Neither card can switch
+   purposes or act on a replacement session; another operation requires a new
+   user prompt and purpose card. The model must not call app-only actions for the
+   user. Disconnection does not revoke onchain permissions. If the requested wallet
+   is already connected, report current interaction status without another pairing.
+   A no-session-to-disconnect refusal needs no repeated status check or new Review.
+
+For "disconnect my wallet", open `session_open_wallet_disconnection_card` when the
+session is manageable. Confirm disconnect removes that exact session; Cancel ends
+only this card and leaves the session unchanged. The card starts no pairing.
+Do not substitute Clear saved read address or claim revocation of onchain permissions.
+If disconnection is already pending, read or wait on its exact card rather than
+creating another operation. For a connect request, if the requested wallet is already connected,
+report current interaction status without another pairing.
 
 3. `session_get_wallet_connection_card` and `session_wait_wallet_connection_card` use the
-   returned cardId. An unsubmitted card needs input; waiting does not create a
-   pairing. Pairing credentials/QR never belong in chat text.
-4. After connection/account selection, read `session_get_interaction_status` and confirm `assetReadAccount` is available before
-   stating which account is active. A connected session and active context are
-   separate facts, especially after clear or a multiple-account approval.
-5. A wait timeout does not prove failure, disconnection or a remote dialog's
-   cancellation. Report the actual stored outcome and pending user action.
+   returned cardId. The response's fixed `card` is separate from its current exact
+   `operation`, service availability and evaluation time. Waiting does not create a
+   pairing or follow a later operation. Without an admitted operation, waiting ends immediately. Pairing
+   credentials and QR data never belong in chat text.
+4. Settings selects networks for the next connection, default Sui. Only returned
+   requested networks are usable. A single distinct address binds automatically;
+   several addresses make that chain unavailable, with no chooser. Reconnect to
+   change the address or scope. Changing Settings does not modify current approval.
+5. A timeout does not prove failure, removal or cancellation of a wallet dialog.
+   Read the saved outcome and pending cleanup separately. An approval or
+   disconnection recorded as completed remains completed while cleanup is pending;
+   do not describe that result as stopped. SDK exit and late
+   response processing must not be called user cancellation.
+6. Explicit Cancel or Stop permanently ends that card's input. Cleanup cannot
+   restore it. Open a new card only for a new user request. Settings Clear saved
+   read address suppresses implicit read context across restart of the same
+   connection; it does not cancel a request, change fixed addresses or disconnect.
 
 Use `session_get_interaction_status` for bounded pending interactions. A Review
 status of `ready_for_wallet_review` is displayed as Ready for your review: the
@@ -331,7 +365,7 @@ success/failure. stopped, request_failed and outcome_unknown never imply chain
 failure or absence of execution. Use `session_get_execution_result` to read the
 known digest without resubmitting. `session_open_review_management` requires the
 exact reviewSessionId and attemptId and grants no new signing/refresh action.
-With one available wallet/account, the live Review card prepares and renews verified conditions automatically. The user inspects the PTB and amounts, then chooses Request wallet approval. Multiple valid connections must first be resolved through target-specific disconnection; several approved addresses belong to one connection. Failed preparation may need Retry review. Do not ask users to manually update after normal review-detail expiry; the card updates automatically when permitted. Receipt and completed Review show the actual transaction graph when private display metadata is available, followed by observed results. Additional facts are in Details; missing metadata means the graph is unavailable, not that the transaction has no inputs.
+A new Review fixes the current Sui account and connection before preparation. Its live card prepares and renews verified conditions automatically while that exact target qualifies. The user inspects the PTB and amounts, then chooses Request wallet approval. Use the exact fixed target. Reconnecting cannot retarget an existing Review; a replacement connection needs a new Review. Settings selects requested networks, default Sui; only a single valid returned address per chain is usable. Do not repeat already-determined chain/address choices in a card. Failed preparation may need Retry review. Do not ask users to manually update after normal review-detail expiry; the card updates automatically when permitted. Receipt and completed Review show the actual transaction graph when private display metadata is available, followed by observed results. Additional facts are in Details; missing metadata means the graph is unavailable, not that the transaction has no inputs.
 
 Frame recreation and chat navigation first reread the same DB state. Only a currently permitted live View can continue its backend-directed automatic preparation; completed, managed and public saved cards never restart it. SDK restoration does
 not replay a financial request or restore cleared read context.
@@ -339,13 +373,10 @@ not replay a financial request or restore cleared read context.
 Treat `walletAvailability` as the local connection service's state and
 `walletObservation` as its last confirmed observation, not the wallet app's live
 screen. `initializing` and `recovering` do not mean the user rejected anything.
-If `connectionConflict` is present, explain that several saved connections
-prevent using a wallet. On the user's request, open Connect/manage for them to
-confirm the connections they want to disconnect. Do not choose the first or
-most recent connection, change the default address or call `ui_act_card` for
-them. `allowedActions` describes permitted action types, not all buttons visible
-in a particular frame. In particular, a card without a target does not show
-Disconnect or Use account merely because a general action name was mentioned.
+One connection is current. Its fixed addresses, live grant and stored read context
+are separate facts. An old Review stays bound to its original account/connection;
+a replacement connection requires a new Review. `allowedActions` describes
+permitted app action types, never model authority or a mandatory visible button list.
 
 Connection-service recovery belongs to Settings. When the service is unavailable
 or a connection operation remains unresponsive, open
@@ -356,12 +387,12 @@ A new Settings card can explicitly supersede a startup still pending. Read the
 same operation's result; neither a new available run nor restart completion
 confirms an interrupted disconnect or a transaction result. Do not repeatedly
 request wallet approval or report recovery before its new run is observed.
-`manageableConnectionIds` names exact disconnect targets, not usable wallet
-choices. A terminal record may remain manageable when its SDK session is still
-present; do not describe the old failed operation as successful. If
+`canDisconnect` qualifies the current exact cleanup target, not financial usage.
+A terminal or older-data-generation record can remain disconnectable when its SDK
+session is still present or unusable; do not describe the old failed operation as successful. If
 `connectionReconciliationRequired` is true, explain that the service contains an
-unrecorded connection. Ask the user to remove that retained connection in the
-wallet app, then check its status. Settings/Troubleshooting can restart the
+unrecorded connection. New pairing and financial input are blocked. Ask the user
+to remove that retained connection in the wallet app, then check its status. Settings/Troubleshooting can restart the
 service to inspect it again; restarting does not approve an unrecorded session.
 Do not infer a free pairing slot from a failed or expired record.
 
@@ -370,7 +401,7 @@ procedure in the setup guide. All participating MCP connections must stop and th
 closing a peer or window can leave the owner alive. Follow the same parent
 stop/reopen procedure for stored endpoint or installation changes. Do not kill another app's processes.
 
-A failed `connectionAction: "disconnect"` means removal was not confirmed.
+A failed operation with `operation.action: "disconnect"` means removal was not confirmed.
 Direct the user to inspect/remove the retained connection in their wallet app.
 App restart does not prove remote revocation or cancel a transaction on Sui.
 Already submitted transactions keep their digest and remain readable; a new
@@ -484,26 +515,23 @@ For `read_list_review_activity`, `dataScope.recordCount` is the full matching lo
 
 For `read_get_review_session_detail`, transition rows with `isNoOp: true` are repeated lifecycle observations where the stored status did not change. Mention them only as audit details; do not count them as extra funnel progress.
 
-For local settings, local records or connection-service recovery, call `settings_create_local_settings_session` to open the internal Settings card. No external URL is returned. Explain Address for viewing assets, Local records, Troubleshooting or Advanced settings as needed and leave selection/confirmation to the user.
-
-For a backup, use the exact label Download backup in Local records. It prepares
-and verifies the snapshot internally and asks the app to save it in one user
-action. Do not instruct a separate Create backup step or confuse Download backup
-with Restore local records. If the actual download function is unsupported,
-the same file is saved once in the Sui MCP backup folder. Use the verified
-Backup saved result's Folder and File name for that local artifact. Do not
-describe that folder as the Host download destination. Suggested file name and Host acknowledgment do not establish where
-or whether a file was saved. Retry download is explicit and may create another
-copy after an unconfirmed earlier request. It uses the same snapshot only during
-its fixed transfer period; a new request after expiry or server restart captures
-current records. Cancel download does not delete a file already saved by the app.
-Use the same function-based product instructions across desktop apps. Missing
-advertisement is not proof of non-support, and timeout, cancellation or denial
-does not trigger local saving. Save a local copy is the explicit decision after
-an earlier possibly handled request. Retry save follows only a failure recorded as `not_published`; Check status settles uncertain saving or cleanup without
-another file effect. Report saved-file and cleanup facts separately.
-
-Ordinary MCP tools never apply a Settings change. Do not call `ui_act_card` or `ui_read_settings_file` as model work. Never request/paste raw backup bytes or card permissions in chat. Clear default address only changes read context, not wallet connections or admitted transactions. Endpoint changes require the shared parent to stop and reopen; a connection-service restart does not apply them. Report operation result, temporary-file cleanup and Host download acknowledgment as separate facts. A saved result is not proof that the Host saved a downloaded file. For restore validation refusal, let the user correct input or choose another file and prepare a new confirmation; reading or returning to a frame never applies it.
+For local settings, local records or connection-service recovery, call `settings_create_local_settings_session` to open the internal Settings card. No external URL is returned. Explain Address for viewing assets, Wallet networks, Local records, Troubleshooting or Advanced settings as needed and leave selection/confirmation to the user.
+
+For a backup, use Download backup in Settings → Local records. Do not request a
+separate Create backup step. Report only the returned saved-file and delivery
+facts: Host acknowledgment does not prove a saved file or its destination.
+A completed delivery card cannot retry. For a requested retry of a retained
+backup, open `settings_create_local_settings_session` with `backupDelivery` and
+the exact recorded operation/file identifiers; the user chooses one delivery or
+local-save attempt there. To check current delivery or cleanup, open the same
+tool with `operationStatus`. Do not ask the user to press a control in an ended
+card. Expired or invalidated backups require a new backup request. These three
+card purposes and file outcomes are defined in [Settings Tools](MCP_TOOLS.md#settings-tools).
+Use the same function-based instructions across apps. Neither missing capability
+advertisement nor timeout, denial or uncertain delivery means method-not-found.
+A local copy after a possibly handled delivery requires explicit user consent.
+
+Ordinary MCP tools never apply a Settings change. Do not call `ui_act_card` or `ui_read_settings_file` as model work. Never request/paste raw backup bytes or card permissions in chat. Clear saved read address belongs to Settings. It suppresses implicit Sui read context, not fixed wallet addresses or admitted transactions. Endpoint changes require the shared parent to stop and reopen; a connection-service restart does not apply them. Report operation result, temporary-file cleanup and Host download acknowledgment as separate facts. A saved result is not proof that the Host saved a downloaded file. For restore validation refusal, let the user correct input or choose another file and prepare a new confirmation; reading or returning to a frame never applies it.
 
 ## User Vocabulary
 
@@ -531,7 +559,7 @@ Do not silently turn vague words into amounts.
 | "Do you think I should buy this?" | Do not give investment advice. Offer price, liquidity, quote, and risk-input facts when supported. |
 | "Tell me when the price drops." | Say alerts are unsupported. Offer a one-time price or quote check. |
 | "Let's buy Bitcoin too." | Say this toolkit only exposes Sui mainnet surfaces. |
-| "Am I connected? / Am I logged in?" | Read `session_get_interaction_status.connections` with `walletAvailability`. When unavailable, report that connection state cannot be confirmed. The stored active account is not proof of a connection or login. Do not say the user is connected to DeepBook or signed in. |
+| "Am I connected? / Am I logged in?" | Read `session_get_interaction_status.connection` with `walletAvailability`. When unavailable, report that connection state cannot be confirmed. The stored active account is not proof of a connection or login. Do not say the user is connected to DeepBook or signed in. |
 | "Show my balances over time." | Held-balance history and P&L are not tool surfaces. Use `read_get_account_asset_timeline` only for stored raw net-flow bars over a UTC range; if `balanceStatus` is `unavailable_no_balance_anchor`, say held balances are unavailable. `read_summarize_wallet_assets` returns a current snapshot at `fetchedAt`. |
 | "How much profit did I make?" | Profit, tax, performance, and cost-basis calculations are not Sui MCP surfaces. Offer raw activity, balance snapshots, or quote evidence instead; do not provide a profit formula or hypothetical profit example. |
 | "Can you calculate my profit if I bought 10 SUI for 10 USDC?" | An assumed acquisition price does not change the boundary. P&L and accounting calculations are unsupported; do not provide a formula, worked example, tax treatment, or performance result. |

package/docs/LOCAL_DB_ARCHITECTURE.md

@@ -33,7 +33,7 @@ User-requested bounded transaction scans can store normalized facts only when a
 
 The default Sui mainnet gRPC and GraphQL endpoints are stored in the local SQLite settings table on first run.
 
-To inspect settings or change local data, ask for the internal Settings card. Ordinary MCP creates an unsubmitted card or reads settings; scoped app-only preparation/confirmation owns changes. No external page or Settings HTTP API remains.
+To inspect settings or change local data, ask for the internal Settings card. Ordinary MCP creates an unsubmitted card or reads settings; scoped app-only user input applies changes. Endpoint changes, data replacement and service restart require their concrete impact confirmation. No external page or Settings HTTP API exists.
 
 Endpoint changes apply after the MCP server restarts.
 
@@ -84,8 +84,7 @@ WAL mode can create companion files next to the main database, such as `sui-mcp.
 
 ## Tables
 
-- `accounts`: normalized Sui account addresses and first/last use timestamps.
-- `active_account_context`: a single-row read context. It can point to one active account or be cleared.
+- `accounts`: normalized `(chain_id, address)` identities and first/last use timestamps for supported mainnets.
 - `review_sessions`: review session header, current status, full action plan JSON, and materialized requested intent JSON when present.
 - `review_state_snapshots`: append-only account-bound `ReviewState` snapshots with status and reason columns for queryability.
 - `review_status_transitions`: append-only review lifecycle timing for funnel and review-timing analysis.
@@ -93,20 +92,21 @@ WAL mode can create companion files next to the main database, such as `sui-mcp.
 - `review_executions`: verified chain success/failure, keyed by `attempt_id` and bound to review session, account, plan and digest. Wallet rejection and uncertainty never create a chain failure row.
 - `external_activity_scans`: user-requested digest lookups, bounded account scans, or sent-function scans, including request window, endpoint host, chain identifier, continuation metadata, coverage signals, and internal scan-kind provenance.
 - `external_activity_transactions`: normalized Sui transaction facts linked to a known local account and the first/last scan that observed them. The optional detail JSON stores typed facts such as capped Move call targets, raw balance changes, object changes, event summaries, gas raw cost fields, execution errors, and truncation flags when GraphQL returns them. Each stored detail JSON value is capped at 64 KiB.
-- `local_settings`: allowlisted local settings. The current key set is `suiGrpcUrl` and `suiGraphqlUrl`, stored as JSON-encoded text and applied after restart.
+- `local_settings`: allowlisted local settings. The keys are `suiGrpcUrl`, `suiGraphqlUrl` and `walletConnectionChains`, stored as JSON. Endpoints apply after restart; requested networks apply only to new connections.
 - `coin_metadata_cache`: account-independent positive cache for Sui coin metadata used only to format wallet balance display amounts. Rows are keyed by normalized coin type and verified mainnet chain identifier, expire after 24 hours, and are excluded from local data export/import. Read or write failures for this cache block affected wallet unit reads with `metadata_cache_unavailable`; they are not reported as unavailable token decimals.
 
 The following live session tables hold runtime session state in the shared database so the shared backend can serve cards and sessions created by participating clients (see [Shared local server](#shared-local-server)):
 
 - `live_review_sessions`: the live review session record — status, bound
-  account, preparation/connection revision, current attempt reference,
+  account, preparation/Sui grant revision, current attempt reference,
   plan/review-state JSON, timestamps, revision and write-contract marker —
   keyed by session id.
 - `live_private_review_artifacts`: per-session private review evidence (the transaction-material handle, its digest commitment, and derived evidence), cascade-deleted with its review session.
 - `live_transaction_materials`: locally built unsigned transaction bytes stored as a BLOB behind a redacted handle, with a TTL; retained for the admitted request. Terminal request cleanup removes only material still owned by that revision, preserving newer preparation. Owner replacement deletes old private material while retaining immutable review and chain-result evidence.
-- `live_wallet_connections`: verified connection facts, private topic and callback state.
+- `live_wallet_connections`: connection history and at most one current row, enforced by nullable `current_slot` (NULL or 1) and UNIQUE. The row owns its admission `data_epoch`, private topic, immutable requested scope/`chainResults`, current grants, per-chain grant revisions and `read_address_cleared`. Fixed addresses use chain/address identity, not replaceable public account IDs.
+- `wallet_connection_operations`: at most one Connect/Disconnect operation per card (unique card_id), exact input, owner/run/data epoch, deadline, immutable result and pending SDK settlement. Operation identity is distinct from connection identity.
 - `live_read_cards`: public card state with private permission hash, scope, operation and CAS revision.
-- `settings_operations`: one draft/upload/preparation/admission/result identity per Settings card, with owner/data epoch, user-data revision, fingerprint and SDK supersession/checkpoint facts. A download stores its typed snapshot lifetime and per-attempt delivery reports in private `preparation_json`, separately from the immutable result. Updating delivery never reserializes a terminal `result_json`.
+- `settings_operations`: one draft/upload/preparation/admission/result identity per ordinary Settings card; read-only status and new backup-delivery cards reference that operation rather than duplicating it, with owner/data epoch, user-data revision, fingerprint and SDK supersession facts. Wallet network saving binds the selected and previously displayed networks, applies the setting and records its result atomically. A download stores its typed snapshot lifetime and per-attempt delivery reports in private `preparation_json`, separately from the immutable result. Updating delivery never reserializes a terminal `result_json`.
 - `settings_files`: private file identity, original operation, upload/export role, generated paths, lengths/hash, chunk reservation and seal/invalidation/cleanup state. `cleanup_operation_id` separately names the operation responsible for cleanup; replacement can transfer that responsibility without changing the file identity, public path or input eligibility.
 - `settings_control`: current data epoch/user-data revision, one final-operation slot, one file-I/O reservation and the SDK input block owner. These are semantic state/authority facts, not release-version counters.
 
@@ -116,7 +116,7 @@ Database columns use snake_case. MCP and HTTP JSON fields use camelCase, so the
 
 Table relationships:
 
-- `active_account_context.account_id` and `review_sessions.account_id` point to `accounts.id` when an account is present.
+- `accounts` has an id primary key and unique `(chain_id,address)`. Sui financial history references Sui account rows; another chain cannot become a Sui history or signer target. There is no mutable per-chain default selector.
 - `review_state_snapshots`, `review_status_transitions`, and `review_executions` point to `review_sessions.id` through `review_session_id` and can also point to `accounts.id` through `account_id`.
 - `external_activity_scans.account_id` points to `accounts.id`. It records which known local account the user-requested lookup or scan was scoped to.
 - `external_activity_transactions.account_id` points to `accounts.id`, and `first_scan_id` / `last_scan_id` point to `external_activity_scans.scan_id`. `known_sender_account_id` points to `accounts.id` only when the sender is also a known local account. Non-known party account addresses are not stored; normalized detail JSON keeps account-owner and event-sender fields only when they match the known local account.
@@ -144,24 +144,34 @@ never recreates that result from a callback after deleting it. Rollback
 preserves the prior data, permissions and admission state.
 The private `live_wallet_connections` service journal remains because replacing
 user data does not end SDK sessions. It cannot restore old card permissions or
-transaction authority and is not imported from a backup. Reset clears the
-default address; an imported default still needs its exact current connection
-ID and approved address. Outstanding connection SDK callbacks also block replacement.
+transaction authority and is not imported from a backup. Reset/import advance the data generation and restore no active wallet context.
+The retained connection is available for cleanup only; a new explicit connection
+is required for new financial input. Outstanding connection SDK callbacks also block replacement.
 
 User-data and wallet/request writers invalidate affected preparations and
-increment their card revision in the same transaction. The trigger and `settings_back`
+increment their active card revision in the same transaction; they never update a closed card. The trigger and `settings_back`
 reuse one SQL transition: a complete, sealed, non-invalidated upload belonging
 to that operation returns to sealed; other preparations return to draft. Old
 confirmations cannot apply. Backup checking and final I/O still verify physical content;
 a manifest alone is not proof of a valid file.
 
+Settings operation writes atomically invalidate an upload when its input is
+replaced, its draft changes away from import, or its use ends. The file keeps its
+identity and cleanup owner until physical cleanup succeeds. Back that preserves
+an eligible selected upload does not invalidate it. Filesystem cleanup runs after
+the stored effect/result; cleanup failure cannot repeat that effect or replace
+its immutable result.
+
 A `download_backup` admission consumes one card input and captures one local-data
 snapshot in the same SQLite transaction. The export role and exact generated
 `.settings-staging/<fileId>.download` namespace identify its private file; an
 export role or display name alone is insufficient. File bytes are not stored
 in operation JSON or nested in exported local data. Physical write, fsync, length and SHA checks
-finish before the snapshot becomes available. `result` is immutable preparation
-evidence; delivery reports have separate typed state and atomic attempt identity.
+finish before the snapshot becomes available; readiness does not end its card.
+Delivery attempts bind their owning card IDs in the existing journal. The card
+closes with its Host report, verified local publication, expiry, failure or Cancel.
+A new explicit delivery uses a new card, the exact same file and original TTL.
+Late reports update the domain journal without altering an ended card.
 
 An exact unsupported download report can atomically reserve final/file I/O and
 admit local publication of that same snapshot. An earlier possibly handled
@@ -177,8 +187,8 @@ is committed before exclusive same-volume hard-link publication. The source and
 target must name the recorded file and pass size/SHA checks before `saved` is
 committed. Existing destinations are never overwritten or removed. Private
 unlink follows that result and actual descriptor closure; the final file has
-no automatic expiry. Historical export path validation remains distinct from
-the private `.download` row identity.
+no automatic expiry. Private cleanup validates the exact `.download` row identity and never removes
+a user backup.
 
 Unknown file effects remain `saving`, retaining their source and reservations.
 A failed DB result write retains the ended physical outcome for settlement.
@@ -213,7 +223,7 @@ cleanup stays visible. Another operation's reservation is never released.
 An explicit same-result read may finish its cleanup or verify an existing
 published export, never regenerate a backup, repeat Host delivery, reapply data
 or replace an SDK run. Files/permissions/SDK credentials/private transaction
-material are excluded from public backups. Clearing the default address does
+material are excluded from public backups. Clearing the saved read address does
 not invalidate account-independent coin metadata or disconnect the wallet.
 
 Non-terminal review session expiry is recorded lazily when the session is read or mutated after its TTL. Review-session expiry has no background worker; private download retention uses the separate owner timer described above.
@@ -228,7 +238,11 @@ All state-writing MCP callers use this owner, including reads that save activity
 
 ### Read cards
 
-`live_read_cards` owns the card kind (account, receipt, chart, connect, review or settings), permission hash, backend owner, revision, original/accepted input, state/reason and saved result or scoped workflow operation reference. Business request status is not copied into a separate card state machine. Admission and result writes use conditional updates. Expiry is applied by the backend to unsubmitted input; a View timer only requests state. Frame recreation and chat navigation perform no close transition. The backend rejects late writes after local data replacement or owner changes, and recovery closes unfinished cards without repeating their source query.
+`live_read_cards` owns the card kind (account, receipt, chart, connect, disconnect, review or settings), permission hash, backend owner, revision, original/accepted input, state/reason and saved result or scoped workflow operation reference. Domain request state remains in its existing journal. At closure, a typed public
+result is saved atomically in live_read_cards.result_json. A database trigger
+rejects updates to closed rows. Domain callbacks skip them; closed reads return
+only that saved result, not current wallet or Settings projections. Connect and
+Disconnect terminal results exclude addresses and QR data. Admission and result writes use conditional updates. Expiry is applied by the backend to unsubmitted input; a View timer only requests state. Frame recreation and chat navigation perform no close transition. The backend rejects late writes after local data replacement or owner changes, and recovery closes unfinished cards without repeating their source query.
 
 The same record contains a model-safe result and, for receipts, separately validated UI-only input values and PTB display data. They are projections of one source read. They are not activity evidence or serialized signing material. Public saved resources exclude the private partition, and product backups exclude card records and permission hashes entirely.
 
@@ -279,48 +293,61 @@ perform a current session check. After digest, signer and mainnet verification,
 the parent performs a final session check before the synchronous submission CAS
 and dispatch. A later remote event is not presumed already known.
 
-Historical service-recovery results in `live_read_cards` remain readable;
-Connect accepts no new service-restart input. Parent recovery closes unfinished
-cards as `server_restarted`. SDK callback flags remain pending until actual
-child exit, while parent verification, submission and lookup flags remain until
-their own work ends. SDK readiness does not clear those independent guards.
-
-Initial SDK restoration considers the entire known connection set, including
-prior-owner records, before publishing current eligibility. Confirmed known
-connected records transfer to the new owner. Known terminal records with a
-present SDK session transfer management metadata without changing their outcome.
-Multiple known occupied connections are management targets, not usable wallet
-choices: `connectionConflict` is derived from the journal and current supervisor
-snapshot, with no additional table. Targeted disconnection remains
-available while new pairing, account use, review preparation and signing are
-blocked. The final submission transaction applies the same single-connection
-rule. Failed/stopped records and unknown SDK sessions do not restore authority.
-
-`active_account_context.wallet_id` preserves the connection through which the
-default address was selected. Current eligibility requires that exact ID and
-an approved address in the sole unexpired connection, with no pending connection
-operation. Missing source IDs remain valid historical/import data but require
-explicit selection before current default use. Eligibility is derived at the
-database evaluation time and published to cards as `usableConnectionId` and
-`assetReadAccount`; Views do not recount recorded connections. Stored status, disconnection outcomes and historical
-account records retain their separate meanings.
-The store reads the current run's private supervisor snapshot inside evaluation
-and immediate admission. Missing inspection does not mean an empty service.
-`manageableConnectionIds` names exact nonpending recorded disconnect targets,
-including known terminal records whose SDK sessions remain present. They are not
-usable account choices. `connectionReconciliationRequired: true` means a present
-SDK session has no journal target after ordinary registration/cleanup has ended;
-it blocks pairing, account use and unsubmitted signing until the user removes the
-retained connection in the wallet app and a complete current-run observation
-confirms absence. Settings can explicitly restart the service to inspect it
-again; restart alone does not resolve retained presence. Topics remain private. A pending registration
-is not reported as a reconciliation failure.
-
-An admission that changes connection eligibility or targets also publishes the
-owner's ready Connect/Review card revisions in that same transaction, after
-consuming its own input. A competing admission after the confirmation read
-therefore invalidates the earlier revision even before the SDK returns a QR or
-approval. Publication failure rolls back admission; no SDK operation starts.
+Connect accepts no service-restart input; Settings owns that operation. Parent
+recovery closes old card input and settles interrupted management outcomes without
+replaying effects. Pending SDK work is released only after actual child exit or
+confirmed acquisition of its private store by a new child. Parent verification,
+submission and lookup retain their independent completion guards.
+
+Recovery evaluates the one current slot against a fresh SDK run, including rows
+from a previous owner or data generation. Missing exact topics require the SDK
+session check before absence is recorded. Confirmed absence plus settled I/O
+releases occupancy; a stale connected row is not a permanent lock. A valid approved
+current-generation session can regain usage. Terminal, unusable or older-generation
+sessions receive cleanup ownership only, allowing exact Disconnect without granting
+financial authority. Immutable results and read-address suppression remain intact.
+Unknown SDK sessions are never adopted and block new pairing/financial inputs.
+
+Fixed identity is `(chainId, normalizedAddress)`. Import/reset account-ID reuse
+cannot retarget private connections. Public backups contain address history,
+records and settings, excluding selectors, private grants, operations and authority.
+Data replacement increments the generation and does not activate restored accounts.
+The retained private session can be disconnected without rewriting its old epoch.
+Settings Clear saved read address changes only `read_address_cleared`; reconciling
+the same session does not reset it. Another explicit connection supplies new facts.
+
+The store reads the current supervisor snapshot inside evaluation and atomic
+admission. Missing inspection is not an empty service. `canDisconnect` qualifies
+the current exact target, while `usableConnectionId` qualifies its transaction
+usage. Reconciliation notices reveal no private topic. Pending approval publication
+is not reported as an unexpected session. Current slot transfer, new connection,
+operation and card admission commit or roll back together before SDK I/O.
+
+Management admission publishes its exact operation and affected current card
+facts atomically. Scoped grant/impact revisions reject conflicting input,
+while an unrelated chain update does not reject a still-valid Sui target.
+Publication failure rolls back admission before SDK I/O. A reconnection cannot
+retarget a bound Review. Grant changes invalidate only the affected chain. Admission consumes the card's one operation. Its final result closes input;
+no later connection state can attach another effect.
+
+After an SDK approval arrives, its exact operation, connection, run and data
+generation own private topic retention before success publication. Retention
+grants cleanup ownership only. Connection approval, immutable chain results,
+address history and the operation's success result then commit in one transaction.
+A failed success publication rolls those public effects back without discarding
+the retained cleanup target. A duplicate response for the same completed operation
+and topic reads its saved result without changing addresses or read suppression.
+An unrelated topic is neither adopted nor disconnected.
+
+If cleanup ownership cannot yet be recorded, the workflow retains the private
+response and cleanup-only write in its existing per-operation pending writes.
+Its callback is not settled merely because the response arrived. Once retention
+and cleanup are resolved, database retries never repeat remote disconnection or
+retry failed success publication. Unconfirmed remote removal remains an exact
+cleanup target for explicit Disconnect; it is not successful absence or financial
+authority. Owner/run/data-generation changes fence the old callback. If no topic
+could be retained before the parent exits, recovery cannot infer its ownership:
+the resulting unrecorded session blocks new pairing and financial input.
 
 Service-loss authority revocation is retained against its SDK run and data
 generation until it commits. Current wallet-state reads retry that database
@@ -353,9 +380,9 @@ This is not availability during an unreadable database or a bypass of authority
 revocation failures.
 
 Connection facts and workflow maintenance have separate internal contracts.
-`readConnectionFacts(at)` collects recorded connections, current-run SDK presence,
+`readConnectionFacts(at)` collects the current recorded connection, current-run SDK presence,
 pending work and read-address provenance from one SQLite read snapshot. The
-shared selector and qualification projection compute eligibility from those
+shared qualification projection computes eligibility from those
 facts; they do not update requests, expire connections or repair callbacks.
 Settings general facts use this diagnostic path and stored counts, so another
 request's refused deadline write does not prevent opening or reading Settings.
@@ -408,7 +435,7 @@ running. `ReviewSession.preparationError`, stored in `live_review_sessions.prepa
 is a saved review message: it can record a failed preparation or invalidation
 caused by a wallet connection change. Its presence does not prove that a
 computation ran. The View labels it Earlier review message and keeps it distinct
-from current account-selection guidance and a command delivery failure. These
+from current wallet-availability guidance and a command delivery failure. These
 fields describe different facts; none grants action or retry authority.
 
 Signature admission independently checks the current material handle, expiry,
@@ -419,9 +446,9 @@ Revision-specific evidence validity does not remove session/account pending-work
 or data-replacement protections. Mandatory activity rows commit with the state;
 optional event-log failures do not roll back that commit or repeat an operation.
 
-Review preparation also checks the immutable bound account against current read
-context and the selected account before writing preparation state. The same pure
-account rule supplies evaluated choices. A selection mismatch is a current
+Review preparation checks the immutable bound account against the current fixed
+connection and explicit app input before writing preparation state. Saved read
+context suppression does not alter that target. A target mismatch is a current
 restriction, not a stored preparation error or an activity transition.
 
 Request interruption consumes both its internal origin and the request phase.
@@ -465,9 +492,12 @@ and public backup export also read recorded facts without advancing live
 requests or treating imported history as authority. Replacement warnings do not
 claim an earlier stored-counts snapshot is the number being deleted now.
 
-Disconnect progress is the existing running Connect card's accepted disconnect
-action and connection reference. Connection updates preserve that operation
-until its result is recorded; no additional persisted connection status is used.
+Workflow `pendingOperation` is derived from the current connection's one running
+or SDK-pending operation, carrying its identity, action, status and settlement
+flag. It uses the same read transaction as the card result. This summary creates
+no new persisted state or authority. A completed disconnect with pending
+settlement stays completed; only a running disconnect is in progress. Connection
+updates preserve the original operation result and card input lifetime.
 
 ### Current format and backups
 
@@ -479,7 +509,7 @@ With a new empty data directory, users configure account context and endpoints;
 
 ## Boundaries
 
-The active account is a read context only. It is not signing authorization, login, authentication for transactions, custody, permission for transactions, or proof of ownership. It stores at most one address per database file; setting a new active account replaces the previous one without revoking anything onchain.
+The active account is the current connection's saved Sui read context. It is not signing authorization, login, custody or proof of ownership. Settings can suppress this context without changing the connection's fixed address or requests. Changing the wallet address requires disconnecting and reconnecting. Accounts retained in history are not current choices.
 
 NDJSON event logs remain optional audit/debug logs. They are not the product activity source of truth. User-facing activity summaries read from SQLite. Event log write failures do not fail product session transitions or SQLite evidence writes.