@zktx.io/sui-mcp 0.5.0 → 0.6.0

package/docs/AGENT_DEVELOPMENT_POLICY.md

@@ -21,9 +21,10 @@ Target repository structure:
   protocol support must be added through adapter contracts rather than a
   custom-only product path.
 - `src/mcp/`: MCP server and tool definitions.
-- `src/review-server/`: local review HTTP server and session APIs.
-- `review-app/`: the Settings page and shared display helpers/styles.
-- `src/mcp-ui/`: internal Account, Receipt, Chart, Connect and Review cards, their
+- `src/review-server/`: loopback HTTP routing and Host/Origin checks; no public
+  browser page or Settings mutation API.
+- `review-app/`: shared card display helpers/styles; no external Settings page.
+- `src/mcp-ui/`: internal Account, Receipt, Chart, Connect, Review and Settings cards, their
   common lifecycle and view code.
 - `src/runtime/shared/`: authenticated server ownership and MCP forwarding.
 - `registry/`: local policy, allowlists, aliases, and generated mainnet metadata.
@@ -517,10 +518,11 @@ other boundaries, define the equivalent negative combinations before editing.
   sessions and return internal cards, but model calls must not authorize
   signing or execution. Scoped app-only actions admit an exact user selection;
   the backend performs wallet I/O and verifies each resulting signature.
-- The local settings control panel is a review-server frontend mutator. MCP may
-  create a settings session URL and read current settings, but settings
-  mutations must happen through the local settings page after Host/Origin checks
-  and settings-token validation.
+- Settings uses an internal card. Ordinary MCP may create that card or read
+  settings. Only scoped app-only input with current card/operation/revision and
+  explicit confirmation may apply a local change or restart the connection
+  service. Shared HTTP Host/Origin checks and private transport authentication
+  remain separate boundaries; no Settings URL or HTTP mutation fallback exists.
 
 ## Network Policy
 
@@ -635,7 +637,7 @@ only in host UI metadata. Reads never create approval, pairing or a signature
 request. Frame recreation is not an input transition. Its state read may
 reconcile existing deadlines and wallet records without starting a new
 operation. Only the backend owns admission, request deadlines and chain
-observation. Settings page tokens remain in URL fragments and authenticated HTTP headers, never query strings or logs.
+observation. Settings permissions remain in UI metadata and scoped app-only inputs, never URLs, model responses or logs. File bytes use only app-only file-transfer inputs/UI metadata. Same-operation cleanup and verification of an existing backup may resume without reapplying data, creating a backup or restarting the SDK.
 
 ## Utility Script Rule
 
@@ -668,8 +670,8 @@ observation. Settings page tokens remain in URL fragments and authenticated HTTP
 - Validate tool inputs and outputs at the MCP server boundary.
 - Review whether tool authority expanded whenever a tool schema or description
   changes.
-- Settings tools are session-gateway tools. They may create a local settings
-  page session or read current settings. They must not mutate settings directly,
+- Settings tools are card gateways. They may create an internal Settings card
+  or read current settings. They must not mutate settings directly,
   execute transactions, sign, create custody, or produce signing material.
 - For stdio MCP servers, stdout is reserved for valid MCP JSON-RPC messages.
   Send logs to stderr or a file. Do not use `console.log` in stdio server code.
@@ -747,8 +749,10 @@ For API review work, block or fix the change when:
 - Bind the local review server to `127.0.0.1`.
 - Use a dynamic port unless a fixed port is explicitly required.
 - Implement Host and Origin checks in the review server itself.
-- Do not treat Host or Origin checks as authentication. Settings APIs must validate their session token; internal app actions
-  must validate their scoped UI permission and stored target/revision.
+- Do not treat Host or Origin checks as authentication. Private MCP/control
+  routes require their runtime credential; internal app actions must validate
+  their scoped UI permission and stored target/revision. Settings has no public
+  URL or HTTP mutation fallback.
 - Do not use MCP SDK host validation helpers as a substitute for review server
   authentication.
 

package/docs/FRONTEND_POLICY.md

@@ -1,11 +1,19 @@
 # Frontend Policy
 
-Account, Receipt, Chart, Connect and Review use internal MCP Apps cards.
-Settings remains a local session-token page. Cards display backend-validated
+Account, Receipt, Chart, Connect, Review and Settings use internal MCP Apps cards.
+There is no external Settings page. Cards display backend-validated
 facts and forward explicit user selections through scoped app-only tools. They
 never hold transaction bytes/signatures or call a wallet, Sui RPC, Indexer or
 local HTTP endpoint directly. Direct NFT image loading is the display exception.
 
