@zktx.io/sui-mcp 0.5.0 → 0.6.0

package/README.md

@@ -16,8 +16,8 @@ cause another signing or submission request. Request failures and unknown
 outcomes are separate from independently observed chain success/failure.
 
 Account, Receipt and Chart cards provide read-only evidence independently of
-signing. Connect and Review also run inside the MCP host. Settings currently
-uses a local token page. Human-readable review is not a guarantee of safety or
+signing. Connect, Review and Settings also run inside the MCP host. Settings
+provides local data controls and explicit connection-service recovery. Human-readable review is not a guarantee of safety or
 of complete interpretation of every transaction detail; the raw PTB structure
 and addresses remain inspectable.
 
@@ -27,13 +27,13 @@ Users can ask ordinary questions:
 - "How much are my USD-denominated assets together?"
 - "What is the shortfall?"
 
-This document describes `@zktx.io/sui-mcp@0.5.0`. Confirm that version is
+This document describes `@zktx.io/sui-mcp@0.6.0`. Confirm that version is
 published before using npm installation commands. For a local build, follow
 [Developer Checkout Setup](docs/MCP_SETUP.md#developer-checkout-setup).
 
 ## Product Scope in Two Layers
 
-- **Implemented:** Sui mainnet read evidence, non-signable external proposal review, and account-bound DeepBook swap review using protocol-agnostic adapters. Five internal cards use the same SQLite state and permission model. The backend verifies stored material, ownership, quote/policy provenance, human-readable facts, simulation and PTB evidence before an explicit user request. WalletConnect carries bytes only between the backend and wallet; ordinary MCP responses expose facts, request status and observed execution results. Settings remains a local token page; an internal Settings card is not implemented.
+- **Implemented:** Sui mainnet read evidence, non-signable external proposal review, and account-bound DeepBook swap review using protocol-agnostic adapters. Six internal cards use the same SQLite state and permission model. The backend verifies stored material, ownership, quote/policy provenance, human-readable facts, simulation and PTB evidence before an explicit user request. WalletConnect carries bytes only between the backend and wallet; ordinary MCP responses expose facts, request status and observed execution results. Settings owns endpoint and read-address controls, local backup/import/reset, and explicit connection-service recovery. Settings operations require scoped user confirmation; ordinary MCP calls only create the card or read settings.
 - **Never (permanently unsupported at every layer):** no private-key custody, no MCP or AI autonomous execution, no forwarding of opaque external transaction bytes to a wallet, no silent settlement-token or route choice, no fiat cash-out, no P&L, no peg guarantee.
 
 DeepBook provides the current scoped Sui conversion, price, and orderbook
@@ -193,12 +193,12 @@ running from a local checkout, see [docs/MCP_SETUP.md](docs/MCP_SETUP.md).
 
 ### Package and repository transition
 
-The package for this release is `@zktx.io/sui-mcp@0.5.0`, and its repository is
+The package for this release is `@zktx.io/sui-mcp@0.6.0`, and its repository is
 `zktx-mcp/sui-mcp`. The previous package is `@zktx.io/say-ur-intent` (through
 0.4.4). The older `@stelis/say-ur-intent@0.4.0` is also a separate package.
 Existing installations and MCP client registrations do not change names
 automatically. Before switching, confirm the new package with
-`npm view @zktx.io/sui-mcp@0.5.0 version`; renaming the repository does not publish
+`npm view @zktx.io/sui-mcp@0.6.0 version`; renaming the repository does not publish
 an npm package or MCP Registry entry.
 
 Use the full scoped package name: the unscoped `sui-mcp` package is a different

package/dist/adapters/deepbook/deepbookTransactionMaterialProducer.js

@@ -112,9 +112,9 @@ export function createDeepbookSwapTransactionMaterialProducer(options) {
             });
             const transaction = new Transaction();
             transaction.setSender(input.account);
-            // The DeepBook SDK reserves a 0.25 SUI gas budget by default, which
-            // blocks small wallets whose balance is close to the swap amount. A
-            // mainnet DeepBook swap costs well under this explicit 0.05 SUI budget.
+            // Set the product's explicit 0.05 SUI spending cap before the SDK's
+            // setGasBudgetIfNotSet fallback (0.25 SUI). This is not a cost estimate;
+            // funding and checks-enabled simulation must validate each transaction.
             transaction.setGasBudget(DEEPBOOK_SWAP_GAS_BUDGET_MIST);
             // input_coin fee mode swaps with an explicit zero DEEP coin; the Move
             // entry point then charges the taker fee in the source coin at the

