@adep/cli 0.4.4 → 0.4.5

package/templates/app-mobile/plugins/adep-bridge/ios/Sources/AdepSqlite.swift

@@ -0,0 +1,614 @@
+import Foundation
+import SQLCipher
+
+/// 设备本地 SQLite 桥（APP-022 B 段；PRD §2.11.3「设备本地 SQLite」行）。
+///
+/// 供 `AdepBridge` 的 `sqlite.run` / `sqlite.all` / `sqlite.get` 三个能力消费，
+/// 形状对齐 `@adep/app-runtime` 的 `DeviceSqliteBridge`（bridge.ts：run → { changes }、
+/// all → 对象行数组、get → 行或 null）。**门控不在本文件**：能力声明由 `adep.permissions.json`
+/// 决定，未声明即 `PERMISSION_DENIED`（ADR-0007 硬约束 3，门控做在原生侧）。
+///
+/// ## 为什么是 SQLCipher（APP-025，回补 ADR-0007 的显式偏离）
+///
+/// APP-022 首版用系统 SQLite 明文（SPM + xtool 接 SQLCipher 当时是独立课题）。
+/// APP-025 换 **SQLCipher.swift 4.19 的 binary xcframework**（checksum 钉死在
+/// 包根 Package.swift），keying 走 **PRAGMA key**——不走 `sqlite3_key` C API：
+/// 该声明在 `#ifdef SQLITE_HAS_CODEC` 里，消费方必须定义宏才可见；纯 SPM 包里
+/// `.define()` 走 `-D` 对 clang importer 无效，`unsafeFlags` 又被 SwiftPM 在
+/// **被依赖的包**里禁止（adep-bridge 正是被 AdepShell 依赖的包）⇒ C API 路线
+/// 在包形态下是死路。PRAGMA 是纯 SQL 面，不碰宏（macOS 行为级探针 2026-10-22 全 PASS）。
+///
+/// run/all/get 契约**零改动**——APP-022 偏离声明承诺的升级路径（只换打开方式）。
+///
+/// ## key 来源与明文迁移（APP-025）
+///
+/// - key 由 `AdepBridge` 装配时注入（`init(databasePath:keyProvider:)`）；缺省 provider
+///   读 Keychain 的 ownerKey（`AdepKeychain.loadOwnerKey`），读不到用设备固定缺省
+///   （首启未签发也要加密落盘，不能明文裸奔）。
+/// - **ownerKey 迟到 ⇒ key 升级（APP-027）**：签发是首启异步完成的，库可能先用
+///   `fallbackKey` 建好（离线首启就是这形态）。ownerKey 落 Keychain 后由 `adoptKey` 原地
+///   `PRAGMA rekey`；重启时若换代发生在「上次退出前」，`open()` 会探测到「当前 key 打不开
+///   但缺省 key 打得开」并自动升级（`upgradeFallbackKeyedDatabase`）。
+///   ⚠️ **不处理就是「换 key 后老库打不开」**——用户看到的是数据全丢。
+/// - **明文迁移**：APP-022 时代建的库是明文（头 = `SQLite format 3\0`）。open 时检测到
+///   明文头即走 `sqlcipher_export + ATTACH` 原地转密（`PRAGMA key=''` + `rekey` 被
+///   SQLCipher 4.19 拒绝——「requires a key of one or more characters」，export 是唯一
+///   路径，探针实测），同目录临时文件 + 原子替换，迁移后行数校验，旧明文库不留盘。
+/// - **错 key fail loud 钉在 open() 阶段**：PRAGMA key 本身不报错（SQLCipher 惰性验证），
+///   错 key 要到首次读表才爆（`file is not a database`）⇒ keying 后立刻跑探活语句，
+///   把报错点钉在打开时而不是第一次业务查询（报错点漂移是排查噩梦）。
+///
+/// ## 为什么长持单连接 + 串行队列（2026-10-22 真机第六轮改版）
+///
+/// 首版「每次调用现开现关」被真机第六轮读数证伪：`@adep/runtime` builder 的
+/// `runOwnedWrite` 事务协议是 **SAVEPOINT → 业务 SQL → RELEASE/ROLLBACK 三次独立桥调用**
+/// （owned.ts），而 SAVEPOINT 是**连接级**状态——第三条语句到达时连接已换，
+/// SQLite 报 `no such savepoint`。
+///
+/// - 库路径唯一（Application Support/AdepBridge/app.sqlite）：运行时侧 `ProjectDriver`
+///   语义是「项目本地库」，不需要多库句柄；
+/// - 长持连接：懒开（首次调用建目录 + open），跨调用复用——SAVEPOINT / 事务 / PRAGMA
+///   等连接级状态因此跨桥调用存活；
+/// - 串行队列：桥调用可能来自不同线程（Capacitor 派发），SQLite 句柄非线程安全；
+///   同队列串行也让 `sqlite3_changes`「step 后立刻读」的时序天然成立；
+/// - `close()` 幂等收口 + deinit：插件销毁时关连接，防 WebView reload 场景 fd 泄漏；
+///   进程被杀由 SQLite journal 恢复兜底。
+///
+/// ## 参数绑定与取值（对齐 node:sqlite / better-sqlite3 的 JS 面）
+///
+/// - 占位符 `?` / `?N` / `:name` 全支持（C API 原生语义）；
+/// - JS 侧绑定值支持：String / Double / Int（转 Double 语义等价）/ Bool（→ 0/1）/ null；
+/// - 取值映射：INTEGER → JS number（⚠️ 超 2^53 精度丢失——设备端 owned 表 id 是 snowflake 的
+///   场景见 §2.11.5，运行时 id 一律字符串，见 SHOP-007 纪律）；REAL → number；TEXT → string；
+///   BLOB → ArrayBuffer；NULL → null。
+public final class AdepSqlite {
+    /// 可复用的错误码族（JS 侧 catch 分支判断；与 DEVICE_CODES 风格同源但**不**复用其常量——
+    /// 错误码是跨实现锚点，原生侧自有清单）。
+    public enum Code {
+        public static let openFailed = "SQLITE_OPEN_FAILED"
+        public static let multipleStatements = "SQLITE_MULTIPLE_STATEMENTS"
+        public static let prepareFailed = "SQLITE_PREPARE_FAILED"
+        public static let execFailed = "SQLITE_EXEC_FAILED"
+        public static let bindFailed = "SQLITE_BIND_FAILED"
+        public static let columnFailed = "SQLITE_COLUMN_FAILED"
+        public static let invalidParam = "SQLITE_INVALID_PARAM"
+    }
+
+    /// 库文件唯一落点（Application Support/AdepBridge/app.sqlite）。
+    /// 目录不存在时 `open` 幂等创建（iOS 沙盒保证 Application Support 一定可写）。
+    private let databasePath: String
+
+    /// `open` 抛出的结构化错误（domain 固定，code 走 `Code.openFailed` 语义——NSError 的
+    /// code 是 Int，JS 侧要的是字符串码，所以 message 里带 `Code.openFailed` 前缀）。
+    public static func defaultDatabasePath() -> String {
+        let support = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+        return support.appendingPathComponent("AdepBridge", isDirectory: true)
+            .appendingPathComponent("app.sqlite", isDirectory: false).path
+    }
+
+    /// 注入式构造（测试与 C 段 WebView 装配可指定路径；生产走 `init()` 缺省路径）。
+    /// `keyProvider` 在每次 open 时被调用（同队列串行 ⇒ 无并发读）——返回 nil 时用
+    /// 设备固定缺省（首启未签发也要加密落盘）。
+    public init(databasePath: String, keyProvider: (() -> String?)? = nil) {
+        self.databasePath = databasePath
+        self.keyProvider = keyProvider
+    }
+
+    /// 生产缺省构造：Application Support/AdepBridge/app.sqlite + 静态缺省 key 源。
+    /// ⚠️ key 源走 `defaultKeyProvider` 静态钩子而非直连 `AdepKeychain`：本类型被行为级门
+    /// 单文件编译（无 Security framework / AdepKeychain 同模块），钩子由壳装配层
+    /// （AdepBridge 安装点）设置——依赖倒置，行为级门不必拖进 Keychain。
+    public convenience init() {
+        self.init(databasePath: AdepSqlite.defaultDatabasePath(), keyProvider: AdepSqlite.defaultKeyProvider)
+    }
+
+    /// 缺省 key 源（壳装配层注入；缺省返回 nil ⇒ 用设备固定缺省 key）。
+    /// AdepBridge 装配时设为 `{ AdepKeychain.loadOwnerKey() }`（ownerKey 即库 key）。
+    nonisolated(unsafe) public static var defaultKeyProvider: (() -> String?)? = nil
+
+    // MARK: - 加密（APP-025）
+
+    /// key 来源（装配时注入；缺省读 Keychain ownerKey）。
+    private let keyProvider: (() -> String?)?
+
+    /// keyProvider 返回 nil（首启未签发）时的设备固定缺省。
+    /// ⚠️ 不是安全 key——它只是把「明文裸奔」变成「有锁的库」；ownerKey 签发后由
+    /// 产品级 key 轮换换成正式 key（另议，超出本单）。
+    private static let fallbackKey = "adep-device-default-key-v1"
+
+    /// 生效 key：provider 优先，nil 时走缺省。
+    private var effectiveKey: String {
+        keyProvider?() ?? Self.fallbackKey
+    }
+
+    /// 本次打开**实际使用**的 key（仅在连接成功打开后非 nil）。
+    ///
+    /// 为什么要记住：ownerKey 是首启签发、**异步到达**的（APP-027）——连接可能先用
+    /// `fallbackKey` 建好，ownerKey 随后才落 Keychain。这时必须知道「手上这把连接用的是
+    /// 哪把 key」才能决定要不要 rekey（`adoptKey`）。
+    private var currentKey: String?
+
+    /// SQLite 明文库 magic 头（16 字节，含结尾 \0）。文件头与之相等 = 明文库。
+    private static let plainHeaderMagic = "SQLite format 3\u{0}"
+
+    // MARK: - 对外三方法（DeviceSqliteBridge 同形）
+
+    /// 执行写语句（DDL / DML），返回受影响行数。
+    /// ⚠️ 连接长持（懒开）：SAVEPOINT / 事务状态可跨调用存活——`runOwnedWrite`
+    /// 协议（SAVEPOINT → 业务 → RELEASE，三次独立桥调用）依赖这一点。
+    public func run(_ sql: String, params: [Any]?) throws -> Int32 {
+        try enqueue {
+            let statement = try self.prepare(sql, params: params)
+            defer { sqlite3_finalize(statement) }
+            // ⚠️ 不能只认 SQLITE_DONE：run 也可能收到 SELECT（调用方想拿 changes=0 的语义），
+            // SQLite 对 SELECT 的 step 返回 SQLITE_ROW——只认 DONE 会报「another row available」
+            // （行为探针 case7 当场抓住：SELECT 走 run 报 execFailed，而不是返回 changes=0）。
+            // 语义与 node:sqlite 对齐：run 完成 = 语句执行到无更多行，行数据丢弃。
+            var rc = sqlite3_step(statement)
+            while rc == SQLITE_ROW {
+                rc = sqlite3_step(statement)
+            }
+            guard rc == SQLITE_DONE else {
+                throw self.sqliteError(Code.execFailed, sql: sql)
+            }
+            return sqlite3_changes(self.db!)
+        }
+    }
+
+    /// 执行查询，返回对象行数组。
+    public func all(_ sql: String, params: [Any]?) throws -> [[String: Any]] {
+        try enqueue {
+            let statement = try self.prepare(sql, params: params)
+            defer { sqlite3_finalize(statement) }
+            var rows: [[String: Any]] = []
+            while true {
+                let rc = sqlite3_step(statement)
+                if rc == SQLITE_ROW {
+                    rows.append(try self.readRow(statement, sql: sql))
+                } else if rc == SQLITE_DONE {
+                    break
+                } else {
+                    throw self.sqliteError(Code.columnFailed, sql: sql)
+                }
+            }
+            return rows
+        }
+    }
+
+    /// 执行单行查询；无行返回 nil。
+    public func get(_ sql: String, params: [Any]?) throws -> [String: Any]? {
+        try enqueue {
+            let statement = try self.prepare(sql, params: params)
+            defer { sqlite3_finalize(statement) }
+            let rc = sqlite3_step(statement)
+            if rc == SQLITE_ROW {
+                return try self.readRow(statement, sql: sql)
+            }
+            if rc == SQLITE_DONE {
+                return nil
+            }
+            throw self.sqliteError(Code.columnFailed, sql: sql)
+        }
+    }
+
+    // MARK: - 内部：连接 / prepare / 绑定 / 取值
+
+    /// 长持连接句柄（懒开）。所有访问必须经 `queue` 串行化。
+    private var db: OpaquePointer?
+
+    /// 串行队列：SQLite 句柄非线程安全，桥调用可能来自不同线程；
+    /// 同队列串行也让 `sqlite3_changes`「step 后立刻读」的时序天然成立。
+    private let queue = DispatchQueue(label: "adep.sqlite.bridge")
+
+    /// 打开失败的结构化错误（与 `sqliteError` 同 message 形态，enqueue 包装复用）。
+    private func openError(_ message: String) -> NSError {
+        NSError(
+            domain: "AdepSqlite", code: 1,
+            userInfo: [NSLocalizedDescriptionKey: "\(Code.openFailed): \(message)（path: \(databasePath)）"]
+        )
+    }
+
+    /// 打开连接（目录幂等创建；`sqlite3_open` 会自动建库文件，不存在时）。
+    /// ⚠️ 不能用 `try?`：打开失败必须带 sqlite errmsg 抛出，静默 nil 会让后续
+    /// prepare 段错误（野指针）。已打开时直接返回（长持复用）。
+    ///
+    /// APP-025 keying 顺序（探针实证的语义，顺序不能动）：
+    /// 1. `sqlite3_open` 成功后**立刻** `PRAGMA key`（任何其他语句先于 key 都会被
+    ///    当作对明文/错密库的操作）；
+    /// 2. **明文库检测与迁移**：库文件已存在且头是明文 magic ⇒ `sqlcipher_export`
+    ///    原地转密（在 keying 之前的裸连接上做——export 的源就是当前明文库）；
+    /// 3. **探活语句**：PRAGMA key 惰性验证，错 key 要到首次读表才报
+    ///    `file is not a database` ⇒ 这里跑一条 `SELECT count(*) FROM sqlite_master;`
+    ///    把报错点钉在 open()，错误码 `SQLITE_OPEN_FAILED`。
+    private func open() throws {
+        guard db == nil else { return }
+        let dir = (databasePath as NSString).deletingLastPathComponent
+        if !FileManager.default.fileExists(atPath: dir) {
+            try FileManager.default.createDirectory(atPath: dir, withIntermediateDirectories: true)
+        }
+        var handle: OpaquePointer?
+        guard sqlite3_open(databasePath, &handle) == SQLITE_OK else {
+            let message = handle.map { String(cString: sqlite3_errmsg($0)) } ?? "sqlite3_open 失败"
+            // 打开失败时 handle 仍可能非 nil（SQLite 语义：失败也回填句柄），必须关掉防泄漏。
+            handle.map { sqlite3_close($0) }
+            throw openError(message)
+        }
+        db = handle
+        do {
+            // 明文库检测必须在 keying 之前：keying 后这个连接就对明文不可读了。
+            try migratePlainDatabaseIfNeeded()
+            let desired = effectiveKey
+            if try keyAndProbe(desired) {
+                currentKey = desired
+                return
+            }
+            // 探活**返回 false**（而非抛错）只可能是「库不是用这把 key 建的」：
+            // `sqlite3_open` 新建的空库对任何 key 都能探活通过，所以「文件是本次才建的」
+            // 与「走到了这里」互斥——不需要再判文件是否存在（初版写过这个条件，
+            // 变异自证时发现它恒为 true，属不可达死码，已删；保留会让读者误以为
+            // 存在「新库被误判成老库」的路径）。
+            //
+            // 剩下的两种真实成因：①此前用设备固定缺省 key 建好的存量库，而 ownerKey
+            // 刚签发（APP-027 之前的所有安装都是这个形态）⇒ 用缺省 key 打开并 rekey；
+            // ②库坏了 / 是别人的 key 建的 ⇒ `upgradeFallbackKeyedDatabase` 里旧 key
+            // 也打不开，抛带原因的错误（绝不按新库重建 = 静默丢数据）。
+            // `desired == fallbackKey` 短路掉：同一把 key 再试一次毫无意义，且此时
+            // 唯一成因就是库已损坏，直接报「库已损坏」比报「升级失败」好排障。
+            guard desired != Self.fallbackKey else {
+                throw openError("key 校验失败（\(lastErrorMessage())）——密钥不匹配或库已损坏")
+            }
+            try upgradeFallbackKeyedDatabase(to: desired)
+        } catch {
+            // keying / 迁移 / 探活失败：关掉半开连接（防泄漏），统一按 openFailed 语义。
+            closeLocked()
+            currentKey = nil
+            throw error
+        }
+    }
+
+    /// 用指定 key keying 并探活。返回是否可用。
+    ///
+    /// ⚠️ 探活是必须的：`PRAGMA key` **惰性验证**——错 key 要到首次读表才报
+    /// `file is not a database`。不在这里探，报错点会漂到第一次业务查询（排查噩梦）。
+    private func keyAndProbe(_ key: String) throws -> Bool {
+        try rawExec("PRAGMA key = '\(Self.escape(key))';")
+        return rawScalar("SELECT count(*) FROM sqlite_master;") != nil
+    }
+
+    /// 老库 key 升级：`fallbackKey` → 正式 key（ownerKey）原地 rekey（APP-027）。
+    ///
+    /// 只能在「旧 key 已知」的方向做（SQLCipher 4.19 拒绝 `key='' + rekey`，APP-025 探针实证），
+    /// 而设备固定缺省 key 是常量、永远可知 ⇒ 这条路对存量设备是通的。
+    ///
+    /// 顺序不能省：关连接 → 重开 → 用**旧 key** keying 成功 → `PRAGMA rekey` → 用**新 key** 探活。
+    /// 任何一步失败都关连接抛出（保持原库不动，下次启动重试；绝不「打不开就当新库建」）。
+    private func upgradeFallbackKeyedDatabase(to desired: String) throws {
+        closeLocked()
+        var handle: OpaquePointer?
+        guard sqlite3_open(databasePath, &handle) == SQLITE_OK else {
+            let message = handle.map { String(cString: sqlite3_errmsg($0)) } ?? "sqlite3_open 失败"
+            handle.map { sqlite3_close($0) }
+            throw openError("key 升级重开失败：\(message)")
+        }
+        db = handle
+        guard try keyAndProbe(Self.fallbackKey) else {
+            throw openError(
+                "库既不能用当前 key 打开、也不能用设备缺省 key 打开（\(lastErrorMessage())）"
+                    + "——密钥不匹配或库已损坏；不会按新库重建（那等于静默丢数据）"
+            )
+        }
+        try rawExec("PRAGMA rekey = '\(Self.escape(desired))';")
+        guard rawScalar("SELECT count(*) FROM sqlite_master;") != nil else {
+            throw openError("key 升级后探活失败（\(lastErrorMessage())）——rekey 未生效，原库仍以缺省 key 可读")
+        }
+        currentKey = desired
+    }
+
+    /// 库 key 换成正式 key（APP-027 自举拿到 ownerKey 后由壳装配层调用）。
+    ///
+    /// 三种情形都要正确：
+    /// 1. 连接**还没开**（最常见）⇒ 什么都不做——下次 open 时 keyProvider 已能读到 ownerKey；
+    /// 2. 连接已开且就是这把 key ⇒ 什么都不做（幂等）；
+    /// 3. 连接已开、用的是 fallbackKey ⇒ `PRAGMA rekey` 原地换 key（数据行原样保留）。
+    ///
+    /// ⚠️ 失败**不改变可用性**：库仍以旧 key 可读（只是还没升级），下次启动 `open()` 会走
+    /// `upgradeFallbackKeyedDatabase` 重试。所以这里只记日志，不抛（抛也无处可抛——
+    /// 调用方是后台自举线程）。
+    public func adoptKey(_ key: String) {
+        guard !key.isEmpty else { return }
+        queue.sync {
+            guard db != nil else { return }
+            guard currentKey != key else { return }
+            do {
+                try rawExec("PRAGMA rekey = '\(Self.escape(key))';")
+                guard rawScalar("SELECT count(*) FROM sqlite_master;") != nil else {
+                    throw openError("rekey 后探活失败（\(lastErrorMessage())）")
+                }
+                currentKey = key
+            } catch {
+                NSLog("[adep-sqlite] 库 key 升级（adoptKey）失败，库仍以旧 key 可读：\(error.localizedDescription)")
+            }
+        }
+    }
+
+    /// SQL 字面量里的单引号转义（key 来自 Keychain / 配置，可能是任意字符串）。
+    private static func escape(_ value: String) -> String {
+        value.replacingOccurrences(of: "'", with: "''")
+    }
+
+    /// 连接级错误文案（未打开时给固定串，不段错误）。
+    private func lastErrorMessage() -> String {
+        db.map { String(cString: sqlite3_errmsg($0)) } ?? "连接未打开"
+    }
+
+    /// 裸 exec（不做 keying 假设；迁移路径专用——export 要跑在 keying 之前的明文连接上）。
+    private func rawExec(_ sql: String) throws {
+        var errorPointer: UnsafeMutablePointer<CChar>?
+        let rc = sqlite3_exec(db!, sql, nil, nil, &errorPointer)
+        if rc != SQLITE_OK {
+            let message = errorPointer.map { String(cString: $0) } ?? "sqlite3_exec 失败（rc=\(rc)）"
+            if let errorPointer { sqlite3_free(errorPointer) }
+            throw openError("\(message)（sql: \(sql.prefix(120))）")
+        }
+    }
+
+    /// 裸单值查询（返回首行首列整数值；失败/无行返回 nil——由调用方决定语义）。
+    private func rawScalar(_ sql: String) -> Int32? {
+        var statement: OpaquePointer?
+        guard sqlite3_prepare_v2(db!, sql, -1, &statement, nil) == SQLITE_OK, let statement else {
+            return nil
+        }
+        defer { sqlite3_finalize(statement) }
+        guard sqlite3_step(statement) == SQLITE_ROW else { return nil }
+        return sqlite3_column_int(statement, 0)
+    }
+
+    /// 明文库 → 密文库原地迁移（APP-025）。仅在库文件存在且头是明文 magic 时执行。
+    ///
+    /// 路径：ATTACH 临时文件**带真实 key**，`sqlcipher_export(migrateTarget ← main)`
+    /// 产出密文临时库，校验表数一致后**原子替换**原文件。旧明文库不留盘（替换即消失）。
+    /// 任何一步失败都保持原明文库不动（可重试）。
+    private func migratePlainDatabaseIfNeeded() throws {
+        guard FileManager.default.fileExists(atPath: databasePath) else { return }
+        guard let header = fileHeader16(databasePath), header == Self.plainHeaderMagic else { return }
+        let tempPath = databasePath + ".migrating"
+        // 幂等清理：上次迁移中断留下的半成品直接删（export 从原明文库重跑）。
+        try? FileManager.default.removeItem(atPath: tempPath)
+        let before = rawScalar("SELECT count(*) FROM sqlite_master;") ?? -1
+        // sqlcipher_export(dst, src) 语义：把 src 写进 dst 所在库，密文形态由 dst 的
+        // key 决定（探针实证：ATTACH 带 KEY '' 产出明文假迁移；带真实 key 产出密文）。
+        // ⚠️ ATTACH 的 KEY 就是新库的加密 key——不是「声明源库 key」。
+        // 临时文件名里的单引号：databasePath 由本类管理（固定目录 + 固定文件名），
+        // 不含单引号；即便未来可配，这里同样做转义。
+        let escapedTemp = tempPath.replacingOccurrences(of: "'", with: "''")
+        let escapedKey = effectiveKey.replacingOccurrences(of: "'", with: "''")
+        try rawExec("ATTACH DATABASE '\(escapedTemp)' AS migrateTarget KEY '\(escapedKey)';")
+        defer {
+            _ = rawExecIgnoreError("DETACH DATABASE migrateTarget;")
+        }
+        try rawExec("SELECT sqlcipher_export('migrateTarget', 'main');")
+        // 校验：迁移后的目标库表数与源一致（行数校验针对业务表不可行——sqlite_master
+        // 的表数是结构完整性最直接的代理指标；数据级校验由行为级门覆盖典型场景）。
+        let after = rawScalar("SELECT count(*) FROM migrateTarget.sqlite_master;") ?? -2
+        guard after == before, before >= 0 else {
+            throw openError("明文库迁移校验失败：源 sqlite_master \(before) 条 vs 目标 \(after) 条")
+        }
+        // 关掉当前对明文库的连接，才能替换文件（Windows 语义不存在，但 macOS 上
+        // 替换打开中的文件会让句柄指向旧 inode——长持连接必须重开指向新文件）。
+        closeLocked()
+        do {
+            let backupPath = databasePath + ".plain-backup"
+            try? FileManager.default.removeItem(atPath: backupPath)
+            try FileManager.default.moveItem(atPath: databasePath, toPath: backupPath)
+            do {
+                try FileManager.default.moveItem(atPath: tempPath, toPath: databasePath)
+            } catch {
+                // 替换失败：回滚备份，保持明文原状（可重试）。
+                try? FileManager.default.moveItem(atPath: backupPath, toPath: databasePath)
+                throw openError("明文库迁移替换失败：\(error.localizedDescription)")
+            }
+            // 替换成功：删明文备份（不留盘是验收标准；失败不致命——下次迁移会重建）。
+            try? FileManager.default.removeItem(atPath: backupPath)
+            // 重开连接到新密文库（本次调用继续用；keying 由调用方 open() 继续执行）。
+            var handle: OpaquePointer?
+            guard sqlite3_open(databasePath, &handle) == SQLITE_OK else {
+                let message = handle.map { String(cString: sqlite3_errmsg($0)) } ?? "sqlite3_open 失败"
+                handle.map { sqlite3_close($0) }
+                throw openError("迁移后重开失败：\(message)")
+            }
+            db = handle
+        } catch let error as NSError where error.domain == "AdepSqlite" {
+            throw error
+        } catch {
+            throw openError("明文库迁移文件操作失败：\(error.localizedDescription)")
+        }
+    }
+
+    /// 读文件头 16 字节（不足 16 字节 = 不是 SQLite 库，返回 nil 走「非明文」分支）。
+    private func fileHeader16(_ path: String) -> String? {
+        guard let handle = FileHandle(forReadingAtPath: path) else { return nil }
+        defer { handle.closeFile() }
+        let data = handle.readData(ofLength: 16)
+        guard data.count == 16 else { return nil }
+        return String(data: data, encoding: .ascii)
+    }
+
+    /// 仅用于 defer 清理的 exec（失败静默——DETACH 失败不影响主流程，连接即将关闭）。
+    private func rawExecIgnoreError(_ sql: String) {
+        var errorPointer: UnsafeMutablePointer<CChar>?
+        _ = sqlite3_exec(db!, sql, nil, nil, &errorPointer)
+        if let errorPointer { sqlite3_free(errorPointer) }
+    }
+
+    /// 关闭连接（幂等：nil 时无操作）。只在 `close()` 内调用（同队列）。
+    private func closeLocked() {
+        if let handle = db {
+            sqlite3_close(handle)
+            db = nil
+        }
+        currentKey = nil
+    }
+
+    /// 插件实例销毁时收口（幂等）。进程被杀的场景由 SQLite journal 恢复兜底。
+    public func close() {
+        queue.sync { closeLocked() }
+    }
+
+    deinit {
+        close()
+    }
+
+    /// 串行化包装：queue.sync → ensure open → body。⚠️ 连接**不**在调用结束时关闭
+    /// ——长持是 SAVEPOINT 跨调用存活的前提。body 内 `self.db!` 强解包安全：
+    /// open() 已保证非 nil，且同队列串行，无并发 closeLocked 置 nil 的窗口。
+    private func enqueue<T>(_ body: () throws -> T) throws -> T {
+        try queue.sync {
+            try open()
+            return try body()
+        }
+    }
+
+    /// prepare + 绑定。`defer finalize` 由调用方负责（本方法返回语句句柄）。
+    /// ⚠️ 无强解包：prepare 失败 / 绑定失败 / 参数个数超出语句占位符，都要 finalize + 抛错，
+    /// 不能段错误（行为探针 11/11 里的 fail-loud 三例就是走这里）。
+    private func prepare(_ sql: String, params: [Any]?) throws -> OpaquePointer {
+        guard let db = db else {
+            throw sqliteError(Code.openFailed, sql: sql)
+        }
+        var statement: OpaquePointer?
+        // ⚠️ sql 必须先落**自管** C 缓冲：Swift String 直传时是桥接临时副本，prepare 返回后
+        // 副本销毁 ⇒ pzTail 悬空（读到全 0，行为探针 case15 抓到「该红不红」）。cString 的
+        // 数组由本作用域持有，tail 相对它有效。
+        guard let sqlBytes = sql.cString(using: .utf8) else {
+            throw sqliteError(Code.prepareFailed, sql: sql)
+        }
+        var tail: UnsafePointer<CChar>?
+        guard sqlite3_prepare_v2(db, sqlBytes, -1, &statement, &tail) == SQLITE_OK, let statement else {
+            throw sqliteError(Code.prepareFailed, sql: sql)
+        }
+        // ⚠️ 多语句 fail loud：sqlite3_prepare_v2 只编译**第一条**语句，尾随语句被 SQLite
+        // **静默丢弃**（行为探针 case15 实测：`SELECT * FROM m; DROP TABLE m` ⇒ DROP 没执行，
+        // 调用方以为两条都跑了）。tail 指向剩余字节——剥掉空白与注释后非空即拒绝。
+        if let tail {
+            let remainder = String(cString: tail)
+            var stripped = ""
+            var inLineComment = false
+            var inBlockComment = false
+            var previous: Character = "\0"
+            for char in remainder {
+                if inLineComment {
+                    if char == "\n" { inLineComment = false }
+                    continue
+                }
+                if inBlockComment {
+                    if previous == "*" && char == "/" { inBlockComment = false; previous = "\0"; continue }
+                    previous = char
+                    continue
+                }
+                if previous == "-" && char == "-" { inLineComment = true; stripped = String(stripped.dropLast()); previous = char; continue }
+                if previous == "/" && char == "*" { inBlockComment = true; stripped = String(stripped.dropLast()); previous = char; continue }
+                previous = char
+                if !char.isWhitespace { stripped.append(char) }
+            }
+            if !stripped.isEmpty {
+                sqlite3_finalize(statement)
+                throw NSError(
+                    domain: "AdepSqlite", code: 4,
+                    userInfo: [NSLocalizedDescriptionKey:
+                        "\(Code.multipleStatements): SQL 含多条语句（尾随语句会被 SQLite 静默丢弃，已拒绝执行）；sql: \(sql.prefix(120))"]
+                )
+            }
+        }
+        if let params {
+            // 越界参数 fail loud：SQLite 对多余绑定值静默忽略（bind 返回 SQLITE_RANGE），
+            // 静默 = 参数清单与语句漂移时查不出来（与「列类型不映射」同族的静默陷阱）。
+            // ⚠️ 参数个数必须**恰好等于**占位符数：多了 SQLite 静默忽略（SQLITE_RANGE），
+            // 少了缺的占位符按 NULL 语义执行（行为探针 case12 实测：INSERT 两列只给一列
+            // 的值 ⇒ 行照插、另一列 NULL——「不报错只恒不命中」的插入版）。两侧都 fail loud。
+            let placeholderCount = sqlite3_bind_parameter_count(statement)
+            guard params.count == Int(placeholderCount) else {
+                sqlite3_finalize(statement)
+                throw NSError(
+                    domain: "AdepSqlite", code: 3,
+                    userInfo: [NSLocalizedDescriptionKey:
+                        "\(Code.bindFailed): 参数个数 \(params.count) 与占位符数 \(placeholderCount) 不一致（多了会被静默忽略，少了按 NULL 执行——两侧都不允许）；sql: \(sql.prefix(120))"]
+                )
+            }
+            for (index, param) in params.enumerated() {
+                let rc = bind(param, at: Int32(index + 1), to: statement)
+                if rc != SQLITE_OK {
+                    sqlite3_finalize(statement)
+                    throw sqliteError(Code.bindFailed, sql: sql)
+                }
+            }
+        }
+        return statement
+    }
+
+    /// 绑定单参数（1-based index；支持 String / 数值 / Bool / null；其他类型抛 invalidParam）。
+    private func bind(_ value: Any, at index: Int32, to statement: OpaquePointer) -> Int32 {
+        switch value {
+        case let text as String:
+            return sqlite3_bind_text(statement, index, text, -1, SQLITE_TRANSIENT)
+        case let number as Double:
+            return sqlite3_bind_double(statement, index, number)
+        case let number as Int:
+            // Int64 语义：SQLite 整数上限；超过 2^53 的 number 语义由调用方保证（id 一律字符串）。
+            return sqlite3_bind_int64(statement, index, Int64(number))
+        case let number as Bool:
+            return sqlite3_bind_int64(statement, index, number ? 1 : 0)
+        default:
+            // null 之外的未知类型 fail loud：静默绑 NULL 会让 WHERE 条件静默不命中
+            // （「不报错只恒不命中」正是本仓最忌讳的静默陷阱形态）。
+            if value is NSNull {
+                return sqlite3_bind_null(statement, index)
+            }
+            return SQLITE_MISUSE
+        }
+    }
+
+    /// 读一行成对象（列名 → 值；类型映射见文件头注释）。
+    private func readRow(_ statement: OpaquePointer, sql: String) throws -> [String: Any] {
+        let columnCount = sqlite3_column_count(statement)
+        var row: [String: Any] = [:]
+        for index in 0..<columnCount {
+            let name = String(cString: sqlite3_column_name(statement, index))
+            let value: Any
+            switch sqlite3_column_type(statement, index) {
+            case SQLITE_INTEGER:
+                value = sqlite3_column_int64(statement, index) // Int64 → JS number（精度见文件头）
+            case SQLITE_FLOAT:
+                value = sqlite3_column_double(statement, index)
+            case SQLITE_TEXT:
+                value = String(cString: sqlite3_column_text(statement, index))
+            case SQLITE_BLOB:
+                if let bytes = sqlite3_column_blob(statement, index) {
+                    let count = Int(sqlite3_column_bytes(statement, index))
+                    value = Data(bytes: bytes, count: count)
+                } else {
+                    value = Data()
+                }
+            case SQLITE_NULL:
+                value = NSNull()
+            default:
+                throw sqliteError(Code.columnFailed, sql: sql)
+            }
+            row[name] = value
+        }
+        return row
+    }
+
+    /// 统一错误构造（带 SQL 文本截断与 sqlite errmsg；message 前缀是 JS 侧 catch 的锚）。
+    private func sqliteError(_ code: String, sql: String) -> NSError {
+        let snippet = sql.count > 120 ? String(sql.prefix(120)) + "…" : sql
+        let message = db.map { String(cString: sqlite3_errmsg($0)) } ?? "连接未打开"
+        return NSError(
+            domain: "AdepSqlite", code: 2,
+            userInfo: [NSLocalizedDescriptionKey: "\(code): \(message)（sql: \(snippet)）"]
+        )
+    }
+}
+
+/// SQLITE_TRANSIENT：让 SQLite 自己拷贝绑定字符串（C API 的经典坑——传静态常量时
+/// SQLite 不拷贝，语句 finalize 前字符串必须存活；Swift 字符串作用域短，必须 TRANSIENT）。
+private let SQLITE_TRANSIENT = unsafeBitCast(-1, to: sqlite3_destructor_type.self)

