@adep/cli 0.4.1 → 0.4.5

package/templates/app-mobile/plugins/adep-bridge/android/src/main/java/com/adep/bridge/AdepSqlite.kt

@@ -0,0 +1,506 @@
+package com.adep.bridge
+
+import android.content.Context
+import android.database.Cursor
+import android.util.Base64
+import java.io.File
+import java.io.RandomAccessFile
+import net.zetetic.database.sqlcipher.SQLiteDatabase
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * 设备本地 SQLite 桥的**执行层**（Android，APP-023；APP-026 换 SQLCipher）。
+ *
+ * 消费 {@link AdepSqliteLogic} 的所有决策（错误码 / 参数分流 / 多语句拒绝 / 占位符计数 /
+ * 类型映射 / 成功信封）；本文件只负责把决策落到 SQLCipher 真执行。
+ *
+ * ## 为什么是 SQLCipher（APP-026，回补 APP-024 forbidden 的显式偏离）
+ *
+ * APP-024 首版用 framework `android.database.sqlite`（明文先通链路，与 iOS APP-022
+ * 同口径）；APP-025 把 iOS 侧接上 SQLCipher 后，「落盘即密文」在 Android 侧仍是明文
+ * ——同设备语义两平台分叉。本单换 **net.zetetic:sqlcipher-android 4.6.1**
+ * （`net.zetetic.database.sqlcipher.*`，API 与 framework 同构，替换成本在 import 与
+ * open 一处），run/all/get 契约零改动。
+ *
+ * ⚠️ **`System.loadLibrary("sqlcipher")` 必须显式调用且先于任何 open**：AAR 的
+ * classes.jar 里没有任何类负责加载 so（javap + 常量池全量扫描 0 命中），上游 README
+ * 明文「the developer must load this library explicitly」。漏写 = 首次 open 报
+ * `UnsatisfiedLinkError`（只在 Android runtime 上爆，本机 JVM 门测不到——由静态契约
+ * 门钉「loadLibrary 在任何 open 之前」的顺序）。`companion object` 的懒加载守护保证
+ * 进程内只 load 一次（重复 load 幂等，但守护让语义显式）。
+ *
+ * ## keying 语义（与 iOS APP-025 逐条对齐）
+ *
+ * - **key 由 `open(context, keyProvider)` 注入**：生产装配传
+ *   `{ AdepKeystore.loadOwnerKey(context) }`（ownerKey 即库 key）；返回 null 时用
+ *   设备固定缺省（首启未签发也要加密落盘，不能明文裸奔）。
+ * - **ownerKey 迟到 ⇒ key 升级（APP-027）**：签发是首启异步完成的，库可能先用
+ *   FALLBACK_KEY 建好（离线首启就是这形态）。ownerKey 落 Keystore 后由 {@link adoptKey}
+ *   原地 `PRAGMA rekey`；重启时若换代发生在退出前，{@link ensureOpenHelper} 会探测到
+ *   「当前 key 打不开但缺省 key 打得开」并自动升级。不处理就是「换 key 后老库打不开」。
+ * - **passphrase 走 `openOrCreateDatabase(path, passphrase, factory, errorHandler)`**：
+ *   SQLCipher 连接层在 open 时做 keying（等价 iOS PRAGMA key；javap 实证该重载存在）。
+ * - **明文库迁移**：APP-024 时代建的库是明文（头 = `SQLite format 3\0`）。open 时
+ *   检测到明文头，先以**无 key 形态**打开旧库，`ATTACH` 带真实 key 的临时文件 +
+ *   `sqlcipher_export` 转密 + 表数校验 + 原子替换（迁移方向语义与 iOS 探针实证一致：
+ *   export 产出密文形态由 **目标库的 key** 决定——ATTACH KEY '' 产出明文假迁移）。
+ * - **错 key fail loud 钉在 open 阶段**：passphrase 错不报错（SQLCipher 惰性验证），
+ *   错 key 要到首次读表才爆（`file is not a database`）⇒ keying 后立刻跑探活语句，
+ *   报错点钉在打开时（错误码 `SQLITE_OPEN_FAILED`），不漂移到首次业务查询。
+ *
+ * ## 与 iOS `AdepSqlite.swift` 的语义对齐（2026-10-22 真机七轮排障沉淀，逐条移植）
+ *
+ * - **长持单连接**（不现开现关）：`runOwnedWrite` 事务协议（SAVEPOINT → 业务 → RELEASE/ROLLBACK）
+ *   是**三次独立桥调用**，SAVEPOINT 是连接级状态——现开现关会让第三条语句连接已换 ⇒
+ *   「no such savepoint」。SQLCipher 版 {@link SQLiteOpenHelper} 同样长持
+ *   （getWritableDatabase 返回同一实例）。
+ * - **串行化**：SQLite 句柄非线程安全，桥调用来自不同线程 ⇒ 单线程
+ *   {@link java.util.concurrent.Executors#newSingleThreadExecutor} 串行执行
+ *   （同队列也让「写后读」时序天然成立）。
+ * - **多语句拒绝**：iOS 因 `prepare_v2` 只编第一条会**静默丢尾随**；Android 的
+ *   `execSQL` 可能**多执行**——两边行为必须对齐为「拒绝多语句」（`countSqlStatements != 1`
+ *   fail loud）。
+ * - **占位符计数**：绑定值数必须**恰好**等于占位符数（多了静默忽略 / 少了按 NULL——两侧 fail）。
+ */
+class AdepSqlite private constructor(
+    private val context: Context,
+    private val keyProvider: (() -> String?)?,
+) {
+    /** 串行执行器：句柄非线程安全，同队列也让「写后读」时序天然成立（等价 iOS DispatchQueue）。 */
+    private val executor = java.util.concurrent.Executors.newSingleThreadExecutor()
+    private var open = true
+
+    companion object {
+        /** 库文件名（与 iOS `app.sqlite` 同语义；Android 落 `databases/app.sqlite`）。 */
+        const val DATABASE_NAME = "app.sqlite"
+        const val DATABASE_VERSION = 1
+
+        /** keyProvider 返回 nil（首启未签发）时的设备固定缺省（与 iOS fallbackKey 同值）。 */
+        private const val FALLBACK_KEY = "adep-device-default-key-v1"
+
+        /** SQLCipher 明文库 magic 头（16 字节，含结尾 \0）。文件头与之相等 = 明文库。 */
+        private val PLAIN_HEADER_MAGIC = "SQLite format 3\u0000".toByteArray(Charsets.US_ASCII)
+
+        /** SQLCipher native 库加载守护：进程内恰好一次（explicit，上游 README 纪律）。 */
+        @Volatile
+        private var nativeLoaded = false
+
+        private fun ensureNativeLoaded() {
+            if (!nativeLoaded) {
+                synchronized(this) {
+                    if (!nativeLoaded) {
+                        System.loadLibrary("sqlcipher")
+                        nativeLoaded = true
+                    }
+                }
+            }
+        }
+
+        /**
+         * 工厂：`context.getDatabasePath(DATABASE_NAME)`（Android 标准 databases 目录）。
+         * `keyProvider` 在每次打开时被调用（串行队列 ⇒ 无并发读）——返回 null 用缺省 key。
+         * 生产装配：`AdepSqlite.open(context) { AdepKeystore.loadOwnerKey(context) }`。
+         */
+        fun open(context: Context, keyProvider: (() -> String?)? = null): AdepSqlite {
+            ensureNativeLoaded()
+            return AdepSqlite(context.applicationContext, keyProvider)
+        }
+
+        /** 生效 key：provider 优先，null 时走缺省。 */
+        private fun effectiveKey(keyProvider: (() -> String?)?): String =
+            keyProvider?.invoke() ?: FALLBACK_KEY
+    }
+
+    /** 执行写语句（DDL / DML），返回受影响行数。串行 + 多语句拒绝 + 占位符校验。 */
+    fun run(sql: String, params: List<Any>): Int {
+        return execute { db ->
+            rejectIfMultiple(sql)
+            if (params.isEmpty()) {
+                db.execSQL(sql)
+            } else {
+                rejectIfPlaceholderMismatch(sql, params)
+                db.execSQL(sql, bindArray(params))
+            }
+            // 受影响行数：sqlcipher-android 的 SQLiteDatabase 没有 framework 的
+            // changedRowCount；语义等价物是 compileStatement.executeUpdateDelete()
+            // （session.executeForChangedRowCount 的公开面）——重编一次代价可接受
+            // （写路径非热点），换来与 iOS sqlite3_changes 同语义的返回值。
+            val count = db.compileStatement("SELECT changes()").simpleQueryForLong()
+            count.toInt()
+        }
+    }
+
+    /** 执行查询，返回对象行数组（[{列名:值}]）。 */
+    fun all(sql: String, params: List<Any>): JSONArray {
+        return execute { db ->
+            rejectIfMultiple(sql)
+            if (params.isEmpty()) {
+                queryRows(db.rawQuery(sql, null))
+            } else {
+                rejectIfPlaceholderMismatch(sql, params)
+                queryRows(db.rawQuery(sql, bindArray(params)))
+            }
+        }
+    }
+
+    /** 执行单行查询，无行返回 `JSONObject.NULL`（JS 侧 null）。 */
+    fun get(sql: String, params: List<Any>): Any {
+        val rows = all(sql, params)
+        if (rows.length() == 0) return JSONObject.NULL
+        return rows.getJSONObject(0)
+    }
+
+    /** 关闭连接（幂等；插件销毁时调用，等价 iOS `close()`）。 */
+    fun close() {
+        synchronized(this) {
+            if (!open) return
+            open = false
+        }
+        executor.execute {
+            try {
+                openHelper?.close()
+            } catch (_: Exception) {
+                // 关闭已断连接不抛（幂等收口）。
+            }
+        }
+    }
+
+    // MARK: - 打开 / keying / 明文迁移（APP-026）
+
+    /** 长持 helper（懒建；getWritableDatabase 返回同一实例 ⇒ SAVEPOINT 跨调用存活）。 */
+    private var openHelper: net.zetetic.database.sqlcipher.SQLiteOpenHelper? = null
+
+    /**
+     * 本次打开**实际使用**的 passphrase（仅在成功打开后非 null）。
+     *
+     * 为什么要记住：ownerKey 是首启签发、**异步到达**的（APP-027）——连接可能先用
+     * [FALLBACK_KEY] 建好，ownerKey 随后才落 Keystore。这时必须知道「手上这把连接用的是
+     * 哪把 key」才能决定要不要 rekey（[adoptKey]）。
+     */
+    private var currentKey: String? = null
+
+    private fun databaseFile(): File = context.getDatabasePath(DATABASE_NAME)
+
+    /**
+     * 打开 helper（懒建一次、跨调用复用）。APP-026 keying 顺序（与 iOS 逐条对齐，顺序不能动）：
+     * 1. **明文库检测与迁移**（keying 之前——旧明文库必须以无 key 形态打开才能读）；
+     * 2. 建 SQLCipher 版 {@link SQLiteOpenHelper}（passphrase 由 keyProvider 决定）；
+     * 3. **探活语句**：getWritableDatabase 后立刻 `SELECT count(*) FROM sqlite_master`，
+     *    把错 key 的报错钉在打开时（惰性验证，见类注释）。
+     *
+     * APP-027 增量：探活失败且「当前 key 不是缺省 key」⇒ 说明这是「此前用 [FALLBACK_KEY]
+     * 建的老库，而 ownerKey 刚签发」⇒ 走 [upgradeFallbackKeyedDatabase] 原地 rekey。
+     * 不处理的话症状是「换到正式 key 后老库打不开」——用户看到的是数据全丢。
+     *
+     * ⚠️ 探活**失败**（而非抛错）只可能是「库不是用这把 key 建的」：helper 新建的空库对任何
+     * passphrase 都能探活通过，所以「文件是本次才建的」与「走到了升级分支」互斥——初版在这里
+     * 还判过 `file.exists() && length > 0`，变异自证时发现它恒为 true（不可达死码）已删；
+     * 保留会让读者误以为存在「新库被误判成老库」的路径。
+     */
+    private fun ensureOpenHelper(): net.zetetic.database.sqlcipher.SQLiteOpenHelper {
+        openHelper?.let { return it }
+        val file = databaseFile()
+        file.parentFile?.mkdirs()
+        migratePlainDatabaseIfNeeded(file)
+        val desired = effectiveKey(keyProvider)
+        val helper = try {
+            buildHelper(file, desired)
+        } catch (firstError: Exception) {
+            // `desired == FALLBACK_KEY` 短路：同一把 key 再试一次毫无意义，此时唯一成因就是
+            // 库已损坏，直接报「库坏了」比报「升级失败」好排障。
+            if (desired == FALLBACK_KEY) throw firstError
+            upgradeFallbackKeyedDatabase(file, desired, firstError)
+        }
+        openHelper = helper
+        currentKey = desired
+        return helper
+    }
+
+    /** 建一个带指定 passphrase 的 helper 并探活；探活失败抛（调用方决定升级还是失败）。 */
+    private fun buildHelper(file: File, passphrase: String): net.zetetic.database.sqlcipher.SQLiteOpenHelper {
+        val helper = object : net.zetetic.database.sqlcipher.SQLiteOpenHelper(
+            context,
+            file.absolutePath,
+            passphrase,
+            null,
+            DATABASE_VERSION,
+            DATABASE_VERSION,
+            null,
+            null,
+            true,
+        ) {
+            override fun onCreate(db: SQLiteDatabase) {
+                // 库文件由 helper 幂等创建；schema/baseline 由页面装配器在启动时经
+                // sqliteRun 应用（与 iOS 同语义——壳不预建业务表）。
+            }
+
+            override fun onUpgrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) {
+                // 版本迭代策略：业务表归页面 schema 管理；此处无迁移（首版 v1）。
+            }
+        }
+        try {
+            // 探活：错 key 到这里才报（passphrase 惰性验证）——主动读一把，
+            // 让 SQLITE_OPEN_FAILED 出现在打开阶段而不是首次业务查询。
+            probe(helper)
+        } catch (error: Exception) {
+            try {
+                helper.close()
+            } catch (_: Exception) {
+                // 打不开的 helper 关不掉不致命（下次 ensureOpenHelper 重建）。
+            }
+            throw error
+        }
+        return helper
+    }
+
+    /** 探活语句（错 key / 库损坏在这里暴露）。 */
+    private fun probe(helper: net.zetetic.database.sqlcipher.SQLiteOpenHelper) {
+        helper.writableDatabase.rawQuery("SELECT count(*) FROM sqlite_master", null).use { cursor ->
+            if (!cursor.moveToFirst()) {
+                throw SqliteBridgeError(
+                    SqliteCode.OPEN_FAILED,
+                    "SQLITE_OPEN_FAILED: key 校验失败（探活语句无行返回）——密钥不匹配或库已损坏",
+                )
+            }
+        }
+    }
+
+    /**
+     * 老库 key 升级：`FALLBACK_KEY` → 正式 key（ownerKey）原地 rekey（APP-027）。
+     *
+     * 只能在「旧 key 已知」的方向做（SQLCipher 4.19 拒绝 `key='' + rekey`，iOS APP-025 探针实证），
+     * 而设备固定缺省 key 是常量、永远可知 ⇒ 这条路对存量设备是通的。
+     *
+     * 顺序不能省：用**旧 key** 打开 → `PRAGMA rekey` → 探活 → 关 → 用**新 key** 重建。
+     * 任何一步失败都关连接抛出（保持原库不动，下次启动重试；绝不「打不开就当新库建」）。
+     */
+    private fun upgradeFallbackKeyedDatabase(
+        file: File,
+        desired: String,
+        firstError: Exception,
+    ): net.zetetic.database.sqlcipher.SQLiteOpenHelper {
+        val legacy = try {
+            buildHelper(file, FALLBACK_KEY)
+        } catch (error: Exception) {
+            throw SqliteBridgeError(
+                SqliteCode.OPEN_FAILED,
+                "SQLITE_OPEN_FAILED: 库既不能用当前 key 打开、也不能用设备缺省 key 打开" +
+                    "（${firstError.message}）——密钥不匹配或库已损坏；不会按新库重建（那等于静默丢数据）",
+            )
+        }
+        try {
+            legacy.writableDatabase.execSQL("PRAGMA rekey = '${escapeKey(desired)}';")
+            probe(legacy)
+        } catch (error: Exception) {
+            try {
+                legacy.close()
+            } catch (_: Exception) {
+                // 同上：关不掉不致命。
+            }
+            throw SqliteBridgeError(
+                SqliteCode.OPEN_FAILED,
+                "SQLITE_OPEN_FAILED: 库 key 升级（fallback → ownerKey）失败：${error.message}（原库仍以缺省 key 可读）",
+            )
+        }
+        try {
+            legacy.close()
+        } catch (_: Exception) {
+            // 收口失败不致命：文件已 rekey，新 helper 打开时会重新取句柄。
+        }
+        return buildHelper(file, desired)
+    }
+
+    /**
+     * 库 key 换成正式 key（APP-027 自举拿到 ownerKey 后由插件层调用）。
+     *
+     * 三种情形都要正确：
+     * 1. helper **还没建**（最常见）⇒ 什么都不做——之后 [ensureOpenHelper] 的
+     *    `effectiveKey(keyProvider)` 已能读到 ownerKey；
+     * 2. 已建且就是这把 key ⇒ 什么都不做（幂等）；
+     * 3. 已建、用的是 [FALLBACK_KEY] ⇒ `PRAGMA rekey` 原地换 key（数据行原样保留）。
+     *
+     * ⚠️ 失败**不改变可用性**：库仍以旧 key 可读（只是还没升级），下次启动
+     * [ensureOpenHelper] 会走升级路径重试，所以这里只记日志不抛（调用方是后台自举线程）。
+     */
+    fun adoptKey(key: String) {
+        if (key.isEmpty()) return
+        val job = executor.submit {
+            val helper = openHelper ?: return@submit
+            if (currentKey == key) return@submit
+            try {
+                helper.writableDatabase.execSQL("PRAGMA rekey = '${escapeKey(key)}';")
+                probe(helper)
+                currentKey = key
+            } catch (error: Exception) {
+                android.util.Log.e("adep-sqlite", "库 key 升级（adoptKey）失败，库仍以旧 key 可读", error)
+            }
+        }
+        try {
+            job.get()
+        } catch (error: Exception) {
+            android.util.Log.e("adep-sqlite", "adoptKey 调度失败", error)
+        }
+    }
+
+    /** SQL 字面量里的单引号转义（key 来自 Keystore / 配置，可能是任意字符串）。 */
+    private fun escapeKey(value: String): String = value.replace("'", "''")
+
+    /**
+     * 明文库 → 密文库原地迁移（APP-026）。仅在库文件存在且头是明文 magic 时执行。
+     *
+     * 路径（与 iOS APP-025 探针实证的语义一致）：以**无 key 形态**打开旧明文库 →
+     * `ATTACH` 临时文件**带真实 key** → `sqlcipher_export(migrateTarget ← main)` 产出
+     * 密文临时库（密文形态由 ATTACH 的 KEY 决定——KEY '' 产出明文假迁移）→ 校验
+     * 表数一致 → 关连接 → 原子替换。旧明文库不留盘（替换即消失）；任何一步失败都
+     * 保持原明文库不动（可重试）。
+     */
+    private fun migratePlainDatabaseIfNeeded(file: File) {
+        if (!file.exists() || !file.length().let { it > 0 }) return
+        val header = readFileHeader(file, PLAIN_HEADER_MAGIC.size) ?: return
+        if (!header.contentEquals(PLAIN_HEADER_MAGIC)) return
+        val key = effectiveKey(keyProvider)
+        val tempPath = file.absolutePath + ".migrating"
+        val tempFile = File(tempPath)
+        // 幂等清理：上次迁移中断留下的半成品直接删（export 从原明文库重跑）。
+        tempFile.delete()
+        var plainDb: SQLiteDatabase? = null
+        try {
+            // 无 key 形态打开明文库（String 重载与 ByteArray 重载在 null factory 下有
+            // 歧义 ⇒ 显式转型 factory 参数消歧）。
+            plainDb = SQLiteDatabase.openDatabase(
+                file.absolutePath,
+                null as SQLiteDatabase.CursorFactory?,
+                SQLiteDatabase.OPEN_READWRITE,
+            )
+            val opened = plainDb!!
+            val before = scalar(opened, "SELECT count(*) FROM sqlite_master") ?: -1
+            val escapedTemp = tempPath.replace("'", "''")
+            val escapedKey = key.replace("'", "''")
+            opened.execSQL("ATTACH DATABASE '$escapedTemp' AS migrateTarget KEY '$escapedKey';")
+            try {
+                opened.execSQL("SELECT sqlcipher_export('migrateTarget', 'main');")
+                val after = opened
+                    .rawQuery("SELECT count(*) FROM migrateTarget.sqlite_master", null)
+                    .use { c -> if (c.moveToFirst()) c.getLong(0) else -2L }
+                if (after != before || before < 0) {
+                    throw SqliteBridgeError(
+                        SqliteCode.OPEN_FAILED,
+                        "SQLITE_OPEN_FAILED: 明文库迁移校验失败：源 sqlite_master $before 条 vs 目标 $after 条",
+                    )
+                }
+            } finally {
+                opened.execSQL("DETACH DATABASE migrateTarget;")
+            }
+        } finally {
+            plainDb?.close()
+        }
+        // 关掉对明文库的连接后替换文件（长持连接必须重开指向新文件；helper 在上层重建）。
+        val backupPath = file.absolutePath + ".plain-backup"
+        val backupFile = File(backupPath)
+        backupFile.delete()
+        if (!file.renameTo(backupFile)) {
+            throw SqliteBridgeError(
+                SqliteCode.OPEN_FAILED,
+                "SQLITE_OPEN_FAILED: 明文库迁移替换失败（rename 到备份位）",
+            )
+        }
+        if (!tempFile.renameTo(file)) {
+            // 替换失败：回滚备份，保持明文原状（可重试）。
+            backupFile.renameTo(file)
+            throw SqliteBridgeError(
+                SqliteCode.OPEN_FAILED,
+                "SQLITE_OPEN_FAILED: 明文库迁移替换失败（临时文件落位）",
+            )
+        }
+        // 替换成功：删明文备份（不留盘是验收标准；失败不致命——下次迁移会重建）。
+        backupFile.delete()
+    }
+
+    /** 读文件头 n 字节（不足 n 字节 = 不是 SQLite 库，返回 null 走「非明文」分支）。 */
+    private fun readFileHeader(file: File, n: Int): ByteArray? {
+        return try {
+            RandomAccessFile(file, "r").use { handle ->
+                val buffer = ByteArray(n)
+                val read = handle.read(buffer)
+                if (read == n) buffer else null
+            }
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    /** 裸单值查询（返回首行首列整数值；失败/无行返回 null——由调用方决定语义）。 */
+    private fun scalar(db: SQLiteDatabase, sql: String): Long? = try {
+        db.rawQuery(sql, null).use { cursor -> if (cursor.moveToFirst()) cursor.getLong(0) else null }
+    } catch (_: Exception) {
+        null
+    }
+
+    // MARK: - 内部执行（APP-024 原样：串行 + 解包 + 判定委托纯逻辑层）
+
+    private fun <T> execute(block: (SQLiteDatabase) -> T): T {
+        val job = executor.submit<T> {
+            val db = ensureOpenHelper().writableDatabase // 长持：同实例复用（SAVEPOINT 跨调用存活）
+            block(db)
+        }
+        return try {
+            job.get()
+        } catch (error: java.util.concurrent.ExecutionException) {
+            throw error.cause ?: error // 解开 Promise 式包装，抛出原始 SqliteBridgeError
+        }
+    }
+
+    private fun rejectIfMultiple(sql: String) {
+        val count = countSqlStatements(sql)
+        check(count == 1) {
+            "SQLITE_MULTIPLE_STATEMENTS: SQL 含 $count 条语句（Android 的 execSQL 会多执行、iOS 会静默丢尾随——两侧都拒绝以对齐语义）；sql: ${sql.take(120)}"
+        }
+    }
+
+    private fun rejectIfPlaceholderMismatch(sql: String, params: List<Any>) {
+        val placeholderCount = countPlaceholders(sql)
+        check(placeholderCount == params.size) {
+            "SQLITE_BIND_FAILED: 参数个数 ${params.size} 与占位符数 $placeholderCount 不一致（多了会被静默忽略，少了按 NULL 执行——两侧都不允许）；sql: ${sql.take(120)}"
+        }
+    }
+
+    private fun bindArray(params: List<Any>): Array<Any?> =
+        params.map { if (it === JSONObject.NULL) null else it }.toTypedArray()
+
+    private fun queryRows(cursor: Cursor): JSONArray {
+        val rows = JSONArray()
+        try {
+            val columnCount = cursor.columnCount
+            while (cursor.moveToNext()) {
+                val row = JSONObject()
+                for (i in 0 until columnCount) {
+                    val name = cursor.getColumnName(i)
+                    row.put(name, cursorValue(cursor, i))
+                }
+                rows.put(row)
+            }
+        } finally {
+            cursor.close()
+        }
+        return rows
+    }
+
+    /** 按 `Cursor.getType` 把当前行列读成 JSON 值（类型映射经纯逻辑层 {@link mapCursorFieldType}）。 */
+    private fun cursorValue(cursor: Cursor, column: Int): Any? {
+        return when (mapCursorFieldType(cursor.getType(column))) {
+            "integer" -> cursor.getLong(column)          // 超 2^53 由调用方保证 id 字符串
+            "float" -> cursor.getDouble(column)
+            "string" -> cursor.getString(column)
+            "blob" -> blobToB64(cursor.getBlob(column))  // BLOB → base64（DeviceFile 同形态）
+            "null" -> JSONObject.NULL
+            else -> throw SqliteBridgeError(
+                SqliteCode.COLUMN_FAILED,
+                "未知列类型（column=$column）——SQLite Cursor.getType 泄漏了新类型？",
+            )
+        }
+    }
+
+    private fun blobToB64(bytes: ByteArray): String =
+        Base64.encodeToString(bytes, Base64.NO_WRAP)
+}