package/dist/core/activity/localDataService.js

@@ -1,8 +1,8 @@
+import { SETTINGS_DOWNLOAD_FILE_SQL, SETTINGS_FILE_CLEANUP_SQL } from "../session/settingsFileIdentity.js";
 import { hasUnsettledWalletWork } from "../session/sqliteWalletWorkflowStore.js";
-import { DB_USER_VERSION } from "./schemaVersion.js";
 import { SuiEndpointError, parseGraphqlUrl, parseGrpcUrl } from "../suiEndpoint.js";
 import { LOCAL_DATA_EXPORT_FORMAT, LOCAL_DATA_NETWORK, LocalDataError } from "./localDataTypes.js";
-import { activeAccountChange, countsForPayload, invalidBackup, maxNumber, parseLocalDataEnvelope, suiGraphqlUrlFromPayload, suiGrpcUrlFromPayload } from "./localDataValidation.js";
+import { activeAccountChange, activeAccountAddress, countsForPayload, invalidBackup, maxNumber, parseLocalDataEnvelope, suiGraphqlUrlFromPayload, suiGrpcUrlFromPayload } from "./localDataValidation.js";
 export * from "./localDataTypes.js";
 export class SqliteLocalDataService {
     db;
@@ -15,18 +15,18 @@ export class SqliteLocalDataService {
     }
     now() { return this.options.now?.() ?? new Date(); }
     async getDataCounts() {
-        return this.currentDataCounts();
+        return this.currentDataCountsSync();
     }
-    currentDataCounts() {
+    currentDataCountsSync(now = this.now()) {
         return this.db.transaction(() => {
-            this.options.advanceRequestDeadlines(this.now());
+            this.options.advanceRequestDeadlines(now);
             return this.getDataCountsSync();
         }).immediate();
     }
-    async exportLocalData(now = new Date()) {
+    async exportLocalData(now = new Date()) { return this.exportLocalDataSync(now); }
+    exportLocalDataSync(now = this.now()) {
         return this.db.transaction(() => {
             const envelope = {
-                schemaVersion: DB_USER_VERSION,
                 format: LOCAL_DATA_EXPORT_FORMAT,
                 network: LOCAL_DATA_NETWORK,
                 exportedAt: now.toISOString(),
@@ -48,32 +48,48 @@ export class SqliteLocalDataService {
             });
         })();
     }
-    async previewImportLocalData(input) {
+    async previewImportLocalData(input) { return this.previewImportLocalDataSync(input); }
+    previewImportLocalDataSync(input, now = this.now()) {
         const envelope = parseLocalDataEnvelope(input, {
             validateAdapterLifecycle: this.validateAdapterLifecycle
         });
-        return {
-            status: "valid",
-            format: envelope.format,
-            network: envelope.network,
-            exportedAt: envelope.exportedAt,
-            currentCounts: this.currentDataCounts(),
-            incomingCounts: countsForPayload(envelope.data),
-            willReplace: true,
-            activeAccountChange: activeAccountChange(this.selectAll("accounts"), this.selectAll("active_account_context"), envelope.data.accounts, envelope.data.activeAccountContext),
-            restartRequiredAfterImport: true,
-        };
+        return this.db.transaction(() => {
+            this.options.advanceRequestDeadlines(now);
+            const currentAccounts = this.selectAll("accounts");
+            const currentContext = this.selectAll("active_account_context");
+            return {
+                status: "valid",
+                format: envelope.format,
+                network: envelope.network,
+                exportedAt: envelope.exportedAt,
+                currentCounts: this.getDataCountsSync(),
+                incomingCounts: countsForPayload(envelope.data),
+                willReplace: true,
+                activeAccountChange: activeAccountChange(currentAccounts, currentContext, envelope.data.accounts, envelope.data.activeAccountContext),
+                currentReadAddress: activeAccountAddress(currentAccounts, currentContext),
+                incomingReadAddress: activeAccountAddress(envelope.data.accounts, envelope.data.activeAccountContext),
+                restartRequiredAfterImport: true,
+            };
+        }).immediate();
     }
     async importLocalDataReplace(input, _now = new Date()) {
         const envelope = await this.parseAndVerifyImportEnvelope(input);
-        this.db.transaction(() => {
-            // Endpoint verification may have outlived the original request window.
-            // Evaluate the current owner state inside the actual replacement transaction.
-            const now = this.now();
-            this.options.advanceRequestDeadlines(now);
-            if (hasUnsettledWalletWork(this.db, now))
-                throw new LocalDataError("input_invalid", "A wallet request is still unsettled.", { reason: "wallet_request_unsettled" });
-            this.resetLocalDataTables();
+        const result = this.db.transaction(() => this.applyValidatedReplacement(envelope, this.now()))();
+        this.notifyDataReplaced();
+        return result;
+    }
+    async resetLocalData(now = this.now()) {
+        const result = this.db.transaction(() => this.applyValidatedReplacement(undefined, now))();
+        this.notifyDataReplaced();
+        return result;
+    }
+    // The caller commits this primitive with the admitted Settings card/result.
+    // It contains no async gap or post-commit reconstruction of its own authority.
+    applyValidatedReplacement(envelope, now, preserveCardId) {
+        this.options.advanceRequestDeadlines(now);
+        this.assertReplacementAllowed(now);
+        this.resetLocalDataTables(preserveCardId);
+        if (envelope) {
             this.insertAccounts(envelope.data.accounts);
             this.insertActiveAccountContext(envelope.data.activeAccountContext);
             this.insertReviewSessions(envelope.data.reviewSessions);
@@ -85,39 +101,37 @@ export class SqliteLocalDataService {
             this.insertExternalActivityTransactions(envelope.data.externalActivityTransactions);
             this.insertLocalSettings(envelope.data.localSettings);
             this.syncSqliteSequences(envelope.data);
-        })();
-        this.options.onDataReplaced?.();
-        return {
-            status: "imported",
-            dataCounts: this.getDataCountsSync(),
-            sessionsInvalidated: true
-        };
-    }
-    async resetLocalData(now = this.now()) {
-        this.db.transaction(() => {
-            this.options.advanceRequestDeadlines(now);
-            if (hasUnsettledWalletWork(this.db, now))
-                throw new LocalDataError("input_invalid", "A wallet request is still unsettled.", { reason: "wallet_request_unsettled" });
-            this.resetLocalDataTables();
+        }
+        else
             this.insertDefaultSuiGrpcUrl(now);
-        })();
-        this.options.onDataReplaced?.();
-        return {
-            status: "reset",
-            dataCounts: this.getDataCountsSync(),
-            sessionsInvalidated: true
-        };
+        this.db.prepare("UPDATE settings_control SET data_epoch=data_epoch+1 WHERE id=1").run();
+        if (preserveCardId)
+            this.db.prepare(`UPDATE settings_operations SET data_epoch=(SELECT data_epoch FROM settings_control WHERE id=1)
+      WHERE card_id=?`).run(preserveCardId);
+        return { status: envelope ? "imported" : "reset", dataCounts: this.getDataCountsSync(), sessionsInvalidated: true };
     }
-    resetLocalDataTables() {
+    notifyDataReplaced() { this.options.onDataReplaced?.(); }
+    resetLocalDataTables(preserveCardId) {
+        this.db.prepare(`UPDATE settings_files SET invalidated=1 WHERE role='upload' OR ${SETTINGS_DOWNLOAD_FILE_SQL}`).run();
+        if (preserveCardId) {
+            // Deleted cards cannot report or retry their cleanup. Transfer cleanup
+            // responsibility while preserving file identities and public backup paths.
+            // Uploads remain invalidated and never replace the selected input.
+            const operation = this.db.prepare("SELECT operation_id FROM settings_operations WHERE card_id=?").get(preserveCardId);
+            if (!operation)
+                throw new LocalDataError("internal_error", "The replacement result identity is unavailable.");
+            this.db.prepare(`UPDATE settings_files SET cleanup_operation_id=? WHERE cleanup!='complete'
+        AND ${SETTINGS_FILE_CLEANUP_SQL}`).run(operation.operation_id);
+            this.db.prepare("DELETE FROM live_read_cards WHERE id!=?").run(preserveCardId);
+        }
+        else
+            this.db.prepare("DELETE FROM live_read_cards").run();
         for (const table of [
-            "live_read_cards",
             "live_execution_details",
             "live_request_authority",
-            "live_wallet_connections",
             "live_transaction_materials",
             "live_private_review_artifacts",
             "live_review_sessions",
-            "live_settings_sessions",
             "external_activity_transactions",
             "external_activity_scans",
             "review_state_snapshots",
@@ -259,6 +273,11 @@ export class SqliteLocalDataService {
             }
         }
     }
+    // Preparation and final replacement use the same rule without starting wallet I/O.
+    assertReplacementAllowed(now = this.now()) {
+        if (hasUnsettledWalletWork(this.db, now))
+            throw new LocalDataError("input_invalid", "A wallet request is still unsettled.", { reason: "wallet_request_unsettled" });
+    }
     async parseAndVerifyImportEnvelope(input) {
         const envelope = parseLocalDataEnvelope(input, {
             validateAdapterLifecycle: this.validateAdapterLifecycle

package/dist/core/activity/localDataValidation.js

@@ -1,6 +1,5 @@
 import { transactionRequestStatusSchema, transactionRequestSchema } from "../session/transactionRequest.js";
 import { REVIEW_TRANSITION_EVENTS } from "./sqliteActivityStoreRows.js";
-import { DB_USER_VERSION } from "./schemaVersion.js";
 import { z } from "zod";
 import { assertNoForbiddenMcpFields } from "../action/forbiddenFields.js";
 import { parseLifecycleValidatedReviewState } from "../action/reviewStateValidation.js";
@@ -144,7 +143,6 @@ const payloadSchema = z.object({
     localSettings: z.array(localSettingRowSchema).length(2)
 }).strict();
 const envelopeSchema = z.object({
-    schemaVersion: z.literal(DB_USER_VERSION),
     format: z.literal(LOCAL_DATA_EXPORT_FORMAT),
     network: z.literal(LOCAL_DATA_NETWORK),
     exportedAt: isoTimestamp,
@@ -427,7 +425,7 @@ export function activeAccountChange(currentAccounts, current, incomingAccounts,
     }
     return incomingAccount === null ? "cleared" : "set";
 }
-function activeAccountAddress(accounts, context) {
+export function activeAccountAddress(accounts, context) {
     const accountId = context[0]?.account_id ?? null;
     if (accountId === null) {
         return null;

package/dist/core/activity/sqliteActivityStore.js

@@ -17,7 +17,8 @@ import { SqlitePreferencesRepository } from "../preferences/sqlitePreferencesRep
 import { SqliteTransactionMaterialStore } from "../session/sqliteTransactionMaterialStore.js";
 import { SqliteCardRecordStore } from "../session/sqliteCardStore.js";
 import { sameHandle } from "../session/transactionMaterialStore.js";
-import { SqliteSessionRecordStore, SqlitePrivateReviewArtifactStore, createSqliteSettingsRecordStore, sessionFromLiveReviewSessionRow, insertLiveReviewSessionRow, updateLiveReviewSessionRow } from "../session/sqliteSessionStore.js";
+import { SqliteSessionRecordStore, SqlitePrivateReviewArtifactStore, sessionFromLiveReviewSessionRow, insertLiveReviewSessionRow, updateLiveReviewSessionRow } from "../session/sqliteSessionStore.js";
+import { SqliteSettingsWorkflowStore } from "../session/sqliteSettingsWorkflowStore.js";
 import { SqliteLocalDataService } from "./localDataService.js";
 import { buildExternalActivityCoverageResult } from "./externalActivityCoverage.js";
 import { buildExternalActivityTransactionStreamResult, canonicalExternalActivityTransactions } from "./externalActivityTransactionStream.js";
@@ -117,7 +118,8 @@ export class SqliteActivityStore {
     async getActiveAccount() {
         return this.getActiveAccountSync();
     }
-    async clearActiveAccount(now = new Date()) {
+    async clearActiveAccount(now = new Date()) { this.clearActiveAccountSync(now); }
+    clearActiveAccountSync(now = new Date()) {
         this.db
             .prepare(`INSERT INTO active_account_context (id, account_id, source, set_at)
          VALUES (?, NULL, 'cleared', ?)
@@ -657,11 +659,14 @@ export class SqliteActivityStore {
     createCardRecordStore() {
         return new SqliteCardRecordStore(this.db);
     }
+    createSettingsWorkflowStore(ownerId, now = () => new Date()) {
+        return new SqliteSettingsWorkflowStore(this.db, ownerId, now);
+    }
     createPrivateReviewArtifactStore() {
         return new SqlitePrivateReviewArtifactStore(this.db);
     }
-    createWalletWorkflowStore(ownerId, clock = () => new Date()) {
-        const records = new SqliteWalletWorkflowStore(this.db, ownerId, (address, id, name, now) => this.setActiveAccountSync(address, "wallet_connection", now, { id, name }), clock, this.createTransactionMaterialStore(), (input, at) => this.evaluateWorkflowState(input, records, ownerId, at === undefined ? clock : () => at), () => this.getActiveAccountSync());
+    createWalletWorkflowStore(ownerId, clock = () => new Date(), readSdkSnapshot = () => undefined) {
+        const records = new SqliteWalletWorkflowStore(this.db, ownerId, (address, id, name, now) => this.setActiveAccountSync(address, "wallet_connection", now, { id, name }), clock, this.createTransactionMaterialStore(), (input, at) => this.reconcileWorkflowState(input, records, ownerId, at === undefined ? clock : () => at), () => this.getActiveAccountSync(), readSdkSnapshot);
         return records;
     }
     finalizeReviewEvaluation(candidate, clock) {
@@ -694,19 +699,26 @@ export class SqliteActivityStore {
         return { session: next, events: next.status === "expired" ? [] : [{ type: "state.computed", sessionId: next.id,
                     status: next.status, reason: "private_review_artifacts_refresh_required", at: now.toISOString() }] };
     }
-    evaluateWorkflowState(input, records, ownerId, clock) {
+    reconcileWorkflowState(input, records, ownerId, clock) {
         return this.db.transaction(() => {
             const now = clock();
+            if (input.purpose !== "current_wallet" && input.purpose !== "review" ||
+                input.purpose === "review" && (!input.readTarget || !input.candidate)) {
+                throw new SessionStoreError("input_invalid", "An explicit workflow evaluation target is required.");
+            }
             const cards = this.createCardRecordStore();
             let record = input.expectedCard && records.currentCard(input.expectedCard);
-            const reviewId = record?.state.kind === "review" ? String(record.state.input.reviewSessionId) : input.reviewSessionId;
+            const reviewId = input.purpose === "review" ? input.reviewSessionId : undefined;
+            if (record && (input.purpose === "review" ? record.state.kind !== "review" || record.state.input.reviewSessionId !== reviewId : record.state.kind !== "connect")) {
+                throw new SessionStoreError("session_mismatch", "The workflow target does not match this card.");
+            }
             const target = reviewId ? records.reviewReadTarget(reviewId, record) : undefined;
-            if (input.readTarget && (!target || input.readTarget.reviewSessionId !== target.reviewSessionId ||
+            if (input.purpose === "review" && (!target || input.readTarget.reviewSessionId !== target.reviewSessionId ||
                 input.readTarget.attemptId !== target.attemptId || !input.readTarget.walletDependent && target.walletDependent)) {
                 throw new SessionStoreError("session_mismatch", "The review target changed while its state was being read. Check this review again.");
             }
             let evaluated;
-            if (reviewId) {
+            if (input.purpose === "review") {
                 if (!input.candidate || input.candidate.session.id !== reviewId)
                     throw new SessionStoreError("session_not_found", "The saved review is unavailable.");
                 evaluated = this.finalizeReviewEvaluationAt(input.candidate, now);
@@ -726,14 +738,13 @@ export class SqliteActivityStore {
             const authority = request && records.authority(request.attemptId);
             const details = request?.execution && records.executionDetails(request.attemptId);
             const connection = record?.state.kind === "connect" && record.operationId ? records.connection(record.operationId) : undefined;
-            const storedAccount = this.getActiveAccountSync(), activeAccount = storedAccount?.address, targetAccount = session?.account ?? activeAccount;
-            const facts = { evaluatedAt: now.toISOString(), ownerId, record, session, request, authority,
+            const connectionFacts = records.readConnectionFacts(now), targetAccount = session?.account ?? connectionFacts.activeAccount;
+            const facts = { ...connectionFacts, ownerId, record, session, request, authority,
                 hasReviewInput: !!session && session.status !== "expired" && Date.parse(session.expiresAt) > now.getTime() &&
                     cards.hasReviewInput(session.id, ownerId, now),
-                walletAvailability: input.walletAvailability, walletObservation: input.walletObservation,
-                runtimeRecovery: record && records.walletRecovery(record), activeAccount, activeAccountConnectionId: storedAccount?.walletId,
+                walletAvailability: input.walletAvailability,
+                runtimeRecovery: record && records.walletRecovery(record),
                 walletDependent: !target || target.walletDependent,
-                connections: records.connectionViews(),
                 connection: connection ? records.connectionView(connection.connection) : undefined,
                 boundReview: request && (record?.operationId || record?.scope === "review_manage") ? records.requestReview(request.attemptId) : undefined,
                 busyForAccount: !!targetAccount && records.busyForAccount(targetAccount, now),
@@ -741,9 +752,6 @@ export class SqliteActivityStore {
             return { ...facts, ...workflowEligibility(facts), events: evaluated?.events ?? [] };
         }).immediate();
     }
-    createSettingsRecordStore() {
-        return createSqliteSettingsRecordStore(this.db);
-    }
     runLiveReviewSessionMutation(live, writeActivity) {
         const stale = new Error("live review session changed before commit");
         try {

package/dist/core/activity/sqliteActivityStoreSchema.js

@@ -1,7 +1,7 @@
 import Database from "better-sqlite3";
 import { EXTERNAL_ACTIVITY_SCAN_MAX_LIMIT } from "./activityStore.js";
-import { DB_USER_VERSION } from "./schemaVersion.js";
 import { ActivityStoreError } from "./sqliteActivityStoreTypes.js";
+import { SETTINGS_RESET_PREPARATION_SQL } from "../session/settingsPreparationSql.js";
 import { LIVE_REVIEW_SESSION_INSERT_TRIGGER, LIVE_REVIEW_SESSION_UPDATE_TRIGGER, LIVE_REVIEW_SESSION_WRITE_CONTRACT_VERSION } from "../session/liveReviewSessionContract.js";
 const EXTERNAL_ACTIVITY_SCAN_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_external_activity_scans_account_fetched
   ON external_activity_scans(account_id, fetched_at)`;
@@ -132,6 +132,7 @@ const CURRENT_SCHEMA_SQL = `
     CREATE TABLE IF NOT EXISTS live_wallet_connections (
       id TEXT PRIMARY KEY,
       owner_id TEXT NOT NULL,
+      run_id TEXT,
       status TEXT NOT NULL,
       revision INTEGER NOT NULL CHECK (revision >= 0),
       topic TEXT UNIQUE,
@@ -141,6 +142,7 @@ const CURRENT_SCHEMA_SQL = `
     CREATE TABLE IF NOT EXISTS live_request_authority (
       attempt_id TEXT PRIMARY KEY REFERENCES review_requests(attempt_id) ON DELETE RESTRICT,
       owner_id TEXT NOT NULL,
+      run_id TEXT,
       connection_id TEXT NOT NULL REFERENCES live_wallet_connections(id) ON DELETE RESTRICT,
       connection_revision INTEGER NOT NULL,
       can_submit INTEGER NOT NULL CHECK (can_submit IN (0,1)),
@@ -220,6 +222,7 @@ const CURRENT_SCHEMA_SQL = `
       owner_id TEXT NOT NULL,
       review_revision INTEGER NOT NULL DEFAULT 0,
       preparation_id TEXT,
+      preparation_run_id TEXT,
       preparation_error TEXT,
       wallet_connection_id TEXT,
       wallet_connection_revision INTEGER,
@@ -239,16 +242,11 @@ const CURRENT_SCHEMA_SQL = `
       artifacts_json TEXT NOT NULL
     );
 
-    CREATE TABLE IF NOT EXISTS live_settings_sessions (
-      id TEXT PRIMARY KEY,
-      session_json TEXT NOT NULL
-    );
-
     CREATE TABLE IF NOT EXISTS live_read_cards (
       id TEXT PRIMARY KEY,
       owner_id TEXT NOT NULL,
       token_hash TEXT NOT NULL,
-      kind TEXT NOT NULL CHECK (kind IN ('account', 'receipt', 'chart', 'connect', 'review')),
+      kind TEXT NOT NULL CHECK (kind IN ('account', 'receipt', 'chart', 'connect', 'review', 'settings')),
       state TEXT NOT NULL CHECK (state IN ('ready', 'running', 'closed')),
       reason TEXT CHECK (reason IN ('completed', 'expired', 'failed', 'server_restarted', 'cancelled')),
       error TEXT,
@@ -256,7 +254,7 @@ const CURRENT_SCHEMA_SQL = `
       created_at TEXT NOT NULL,
       expires_at TEXT NOT NULL,
       input_json TEXT NOT NULL,
-      scope TEXT NOT NULL DEFAULT 'read' CHECK (scope IN ('read', 'connect', 'review', 'review_manage')),
+      scope TEXT NOT NULL DEFAULT 'read' CHECK (scope IN ('read', 'connect', 'review', 'review_manage', 'settings')),
       operation_id TEXT,
       accepted_input_json TEXT,
       result_json TEXT,
@@ -266,6 +264,59 @@ const CURRENT_SCHEMA_SQL = `
       CHECK (receipt_display_json IS NULL OR (kind = 'receipt' AND reason = 'completed'))
     );
     CREATE INDEX IF NOT EXISTS idx_live_read_cards_owner_state ON live_read_cards(owner_id, state);
+    CREATE TABLE IF NOT EXISTS settings_control (
+      id INTEGER PRIMARY KEY CHECK (id=1),
+      data_epoch INTEGER NOT NULL DEFAULT 0 CHECK (data_epoch BETWEEN 0 AND 9007199254740991),
+      user_data_revision INTEGER NOT NULL DEFAULT 0 CHECK (user_data_revision BETWEEN 0 AND 9007199254740991),
+      active_operation_id TEXT,
+      file_io_id TEXT,
+      wallet_input_blocked INTEGER NOT NULL DEFAULT 0 CHECK (wallet_input_blocked IN (0,1)),
+      wallet_block_operation_id TEXT
+    );
+    INSERT INTO settings_control (id) VALUES (1);
+    CREATE TABLE IF NOT EXISTS settings_operations (
+      operation_id TEXT PRIMARY KEY,
+      card_id TEXT NOT NULL UNIQUE REFERENCES live_read_cards(id) ON DELETE CASCADE,
+      owner_id TEXT NOT NULL,
+      data_epoch INTEGER NOT NULL CHECK (data_epoch BETWEEN 0 AND 9007199254740991),
+      kind TEXT,
+      phase TEXT NOT NULL CHECK (phase IN ('draft','uploading','sealed','prepared','executing','stopping','starting','terminal')),
+      draft_json TEXT,
+      preparation_id TEXT,
+      fingerprint TEXT,
+      prepared_user_data_revision INTEGER,
+      preparation_json TEXT,
+      file_id TEXT,
+      accepted_digest TEXT,
+      admitted_at TEXT,
+      result_json TEXT,
+      prior_run_id TEXT,
+      next_run_id TEXT,
+      supersedes_operation_id TEXT,
+      superseded_by_operation_id TEXT,
+      checkpoint TEXT,
+      CHECK ((phase='terminal' AND result_json IS NOT NULL) OR (phase!='terminal' AND result_json IS NULL))
+    );
+    CREATE TRIGGER IF NOT EXISTS settings_immutable_result
+    BEFORE UPDATE ON settings_operations WHEN OLD.result_json IS NOT NULL AND NEW.result_json IS NOT OLD.result_json
+    BEGIN SELECT RAISE(ABORT, 'settings terminal result is immutable'); END;
+    CREATE TABLE IF NOT EXISTS settings_files (
+      file_id TEXT PRIMARY KEY,
+      operation_id TEXT NOT NULL,
+      cleanup_operation_id TEXT NOT NULL,
+      role TEXT NOT NULL CHECK (role IN ('upload','export')),
+      relative_path TEXT NOT NULL UNIQUE,
+      display_name TEXT NOT NULL,
+      total_size INTEGER NOT NULL CHECK (total_size BETWEEN 0 AND 9007199254740991),
+      received_size INTEGER NOT NULL CHECK (received_size BETWEEN 0 AND total_size),
+      sha256 TEXT NOT NULL,
+      sealed INTEGER NOT NULL DEFAULT 0 CHECK (sealed IN (0,1)),
+      invalidated INTEGER NOT NULL DEFAULT 0 CHECK (invalidated IN (0,1)),
+      cleanup TEXT NOT NULL DEFAULT 'pending' CHECK (cleanup IN ('pending','complete','failed')),
+      reservation_json TEXT
+    );
+    ${settingsRevisionTriggers()}
+
     CREATE TRIGGER IF NOT EXISTS live_read_cards_insert_revision
     BEFORE INSERT ON live_read_cards WHEN NEW.revision != 0
     BEGIN SELECT RAISE(ABORT, 'card insert requires revision zero'); END;
@@ -322,11 +373,10 @@ function expectedSchemaSignature() {
     }
 }
 export function assertCurrentDatabaseFormat(db) {
-    const version = db.pragma("user_version", { simple: true });
     const signature = schemaSignature(db);
-    if (version === 0 && signature === "[]")
+    if (signature === "[]" && !db.prepare("SELECT 1 FROM sqlite_schema LIMIT 1").get())
         return "empty";
-    if (version === DB_USER_VERSION && signature === expectedSchemaSignature())
+    if (signature === expectedSchemaSignature())
         return "current";
     throw new ActivityStoreError("Local database format does not match this runtime. Use a new empty SUI_MCP_DATA_DIR; existing data is not converted or deleted.");
 }
@@ -335,7 +385,6 @@ export function initializeDatabase(db) {
         return;
     db.transaction(() => {
         db.exec(CURRENT_SCHEMA_SQL);
-        db.pragma(`user_version = ${DB_USER_VERSION}`);
     })();
 }
 function externalActivityScansTableSql() {
@@ -365,3 +414,25 @@ function externalActivityScansTableSql() {
     )
   )`;
 }
+// Exported user data has one durable revision, including writers outside Settings.
+// A prepared confirmation is invalidated once, in the writer's own transaction.
+function settingsRevisionTriggers() {
+    const userTables = ["accounts", "active_account_context", "review_sessions", "review_state_snapshots",
+        "review_status_transitions", "review_executions", "review_requests", "external_activity_scans",
+        "external_activity_transactions", "local_settings"];
+    const walletTables = ["live_wallet_connections", "live_review_sessions", "live_request_authority"];
+    const invalidate = (condition) => `
+    UPDATE live_read_cards SET revision=revision+1
+      WHERE id IN (SELECT card_id FROM settings_operations WHERE phase='prepared' AND (${condition}));
+    ${SETTINGS_RESET_PREPARATION_SQL}
+      WHERE phase='prepared' AND (${condition});`;
+    return [...new Set([...userTables, ...walletTables])].flatMap((table) => ["INSERT", "UPDATE", "DELETE"].map((event) => `
+      CREATE TRIGGER settings_revision_${table}_${event.toLowerCase()} AFTER ${event} ON ${table}
+      BEGIN
+        ${userTables.includes(table) ? "UPDATE settings_control SET user_data_revision=user_data_revision+1 WHERE id=1;" : ""}
+        ${invalidate([...(userTables.includes(table) ? ["kind IN ('import_local_data','reset_local_data')"] : []),
+        ...(walletTables.includes(table) || table === "review_requests" ? ["kind='restart_wallet_service'"] : []),
+        ...(table === "local_settings" ? ["kind IN ('set_endpoint','restore_endpoint')"] : []),
+        ...(table === "active_account_context" ? ["kind='clear_read_address'"] : [])].join(" OR ") || "0")}
+      END;`)).join("\n");
+}

package/dist/core/preferences/sqlitePreferencesRepository.js

@@ -56,7 +56,8 @@ export class SqlitePreferencesRepository {
     async resetSuiGraphqlUrl(defaultUrl, now = new Date()) {
         return this.setSuiGraphqlUrl(defaultUrl, now);
     }
-    async getLocalSetting(key) {
+    async getLocalSetting(key) { return this.getLocalSettingSync(key); }
+    getLocalSettingSync(key) {
         const settingKey = assertLocalSettingKey(key);
         const row = this.db
             .prepare(`SELECT key, value_json, updated_at
@@ -65,7 +66,8 @@ export class SqlitePreferencesRepository {
             .get(settingKey);
         return row ? rowToLocalSetting(row) : undefined;
     }
-    async setLocalSetting(key, value, now = new Date()) {
+    async setLocalSetting(key, value, now = new Date()) { return this.setLocalSettingSync(key, value, now); }
+    setLocalSettingSync(key, value, now = new Date()) {
         const settingKey = assertLocalSettingKey(key);
         this.db
             .prepare(`INSERT INTO local_settings (key, value_json, updated_at)
@@ -74,7 +76,7 @@ export class SqlitePreferencesRepository {
            value_json = excluded.value_json,
            updated_at = excluded.updated_at`)
             .run(settingKey, encodeSettingValue(settingKey, value), now.toISOString());
-        const record = await this.getLocalSetting(settingKey);
+        const record = this.getLocalSettingSync(settingKey);
         if (!record) {
             throw new PreferencesStoreError("not_recorded", "Local setting was not recorded", { key: settingKey });
         }

package/dist/core/session/cardSession.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 export const walletDisplaySchema = z.object({
     connectionId: z.string().min(1), pairingUri: z.string().startsWith("wc:"), expiresAt: z.string().datetime()
 }).strict();
-export const cardKindSchema = z.enum(["account", "receipt", "chart", "connect", "review"]);
+export const cardKindSchema = z.enum(["account", "receipt", "chart", "connect", "review", "settings"]);
 export const cardStateSchema = z.object({
     cardId: z.string().min(1), kind: cardKindSchema,
     state: z.enum(["ready", "running", "closed"]),