@zktx.io/sui-mcp 0.5.0 → 0.6.0

package/dist/core/session/sqliteSessionStore.js

@@ -126,46 +126,6 @@ export class SqlitePrivateReviewArtifactStore {
         this.db.prepare(`DELETE FROM live_private_review_artifacts`).run();
     }
 }
-/**
- * SQLite-backed id-keyed store for the short-lived settings
- * session manager. Each record is a JSON blob keyed by id; the table name is a
- * trusted constant supplied by the factories below (never user input).
- */
-export class SqliteKeyedRecordStore {
-    db;
-    table;
-    revive;
-    constructor(db, table, revive) {
-        this.db = db;
-        this.table = table;
-        this.revive = revive;
-    }
-    get(id) {
-        const row = this.db
-            .prepare(`SELECT session_json FROM ${this.table} WHERE id = ?`)
-            .get(id);
-        return row ? this.revive(JSON.parse(row.session_json)) : undefined;
-    }
-    set(id, value) {
-        this.db
-            .prepare(`INSERT INTO ${this.table} (id, session_json) VALUES (?, ?)
-         ON CONFLICT(id) DO UPDATE SET session_json = excluded.session_json`)
-            .run(id, JSON.stringify(value));
-    }
-    delete(id) {
-        this.db.prepare(`DELETE FROM ${this.table} WHERE id = ?`).run(id);
-    }
-    ids() {
-        const rows = this.db.prepare(`SELECT id FROM ${this.table}`).all();
-        return rows.map((row) => row.id);
-    }
-    clear() {
-        this.db.prepare(`DELETE FROM ${this.table}`).run();
-    }
-}
-export function createSqliteSettingsRecordStore(db) {
-    return new SqliteKeyedRecordStore(db, "live_settings_sessions", (raw) => raw);
-}
 // Reconstruct the ReviewSession from columns + JSON blobs. Optional fields are
 // omitted (not set to undefined) so the shape matches the in-memory store exactly.
 export function sessionFromLiveReviewSessionRow(row) {

package/dist/core/session/sqliteSettingsWorkflowStore.js

@@ -0,0 +1,463 @@
+import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { SqliteCardRecordStore } from "./sqliteCardStore.js";
+import { SettingsConflict, settingsDownload, storedSettingsDownloadSchema, settingsDraftSchema, settingsResultSchema, retainedBackupRejection } from "./settingsOperation.js";
+import { isSettingsDownloadFile, settingsBackupPath, SETTINGS_FILE_CLEANUP_SQL } from "./settingsFileIdentity.js";
+import { SETTINGS_REUSABLE_UPLOAD_SQL, SETTINGS_RESET_PREPARATION_SQL } from "./settingsPreparationSql.js";
+/** Settings transitions share the activity owner's SQLite connection and card CAS.
+ * Network and filesystem work must remain outside these transactions. */
+export class SqliteSettingsWorkflowStore {
+    db;
+    ownerId;
+    now;
+    cards;
+    constructor(db, ownerId, now = () => new Date()) {
+        this.db = db;
+        this.ownerId = ownerId;
+        this.now = now;
+        this.cards = new SqliteCardRecordStore(db);
+    }
+    transaction(work) { return this.db.transaction(work).immediate(); }
+    control() { return this.db.prepare("SELECT * FROM settings_control WHERE id=1").get(); }
+    create(record) {
+        this.transaction(() => {
+            if (record.scope !== "settings" || record.state.kind !== "settings" || !record.operationId || record.ownerId !== this.ownerId) {
+                throw new SettingsConflict("This Settings card could not be identified.");
+            }
+            this.cards.create(record);
+            this.db.prepare(`INSERT INTO settings_operations (operation_id,card_id,owner_id,data_epoch,phase)
+        VALUES (?,?,?,?,'draft')`).run(record.operationId, record.state.cardId, this.ownerId, this.control().data_epoch);
+        });
+    }
+    get(id) {
+        const row = this.db.prepare("SELECT * FROM settings_operations WHERE operation_id=?").get(id);
+        if (!row)
+            return undefined;
+        return { operationId: row.operation_id, cardId: row.card_id, ownerId: row.owner_id, dataEpoch: row.data_epoch, phase: row.phase,
+            ...(row.draft_json === null ? {} : { draft: settingsDraftSchema.parse(JSON.parse(row.draft_json)) }),
+            ...(row.preparation_id === null ? {} : { preparationId: row.preparation_id }),
+            ...(row.fingerprint === null ? {} : { fingerprint: row.fingerprint }),
+            ...(row.prepared_user_data_revision === null ? {} : { preparedUserDataRevision: row.prepared_user_data_revision }),
+            ...(row.preparation_json === null ? {} : { preparation: JSON.parse(row.preparation_json) }),
+            ...(row.file_id === null ? {} : { fileId: row.file_id }),
+            ...(row.accepted_digest === null ? {} : { acceptedDigest: row.accepted_digest }),
+            ...(row.admitted_at === null ? {} : { admittedAt: row.admitted_at }),
+            ...(row.result_json === null ? {} : { result: settingsResultSchema.parse(JSON.parse(row.result_json)) }),
+            ...(row.prior_run_id === null ? {} : { priorRunId: row.prior_run_id }),
+            ...(row.next_run_id === null ? {} : { nextRunId: row.next_run_id }),
+            ...(row.supersedes_operation_id === null ? {} : { supersedesOperationId: row.supersedes_operation_id }),
+            ...(row.superseded_by_operation_id === null ? {} : { supersededByOperationId: row.superseded_by_operation_id }),
+            ...(row.checkpoint === null ? {} : { checkpoint: row.checkpoint }) };
+    }
+    forCard(record) {
+        const operation = record.operationId && this.get(record.operationId);
+        if (!operation || operation.cardId !== record.state.cardId || record.scope !== "settings") {
+            throw new SettingsConflict("This Settings request does not match the open card.");
+        }
+        return operation;
+    }
+    requireInput(expected, operationId, now = this.now()) {
+        const card = this.cards.get(expected.state.cardId);
+        if (!card || card.ownerId !== this.ownerId || card.tokenHash !== expected.tokenHash || card.scope !== "settings" ||
+            card.state.kind !== "settings" || card.state.revision !== expected.state.revision ||
+            card.state.state !== "ready" || card.acceptedInput !== undefined || Date.parse(card.state.expiresAt) <= now.getTime()) {
+            throw new SettingsConflict("This Settings selection changed or its time limit ended.");
+        }
+        const operation = this.forCard(card);
+        if (operationId !== undefined && operation.operationId !== operationId || operation.ownerId !== this.ownerId ||
+            operation.dataEpoch !== this.control().data_epoch || operation.phase === "terminal") {
+            throw new SettingsConflict("This Settings selection is out of date.");
+        }
+        return { card, operation };
+    }
+    write(expected, next, card, nextCard) {
+        this.transaction(() => {
+            if (!isDeepStrictEqual(this.get(expected.operationId), expected) || next.operationId !== expected.operationId ||
+                next.cardId !== expected.cardId || next.ownerId !== expected.ownerId)
+                throw new SettingsConflict("Settings state changed before it could be saved.");
+            this.db.prepare(`UPDATE settings_operations SET data_epoch=@epoch,kind=@kind,phase=@phase,draft_json=@draft,
+        preparation_id=@preparationId,fingerprint=@fingerprint,prepared_user_data_revision=@userRevision,preparation_json=@preparation,
+        file_id=@fileId,accepted_digest=@accepted,admitted_at=@admitted,result_json=@result,
+        prior_run_id=@prior,next_run_id=@next,supersedes_operation_id=@supersedes,superseded_by_operation_id=@supersededBy,checkpoint=@checkpoint
+        WHERE operation_id=@id`).run({ id: next.operationId, epoch: next.dataEpoch, kind: next.draft?.kind ?? null,
+                phase: next.phase, draft: next.draft ? JSON.stringify(next.draft) : null, preparationId: next.preparationId ?? null,
+                fingerprint: next.fingerprint ?? null, userRevision: next.preparedUserDataRevision ?? null,
+                preparation: next.preparation ? JSON.stringify(next.preparation) : null, fileId: next.fileId ?? null,
+                accepted: next.acceptedDigest ?? null, admitted: next.admittedAt ?? null, result: next.result ? JSON.stringify(next.result) : null,
+                prior: next.priorRunId ?? null, next: next.nextRunId ?? null,
+                supersedes: next.supersedesOperationId ?? null, supersededBy: next.supersededByOperationId ?? null, checkpoint: next.checkpoint ?? null });
+            if (!this.cards.replace(card, nextCard ?? { ...card, state: { ...card.state, revision: card.state.revision + 1 } })) {
+                throw new SettingsConflict("The Settings card changed before it could be saved.");
+            }
+        });
+    }
+    hasReusableUpload(operationId) {
+        return !!this.db.prepare(`SELECT 1 FROM settings_operations WHERE operation_id=? AND (${SETTINGS_REUSABLE_UPLOAD_SQL})`).get(operationId);
+    }
+    resetPreparation(expected, card) {
+        this.transaction(() => {
+            const current = this.requireInput(card, expected.operationId);
+            if (!isDeepStrictEqual(current.operation, expected))
+                throw new SettingsConflict("The Settings selection changed before it could be cleared.");
+            const rejection = retainedBackupRejection(current.operation, current.operation.fileId ? this.file(current.operation.fileId) : undefined);
+            this.db.prepare(`${SETTINGS_RESET_PREPARATION_SQL} WHERE operation_id=?`).run(expected.operationId);
+            if (rejection)
+                this.db.prepare("UPDATE settings_operations SET preparation_json=? WHERE operation_id=?")
+                    .run(JSON.stringify({ restoreCheck: rejection }), expected.operationId);
+            if (!this.cards.replace(current.card, { ...current.card, state: { ...current.card.state, revision: current.card.state.revision + 1 } })) {
+                throw new SettingsConflict("The Settings card changed before its selection could be cleared.");
+            }
+        });
+    }
+    claimFinal(id, replaceId) {
+        this.requireFinalSlot(replaceId);
+        this.db.prepare("UPDATE settings_control SET active_operation_id=? WHERE id=1").run(id);
+    }
+    fileIOAvailable(control = this.control()) { return control.file_io_id === null; }
+    canReserveFileIO(operationId) {
+        const control = this.control();
+        return this.fileIOAvailable(control) && (control.active_operation_id === null || control.active_operation_id === operationId);
+    }
+    // Read-only eligibility check shared by preparation and final admission.
+    requireFinalSlot(replaceId) {
+        const control = this.control();
+        if (!this.fileIOAvailable(control) || control.active_operation_id !== (replaceId ?? null)) {
+            throw new SettingsConflict("Another Settings change or file transfer is in progress. Check its result before confirming again.");
+        }
+    }
+    reserveFileIO(fileId, operationId) {
+        if (!this.canReserveFileIO(operationId)) {
+            throw new SettingsConflict("A file transfer or Settings change is in progress. Check its status before trying again.");
+        }
+        this.db.prepare("UPDATE settings_control SET file_io_id=? WHERE id=1").run(fileId);
+    }
+    releaseFileIO(fileId) {
+        this.db.prepare("UPDATE settings_control SET file_io_id=NULL WHERE id=1 AND file_io_id=?").run(fileId);
+    }
+    admit(expected, input, currentFingerprint, replaceOperationId, now = this.now()) {
+        return this.transaction(() => {
+            const { card, operation } = this.requireAdmission(expected, input, currentFingerprint, replaceOperationId, now);
+            this.claimFinal(operation.operationId, replaceOperationId);
+            const next = { ...operation, phase: operation.draft.kind === "restart_wallet_service" ? "stopping" : "executing",
+                acceptedDigest: settingsIdentity(input), admittedAt: now.toISOString() };
+            this.write(operation, next, card, { ...card, acceptedInput: input, state: { ...card.state,
+                    state: "running", revision: card.state.revision + 1 } });
+            return next;
+        });
+    }
+    // Pure admission checks let deadline reconciliation commit an expected refusal
+    // without claiming a final slot or consuming input. Admission uses the same rule.
+    requireAdmission(expected, input, currentFingerprint, replaceOperationId, now = this.now()) {
+        const result = this.requireInput(expected, input.operationId, now), operation = result.operation;
+        if (operation.phase !== "prepared" || !operation.draft || operation.preparationId !== input.preparationId ||
+            operation.fingerprint !== currentFingerprint())
+            throw new SettingsConflict("This change is out of date. Review it again before confirming.");
+        if (["import_local_data", "reset_local_data"].includes(operation.draft.kind) &&
+            operation.preparedUserDataRevision !== this.control().user_data_revision)
+            throw new SettingsConflict("Local records changed after they were checked. Review the current records before confirming.");
+        this.requireFinalSlot(replaceOperationId);
+        return result;
+    }
+    admitDownload(expected, input, snapshot) {
+        return this.transaction(() => {
+            const { card, operation } = this.requireInput(expected, input.operationId);
+            this.requireFinalSlot();
+            const file = snapshot(operation);
+            if (!isSettingsDownloadFile(file) || file.operationId !== operation.operationId)
+                throw new SettingsConflict("The download snapshot does not match this request.");
+            if (operation.fileId) {
+                const previous = this.file(operation.fileId);
+                if (previous?.role === "upload")
+                    this.writeFile({ ...previous, invalidated: true, cleanup: "pending" });
+            }
+            this.createFile(file);
+            this.claimFinal(operation.operationId);
+            this.reserveFileIO(file.fileId, operation.operationId);
+            const admittedAt = this.now().toISOString();
+            const download = { currentAttemptId: input.attemptId, attempts: [{ attemptId: input.attemptId, admittedAt }] };
+            const next = { operationId: operation.operationId, cardId: operation.cardId, ownerId: operation.ownerId,
+                dataEpoch: operation.dataEpoch, phase: "executing", draft: { kind: "download_backup" }, fileId: file.fileId,
+                preparation: { download }, acceptedDigest: settingsIdentity(input), admittedAt };
+            this.write(operation, next, card, { ...card, acceptedInput: input,
+                state: { ...card.state, state: "running", revision: card.state.revision + 1 } });
+            return file;
+        });
+    }
+    downloadContext(expected, operationId, fileId) {
+        const card = this.cards.get(expected.state.cardId);
+        if (!card || card.tokenHash !== expected.tokenHash || card.ownerId !== this.ownerId || card.scope !== "settings" || card.operationId !== operationId) {
+            throw new SettingsConflict("This download no longer belongs to the current Settings request.");
+        }
+        const operation = this.get(operationId), file = this.file(fileId);
+        if (!operation || operation.cardId !== card.state.cardId || operation.ownerId !== this.ownerId ||
+            operation.dataEpoch !== this.control().data_epoch || operation.fileId !== fileId || !file ||
+            file.operationId !== operationId || !isSettingsDownloadFile(file))
+            throw new SettingsConflict("This download no longer belongs to the current Settings request.");
+        const download = settingsDownload(operation);
+        if (!download)
+            throw new SettingsConflict("This Settings request does not provide a download.");
+        return { card, operation, file, download };
+    }
+    requireDownloadRead(expected, fileId, attemptId) {
+        const context = this.downloadContext(expected, expected.operationId, fileId), { operation, download, file } = context;
+        if (!attemptId || attemptId !== download.currentAttemptId || download.endReason || download.localSave || !download.expiresAt ||
+            this.now().getTime() >= Date.parse(download.expiresAt) || !file.sealed || file.invalidated ||
+            operation.result?.outcome !== "completed")
+            throw new SettingsConflict("This backup's download period has ended or its attempt changed.");
+        return context;
+    }
+    writeDownloadState(expected, download, card) {
+        storedSettingsDownloadSchema.parse(download);
+        this.transaction(() => {
+            if (!isDeepStrictEqual(this.get(expected.operationId), expected) || expected.draft?.kind !== "download_backup") {
+                throw new SettingsConflict("The download state changed before it could be saved.");
+            }
+            // A terminal result is immutable serialized evidence. Updating delivery
+            // state must not reserialize it, even with semantically identical keys.
+            this.db.prepare("UPDATE settings_operations SET preparation_json=? WHERE operation_id=?")
+                .run(JSON.stringify({ download }), expected.operationId);
+            if (!this.cards.replace(card, { ...card, state: { ...card.state, revision: card.state.revision + 1 } })) {
+                throw new SettingsConflict("The download card changed before its state could be saved.");
+            }
+        });
+    }
+    endDownload(id, reason) {
+        const operation = this.get(id);
+        if (!operation)
+            return;
+        const download = settingsDownload(operation), card = this.cards.get(operation.cardId);
+        if (!download || !card || download.endReason || download.localSave?.status === "saving")
+            return;
+        if (reason !== "server_restarted" && operation.ownerId !== this.ownerId)
+            throw new SettingsConflict("The download owner changed.");
+        const file = operation.fileId ? this.file(operation.fileId) : undefined;
+        if (file && isSettingsDownloadFile(file))
+            this.writeFile({ ...file, invalidated: true, cleanup: "pending" });
+        this.writeDownloadState(operation, { ...download, endReason: reason }, card);
+    }
+    expireDownloads(operationId) {
+        const now = this.now().getTime();
+        let failure;
+        for (const operation of this.downloads(operationId)) {
+            const download = settingsDownload(operation);
+            if (!download.endReason && download.localSave?.status !== "saving" && download.expiresAt && now >= Date.parse(download.expiresAt)) {
+                try {
+                    this.transaction(() => this.endDownload(operation.operationId, "expired"));
+                }
+                catch (error) {
+                    failure ??= error;
+                }
+            }
+        }
+        if (failure)
+            throw failure;
+    }
+    downloads(operationId) {
+        return this.db.prepare(`SELECT operation_id FROM settings_operations WHERE kind='download_backup' AND owner_id=?
+      ${operationId === undefined ? "" : "AND operation_id=?"}`)
+            .all(this.ownerId, ...(operationId === undefined ? [] : [operationId])).map((row) => this.get(row.operation_id));
+    }
+    continueDownload(expected, input) {
+        return this.transaction(() => {
+            // Validate the caller's scope before any target reads or expiry writes.
+            this.downloadContext(expected, input.operationId, input.fileId);
+            this.expireDownloads(input.operationId);
+            const { card, operation, file, download } = this.downloadContext(expected, input.operationId, input.fileId);
+            if (input.action === "settings_store_backup") {
+                const save = download.localSave;
+                const duplicate = save?.attempts.find((a) => a.saveAttemptId === input.saveAttemptId);
+                if (duplicate) {
+                    if (save.attemptId !== input.attemptId || duplicate.previousSaveAttemptId !== input.previousSaveAttemptId ||
+                        duplicate.allowPossibleCopy !== input.allowPossibleCopy)
+                        throw new SettingsConflict("This save does not match the recorded request.");
+                    return;
+                }
+                if (!save || save.attemptId !== input.attemptId || download.endReason || !download.expiresAt ||
+                    Date.parse(download.expiresAt) <= this.now().getTime() || file.invalidated || !file.sealed ||
+                    (save.status === "needs_consent" ? input.previousSaveAttemptId !== undefined :
+                        save.status !== "failed" || save.failure !== "not_published" || input.previousSaveAttemptId !== save.currentSaveAttemptId) ||
+                    input.allowPossibleCopy !== this.previousDeliveryPossible(download))
+                    throw new SettingsConflict("This backup cannot be saved by that request. Check its current status.");
+                const next = this.admitLocalSave(operation, file, save, input.saveAttemptId, input.allowPossibleCopy, input.previousSaveAttemptId);
+                this.writeDownloadState(operation, { ...download, localSave: next }, card);
+                return file;
+            }
+            if (input.action === "settings_retry_download") {
+                const duplicate = download.attempts.find((attempt) => attempt.attemptId === input.attemptId);
+                if (duplicate) {
+                    if (duplicate.previousAttemptId !== input.previousAttemptId)
+                        throw new SettingsConflict("This retry does not match the recorded download attempt.");
+                    return;
+                }
+                if (download.currentAttemptId !== input.previousAttemptId || download.endReason || download.localSave || !download.expiresAt || !file.sealed ||
+                    file.invalidated || operation.result?.outcome !== "completed")
+                    throw new SettingsConflict("This backup is no longer available for that retry.");
+                const next = { ...download, currentAttemptId: input.attemptId,
+                    attempts: [...download.attempts, { attemptId: input.attemptId, previousAttemptId: input.previousAttemptId, admittedAt: this.now().toISOString() }] };
+                this.writeDownloadState(operation, next, card);
+                return;
+            }
+            const entry = download.attempts.find((attempt) => attempt.attemptId === input.attemptId);
+            if (!entry)
+                throw new SettingsConflict("This download attempt was not admitted.");
+            if (input.action === "settings_report_download") {
+                if (!download.readyAt)
+                    throw new SettingsConflict("The download snapshot is not ready.");
+                if (entry.hostReport) {
+                    if (entry.hostReport !== input.status || !isDeepStrictEqual(entry.failure, input.failure))
+                        throw new SettingsConflict("A different result was already reported for this download attempt.");
+                    return;
+                }
+                const next = { ...download, attempts: download.attempts.map((attempt) => attempt === entry
+                        ? { ...attempt, hostReport: input.status, ...(input.failure ? { failure: input.failure } : {}) } : attempt) };
+                let admitted = false;
+                if (input.status === "unsupported" && input.attemptId === download.currentAttemptId && !download.endReason &&
+                    download.expiresAt && this.now().getTime() < Date.parse(download.expiresAt) && file.sealed && !file.invalidated) {
+                    const save = { status: "needs_consent", attemptId: input.attemptId, fileId: file.fileId,
+                        sha256: file.sha256, totalSize: file.totalSize, destination: settingsBackupPath(operation.operationId), ownerId: this.ownerId, attempts: [] };
+                    if (this.previousDeliveryPossible(download))
+                        next.localSave = save;
+                    else {
+                        next.localSave = this.admitLocalSave(operation, file, save, randomUUID(), false);
+                        admitted = true;
+                    }
+                }
+                this.writeDownloadState(operation, next, card);
+                if (input.attemptId === download.currentAttemptId && input.status === "acknowledged" && !download.endReason)
+                    this.endDownload(operation.operationId, "acknowledged");
+                return admitted ? file : undefined;
+            }
+            else {
+                if (input.attemptId !== download.currentAttemptId)
+                    throw new SettingsConflict("A different download attempt is current.");
+                if (download.localSave?.status === "saving")
+                    throw new SettingsConflict("Saving has already started. Check its result before continuing.");
+                this.endDownload(operation.operationId, "cancelled");
+            }
+        });
+    }
+    previousDeliveryPossible(download) {
+        return download.attempts.some((a) => a.attemptId !== download.currentAttemptId && a.hostReport !== "unsupported");
+    }
+    admitLocalSave(operation, file, saved, saveAttemptId, allowPossibleCopy, previousSaveAttemptId) {
+        this.claimFinal(operation.operationId);
+        this.reserveFileIO(file.fileId, operation.operationId);
+        const { failure: _failure, sourceIdentity: _identity, savedAt: _savedAt, ...base } = saved;
+        return { ...base, status: "saving", currentSaveAttemptId: saveAttemptId, attempts: [...saved.attempts,
+                { saveAttemptId, allowPossibleCopy, admittedAt: this.now().toISOString(), ...(previousSaveAttemptId ? { previousSaveAttemptId } : {}) }] };
+    }
+    localSaveContext(id, saveAttemptId) {
+        const operation = this.get(id), download = operation && settingsDownload(operation), save = download?.localSave;
+        const file = operation?.fileId ? this.file(operation.fileId) : undefined;
+        const card = operation && this.cards.get(operation.cardId);
+        if (!operation || operation.ownerId !== this.ownerId || operation.dataEpoch !== this.control().data_epoch ||
+            !download || !save || !file || !card || save.status !== "saving" || save.currentSaveAttemptId !== saveAttemptId ||
+            save.fileId !== file.fileId || save.sha256 !== file.sha256 || save.totalSize !== file.totalSize ||
+            save.destination !== settingsBackupPath(id) || this.control().active_operation_id !== id || this.control().file_io_id !== file.fileId) {
+            throw new SettingsConflict("The admitted backup save changed before it could be settled.");
+        }
+        return { operation, download, save, file, card };
+    }
+    rememberLocalSaveSource(id, saveAttemptId, sourceIdentity) {
+        this.transaction(() => {
+            const { operation, download, save, card } = this.localSaveContext(id, saveAttemptId);
+            if (save.sourceIdentity && !isDeepStrictEqual(save.sourceIdentity, sourceIdentity))
+                throw new SettingsConflict("The backup file changed before saving.");
+            this.writeDownloadState(operation, { ...download, localSave: { ...save, sourceIdentity } }, card);
+        });
+    }
+    settleLocalSave(id, saveAttemptId, outcome) {
+        this.transaction(() => {
+            const { operation, download, save, file, card } = this.localSaveContext(id, saveAttemptId);
+            const expired = !download.expiresAt || this.now().getTime() >= Date.parse(download.expiresAt);
+            const ended = outcome.status === "saved" ? "stored_locally" : save.ownerId !== this.ownerId ? "server_restarted"
+                : expired ? "expired" : outcome.reason !== "not_published" ? "local_save_failed" : undefined;
+            const localSave = outcome.status === "saved"
+                ? { ...save, status: "saved", savedAt: this.now().toISOString() }
+                : { ...save, status: "failed", failure: save.ownerId !== this.ownerId && outcome.reason === "not_published" ? "interrupted" : outcome.reason };
+            this.writeDownloadState(operation, { ...download, localSave, ...(ended ? { endReason: ended } : {}) }, card);
+            if (ended)
+                this.writeFile({ ...file, invalidated: true, cleanup: "pending" });
+            this.releaseFileIO(file.fileId);
+            this.db.prepare("UPDATE settings_control SET active_operation_id=NULL WHERE id=1 AND active_operation_id=?").run(id);
+        });
+    }
+    recordDownloadReady(id, readyAt, retryWindowMs) {
+        const operation = this.get(id);
+        if (!operation || operation.ownerId !== this.ownerId || operation.dataEpoch !== this.control().data_epoch)
+            throw new SettingsConflict("The snapshot owner changed.");
+        const download = settingsDownload(operation);
+        if (download.readyAt)
+            return;
+        const card = this.cards.get(operation.cardId);
+        this.writeDownloadState(operation, { ...download, readyAt,
+            expiresAt: new Date(Date.parse(readyAt) + retryWindowMs).toISOString() }, card);
+    }
+    filesForCleanup(operationId) {
+        const rows = this.db.prepare(`SELECT file_id FROM settings_files WHERE cleanup!='complete' AND ${SETTINGS_FILE_CLEANUP_SQL}
+      ${operationId === undefined ? "" : "AND cleanup_operation_id=?"}`).all(...(operationId === undefined ? [] : [operationId]));
+        return rows.map((row) => this.file(row.file_id));
+    }
+    finish(id, result) {
+        return this.transaction(() => {
+            const old = this.get(id);
+            if (!old || old.ownerId !== this.ownerId)
+                return false;
+            if (old.result)
+                return isDeepStrictEqual(old.result, result);
+            if (old.dataEpoch !== this.control().data_epoch)
+                return false;
+            if (result.outcome === "completed" && (!old.admittedAt || !old.acceptedDigest ||
+                !["executing", "starting"].includes(old.phase)))
+                throw new SettingsConflict("An unconfirmed Settings change cannot complete.");
+            const card = this.cards.get(old.cardId);
+            if (!card || card.ownerId !== this.ownerId || card.operationId !== id)
+                return false;
+            const next = { ...old, phase: "terminal", result };
+            this.write(old, next, card, { ...card, state: { ...card.state, revision: card.state.revision + 1,
+                    state: "closed", reason: card.state.reason ?? (result.outcome === "completed" ? "completed" : result.outcome === "superseded" || !old.admittedAt ? "cancelled" : "failed") } });
+            this.db.prepare(`UPDATE settings_control SET active_operation_id=NULL WHERE id=1 AND active_operation_id=?`).run(id);
+            this.db.prepare(`UPDATE settings_control SET wallet_input_blocked=0,wallet_block_operation_id=NULL
+        WHERE id=1 AND wallet_block_operation_id=?`).run(id);
+            return true;
+        });
+    }
+    file(id) {
+        const row = this.db.prepare("SELECT * FROM settings_files WHERE file_id=?").get(id);
+        return row ? { fileId: row.file_id, operationId: row.operation_id, role: row.role, relativePath: row.relative_path,
+            displayName: row.display_name, totalSize: row.total_size, receivedSize: row.received_size, sha256: row.sha256,
+            sealed: row.sealed === 1, invalidated: row.invalidated === 1, cleanup: row.cleanup,
+            cleanupOperationId: row.cleanup_operation_id,
+            ...(row.reservation_json === null ? {} : { reservation: JSON.parse(row.reservation_json) }) } : undefined;
+    }
+    filesNeedingCleanup(operationId) {
+        const rows = this.db.prepare(`SELECT file_id FROM settings_files WHERE cleanup_operation_id=? AND cleanup!='complete'
+      AND ${SETTINGS_FILE_CLEANUP_SQL}`).all(operationId);
+        return rows.map((row) => this.file(row.file_id));
+    }
+    temporaryFileCleanup(operationId) {
+        const row = this.db.prepare(`SELECT CASE WHEN sum(cleanup='failed')>0 THEN 'failed'
+      WHEN sum(cleanup='pending' OR file_id=(SELECT file_io_id FROM settings_control WHERE id=1))>0 THEN 'pending'
+      WHEN count(*)>0 THEN 'complete' ELSE NULL END AS status
+      FROM settings_files WHERE cleanup_operation_id=? AND ${SETTINGS_FILE_CLEANUP_SQL}`).get(operationId);
+        return row.status ?? undefined;
+    }
+    createFile(file) {
+        this.db.prepare(`INSERT INTO settings_files
+      (file_id,operation_id,cleanup_operation_id,role,relative_path,display_name,total_size,received_size,sha256,sealed,invalidated,cleanup,reservation_json)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(file.fileId, file.operationId, file.cleanupOperationId ?? file.operationId, file.role, file.relativePath, file.displayName, file.totalSize, file.receivedSize, file.sha256, Number(file.sealed), Number(file.invalidated), file.cleanup, file.reservation ? JSON.stringify(file.reservation) : null);
+    }
+    writeFile(file) {
+        if (this.db.prepare(`UPDATE settings_files SET received_size=?,sealed=?,invalidated=?,cleanup=?,reservation_json=? WHERE file_id=?`)
+            .run(file.receivedSize, Number(file.sealed), Number(file.invalidated), file.cleanup, file.reservation ? JSON.stringify(file.reservation) : null, file.fileId).changes !== 1) {
+            throw new SettingsConflict("The selected file is no longer available.");
+        }
+    }
+}
+// The input is already a strict typed action. Sort object keys recursively so
+// JSON-RPC ids and object insertion order never change business idempotency.
+export function settingsIdentity(value) {
+    const canonical = (input) => Array.isArray(input) ? input.map(canonical) : input !== null && typeof input === "object"
+        ? Object.fromEntries(Object.entries(input).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, canonical(item)])) : input;
+    return createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex");
+}