+All six cards use the same product UI and interaction rules across desktop
+Hosts. Equivalent validated data, authority, time, theme and viewport produce
+the same information, labels, controls and recovery flow. Qualified transport
+formats are normalized at the common integration boundary; Host names do not
+select product features or grant authority. Native window chrome and file
+pickers belong to the Host. Actual delivery remains a required integration
+check; a common error screen does not establish working file delivery.
+
 ## Display and review facts
 
 Show what is happening, the relevant asset flow, whether an action is available,
@@ -307,20 +315,95 @@ same View and opened Details during unchanged state reads; disposed callbacks
 cannot alter its replacement. Normal display changes do not postpone required
 backend state reads.
 
-For a stopped/unresponsive connection service, explain the actual operational
-path: fully quit all apps using Sui MCP, then reopen them. Closing a peer
-or window alone may not stop the shared owner. Do not promise that restart
-removes remote sessions or confirms an interrupted disconnect. Normal QR or
-initialization is not diagnosed as failure by a timer. An uncertain command
-first offers the same-request status check; the model cannot act for the user.
-Historical service-recovery cards retain their own recorded result and no new
-input. Their service outcome never implies connection approval, remote removal
-or a transaction outcome.
+Connection-service recovery belongs to Settings/Troubleshooting and requires
+explicit user preparation/confirmation of the affected SDK run and requests.
+Connect/Review explain that path when recovery is relevant; they do not host
+service-restart controls. Normal QR approval or initialization is not a failure
+diagnosis. An uncertain command first offers its same-request status check.
+If the parent/Settings is unavailable or a parent endpoint/installation change
+must apply, explain full exit/reopen of all participating apps. Child restart
+never implies remote disconnection, connection approval or chain outcome.
+
+Settings separates ordinary Read address, Local records and Troubleshooting
+from Advanced endpoint controls. Show operation impact and errors in the body;
+technical values use the existing Details disclosure. Each card owns one
+operation and its stored result. Preview, Back, chat navigation and state reads
+do not apply settings, create another file or restart the SDK. A valid sealed
+upload remains available for a new Preview after preparation invalidation;
+explicit file change uses the backend selection action. Validation rejection
+retains the actual current card and a usable correction/selection path.
+
+Local records offers Download backup as one explicit action. Snapshot creation
+and verification are internal progress, without a separate creation or
+confirmation page. New downloads use one private temporary snapshot. A supported
+download does not publish a permanent server backup. Other Settings choices do not appear on
+its progress or result page. File delivery uses the standard Host-mediated
+request, without hiding the action according to a Host name or download
+advertisement. Missing card authority still prevents actions.
+
+If that actual `ui/download-file` request returns method-not-found (-32601),
+the same snapshot is saved once in the Sui MCP backup folder. The initial choice
+explains this conditional destination. A verified local result shows Backup
+saved with a readable, selectable Folder and File name. It offers no second
+download action. Missing advertisement, cancellation, denial, invalid parameters,
+timeouts and errors from other methods do not select this path. Application
+names do not select either path.
+
+An earlier possibly handled attempt requires Save a local copy before local
+saving, with a warning that another copy may exist. A local save in progress
+offers status observation, not another save, Host retry or cancellation. A
+confirmed failure with no publication can offer Retry save within the original
+period; an uncertain result offers only Check status. State, authority, expiry,
+navigation and controls use the same current projection. Recorded saving and
+temporary cleanup remain separate facts, including when cleanup fails.
+
+Results distinguish snapshot preparation, Host-reported delivery, temporary
+cleanup and actual user file storage. Suggested file name is not a confirmed
+save location. Host acknowledgment ends server retention but is not proof of a
+saved file; isError does not classify cancellation, denial or failure. Lost
+responses are unconfirmed. An explicit retry uses the same verified snapshot
+within its fixed transfer period and warns when a prior request may already
+have been handled. Frame recreation and state reads never download again.
+Cancel download ends further transfer and cleans the temporary snapshot; it
+cannot close a Host dialog or delete a saved user file. A new frame needs an
+explicit retry, and a server restart ends the old transfer. An already-admitted
+local save may be settled by verifying its existing artifact after restart;
+recovery never creates a missing backup or restores old input permission.
+
+The backend owns a thirty-minute transfer period starting when the snapshot is
+physically ready, separately from the original card-input deadline. Reads and
+retries do not extend it. The View consumes relative remaining time without
+extending a confirmed deadline. Permission, operation, file, attempt and current
+state are checked before delivery. The elapsed time of the authenticated
+pre-delivery read, including a coalesced read, reduces the remaining period; a
+delayed reply cannot grant a fresh transfer period. A corrupt or unavailable snapshot sends no
+bytes to the Host. A local save admitted before the deadline finishes its file work and result
+settlement; the verified final backup is not subject to the private-file TTL.
+Existing saved backup results retain their recorded facts;
+their public files are not removed by temporary cleanup.
+
+Incomplete cleanup offers Check status for the same operation. Cleanup includes
+settlement of that operation's ended I/O reservation and waits for its actual
+file reads/writes to end. A stored result remains readable while settlement is
+retried; it does not release another operation's running I/O. Reading a recorded
+Host report resolves a lost reply without sending the file again.
 
 Local-data counts describe the backend state at the time they are read. A later
 replacement warning must not use a stale count, especially zero, as an assurance
 that no unconfirmed transaction records will be deleted. Warn that replacement
 can remove those records and cannot cancel a transaction on Sui.
