@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/core/activity/sqliteActivityStore.js

@@ -0,0 +1,820 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import Database from "better-sqlite3";
+import { assertNoForbiddenMcpFields } from "../action/forbiddenFields.js";
+import { parseLifecycleValidatedReviewState } from "../action/reviewStateValidation.js";
+import { actionPlanSchema, executionResultSchema } from "../action/schemas.js";
+import { parseSuiAddress } from "../suiAddress.js";
+import { SqlitePreferencesRepository } from "../preferences/sqlitePreferencesRepository.js";
+import { SqliteLocalDataService } from "./localDataService.js";
+import { ActivityStoreReadError, REVIEW_ACTIVITY_DETAIL_MAX_ITEMS, REVIEW_ACTIVITY_LOW_SAMPLE_THRESHOLD } from "./activityStore.js";
+import { configureDatabase, initializeDatabase } from "./sqliteActivityStoreSchema.js";
+import { ActivityStoreError } from "./sqliteActivityStoreTypes.js";
+import { EXTERNAL_ACTIVITY_RELATIONSHIPS, EXTERNAL_ACTIVITY_STATUSES, INTERNAL_SESSION_STATUSES, REVIEW_STATE_STATUSES, REVIEW_TRANSITION_EVENTS, asAccountSource, asInternalSessionStatus, asReviewTransitionEvent, asString, assertDateRange, canAdvanceReviewExecution, coinMetadataCacheRecordFromRow, countMap, emptyExternalActivitySummaryStats, emptyReviewFunnelSummary, externalActivityScanFromRow, externalActivitySummaryResult, externalActivityTransactionFromRow, extractRequestedIntent, isSameReviewExecution, normalizeExternalActivityLimit, normalizeListLimit, nullableSeconds, parseActionPlanEvidence, parseEvidenceJson, parseIsoTimestamp, parseOptionalIsoTimestamp, reasonForReviewState, reviewActivityListResult, reviewActivityRowFromStorage, reviewFunnelResult, reviewSessionWhere, serializeExternalActivityTransactionDetail, serializeJson, serializeOptionalJson } from "./sqliteActivityStoreRows.js";
+export { ActivityStoreError };
+const ACTIVE_ACCOUNT_SINGLETON_ID = 1;
+export const DATA_DIR_ENV = "SAY_UR_INTENT_DATA_DIR";
+export const ACTIVITY_DATABASE_FILENAME = "say-ur-intent.sqlite";
+export class SqliteActivityStore {
+    db;
+    validateAdapterLifecycle;
+    constructor(options) {
+        this.validateAdapterLifecycle = options.validateAdapterLifecycle;
+        try {
+            mkdirSync(dirname(options.databasePath), { recursive: true });
+        }
+        catch {
+            throw new ActivityStoreError(`Could not create the local activity data directory. Check directory permissions or set ${DATA_DIR_ENV}.`);
+        }
+        this.db = new Database(options.databasePath);
+        try {
+            configureDatabase(this.db);
+            initializeDatabase(this.db);
+        }
+        catch (error) {
+            this.db.close();
+            throw error;
+        }
+    }
+    async upsertAccount(address, source, now = new Date()) {
+        return this.upsertAccountSync(address, source, now.toISOString());
+    }
+    async getKnownAccount(address) {
+        const normalized = parseSuiAddress(address);
+        if (!normalized) {
+            throw new ActivityStoreReadError("input_invalid", "Invalid account address", { field: "account" });
+        }
+        return this.getAccountByAddressSync(normalized);
+    }
+    async setActiveAccount(address, source, now = new Date(), wallet) {
+        const timestamp = now.toISOString();
+        return this.db.transaction(() => {
+            const account = this.upsertAccountSync(address, source, timestamp);
+            this.db
+                .prepare(`INSERT INTO active_account_context (id, account_id, source, set_at, wallet_name, wallet_id)
+           VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET
+             account_id = excluded.account_id,
+             source = excluded.source,
+             set_at = excluded.set_at,
+             wallet_name = excluded.wallet_name,
+             wallet_id = excluded.wallet_id`)
+                .run(ACTIVE_ACCOUNT_SINGLETON_ID, account.id, source, timestamp, wallet?.name ?? null, wallet?.id ?? null);
+            return {
+                accountId: account.id,
+                address: account.address,
+                source,
+                setAt: timestamp,
+                ...(wallet?.name ? { walletName: wallet.name } : {}),
+                ...(wallet?.id ? { walletId: wallet.id } : {})
+            };
+        })();
+    }
+    async getActiveAccount() {
+        return this.getActiveAccountSync();
+    }
+    async clearActiveAccount(now = new Date()) {
+        this.db
+            .prepare(`INSERT INTO active_account_context (id, account_id, source, set_at)
+         VALUES (?, NULL, 'cleared', ?)
+         ON CONFLICT(id) DO UPDATE SET
+           account_id = NULL,
+           source = 'cleared',
+           set_at = excluded.set_at`)
+            .run(ACTIVE_ACCOUNT_SINGLETON_ID, now.toISOString());
+    }
+    async recordReviewSession(input) {
+        const plan = parseActionPlanEvidence(input.plan);
+        const planJson = serializeJson(plan);
+        const intentJson = serializeOptionalJson(extractRequestedIntent(plan));
+        this.db
+            .transaction(() => {
+            this.db
+                .prepare(`INSERT INTO review_sessions
+               (id, plan_id, action_kind, adapter_id, protocol, current_status,
+                plan_json, intent_json, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(input.reviewSessionId, plan.id, plan.actionKind, plan.adapterId, plan.protocol, input.currentStatus, planJson, intentJson, input.createdAt, input.createdAt);
+            this.insertReviewTransition({
+                reviewSessionId: input.reviewSessionId,
+                event: "created",
+                toStatus: input.currentStatus,
+                transitionedAt: input.createdAt
+            });
+        })();
+    }
+    async recordReviewTransition(input) {
+        this.db
+            .transaction(() => {
+            const accountId = input.account
+                ? this.upsertAccountSync(input.account, "review_execution", input.transitionedAt).id
+                : null;
+            if (accountId !== null) {
+                this.assertReviewSessionAccount(input.reviewSessionId, accountId);
+            }
+            this.insertReviewTransition({ ...input, accountId });
+            this.db
+                .prepare(`UPDATE review_sessions
+             SET current_status = ?, account_id = COALESCE(account_id, ?), updated_at = ?
+             WHERE id = ?`)
+                .run(input.toStatus, accountId, input.transitionedAt, input.reviewSessionId);
+        })();
+    }
+    async recordReviewStateSnapshot(input) {
+        const parsedState = parseLifecycleValidatedReviewState(input.state, this.validateAdapterLifecycle);
+        const stateJson = serializeJson(parsedState);
+        this.db
+            .transaction(() => {
+            const account = this.upsertAccountSync(parsedState.account, "review_execution", input.recordedAt);
+            this.assertReviewSessionAccount(input.reviewSessionId, account.id);
+            this.db
+                .prepare(`INSERT INTO review_state_snapshots
+               (review_session_id, plan_id, account_id, status, blocked_reason, refresh_reason,
+                state_json, updated_at, recorded_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(input.reviewSessionId, parsedState.planId, account.id, parsedState.status, "blockedReason" in parsedState ? parsedState.blockedReason : null, "refreshReason" in parsedState ? parsedState.refreshReason : null, stateJson, parsedState.updatedAt, input.recordedAt);
+            this.insertReviewTransition({
+                reviewSessionId: input.reviewSessionId,
+                event: "state_computed",
+                fromStatus: input.fromStatus,
+                toStatus: parsedState.status,
+                accountId: account.id,
+                reason: reasonForReviewState(parsedState),
+                transitionedAt: input.recordedAt
+            });
+            this.db
+                .prepare(`UPDATE review_sessions
+             SET current_status = ?, account_id = ?, updated_at = ?
+             WHERE id = ?`)
+                .run(parsedState.status, account.id, input.recordedAt, input.reviewSessionId);
+        })();
+    }
+    async recordReviewExecution(input) {
+        const resultJson = serializeJson(input.result);
+        this.db
+            .transaction(() => {
+            const account = this.upsertAccountSync(input.account, "review_execution", input.recordedAt);
+            this.assertReviewSessionAccount(input.reviewSessionId, account.id);
+            const existing = this.getReviewExecutionStorageRow(input.reviewSessionId);
+            if (existing) {
+                if (isSameReviewExecution(existing, account.id, input)) {
+                    return;
+                }
+                if (!canAdvanceReviewExecution(existing, account.id, input)) {
+                    throw new ActivityStoreError(`Conflicting review execution evidence: ${input.reviewSessionId}`);
+                }
+            }
+            this.db
+                .prepare(`INSERT INTO review_executions
+               (review_session_id, plan_id, account_id, status, tx_digest, explorer_url,
+                failure_reason, result_json, recorded_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+             ON CONFLICT(review_session_id) DO UPDATE SET
+               plan_id = excluded.plan_id,
+               account_id = excluded.account_id,
+               status = excluded.status,
+               tx_digest = excluded.tx_digest,
+               explorer_url = excluded.explorer_url,
+               failure_reason = excluded.failure_reason,
+               result_json = excluded.result_json,
+               updated_at = excluded.updated_at`)
+                .run(input.reviewSessionId, input.planId, account.id, input.status, input.txDigest ?? null, input.explorerUrl ?? null, input.failureReason ?? null, resultJson, input.recordedAt, input.recordedAt);
+            this.insertReviewTransition({
+                reviewSessionId: input.reviewSessionId,
+                event: "result_recorded",
+                fromStatus: input.fromStatus,
+                toStatus: input.status,
+                accountId: account.id,
+                reason: input.failureReason,
+                transitionedAt: input.recordedAt
+            });
+            this.db
+                .prepare(`UPDATE review_sessions
+             SET current_status = ?, account_id = ?, updated_at = ?
+             WHERE id = ?`)
+                .run(input.status, account.id, input.recordedAt, input.reviewSessionId);
+        })();
+        const recorded = await this.getReviewExecution(input.reviewSessionId);
+        if (!recorded) {
+            throw new ActivityStoreError(`Review execution was not recorded: ${input.reviewSessionId}`);
+        }
+        return recorded;
+    }
+    getReviewExecutionStorageRow(reviewSessionId) {
+        return this.db
+            .prepare(`SELECT review_session_id, plan_id, account_id, status, tx_digest, explorer_url, failure_reason
+         FROM review_executions
+         WHERE review_session_id = ?`)
+            .get(reviewSessionId);
+    }
+    async getReviewExecution(reviewSessionId) {
+        const row = this.db
+            .prepare(`SELECT r.review_session_id, r.plan_id, r.account_id, a.sui_address AS account,
+                r.status, r.tx_digest, r.explorer_url, r.failure_reason, r.recorded_at, r.updated_at
+         FROM review_executions r
+         JOIN accounts a ON a.id = r.account_id
+         WHERE r.review_session_id = ?`)
+            .get(reviewSessionId);
+        return row
+            ? {
+                reviewSessionId: asString(row.review_session_id),
+                planId: asString(row.plan_id),
+                accountId: row.account_id,
+                account: asString(row.account),
+                status: asString(row.status),
+                txDigest: row.tx_digest === null ? undefined : asString(row.tx_digest),
+                explorerUrl: row.explorer_url === null ? undefined : asString(row.explorer_url),
+                failureReason: row.failure_reason === null ? undefined : asString(row.failure_reason),
+                recordedAt: asString(row.recorded_at),
+                updatedAt: asString(row.updated_at)
+            }
+            : undefined;
+    }
+    async listReviewActivity(filter) {
+        const from = parseOptionalIsoTimestamp(filter.from, "from");
+        const to = parseOptionalIsoTimestamp(filter.to, "to");
+        assertDateRange(from, to);
+        const limit = normalizeListLimit(filter.limit);
+        const scope = this.resolveReviewActivityScope(filter);
+        if (scope.accountId === undefined) {
+            return reviewActivityListResult(scope, from, to, [], false, 0);
+        }
+        const { whereSql, params } = reviewSessionWhere(scope.accountId, from, to, filter.status);
+        const totalRow = this.db
+            .prepare(`SELECT COUNT(*) AS count FROM review_sessions rs ${whereSql}`)
+            .get(...params);
+        const rows = this.db
+            .prepare(`SELECT rs.id AS review_session_id, rs.plan_id, rs.action_kind, rs.adapter_id, rs.protocol,
+                rs.current_status, a.sui_address AS account, rs.created_at, rs.updated_at,
+                re.status AS execution_status, re.tx_digest,
+                (SELECT COUNT(*) FROM review_state_snapshots s WHERE s.review_session_id = rs.id) AS snapshot_count,
+                (SELECT COUNT(*) FROM review_status_transitions t WHERE t.review_session_id = rs.id) AS transition_count
+         FROM review_sessions rs
+         JOIN accounts a ON a.id = rs.account_id
+         LEFT JOIN review_executions re ON re.review_session_id = rs.id
+         ${whereSql}
+         ORDER BY rs.created_at DESC, rs.id DESC
+         LIMIT ?`)
+            .all(...params, limit + 1);
+        const truncated = rows.length > limit;
+        const activities = rows.slice(0, limit).map(reviewActivityRowFromStorage);
+        return reviewActivityListResult(scope, from, to, activities, truncated, totalRow.count);
+    }
+    async summarizeReviewFunnel(filter) {
+        const from = parseOptionalIsoTimestamp(filter.from, "from");
+        const to = parseOptionalIsoTimestamp(filter.to, "to");
+        assertDateRange(from, to);
+        const scope = this.resolveReviewActivityScope(filter);
+        if (scope.accountId === undefined) {
+            return reviewFunnelResult(scope, from, to, emptyReviewFunnelSummary(), 0);
+        }
+        const { whereSql, params } = reviewSessionWhere(scope.accountId, from, to);
+        const total = this.db
+            .prepare(`SELECT COUNT(*) AS count FROM review_sessions rs ${whereSql}`)
+            .get(...params).count;
+        const eventCounts = this.db
+            .prepare(`SELECT t.event AS key, COUNT(DISTINCT t.review_session_id) AS count
+         FROM review_status_transitions t
+         JOIN review_sessions rs ON rs.id = t.review_session_id
+         ${whereSql}
+         GROUP BY t.event`)
+            .all(...params);
+        const currentStatusCounts = this.db
+            .prepare(`SELECT rs.current_status AS key, COUNT(*) AS count
+         FROM review_sessions rs
+         ${whereSql}
+         GROUP BY rs.current_status`)
+            .all(...params);
+        const reachedStateCounts = this.db
+            .prepare(`SELECT t.to_status AS key, COUNT(DISTINCT t.review_session_id) AS count
+         FROM review_status_transitions t
+         JOIN review_sessions rs ON rs.id = t.review_session_id
+         ${whereSql}
+           AND t.to_status IN ('ready_for_wallet_review', 'blocked', 'refresh_required')
+         GROUP BY t.to_status`)
+            .all(...params);
+        const signedPending = this.db
+            .prepare(`SELECT COUNT(DISTINCT t.review_session_id) AS count
+         FROM review_status_transitions t
+         JOIN review_sessions rs ON rs.id = t.review_session_id
+         ${whereSql}
+           AND t.event = 'result_recorded'
+           AND t.to_status = 'signed_pending_result'`)
+            .get(...params).count;
+        const expiredBeforeResult = this.db
+            .prepare(`SELECT COUNT(*) AS count
+         FROM review_sessions rs
+         LEFT JOIN review_executions re ON re.review_session_id = rs.id
+         ${whereSql}
+           AND rs.current_status = 'expired'
+           AND re.review_session_id IS NULL`)
+            .get(...params).count;
+        const timing = this.db
+            .prepare(`WITH scoped AS (
+           SELECT rs.id, rs.created_at
+           FROM review_sessions rs
+           ${whereSql}
+         ),
+         signed AS (
+           SELECT review_session_id, MIN(transitioned_at) AS signed_at
+           FROM review_status_transitions
+           WHERE event = 'result_recorded' AND to_status = 'signed_pending_result'
+           GROUP BY review_session_id
+         ),
+         opened AS (
+           SELECT review_session_id, MIN(transitioned_at) AS opened_at
+           FROM review_status_transitions
+           WHERE event = 'opened'
+           GROUP BY review_session_id
+         )
+         SELECT
+           AVG((julianday(signed.signed_at) - julianday(scoped.created_at)) * 86400.0) AS avg_created_to_signed,
+           AVG(
+             CASE
+               WHEN opened.opened_at IS NULL THEN NULL
+               ELSE (julianday(signed.signed_at) - julianday(opened.opened_at)) * 86400.0
+             END
+           ) AS avg_opened_to_signed
+         FROM scoped
+         JOIN signed ON signed.review_session_id = scoped.id
+         LEFT JOIN opened ON opened.review_session_id = scoped.id`)
+            .get(...params);
+        const currentStatus = countMap(INTERNAL_SESSION_STATUSES, currentStatusCounts);
+        const reachedStates = countMap(REVIEW_STATE_STATUSES, reachedStateCounts);
+        const events = countMap(REVIEW_TRANSITION_EVENTS, eventCounts);
+        const summary = {
+            total,
+            opened: events.opened,
+            walletConnected: events.wallet_connected,
+            stateComputed: events.state_computed,
+            currentStatusCounts: currentStatus,
+            everReachedReviewStateCounts: reachedStates,
+            signedPending,
+            success: currentStatus.success,
+            failure: currentStatus.failure,
+            expiredBeforeResult,
+            avgCreatedToSignedSeconds: nullableSeconds(timing.avg_created_to_signed),
+            avgOpenedToSignedSeconds: nullableSeconds(timing.avg_opened_to_signed)
+        };
+        return reviewFunnelResult(scope, from, to, summary, total);
+    }
+    async getReviewSessionDetail(input) {
+        const scope = this.resolveReviewActivityScope({ account: input.account });
+        if (scope.accountId === undefined) {
+            throw new ActivityStoreReadError("session_not_found", "Review session not found", {
+                reviewSessionId: input.reviewSessionId
+            });
+        }
+        const row = this.db
+            .prepare(`SELECT rs.id AS review_session_id, rs.plan_id, rs.action_kind, rs.adapter_id, rs.protocol,
+                rs.current_status, a.sui_address AS account, rs.created_at, rs.updated_at,
+                rs.plan_json, rs.intent_json,
+                re.status AS execution_status, re.tx_digest, re.explorer_url, re.failure_reason,
+                re.recorded_at AS execution_recorded_at, re.updated_at AS execution_updated_at,
+                re.result_json
+         FROM review_sessions rs
+         JOIN accounts a ON a.id = rs.account_id
+         LEFT JOIN review_executions re ON re.review_session_id = rs.id
+         WHERE rs.id = ? AND rs.account_id = ?`)
+            .get(input.reviewSessionId, scope.accountId);
+        if (!row) {
+            throw new ActivityStoreReadError("session_not_found", "Review session not found", {
+                reviewSessionId: input.reviewSessionId
+            });
+        }
+        const snapshotRows = this.db
+            .prepare(`SELECT s.id, s.plan_id, a.sui_address AS account, s.status, s.blocked_reason, s.refresh_reason,
+                s.state_json, s.updated_at, s.recorded_at
+         FROM review_state_snapshots s
+         JOIN accounts a ON a.id = s.account_id
+         WHERE s.review_session_id = ? AND s.account_id = ?
+         ORDER BY s.recorded_at ASC, s.id ASC
+         LIMIT ?`)
+            .all(input.reviewSessionId, scope.accountId, REVIEW_ACTIVITY_DETAIL_MAX_ITEMS + 1);
+        const transitionRows = this.db
+            .prepare(`SELECT t.id, t.event, t.from_status, t.to_status, a.sui_address AS account,
+                t.reason, t.transitioned_at
+         FROM review_status_transitions t
+         LEFT JOIN accounts a ON a.id = t.account_id
+         WHERE t.review_session_id = ? AND (t.account_id IS NULL OR t.account_id = ?)
+         ORDER BY t.transitioned_at ASC, t.id ASC
+         LIMIT ?`)
+            .all(input.reviewSessionId, scope.accountId, REVIEW_ACTIVITY_DETAIL_MAX_ITEMS + 1);
+        const recordCount = this.db
+            .prepare(`SELECT COUNT(*) AS count FROM review_sessions rs WHERE rs.account_id = ?`)
+            .get(scope.accountId).count;
+        const snapshotsTruncated = snapshotRows.length > REVIEW_ACTIVITY_DETAIL_MAX_ITEMS;
+        const transitionsTruncated = transitionRows.length > REVIEW_ACTIVITY_DETAIL_MAX_ITEMS;
+        const planJson = parseEvidenceJson(row.plan_json, input.reviewSessionId, "plan_json", actionPlanSchema);
+        const intentJson = row.intent_json === null
+            ? undefined
+            : parseEvidenceJson(row.intent_json, input.reviewSessionId, "intent_json");
+        const execution = row.execution_status === null
+            ? undefined
+            : {
+                reviewSessionId: asString(row.review_session_id),
+                planId: asString(row.plan_id),
+                accountId: scope.accountId,
+                account: asString(row.account),
+                status: asString(row.execution_status),
+                txDigest: row.tx_digest === null ? undefined : asString(row.tx_digest),
+                explorerUrl: row.explorer_url === null ? undefined : asString(row.explorer_url),
+                failureReason: row.failure_reason === null ? undefined : asString(row.failure_reason),
+                recordedAt: asString(row.execution_recorded_at),
+                updatedAt: asString(row.execution_updated_at),
+                resultJson: parseEvidenceJson(row.result_json, input.reviewSessionId, "result_json", executionResultSchema)
+            };
+        return {
+            dataScope: {
+                account: scope.account,
+                recordCount
+            },
+            accountSource: scope.accountSource,
+            lowSampleWarning: recordCount < REVIEW_ACTIVITY_LOW_SAMPLE_THRESHOLD,
+            lowSampleThreshold: REVIEW_ACTIVITY_LOW_SAMPLE_THRESHOLD,
+            session: {
+                reviewSessionId: asString(row.review_session_id),
+                planId: asString(row.plan_id),
+                actionKind: asString(row.action_kind),
+                adapterId: asString(row.adapter_id),
+                protocol: asString(row.protocol),
+                currentStatus: asInternalSessionStatus(row.current_status),
+                account: asString(row.account),
+                createdAt: asString(row.created_at),
+                updatedAt: asString(row.updated_at)
+            },
+            planJson,
+            intentJson,
+            stateSnapshots: snapshotRows.slice(0, REVIEW_ACTIVITY_DETAIL_MAX_ITEMS).map((snapshot) => ({
+                id: snapshot.id,
+                planId: asString(snapshot.plan_id),
+                account: asString(snapshot.account),
+                status: asString(snapshot.status),
+                blockedReason: snapshot.blocked_reason === null ? undefined : asString(snapshot.blocked_reason),
+                refreshReason: snapshot.refresh_reason === null ? undefined : asString(snapshot.refresh_reason),
+                stateJson: this.parseReviewStateEvidenceJson(snapshot.state_json, input.reviewSessionId, "state_json"),
+                updatedAt: asString(snapshot.updated_at),
+                recordedAt: asString(snapshot.recorded_at)
+            })),
+            transitions: transitionRows.slice(0, REVIEW_ACTIVITY_DETAIL_MAX_ITEMS).map((transitionRow) => ({
+                id: transitionRow.id,
+                event: asReviewTransitionEvent(transitionRow.event),
+                fromStatus: transitionRow.from_status === null ? undefined : asString(transitionRow.from_status),
+                toStatus: asString(transitionRow.to_status),
+                isNoOp: transitionRow.from_status !== null && asString(transitionRow.from_status) === asString(transitionRow.to_status),
+                account: transitionRow.account === null ? undefined : asString(transitionRow.account),
+                reason: transitionRow.reason === null ? undefined : asString(transitionRow.reason),
+                transitionedAt: asString(transitionRow.transitioned_at)
+            })),
+            execution,
+            truncated: {
+                activities: false,
+                snapshots: snapshotsTruncated,
+                transitions: transitionsTruncated
+            }
+        };
+    }
+    async recordExternalActivityScan(input) {
+        try {
+            assertNoForbiddenMcpFields(input);
+        }
+        catch {
+            throw new ActivityStoreReadError("input_invalid", "External activity scan contains forbidden fields", {
+                reason: "forbidden_field"
+            });
+        }
+        const account = await this.getKnownAccount(input.account);
+        if (!account) {
+            throw new ActivityStoreReadError("input_invalid", "External activity scan account is not a known wallet", {
+                reason: "account_not_known"
+            });
+        }
+        const fetchedAt = parseIsoTimestamp(input.fetchedAt, "fetchedAt");
+        const fromTimestamp = parseOptionalIsoTimestamp(input.fromTimestamp, "from");
+        const toTimestamp = parseOptionalIsoTimestamp(input.toTimestamp, "to");
+        assertDateRange(fromTimestamp, toTimestamp);
+        const record = this.db.transaction(() => {
+            this.db
+                .prepare(`INSERT INTO external_activity_scans
+             (scan_id, kind, account_id, relationship, input_digest, from_checkpoint, to_checkpoint,
+              from_timestamp, to_timestamp, limit_count, request_cursor, response_cursor, endpoint_host,
+              chain_identifier, fetched_at, stored_count, skipped_count, has_more, window_complete,
+              incomplete_reason)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(input.scanId, input.kind, account.id, input.relationship, input.inputDigest ?? null, input.fromCheckpoint ?? null, input.toCheckpoint ?? null, fromTimestamp ?? null, toTimestamp ?? null, input.limit, input.requestCursor ?? null, input.responseCursor ?? null, input.endpointHost, input.chainIdentifier, fetchedAt, 0, input.transactions.length, input.hasMore ? 1 : 0, input.windowComplete === null ? null : input.windowComplete ? 1 : 0, input.incompleteReason ?? null);
+            let storedCount = 0;
+            const skippedCount = input.skippedCount ?? 0;
+            const upsert = this.db.prepare(`INSERT INTO external_activity_transactions
+           (account_id, digest, relationship, checkpoint, timestamp, status, known_sender_account_id,
+            first_scan_id, last_scan_id, first_fetched_at, last_fetched_at, detail_json)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(account_id, digest, relationship) DO UPDATE SET
+           checkpoint = COALESCE(excluded.checkpoint, external_activity_transactions.checkpoint),
+           timestamp = COALESCE(excluded.timestamp, external_activity_transactions.timestamp),
+           status = excluded.status,
+           known_sender_account_id = COALESCE(excluded.known_sender_account_id, external_activity_transactions.known_sender_account_id),
+           last_scan_id = excluded.last_scan_id,
+           last_fetched_at = excluded.last_fetched_at,
+           detail_json = COALESCE(excluded.detail_json, external_activity_transactions.detail_json)`);
+            for (const transaction of input.transactions) {
+                if (transaction.knownSenderAccountId !== undefined && !this.accountIdExists(transaction.knownSenderAccountId)) {
+                    throw new ActivityStoreReadError("input_invalid", "External activity sender account is not known", {
+                        reason: "sender_account_not_known"
+                    });
+                }
+                upsert.run(account.id, transaction.digest, transaction.relationship, transaction.checkpoint ?? null, transaction.timestamp ? parseIsoTimestamp(transaction.timestamp, "transaction.timestamp") : null, transaction.status, transaction.knownSenderAccountId ?? null, input.scanId, input.scanId, fetchedAt, fetchedAt, transaction.details === undefined
+                    ? null
+                    : serializeExternalActivityTransactionDetail(transaction.details, account.address));
+                storedCount += 1;
+            }
+            this.db
+                .prepare(`UPDATE external_activity_scans
+           SET stored_count = ?, skipped_count = ?
+           WHERE scan_id = ?`)
+                .run(storedCount, skippedCount + input.transactions.length - storedCount, input.scanId);
+            return this.externalActivityScanById(input.scanId);
+        })();
+        if (!record) {
+            throw new ActivityStoreReadError("internal_error", "External activity scan was not recorded", {
+                scanId: input.scanId
+            });
+        }
+        return record;
+    }
+    async summarizeExternalActivity(filter) {
+        const from = parseOptionalIsoTimestamp(filter.from, "from");
+        const to = parseOptionalIsoTimestamp(filter.to, "to");
+        assertDateRange(from, to);
+        const limit = normalizeExternalActivityLimit(filter.limit);
+        const scope = this.resolveReviewActivityScope(filter);
+        if (scope.accountId === undefined) {
+            return externalActivitySummaryResult(scope, from, to, [], false, emptyExternalActivitySummaryStats());
+        }
+        const where = ["eat.account_id = ?"];
+        const params = [scope.accountId];
+        if (from !== undefined) {
+            where.push("eat.timestamp >= ?");
+            params.push(from);
+        }
+        if (to !== undefined) {
+            where.push("eat.timestamp <= ?");
+            params.push(to);
+        }
+        const whereSql = `WHERE ${where.join(" AND ")}`;
+        const total = this.db
+            .prepare(`SELECT COUNT(*) AS count FROM external_activity_transactions eat ${whereSql}`)
+            .get(...params).count;
+        const statusCounts = countMap(EXTERNAL_ACTIVITY_STATUSES, this.db
+            .prepare(`SELECT eat.status AS key, COUNT(*) AS count FROM external_activity_transactions eat ${whereSql} GROUP BY eat.status`)
+            .all(...params));
+        const relationshipCounts = countMap(EXTERNAL_ACTIVITY_RELATIONSHIPS, this.db
+            .prepare(`SELECT eat.relationship AS key, COUNT(*) AS count FROM external_activity_transactions eat ${whereSql} GROUP BY eat.relationship`)
+            .all(...params));
+        const timestampRow = this.db
+            .prepare(`SELECT MIN(eat.timestamp) AS earliest_timestamp, MAX(eat.timestamp) AS latest_timestamp
+         FROM external_activity_transactions eat
+         ${whereSql}`)
+            .get(...params);
+        const rows = this.db
+            .prepare(`SELECT eat.account_id, a.sui_address AS account, eat.digest, eat.relationship,
+                eat.checkpoint, eat.timestamp, eat.status, eat.known_sender_account_id,
+                eat.first_scan_id, eat.last_scan_id, eat.first_fetched_at, eat.last_fetched_at,
+                last_scan.incomplete_reason AS last_scan_incomplete_reason,
+                eat.detail_json
+         FROM external_activity_transactions eat
+         JOIN accounts a ON a.id = eat.account_id
+         LEFT JOIN external_activity_scans last_scan ON last_scan.scan_id = eat.last_scan_id
+         ${whereSql}
+         ORDER BY
+           CASE WHEN eat.checkpoint IS NULL THEN 0 ELSE 1 END DESC,
+           CAST(eat.checkpoint AS INTEGER) DESC,
+           COALESCE(eat.timestamp, '') DESC,
+           eat.digest DESC
+         LIMIT ?`)
+            .all(...params, limit + 1);
+        return externalActivitySummaryResult(scope, from, to, rows.slice(0, limit).map(externalActivityTransactionFromRow), rows.length > limit, {
+            transactionCount: total,
+            statusCounts,
+            relationshipCounts,
+            earliestTimestamp: timestampRow.earliest_timestamp ?? undefined,
+            latestTimestamp: timestampRow.latest_timestamp ?? undefined
+        });
+    }
+    close() {
+        this.db.close();
+    }
+    createPreferencesRepository() {
+        return new SqlitePreferencesRepository(this.db);
+    }
+    createLocalDataService(options) {
+        return new SqliteLocalDataService(this.db, options, this.validateAdapterLifecycle);
+    }
+    createCoinMetadataCache() {
+        return new SqliteCoinMetadataCache(this.db);
+    }
+    upsertAccountSync(address, source, timestamp) {
+        const normalized = parseSuiAddress(address);
+        if (!normalized) {
+            throw new ActivityStoreError("Invalid Sui account address");
+        }
+        this.db
+            .prepare(`INSERT INTO accounts (sui_address, first_seen_at, last_used_at, first_source, last_source)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(sui_address) DO UPDATE SET
+           last_used_at = excluded.last_used_at,
+           last_source = excluded.last_source`)
+            .run(normalized, timestamp, timestamp, source, source);
+        const row = this.db
+            .prepare(`SELECT id, sui_address, first_seen_at, last_used_at, first_source, last_source
+         FROM accounts
+         WHERE sui_address = ?`)
+            .get(normalized);
+        if (!row) {
+            throw new ActivityStoreError(`Account was not recorded: ${normalized}`);
+        }
+        return {
+            id: row.id,
+            address: asString(row.sui_address),
+            firstSeenAt: asString(row.first_seen_at),
+            lastUsedAt: asString(row.last_used_at),
+            firstSource: asAccountSource(row.first_source),
+            lastSource: asAccountSource(row.last_source)
+        };
+    }
+    parseReviewStateEvidenceJson(value, reviewSessionId, evidenceField) {
+        const parsed = parseEvidenceJson(value, reviewSessionId, evidenceField);
+        try {
+            return parseLifecycleValidatedReviewState(parsed, this.validateAdapterLifecycle);
+        }
+        catch {
+            throw new ActivityStoreReadError("internal_error", "Malformed activity JSON evidence", {
+                reviewSessionId,
+                evidenceField
+            });
+        }
+    }
+    getAccountByAddressSync(address) {
+        const row = this.db
+            .prepare(`SELECT id, sui_address, first_seen_at, last_used_at, first_source, last_source
+         FROM accounts
+         WHERE sui_address = ?`)
+            .get(address);
+        return row
+            ? {
+                id: row.id,
+                address: asString(row.sui_address),
+                firstSeenAt: asString(row.first_seen_at),
+                lastUsedAt: asString(row.last_used_at),
+                firstSource: asAccountSource(row.first_source),
+                lastSource: asAccountSource(row.last_source)
+            }
+            : undefined;
+    }
+    accountIdExists(accountId) {
+        const row = this.db.prepare("SELECT id FROM accounts WHERE id = ?").get(accountId);
+        return row !== undefined;
+    }
+    externalActivityScanById(scanId) {
+        const row = this.db
+            .prepare(`SELECT eas.scan_id, eas.kind, eas.account_id, a.sui_address AS account, eas.relationship,
+                eas.input_digest, eas.from_checkpoint, eas.to_checkpoint, eas.from_timestamp,
+                eas.to_timestamp, eas.limit_count, eas.request_cursor, eas.response_cursor,
+                eas.endpoint_host, eas.chain_identifier, eas.fetched_at, eas.stored_count,
+                eas.skipped_count, eas.has_more, eas.window_complete, eas.incomplete_reason
+         FROM external_activity_scans eas
+         JOIN accounts a ON a.id = eas.account_id
+         WHERE eas.scan_id = ?`)
+            .get(scanId);
+        return row ? externalActivityScanFromRow(row) : undefined;
+    }
+    insertReviewTransition(input) {
+        this.db
+            .prepare(`INSERT INTO review_status_transitions
+           (review_session_id, event, from_status, to_status, account_id, reason, transitioned_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(input.reviewSessionId, input.event, input.fromStatus ?? null, input.toStatus, input.accountId ?? null, input.reason ?? null, input.transitionedAt);
+    }
+    resolveReviewActivityScope(filter) {
+        if (filter.account) {
+            const normalized = parseSuiAddress(filter.account);
+            if (!normalized) {
+                throw new ActivityStoreReadError("input_invalid", "Invalid account filter", { field: "account" });
+            }
+            const row = this.db
+                .prepare("SELECT id FROM accounts WHERE sui_address = ?")
+                .get(normalized);
+            return {
+                account: normalized,
+                accountId: row?.id,
+                accountSource: "explicit_filter"
+            };
+        }
+        const active = this.getActiveAccountSync();
+        if (!active) {
+            throw new ActivityStoreReadError("active_account_not_set", "Active account read context is not set", {
+                action: "connect_wallet_identity"
+            });
+        }
+        return {
+            account: active.address,
+            accountId: active.accountId,
+            accountSource: "active_account_context"
+        };
+    }
+    getActiveAccountSync() {
+        const row = this.db
+            .prepare(`SELECT a.id AS account_id, a.sui_address AS address, c.source AS source, c.set_at AS set_at,
+                c.wallet_name AS wallet_name, c.wallet_id AS wallet_id
+         FROM active_account_context c
+         JOIN accounts a ON a.id = c.account_id
+         WHERE c.id = ? AND c.account_id IS NOT NULL`)
+            .get(ACTIVE_ACCOUNT_SINGLETON_ID);
+        return row
+            ? {
+                accountId: row.account_id,
+                address: asString(row.address),
+                source: "wallet_identity",
+                setAt: asString(row.set_at),
+                ...(row.wallet_name ? { walletName: row.wallet_name } : {}),
+                ...(row.wallet_id ? { walletId: row.wallet_id } : {})
+            }
+            : undefined;
+    }
+    assertReviewSessionAccount(reviewSessionId, accountId) {
+        const row = this.db
+            .prepare("SELECT account_id FROM review_sessions WHERE id = ?")
+            .get(reviewSessionId);
+        if (!row) {
+            throw new ActivityStoreError(`Review session not found: ${reviewSessionId}`);
+        }
+        if (row.account_id !== null && row.account_id !== accountId) {
+            throw new ActivityStoreError(`Review session already belongs to a different account: ${reviewSessionId}`);
+        }
+    }
+}
+class SqliteCoinMetadataCache {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getCoinMetadata(input) {
+        const row = this.db
+            .prepare(`SELECT coin_type, chain_identifier, decimals, symbol, name, fetched_at, expires_at
+         FROM coin_metadata_cache
+         WHERE coin_type = ? AND chain_identifier = ?`)
+            .get(input.coinType, input.chainIdentifier);
+        if (!row) {
+            return { status: "miss" };
+        }
+        const record = coinMetadataCacheRecordFromRow(row);
+        return record.expiresAt > input.now.toISOString()
+            ? { status: "hit", record }
+            : { status: "expired", record };
+    }
+    async setCoinMetadata(record) {
+        this.db
+            .prepare(`INSERT INTO coin_metadata_cache
+           (coin_type, chain_identifier, decimals, symbol, name, fetched_at, expires_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(coin_type, chain_identifier) DO UPDATE SET
+           decimals = excluded.decimals,
+           symbol = excluded.symbol,
+           name = excluded.name,
+           fetched_at = excluded.fetched_at,
+           expires_at = excluded.expires_at`)
+            .run(record.coinType, record.chainIdentifier, record.decimals, record.symbol, record.name, record.fetchedAt, record.expiresAt);
+    }
+}
+export function resolveActivityDatabasePath(env = process.env, platform = process.platform) {
+    const configured = env[DATA_DIR_ENV];
+    const dataDir = configured && configured.trim() ? configured : defaultDataDir(env, platform);
+    if (dataDir.includes("\0")) {
+        throw new ActivityStoreError(`${DATA_DIR_ENV} must not contain null bytes`);
+    }
+    return resolve(dataDir, ACTIVITY_DATABASE_FILENAME);
+}
+export function assertSqliteEngineAvailable() {
+    const db = new Database(":memory:");
+    try {
+        db.exec("CREATE TABLE engine_check (id INTEGER PRIMARY KEY)");
+        db.prepare("INSERT INTO engine_check (id) VALUES (?)").run(1);
+        const row = db.prepare("SELECT id FROM engine_check").get();
+        if (row?.id !== 1) {
+            throw new ActivityStoreError("better-sqlite3 smoke query failed");
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+function defaultDataDir(env, platform) {
+    const home = homedir();
+    if (platform === "darwin") {
+        return resolve(home, "Library", "Application Support", "say-ur-intent");
+    }
+    if (platform === "win32") {
+        return resolve(env.APPDATA ?? resolve(home, "AppData", "Roaming"), "say-ur-intent");
+    }
+    return resolve(env.XDG_DATA_HOME ?? resolve(home, ".local", "share"), "say-ur-intent");
+}