package/templates/app-mobile/plugins/adep-bridge/package.json

@@ -10,5 +10,15 @@
   },
   "peerDependencies": {
     "@capacitor/core": "^7.0.0"
+  },
+  "capacitor": {
+    "ios": {
+      "src": "ios",
+      "dest": "ios"
+    },
+    "android": {
+      "src": "android",
+      "dest": "android"
+    }
   }
 }

package/templates/app-mobile/template.json

@@ -9,8 +9,17 @@
       "description": "平台项目 slug（写入包名 / adep.app.json / bundle id 推导）"
     },
     { "name": "appName", "description": "应用显示名（iOS / Android 显示名）" },
-    { "name": "platformUrl", "description": "平台地址（页面侧 @adep/client 以此为 baseUrl invoke 云函数）" },
-    { "name": "iosBundleId", "description": "iOS bundle identifier（top.adep.<slug>，连字符合法）" },
-    { "name": "androidPackageId", "description": "Android applicationId（top.adep.<slug 连字符转下划线>，applicationId 不允许连字符）" }
+    {
+      "name": "platformUrl",
+      "description": "平台地址（页面侧 @adep/client 以此为 baseUrl invoke 云函数）"
+    },
+    {
+      "name": "iosBundleId",
+      "description": "iOS bundle identifier（top.adep.<slug>，连字符合法）"
+    },
+    {
+      "name": "androidPackageId",
+      "description": "Android applicationId（top.adep.<slug 剔除连字符>，双端共用一个 appId：capacitor 双端校验禁连字符、下划线形态 iOS 签不了名）"
+    }
   ]
 }