+The private connection-service journal remains; Reset does not claim that the
+SDK is empty or grant a new pairing. Connect controls use backend
+`manageableConnectionIds`, separately from `usableConnectionId`. Unrecorded SDK
+presence uses conditional Settings recovery guidance after registration ends,
+without a synthetic target or global recovery controls in Connect.
+
+Endpoint confirmations name Sui node (gRPC) or Activity data (GraphQL), show the
+stored value before the change and the exact value to store. Their result labels
+the effective value and source at save time. Explain an active environment
+override in the body: restart alone will not apply the stored value while that
+override remains. Do not substitute a current configuration read for the saved
+result or copy default URLs into the View.
 
 ## Internal Read Cards
 
@@ -338,7 +421,7 @@ Receipt input values and their PTB graph use a typed UI-only metadata channel bo
 
 Internal cards provide no clipboard actions, copy buttons, or clipboard fallback controls. Preserve readable facts and ordinary text selection; where a PTB graph is shown, preserve its name/address controls and pan/zoom. NFT images retain no-referrer behavior and a failed-image placeholder. Theme follows the host. Card view cleanup ends timers, subscriptions and rendering observers without cancelling an already admitted server operation.
 
-All five cards, including Review management, adapt to the embedded frame width.
+All six cards, including Review management, adapt to the embedded frame width.
 Forms wrap, narrow fact rows stack their label above the value, and long addresses,
 amounts, names and records remain readable without widening the document. QR,
 chart and PTB drawing areas stay within the card; resizing changes presentation
@@ -446,9 +529,9 @@ Frontend labels stay in English. Localization must preserve protocol names, toke
 
 ## Shared UI And Design Principles
 
-The card views and remaining Settings page share one design-token set and one set of atomic UI
+The card views share one design-token set and one set of atomic UI
 components: vanilla TypeScript DOM helpers in `review-app/src/ui` plus the shared
-stylesheet `review-app/public/ui.css`, served at `/review-assets/ui.css`. There is
+stylesheet `review-app/public/ui.css`, bundled into each self-contained card HTML. There is
 no React, Vue, Svelte, or client router. Views compose the shared atoms and keep
 only their own layout, container, third-party-sizing, and composition CSS. The
 shared atoms are addressed by `ui-` prefixed classes that only the shared
@@ -462,7 +545,7 @@ The shared UI follows these durable principles:
    clearly-signaled async lock. Status and errors are conveyed as text, not color
    alone.
 2. One consistent system: cards share one lifecycle, one component set, and the
-   same element positions. Cards and token pages have no cross-page navigation.
+   same element positions. Cards have no cross-page navigation.
 3. Cards show the current step and next permitted action without permanently
    listing every earlier step. A completed transaction leads with its observed
    result; stored request state is not a second outcome. Settings preview and
@@ -479,28 +562,22 @@ The shared UI follows these durable principles:
    enough detail to diagnose afterward.
 7. Restraint: each page shows only the information it needs, with generous spacing.
 8. Information depth by importance: each page ranks its information and renders the
-   user task first and most prominent. Internal cards are one document: plain sections, rows and whitespace replace nested cards. Supplementary facts use one closed Details slide with plain sections inside, never nested disclosures. Do not repeat summary values or status in another panel. Review and Receipt place the correct transaction graph above their concise decision/result. Important errors and costs remain visible. Settings retains its page layout.
-
-Theme: cards follow the host; the remaining Settings page has a theme toggle. A shared theme helper stores
-only the theme value (`light` or `dark`) under one fixed storage key; it never
-reads or writes a token, session id, wallet account, or any other state. The
-theme is the `data-theme` attribute on the document root and is applied through
-CSS variables with no inline styles, so it works under the strictest page CSP.
+   user task first and most prominent. Internal cards are one document: plain sections, rows and whitespace replace nested cards. Supplementary facts use one closed Details slide with plain sections inside, never nested disclosures. Do not repeat summary values or status in another panel. Review and Receipt place the correct transaction graph above their concise decision/result. Important errors and costs remain visible. Settings uses the same plain sections/rows and one Details disclosure.
 
-Icons are SVG files or inline SVG, never an icon font or a CDN. The favicon
-(`favicon.svg`) and the theme-specific brand marks (`brand-light.svg`,
-`brand-dark.svg`) are served from `/review-assets/`; the header shows the brand
-mark for the active theme.
+All cards follow Host light/dark theme through the document's `data-theme`
+attribute and shared CSS tokens. They do not persist a separate theme choice.
+Use inline SVG icons or bundled assets, never an icon font/CDN or retired
+`/review-assets/` route.
 
 ## Navigation
 
-Read cards open from purpose-specific MCP tools. They contain their own result and error states and do not link to removed Account, Receipt, Chart, home or HTML not-found pages. Cards and the Settings page have no cross-page navigation or linked brand exit.
+Read cards open from purpose-specific MCP tools. They contain their own result and error states and do not link to removed Account, Receipt, Chart, home or HTML not-found pages. Cards have no cross-page navigation or linked brand exit.
 
 ## Security
 
 Tokens must not be accepted in query strings. Wallet addresses must not be written to local event logs in plaintext. Private keys, signatures, transaction bytes, and arbitrary Move calls must not appear in frontend state.
 
-Cards bundle script/style locally with the declared Host CSP and no external execution chunks. The Settings page uses local assets and Host/Origin/session-token checks. App-only tools require scoped UI permission, target and revision checks.
+Cards bundle script/style locally with the declared Host CSP and no external execution chunks. There is no external page/asset or HTTP mutation fallback. Shared private HTTP transport retains Host/Origin and transport authentication checks. App-only tools require scoped UI permission, target and revision checks.
 
 Wallet and review screens must be keyboard reachable and screen-reader labeled. Status and error changes must be exposed as text, not color alone.
 

package/docs/LOCAL_DB_ARCHITECTURE.md

@@ -10,7 +10,7 @@ The process that binds the configured loopback port initializes these local comp
 
 - a local SQLite store;
 - a mainnet guard for the configured Sui gRPC endpoint;
-- the local review HTTP server on `127.0.0.1`;
+- the shared private HTTP transport on `127.0.0.1`;
 - authenticated internal MCP sessions, reached by each client through a stdio forwarder.
 
 The GraphQL endpoint is also mainnet-guarded when it is saved through settings, imported from a local-data backup, or first used by Sui activity tools.
@@ -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 your AI client to create a Sui MCP local settings session and open the returned settings URL in the same machine's system browser.
+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.
 
 Endpoint changes apply after the MCP server restarts.
 
@@ -105,7 +105,10 @@ The following live session tables hold runtime session state in the shared datab
 - `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_settings_sessions`: short-lived Settings page authority.
+- `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_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.
 
 These live tables are distinct from the append-only review evidence tables above: the evidence tables remain the durable activity/audit record, while the live tables hold the in-flight session state that the review server serves.
 
@@ -132,13 +135,92 @@ update triggers reject revision-unaware writers: inserts must use
 `revision = 0` and the current write-contract marker, and updates must increase
 the revision by exactly one and keep the current write-contract marker.
 
-Logical local data reset is the local settings page action that clears stored product state through the runtime without requiring manual database-file deletion. Replace-only import is the settings page import path that replaces local product state from a validated backup. When no unsettled financial request prevents replacement, both logical local data reset and replace-only import clear `coin_metadata_cache`, card records, live review/wallet/settings sessions, private review artifacts and transaction material in the same SQLite transaction. A rollback preserves the existing data and permissions. No separate HTTP cleanup call owns permission invalidation. Clearing active account context does not clear it because coin metadata is account-independent.
-
-Non-terminal review session expiry is recorded lazily when the session is read or mutated after its TTL. There is no background expiry worker.
+Reset/import are explicitly confirmed Settings operations. They validate the
+current backup shape and imported mainnet endpoints, check current prepared
+impact and reject unsettled wallet/transaction work. One SQLite transaction
+replaces user data, clears coin metadata and other live authorities, advances
+data epoch and preserves the applying operation's read-only card/result. It
+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.
+
+User-data and wallet/request writers invalidate affected preparations and
+increment their card revision in the same transaction. 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.
+
+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.
+
+An exact unsupported download report can atomically reserve final/file I/O and
+admit local publication of that same snapshot. An earlier possibly handled
+attempt instead records a pending local-copy decision. Explicit consent/retry
+uses a distinct save-attempt identity and compare-and-set predecessor, without
+creating another snapshot. Application names and absent capability advertisement
+do not authorize this effect.
+
+The private `download.localSave` journal in `preparation_json` records its source
+manifest, fixed `backups/<operationId>.json` destination, attempt/consent and
+physical source device/inode as decimal strings. The verified source identity
+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 table, column or schema version changes.
+
+Unknown file effects remain `saving`, retaining their source and reservations.
+A failed DB result write retains the ended physical outcome for settlement.
+A missing target is distinct from one that could not be read. Only a verified
+absent target with a valid source permits an explicit retry within the original
+period. Recovery after owner exit verifies an existing source-bound target only;
+an absent or mismatching artifact is not regenerated. The new owner inherits
+settlement responsibility without restoring the old card's action permission.
+A committed saved result remains a past fact when its private file is gone.
+
+The fixed thirty-minute transfer period begins at physical readiness, independently
+of the original input expiry. The owner schedules its earliest live transfer
+deadline; current DB time, owner and epoch decide expiry. An abandoned frame does
+not own cleanup. A failed already-due journal cannot create a zero-delay loop or
+cancel another snapshot's future deadline. Status reads and owner recovery can
+retry cleanup. Current-generation access rejects stale callbacks after replacement.
+
+Private staging files survive as cleanup journal entries when cards are
+invalidated. Reset/import invalidate uploads and private downloads and transfer
+cleanup ownership without changing file identity. Existing public backup files
+remain unchanged. Acknowledgment, explicit cancellation, expiry, source failure
+or owner restart ends private retention, except that an already-admitted local
+publication retains the evidence needed to settle its result first. Its final
+reservation blocks competing Settings application and data replacement until
+physical I/O and result settlement end. Active descriptor reads/writes finish
+before deletion; new ranges and retries are refused once authority ends.
+`temporaryFileCleanup` includes physical cleanup and settlement of the operation's
+ended I/O reservation. Stored results remain readable during pending cleanup,
+including when expiry persistence fails; input remains closed and the failed
+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
+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.
 
 ## Shared local server
 
-Exactly one parent runtime owner per data directory binds the configured loopback port and creates the shared product services and SQLite stores. Other clients authenticate the listener before sending control credentials and forward MCP messages to it. The authentication covers database identity, internal API version 7, configuration (including WalletConnect project configuration) and server instance. Proof and subsequent dispatch use the same TCP connection. Host/Origin validation is separate from authentication; neither protects against a malicious process running as the same OS user.
+Exactly one parent runtime owner per data directory binds the configured loopback port and creates the shared product services and SQLite stores. Other clients authenticate the listener before sending control credentials and forward MCP messages to it. The authentication covers database identity, the package release version, configuration (including WalletConnect project configuration) and server instance. Proof and subsequent dispatch use the same TCP connection. Host/Origin validation is separate from authentication; neither protects against a malicious process running as the same OS user.
 
 The private `runtime-control.key` file is separate from UI permissions and wallet credentials and is excluded from product backups. Stdio closure and process signals close the owned server. No client signals a peer backend. The parent may terminate only its own SDK child. A peer can acquire the port after it becomes free. Failed calls are not replayed automatically. MCP framing, cancellation and EOF handling start before backend acquisition; wallet SDK readiness does not block parent service startup.
 
@@ -204,10 +286,12 @@ 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. Only confirmed
-known connected records transfer to the new owner. Multiple valid records are
-management targets, not usable wallet choices: `connectionConflict` is derived
-from those rows with no additional table. Targeted disconnection remains
+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.
@@ -221,6 +305,17 @@ database evaluation time and published to cards as `usableConnectionId` and
 `assetReadAccount`; Views do not recount recorded connections. This adds no
 table or expiry writer. 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
@@ -234,7 +329,8 @@ write; they do not start another SDK process. Repeated reads after a successful
 repair do not repeat the transition. Unrelated stored transaction results and
 already dispatched chain observation remain independent of that write.
 The supervisor's explicit replacement primitive requires fencing and actual
-child exit before a new run, but it has no current card or model entry point.
+child exit before a new run. Its user entry point is a scoped, explicitly
+prepared and confirmed Settings card; ordinary model calls cannot replace it.
 
 If a completed callback's flag write fails, the owner retains its exact operation
 identity as completion evidence. A current state read can retry that database
@@ -257,6 +353,25 @@ The target session/card's own required expiry writes still propagate errors.
 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,
+pending work and read-address provenance from one SQLite read snapshot. The
+shared selector and qualification projection compute 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.
+Creating a card and checking its own permission, input expiry or cleanup retain
+their own writes. Stored counts are not a promise about a later deletion impact.
+
+`reconcileAndEvaluate` requires a current-wallet or server-bound review purpose.
+Current wallet consumers use `reconcileConnectionContext`; exact request reads
+retain their narrower target. Reset/import preparation and final admission still
+settle deadlines and compare the current impact in their transaction. Snapshot
+memory may precede its DB publication: initializing/state_sync does not grant
+account use or establish an unrecorded-connection removal diagnosis. Only a
+published available run can qualify that guidance; missing guidance does not
+prove that the SDK is empty.
+
 Successful reset/import invalidates pending SDK startup or recovery in the old
 data generation and ends that child without automatically starting another.
 Rejected or rolled-back replacement does not change the run or generation.
@@ -335,13 +450,21 @@ unknown-outcome records may be removed after the explicit warning; removing
 records cannot cancel a transaction. A generation change rejects late writes.
 
 The wallet store advances expired signature and initial-observation deadlines
-through the same request transition writer used by the workflow. Current
-session/card reads, current local-data counts and preview counts, and the actual
-reset/import transaction use this operation even when no View is open. Expiry
+through the same request transition writer used by the workflow. Explicit
+current-wallet reconciliation settles current wallet work. A server-bound review
+read settles its own request target unless it depends on current wallet work;
+it does not use an unrelated completed request as a reason for global maintenance.
+Reset/import preparation settles deadlines before calculating its impact, and
+final admission settles them again and compares the current impact in the same
+transaction as replacement, even when no View is open.
+
+General Settings facts and stored local-data counts use the diagnostic read
+contract; they do not advance live requests. Creating or reading a card still
+checks that card's own permission, input expiry and operation cleanup. Expiry
 does not clear pending SDK/submission/lookup callbacks. Stored activity queries
-and public backup export only read recorded facts; they do not advance live
-requests or interpret imported history as authority. Replacement warnings do not
-claim an earlier counts snapshot is the number being deleted now.
+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
@@ -349,9 +472,9 @@ until its result is recorded; no additional persisted connection status is used.
 
 ### Current format and backups
 
-The current `user_version` is 9. It identifies one supported schema; there is no migration registry or older-format decoder. All clients sharing a data directory must use the same compatible runtime.
+The runtime accepts one current SQLite structure, checked against its table, column, constraint, index and trigger definitions before writes. There is no separate database version counter, migration registry or older-format decoder. All clients sharing a data directory must use the same package release.
 
-A current backup carries `format`, `schemaVersion`, `network`, `exportedAt` and its product data. Import rejects a missing or different schema identifier, incomplete required fields, invalid references or invalid raw quantities. Missing settings or activity arrays are not filled from defaults. Supported `function_scan` provenance remains part of the current format. Validation failure leaves current data intact.
+A current backup carries `format`, `network`, `exportedAt` and its product data. It has no numeric schema version. Import rejects a different format, unknown or missing fields, invalid references or invalid raw quantities. Missing settings or activity arrays are not filled from defaults. Supported `function_scan` provenance remains part of the current format. Validation failure leaves current data intact.
 
 New installations do not inherit older local review records, activity scans, known/active accounts or stored endpoints. Users configure the required context again; environment overrides retain their existing precedence. Empty local history does not imply an absence of on-chain transactions. Existing DB and backup files are not deleted by startup.