@bardway/trpg-notebook-native 0.0.0-stage → 0.1.0

package/android/src/main/java/expo/modules/notebookstorage/NotebookStore.kt

@@ -0,0 +1,650 @@
+package expo.modules.notebookstorage
+
+import android.content.Context
+import android.database.DatabaseErrorHandler
+import android.database.sqlite.SQLiteDatabase
+import android.net.Uri
+import android.os.Build
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.File
+import java.nio.ByteBuffer
+import java.nio.charset.CodingErrorAction
+import java.nio.charset.StandardCharsets
+import java.security.MessageDigest
+import java.util.UUID
+
+/** All calls run on the module's single IO queue. User content never leaves noBackupFilesDir. */
+internal class NotebookStore(private val context: Context) {
+  private var database: SQLiteDatabase? = null
+  private val root = File(context.noBackupFilesDir, "trpg-notebook")
+  private val maxFileBytes = 16 * 1024 * 1024
+  private val maxSessionBytes = 256L * 1024 * 1024
+  private val maxAccountBytes = 512L * 1024 * 1024
+
+  private fun fail(message: String): Nothing = throw IllegalStateException(message)
+  private fun str(obj: JSONObject, key: String, max: Int = 256): String {
+    val value = obj.opt(key)
+    if (value !is String || value.isEmpty() || value.length > max) fail("手记参数无效: $key")
+    return value
+  }
+  private fun number(obj: JSONObject, key: String): Double {
+    val value = obj.opt(key)
+    if (value !is Number || !value.toDouble().isFinite()) fail("手记数值无效: $key")
+    return value.toDouble()
+  }
+  private fun hash(text: String): String = MessageDigest.getInstance("SHA-256")
+    .digest(text.toByteArray(StandardCharsets.UTF_8)).joinToString("") { "%02x".format(it) }
+
+  private fun db(): SQLiteDatabase {
+    database?.let { return it }
+    if (!root.exists() && !root.mkdirs()) fail("无法建立手记存储目录")
+    val file = File(root, "notebook.sqlite")
+    // Android's default corruption handler deletes database files. Preserve them for recovery.
+    val errorHandler = DatabaseErrorHandler { fail("手记数据库损坏，已保留原始数据") }
+    val opened = if (Build.VERSION.SDK_INT >= 28) {
+      SQLiteDatabase.openDatabase(file, SQLiteDatabase.OpenParams.Builder()
+        .addOpenFlags(SQLiteDatabase.CREATE_IF_NECESSARY or SQLiteDatabase.ENABLE_WRITE_AHEAD_LOGGING)
+        .setJournalMode("WAL").setSynchronousMode("FULL").setErrorHandler(errorHandler).build())
+    } else {
+      SQLiteDatabase.openDatabase(file.absolutePath, null,
+        SQLiteDatabase.CREATE_IF_NECESSARY, errorHandler).also {
+        // API 24-27 has no per-pool synchronous configuration: retain one rollback-journal connection.
+        it.disableWriteAheadLogging()
+        it.rawQuery("PRAGMA journal_mode=DELETE", null).use { cursor -> cursor.moveToFirst() }
+        it.execSQL("PRAGMA synchronous=FULL")
+      }
+    }
+    try {
+      opened.setForeignKeyConstraintsEnabled(true)
+      opened.rawQuery("PRAGMA quick_check(1)", null).use {
+        if (!it.moveToFirst() || it.getString(0) != "ok") fail("手记数据库校验失败，已保留原始数据")
+      }
+      if (opened.version > 3) fail("手记数据版本较新，请使用较新版本应用")
+      if (opened.version < 3) {
+        // Rebuilding a referenced parent table with foreign keys enabled would cascade-delete ink.
+        // Disable outside the transaction, then verify every reference before committing v3.
+        opened.setForeignKeyConstraintsEnabled(false)
+        try {
+          opened.beginTransaction()
+          try {
+            if (opened.version == 0) createSchema(opened)
+            else if (opened.version == 1) migrateVersionOne(opened)
+            opened.execSQL("ALTER TABLE documents ADD COLUMN memo_template TEXT")
+            validateStoredWorkspaces(opened)
+            opened.rawQuery("PRAGMA foreign_key_check", null).use {
+              if (it.moveToFirst()) fail("手记迁移引用校验失败，已保留原始数据")
+            }
+            opened.version = 3
+            opened.setTransactionSuccessful()
+          } finally { opened.endTransaction() }
+        } finally { opened.setForeignKeyConstraintsEnabled(true) }
+      }
+      database = opened
+      return opened
+    } catch (error: Throwable) {
+      opened.close()
+      throw error
+    }
+  }
+
+  private fun createDocumentsTable(database: SQLiteDatabase, table: String) {
+    database.execSQL("CREATE TABLE $table(id TEXT PRIMARY KEY,account_id TEXT NOT NULL,session_id TEXT NOT NULL,kind TEXT NOT NULL CHECK(kind IN ('memo','imported-markdown')),title TEXT NOT NULL,ordinal INTEGER NOT NULL,revision INTEGER NOT NULL DEFAULT 0,layout TEXT,FOREIGN KEY(account_id,session_id) REFERENCES workspaces(account_id,session_id))")
+  }
+  private fun createSchema(database: SQLiteDatabase) {
+    database.execSQL("CREATE TABLE workspaces(account_id TEXT NOT NULL,session_id TEXT NOT NULL,generation TEXT NOT NULL,active_id TEXT,deleted INTEGER NOT NULL DEFAULT 0,PRIMARY KEY(account_id,session_id))")
+    createDocumentsTable(database, "documents")
+    database.execSQL("CREATE UNIQUE INDEX fixed_documents ON documents(account_id,session_id,kind) WHERE kind='memo'")
+    database.execSQL("CREATE TABLE contents(document_id TEXT PRIMARY KEY,markdown TEXT,content_hash TEXT,FOREIGN KEY(document_id) REFERENCES documents(id) ON DELETE CASCADE)")
+    database.execSQL("CREATE TABLE strokes(document_id TEXT NOT NULL,id TEXT NOT NULL,payload TEXT NOT NULL,PRIMARY KEY(document_id,id),FOREIGN KEY(document_id) REFERENCES documents(id) ON DELETE CASCADE)")
+    database.execSQL("CREATE TABLE operations(document_id TEXT NOT NULL,op_id TEXT NOT NULL,payload_hash TEXT NOT NULL,payload TEXT,revision INTEGER NOT NULL,PRIMARY KEY(document_id,op_id),FOREIGN KEY(document_id) REFERENCES documents(id) ON DELETE CASCADE)")
+    database.execSQL("CREATE TABLE viewports(document_id TEXT PRIMARY KEY,payload TEXT NOT NULL,FOREIGN KEY(document_id) REFERENCES documents(id) ON DELETE CASCADE)")
+    database.execSQL("CREATE TABLE snapshots(document_id TEXT NOT NULL,revision INTEGER NOT NULL,payload TEXT NOT NULL,payload_hash TEXT NOT NULL,PRIMARY KEY(document_id,revision),FOREIGN KEY(document_id) REFERENCES documents(id) ON DELETE CASCADE)")
+  }
+
+  /** Only an untouched, verifiably empty automatic page may be removed. Erased ink is history. */
+  private fun isAutomaticPlaceholder(database: SQLiteDatabase, id: String): Boolean {
+    database.rawQuery("SELECT d.revision,c.document_id,(c.markdown IS NULL OR length(c.markdown)=0),EXISTS(SELECT 1 FROM strokes WHERE document_id=d.id),EXISTS(SELECT 1 FROM operations WHERE document_id=d.id) FROM documents d LEFT JOIN contents c ON c.document_id=d.id WHERE d.id=?", arrayOf(id)).use {
+      if (!it.moveToFirst() || it.isNull(1)) fail("手记正文记录不完整，已保留原始数据")
+      if (it.getLong(0) != 0L || it.getInt(2) != 1 || it.getInt(3) != 0 || it.getInt(4) != 0) return false
+    }
+    var hasEmptySnapshot = false
+    database.rawQuery("SELECT revision,length(payload),payload_hash FROM snapshots WHERE document_id=?", arrayOf(id)).use {
+      while (it.moveToNext()) {
+        // An unfamiliar/corrupt recovery record is retained rather than treated as an empty page.
+        if (it.getLong(0) != 0L || it.getLong(1) > 256) return false
+        val payload = readTextColumn(database, "snapshots", "payload", "document_id=? AND revision=?", arrayOf(id, it.getLong(0).toString()))
+        if (hash(payload) != it.getString(2)) return false
+        try { if (JSONArray(payload).length() != 0) return false } catch (_: Exception) { return false }
+        hasEmptySnapshot = true
+      }
+    }
+    return hasEmptySnapshot
+  }
+
+  private fun migrateVersionOne(database: SQLiteDatabase) {
+    val legacyIds = mutableListOf<String>()
+    database.rawQuery("SELECT id FROM documents WHERE kind='appendix'", null).use {
+      while (it.moveToNext()) legacyIds.add(it.getString(0))
+    }
+    for (id in legacyIds) {
+      if (isAutomaticPlaceholder(database, id)) {
+        for (table in listOf("contents", "strokes", "operations", "viewports", "snapshots"))
+          database.execSQL("DELETE FROM $table WHERE document_id=?", arrayOf(id))
+        database.execSQL("DELETE FROM documents WHERE id=?", arrayOf(id))
+      } else {
+        database.execSQL("UPDATE documents SET kind='imported-markdown' WHERE id=?", arrayOf(id))
+        database.execSQL("UPDATE contents SET markdown='',content_hash=? WHERE document_id=? AND markdown IS NULL", arrayOf(hash(""), id))
+      }
+    }
+    database.execSQL("UPDATE workspaces SET active_id=(SELECT id FROM documents d WHERE d.account_id=workspaces.account_id AND d.session_id=workspaces.session_id AND d.kind='memo') WHERE deleted=0 AND NOT EXISTS(SELECT 1 FROM documents d WHERE d.id=workspaces.active_id AND d.account_id=workspaces.account_id AND d.session_id=workspaces.session_id)")
+    // Child tables retain their document IDs, row order, payloads, hashes and operation receipts.
+    createDocumentsTable(database, "documents_v2")
+    database.execSQL("INSERT INTO documents_v2(id,account_id,session_id,kind,title,ordinal,revision,layout) SELECT id,account_id,session_id,kind,title,ordinal,revision,layout FROM documents")
+    database.execSQL("DROP TABLE documents")
+    database.execSQL("ALTER TABLE documents_v2 RENAME TO documents")
+    database.execSQL("CREATE UNIQUE INDEX fixed_documents ON documents(account_id,session_id,kind) WHERE kind='memo'")
+  }
+
+  private fun validateStoredWorkspaces(database: SQLiteDatabase) {
+    database.rawQuery("SELECT 1 FROM workspaces w WHERE w.deleted=0 AND ((SELECT COUNT(*) FROM documents d WHERE d.account_id=w.account_id AND d.session_id=w.session_id AND d.kind='memo')<>1 OR NOT EXISTS(SELECT 1 FROM documents d WHERE d.id=w.active_id AND d.account_id=w.account_id AND d.session_id=w.session_id)) LIMIT 1", null).use {
+      if (it.moveToFirst()) fail("手记工作区迁移校验失败，已保留原始数据")
+    }
+    database.rawQuery("SELECT 1 FROM documents d LEFT JOIN contents c ON c.document_id=d.id LEFT JOIN viewports v ON v.document_id=d.id WHERE c.document_id IS NULL OR v.document_id IS NULL OR (d.kind='imported-markdown' AND c.markdown IS NULL) OR (d.kind='memo' AND c.markdown IS NOT NULL) LIMIT 1", null).use {
+      if (it.moveToFirst()) fail("手记文档迁移校验失败，已保留原始数据")
+    }
+  }
+
+  private fun <T> transaction(block: (SQLiteDatabase) -> T): T {
+    val database = db()
+    database.beginTransaction()
+    try {
+      val result = block(database)
+      database.setTransactionSuccessful()
+      return result
+    } finally { database.endTransaction() }
+  }
+
+  private fun defaultViewport() = JSONObject().put("scale", 1).put("paperOffsetX", 0).put("paperOffsetY", 0)
+  /** Keep each CursorWindow row below its device-specific limit, including API 24-27. */
+  private fun readTextColumn(database: SQLiteDatabase, table: String, column: String, condition: String, args: Array<String>): String {
+    val result = StringBuilder()
+    var offset = 1L
+    while (true) {
+      val chunk = database.rawQuery("SELECT substr($column,?,65536) FROM $table WHERE $condition", arrayOf(offset.toString(), *args)).use {
+        if (!it.moveToFirst() || it.isNull(0)) return result.toString()
+        it.getString(0)
+      }
+      if (chunk.isEmpty()) break
+      result.append(chunk)
+      // SQLite substr indexes Unicode code points rather than Java UTF-16 units.
+      offset += chunk.codePointCount(0, chunk.length)
+    }
+    return result.toString()
+  }
+  private fun validateContext(database: SQLiteDatabase, request: JSONObject): JSONObject {
+    val scope = request.getJSONObject("context")
+    val account = str(scope, "accountId")
+    val session = str(scope, "sessionId")
+    val generation = str(scope, "generation")
+    database.rawQuery("SELECT generation,deleted FROM workspaces WHERE account_id=? AND session_id=?", arrayOf(account, session)).use {
+      if (!it.moveToFirst() || it.getInt(1) != 0 || it.getString(0) != generation) fail("手记工作区已失效")
+    }
+    return scope
+  }
+  private fun validateDocument(database: SQLiteDatabase, request: JSONObject): String {
+    val scope = validateContext(database, request)
+    val id = str(request, "documentId")
+    database.rawQuery("SELECT id FROM documents WHERE id=? AND account_id=? AND session_id=?", arrayOf(id, str(scope, "accountId"), str(scope, "sessionId"))).use {
+      if (!it.moveToFirst()) fail("手记文档不存在")
+    }
+    return id
+  }
+  private fun parseMemoTemplateInput(input: JSONObject): JSONObject {
+    val rows = input.getJSONArray("rows")
+    if (rows.length() > 1000) fail("Memo template row limit exceeded")
+    val cleanRows = JSONArray()
+    val ids = mutableSetOf<String>()
+    for (index in 0 until rows.length()) {
+      val row = rows.getJSONObject(index)
+      if (!ids.add(str(row, "id"))) fail("Memo template row identity reused")
+      cleanRows.put(JSONObject().put("id", str(row, "id")).put("label", str(row, "label", 8192)))
+    }
+    val rowHeight = number(input, "rowHeight")
+    val labelWidth = number(input, "labelColumnWidth")
+    val bodyGap = number(input, "bodyGap")
+    val bodyHeight = number(input, "bodyHeight")
+    val offset = if (rows.length() == 0) 0.0 else rows.length() * rowHeight + bodyGap
+    if (rowHeight !in 1.0..1e7 || labelWidth !in 1.0..1600.0 || bodyGap !in 0.0..1e7 || bodyHeight <= 0 || bodyHeight > 1e7 || offset + bodyHeight > 1e7) fail("Memo template dimensions invalid")
+    return JSONObject().put("rows", cleanRows).put("rowHeight", rowHeight).put("labelColumnWidth", labelWidth)
+      .put("bodyGap", bodyGap).put("bodyHeight", bodyHeight).put("bodyOffsetY", offset)
+  }
+  private fun readMemoTemplate(database: SQLiteDatabase, id: String): JSONObject? {
+    val exists = database.rawQuery("SELECT memo_template IS NOT NULL FROM documents WHERE id=?", arrayOf(id)).use { it.moveToFirst() && it.getInt(0) == 1 }
+    if (!exists) return null
+    val template = JSONObject(readTextColumn(database, "documents", "memo_template", "id=?", arrayOf(id)))
+    val normalized = parseMemoTemplateInput(template)
+    str(template, "id")
+    if (number(template, "version") != 1.0 || number(template, "bodyOffsetY") != number(normalized, "bodyOffsetY")) fail("Memo template invalid")
+    return template
+  }
+  private fun validateMemoTemplateIdentity(database: SQLiteDatabase, id: String, request: JSONObject): JSONObject? {
+    val template = readMemoTemplate(database, id)
+    if (template == null) {
+      if (request.has("memoTemplateId")) fail("Memo template已失效")
+    } else if (request.opt("memoTemplateId") != template.getString("id")) fail("Memo template已失效")
+    return template
+  }
+  private fun summaries(database: SQLiteDatabase, account: String, session: String): JSONArray {
+    val result = JSONArray()
+    database.rawQuery("SELECT id,kind,title,ordinal,revision FROM documents WHERE account_id=? AND session_id=? ORDER BY ordinal", arrayOf(account, session)).use {
+      while (it.moveToNext()) result.put(JSONObject().put("id", it.getString(0)).put("kind", it.getString(1))
+        .put("title", it.getString(2)).put("ordinal", it.getInt(3)).put("revision", it.getLong(4)))
+    }
+    return result
+  }
+  private fun insertDocument(database: SQLiteDatabase, account: String, session: String, kind: String, title: String, ordinal: Int, markdown: String?): String {
+    val id = UUID.randomUUID().toString()
+    database.execSQL("INSERT INTO documents(id,account_id,session_id,kind,title,ordinal) VALUES(?,?,?,?,?,?)", arrayOf<Any>(id, account, session, kind, title, ordinal))
+    database.execSQL("INSERT INTO contents(document_id,markdown,content_hash) VALUES(?,?,?)", arrayOf(id, markdown, markdown?.let(::hash)))
+    database.execSQL("INSERT INTO viewports(document_id,payload) VALUES(?,?)", arrayOf(id, defaultViewport().toString()))
+    writeSnapshot(database, id, 0)
+    return id
+  }
+  private fun totalBytes(database: SQLiteDatabase, account: String, session: String?): Long {
+    val condition = if (session == null) "d.account_id=?" else "d.account_id=? AND d.session_id=?"
+    val args = if (session == null) arrayOf(account) else arrayOf(account, session)
+    database.rawQuery("SELECT COALESCE(SUM(length(CAST(c.markdown AS BLOB))),0) FROM contents c JOIN documents d ON d.id=c.document_id WHERE $condition", args).use {
+      it.moveToFirst()
+      return it.getLong(0)
+    }
+  }
+
+  fun capabilities(): String {
+    val database = db()
+    val journal = database.rawQuery("PRAGMA journal_mode", null).use { it.moveToFirst(); it.getString(0).lowercase() }
+    val sync = database.rawQuery("PRAGMA synchronous", null).use { it.moveToFirst(); it.getInt(0) }
+    if (sync != 2 || journal !in listOf("wal", "delete", "truncate", "persist")) fail("手记持久化配置不可用")
+    return JSONObject().put("persistent", true).put("excludedFromBackup", true)
+      .put("journalMode", if (journal == "wal") "wal" else "delete").put("synchronous", "full").toString()
+  }
+
+  fun ensureWorkspace(payload: String): String = transaction { database ->
+    val request = JSONObject(payload)
+    val account = str(request, "accountId")
+    val session = str(request, "sessionId")
+    var generation: String? = null
+    var active: String? = null
+    database.rawQuery("SELECT generation,active_id,deleted FROM workspaces WHERE account_id=? AND session_id=?", arrayOf(account, session)).use {
+      if (it.moveToFirst()) {
+        if (it.getInt(2) != 0) fail("该场手记已随会话删除")
+        generation = it.getString(0)
+        active = it.getString(1)
+      }
+    }
+    if (generation == null) {
+      generation = UUID.randomUUID().toString()
+      database.execSQL("INSERT INTO workspaces(account_id,session_id,generation) VALUES(?,?,?)", arrayOf(account, session, generation))
+      active = insertDocument(database, account, session, "memo", "Memo", 0, null)
+      database.execSQL("UPDATE workspaces SET active_id=? WHERE account_id=? AND session_id=?", arrayOf(active, account, session))
+    }
+    JSONObject().put("context", JSONObject().put("accountId", account).put("sessionId", session).put("generation", generation))
+      .put("documents", summaries(database, account, session)).put("activeDocumentId", active).toString()
+  }
+
+  /** Capture host-provided rows once; original ink, operations and recovery records remain intact. */
+  fun initializeMemoTemplate(payload: String): String = transaction { database ->
+    val request = JSONObject(payload)
+    val id = validateDocument(database, request)
+    var existingLayout: JSONObject? = null
+    database.rawQuery("SELECT kind,layout IS NULL FROM documents WHERE id=?", arrayOf(id)).use {
+      if (!it.moveToFirst() || it.getString(0) != "memo") fail("Templates require a blank memo")
+      if (it.getInt(1) == 0) existingLayout = JSONObject(readTextColumn(database, "documents", "layout", "id=?", arrayOf(id)))
+    }
+    val candidate = parseMemoTemplateInput(request.getJSONObject("template"))
+    if (readMemoTemplate(database, id) == null) {
+      val template = candidate
+      val templateId = UUID.randomUUID().toString()
+      template.put("id", templateId).put("version", 1)
+      val layout = existingLayout
+      if (layout != null) {
+        if (number(layout, "paperWidth") != 1600.0 || number(layout, "paperHeight") != 10000.0 || layout.has("memoTemplateId") || number(template, "bodyHeight") < number(layout, "paperHeight")) fail("Original memo layout invalid; data retained")
+        layout.put("paperHeight", number(template, "bodyHeight") + number(template, "bodyOffsetY")).put("geometry", JSONArray())
+          .put("fingerprint", "memo-template:$templateId").put("memoTemplateId", templateId)
+      }
+      database.execSQL("UPDATE documents SET memo_template=?,layout=? WHERE id=?", arrayOf(template.toString(), layout?.toString(), id))
+      database.execSQL("UPDATE viewports SET payload=? WHERE document_id=?", arrayOf(defaultViewport().put("fitToWidth", true).toString(), id))
+    }
+    readDocument(payload)
+  }
+
+  private fun readStrokes(database: SQLiteDatabase, id: String): JSONArray {
+    val result = JSONArray()
+    database.rawQuery("SELECT id FROM strokes WHERE document_id=? ORDER BY rowid", arrayOf(id)).use {
+      while (it.moveToNext()) result.put(JSONObject(readTextColumn(database, "strokes", "payload", "document_id=? AND id=?", arrayOf(id, it.getString(0)))))
+    }
+    return result
+  }
+  private fun recoverStrokes(database: SQLiteDatabase, id: String, revision: Long, layout: JSONObject, memoTemplate: JSONObject?): JSONArray {
+    var lastError: Throwable? = null
+    val candidates = mutableListOf<Pair<Long, String>>()
+    database.rawQuery("SELECT revision,payload_hash FROM snapshots WHERE document_id=? ORDER BY revision DESC", arrayOf(id)).use {
+      while (it.moveToNext()) {
+        val snapshot = readTextColumn(database, "snapshots", "payload", "document_id=? AND revision=?", arrayOf(id, it.getLong(0).toString()))
+        if (hash(snapshot) == it.getString(1)) candidates.add(it.getLong(0) to snapshot)
+      }
+    }
+    for ((snapshotRevision, snapshot) in candidates) {
+      try {
+        val restored = linkedMapOf<String, JSONObject>()
+        val snapshotStrokes = JSONArray(snapshot)
+        for (index in 0 until snapshotStrokes.length()) {
+          val stroke = snapshotStrokes.getJSONObject(index)
+          validateStroke(stroke, id, layout, memoTemplate)
+          restored[str(stroke, "id")] = stroke
+        }
+        var nextRevision = snapshotRevision + 1
+        database.rawQuery("SELECT revision,op_id,payload_hash,payload IS NULL FROM operations WHERE document_id=? AND revision>? ORDER BY revision", arrayOf(id, snapshotRevision.toString())).use {
+          while (it.moveToNext()) {
+            if (it.getLong(0) != nextRevision++ || it.getInt(3) == 1) fail("手记恢复操作不完整")
+            val operationText = readTextColumn(database, "operations", "payload", "document_id=? AND op_id=?", arrayOf(id, it.getString(1)))
+            if (hash(operationText) != it.getString(2)) fail("手记恢复操作校验失败")
+            val operation = JSONObject(operationText)
+            when (str(operation, "type")) {
+              "addStroke" -> {
+                val stroke = operation.getJSONObject("stroke")
+                validateStroke(stroke, id, layout, memoTemplate)
+                restored[str(stroke, "id")] = stroke
+              }
+              "eraseStrokes" -> {
+                val ids = operation.getJSONArray("strokeIds")
+                for (index in 0 until ids.length()) restored.remove(ids.getString(index))
+              }
+              else -> fail("手记恢复操作类型无效")
+            }
+          }
+        }
+        if (nextRevision - 1 != revision) fail("手记恢复版本不完整")
+        return transaction { db ->
+          db.execSQL("DELETE FROM strokes WHERE document_id=?", arrayOf(id))
+          restored.values.forEach { stroke -> db.execSQL("INSERT INTO strokes(document_id,id,payload) VALUES(?,?,?)", arrayOf(id, str(stroke, "id"), stroke.toString())) }
+          readStrokes(db, id)
+        }
+      } catch (error: Throwable) { lastError = error }
+    }
+    throw IllegalStateException("手记笔迹恢复失败，已保留快照与操作记录", lastError)
+  }
+  fun readDocument(payload: String): String {
+    val request = JSONObject(payload)
+    val database = db()
+    val id = validateDocument(database, request)
+    val memoTemplate = readMemoTemplate(database, id)
+    database.rawQuery("SELECT d.kind,d.title,d.ordinal,d.revision,d.layout IS NULL,c.markdown IS NULL,c.content_hash,v.payload FROM documents d JOIN contents c ON c.document_id=d.id JOIN viewports v ON v.document_id=d.id WHERE d.id=?", arrayOf(id)).use {
+      if (!it.moveToFirst()) fail("手记文档记录不完整")
+      val layout = if (it.getInt(4) == 1) null else JSONObject(readTextColumn(database, "documents", "layout", "id=?", arrayOf(id)))
+      val strokes = try {
+        readStrokes(database, id).also { strokes ->
+          if (layout != null) for (index in 0 until strokes.length()) validateStroke(strokes.getJSONObject(index), id, layout, memoTemplate)
+        }
+      } catch (error: Exception) {
+        if (layout == null) throw error
+        recoverStrokes(database, id, it.getLong(3), layout, memoTemplate)
+      }
+      return JSONObject().put("id", id).put("kind", it.getString(0)).put("title", it.getString(1))
+        .put("ordinal", it.getInt(2)).put("revision", it.getLong(3))
+        .put("layout", layout ?: JSONObject.NULL)
+        .put("memoTemplate", memoTemplate ?: JSONObject.NULL)
+        .put("markdown", if (it.getInt(5) == 1) JSONObject.NULL else readTextColumn(database, "contents", "markdown", "document_id=?", arrayOf(id)))
+        .put("contentHash", if (it.isNull(6)) JSONObject.NULL else it.getString(6))
+        .put("viewport", JSONObject(it.getString(7))).put("strokes", strokes).toString()
+    }
+  }
+
+  fun importDocument(payload: String): String = transaction { database ->
+    val request = JSONObject(payload)
+    val scope = validateContext(database, request)
+    val account = str(scope, "accountId")
+    val session = str(scope, "sessionId")
+    val incoming = request.getJSONObject("document")
+    val markdown = incoming.getString("markdown")
+    val bytes = markdown.toByteArray(StandardCharsets.UTF_8).size
+    if (bytes > maxFileBytes) fail("Markdown 文件超过 16 MiB")
+    if (totalBytes(database, account, session) + bytes > maxSessionBytes) fail("本场手记正文超过 256 MiB")
+    if (totalBytes(database, account, null) + bytes > maxAccountBytes) fail("本账号手记正文超过 512 MiB")
+    val baseTitle = str(incoming, "title", 4096)
+    var title = baseTitle
+    val titles = mutableSetOf<String>()
+    var ordinal = 1
+    database.rawQuery("SELECT title,ordinal FROM documents WHERE account_id=? AND session_id=?", arrayOf(account, session)).use {
+      while (it.moveToNext()) { titles.add(it.getString(0)); ordinal = maxOf(ordinal, it.getInt(1) + 1) }
+    }
+    var count = 2
+    while (title in titles) { title = "$baseTitle（${count++}）" }
+    val id = insertDocument(database, account, session, "imported-markdown", title, ordinal, markdown)
+    database.execSQL("UPDATE workspaces SET active_id=? WHERE account_id=? AND session_id=?", arrayOf(id, account, session))
+    JSONObject().put("id", id).put("kind", "imported-markdown").put("title", title).put("ordinal", ordinal).put("revision", 0).toString()
+  }
+
+  private fun validateStroke(stroke: JSONObject, documentId: String, layout: JSONObject, memoTemplate: JSONObject?) {
+    str(stroke, "id")
+    if (str(stroke, "documentId") != documentId) fail("笔迹所属文档无效")
+    if (number(stroke, "layoutVersion") != number(layout, "layoutVersion")) fail("笔迹排版版本不一致")
+    if (stroke.has("coordinateSpace") && stroke.opt("coordinateSpace") != "paper") fail("笔迹坐标空间无效")
+    val maxHeight = if (memoTemplate != null && !stroke.has("coordinateSpace")) number(memoTemplate, "bodyHeight") else number(layout, "paperHeight")
+    val width = number(stroke, "width")
+    if (width <= 0 || width > 64) fail("笔宽超出范围")
+    if (!Regex("#[0-9a-fA-F]{6}").matches(str(stroke, "color", 7))) fail("笔迹颜色无效")
+    str(stroke, "createdAt", 64)
+    val points = stroke.getJSONArray("points")
+    if (points.length() < 1 || points.length() > 100000) fail("笔迹采样点数量超限")
+    for (index in 0 until points.length()) {
+      val point = points.getJSONObject(index)
+      val x = number(point, "x")
+      val y = number(point, "y")
+      if (x < 0 || y < 0 || x > number(layout, "paperWidth") || y > maxHeight) fail("笔迹坐标超出纸面")
+      if (point.has("pressure") && number(point, "pressure") !in 0.0..1.0) fail("笔压超出范围")
+      if (point.has("t") && number(point, "t") < 0) fail("笔迹时间无效")
+    }
+  }
+  private fun applyOperation(database: SQLiteDatabase, documentId: String, operation: JSONObject, layout: JSONObject, memoTemplate: JSONObject?) {
+    when (str(operation, "type")) {
+      "addStroke" -> {
+        val stroke = operation.getJSONObject("stroke")
+        validateStroke(stroke, documentId, layout, memoTemplate)
+        database.execSQL("INSERT INTO strokes(document_id,id,payload) VALUES(?,?,?)", arrayOf(documentId, str(stroke, "id"), stroke.toString()))
+      }
+      "eraseStrokes" -> {
+        val ids = operation.getJSONArray("strokeIds")
+        if (ids.length() > 100000) fail("擦除笔迹数量超限")
+        for (index in 0 until ids.length()) {
+          val id = ids.get(index)
+          if (id !is String || id.isEmpty() || id.length > 256) fail("擦除笔迹标识无效")
+          database.execSQL("DELETE FROM strokes WHERE document_id=? AND id=?", arrayOf(documentId, id))
+        }
+      }
+      else -> fail("手记操作类型无效")
+    }
+  }
+  private fun writeSnapshot(database: SQLiteDatabase, id: String, revision: Long) {
+    val payload = readStrokes(database, id).toString()
+    database.execSQL("INSERT OR REPLACE INTO snapshots(document_id,revision,payload,payload_hash) VALUES(?,?,?,?)", arrayOf<Any>(id, revision, payload, hash(payload)))
+    database.execSQL("DELETE FROM snapshots WHERE document_id=? AND revision NOT IN (SELECT revision FROM snapshots WHERE document_id=? ORDER BY revision DESC LIMIT 2)", arrayOf(id, id))
+    database.execSQL("UPDATE operations SET payload=NULL WHERE document_id=? AND revision < (SELECT MIN(revision) FROM snapshots WHERE document_id=?)", arrayOf(id, id))
+  }
+  fun commitOperation(payload: String): String = transaction { database ->
+    if (payload.toByteArray(StandardCharsets.UTF_8).size > 8 * 1024 * 1024) fail("笔迹操作体积超限")
+    val request = JSONObject(payload)
+    val id = validateDocument(database, request)
+    val operation = request.getJSONObject("operation")
+    val opId = str(operation, "opId")
+    val operationHash = hash(operation.toString())
+    var duplicate = false
+    var revision = 0L
+    database.rawQuery("SELECT revision,payload_hash FROM operations WHERE document_id=? AND op_id=?", arrayOf(id, opId)).use {
+      if (it.moveToFirst()) {
+        if (it.getString(1) != operationHash) fail("相同操作编号包含不同笔迹")
+        duplicate = true
+        revision = it.getLong(0)
+      }
+    }
+    if (!duplicate) {
+      var layout: JSONObject? = null
+      database.rawQuery("SELECT revision,layout IS NULL FROM documents WHERE id=?", arrayOf(id)).use {
+        it.moveToFirst()
+        revision = it.getLong(0) + 1
+        if (it.getInt(1) == 0) layout = JSONObject(readTextColumn(database, "documents", "layout", "id=?", arrayOf(id)))
+      }
+      val profile = layout ?: fail("纸面尚未完成排版，请等待加载")
+      applyOperation(database, id, operation, profile, readMemoTemplate(database, id))
+      database.execSQL("INSERT INTO operations(document_id,op_id,payload_hash,payload,revision) VALUES(?,?,?,?,?)", arrayOf<Any>(id, opId, operationHash, operation.toString(), revision))
+      database.execSQL("UPDATE documents SET revision=? WHERE id=?", arrayOf<Any>(revision, id))
+      if (revision % 64L == 0L) writeSnapshot(database, id, revision)
+    }
+    JSONObject().put("context", request.getJSONObject("context")).put("documentId", id).put("opId", opId)
+      .put("revision", revision).put("duplicate", duplicate).toString()
+  }
+
+  fun saveViewport(payload: String): String = transaction { database ->
+    val request = JSONObject(payload)
+    val id = validateDocument(database, request)
+    validateMemoTemplateIdentity(database, id, request)
+    val viewport = request.getJSONObject("viewport")
+    validateViewport(viewport)
+    database.execSQL("UPDATE viewports SET payload=? WHERE document_id=?", arrayOf(viewport.toString(), id))
+    "{}"
+  }
+  private fun validateViewport(viewport: JSONObject) {
+    if (viewport.has("fitToWidth") && viewport.opt("fitToWidth") != true) fail("视口适配标记无效")
+    if (number(viewport, "scale") !in 0.25..4.0) fail("缩放比例超出范围")
+    if (kotlin.math.abs(number(viewport, "paperOffsetX")) > 1e7 || kotlin.math.abs(number(viewport, "paperOffsetY")) > 1e7) fail("视口位置超出范围")
+  }
+  fun saveLayoutProfile(payload: String): String = transaction { database ->
+    val request = JSONObject(payload)
+    val id = validateDocument(database, request)
+    val memoTemplate = validateMemoTemplateIdentity(database, id, request)
+    val layout = request.getJSONObject("layout")
+    if (memoTemplate == null) {
+      if (layout.has("memoTemplateId")) fail("Memo template已失效")
+    } else if (layout.opt("memoTemplateId") != memoTemplate.getString("id")) fail("Memo template已失效")
+    val mappedViewport = if (request.has("viewport")) request.getJSONObject("viewport") else null
+    if (mappedViewport != null) validateViewport(mappedViewport)
+    listOf("rendererVersion", "fontAssetVersion", "styleProfileId", "fingerprint").forEach { str(layout, it) }
+    val version = number(layout, "layoutVersion")
+    if (version < 1 || version % 1 != 0.0) fail("排版版本无效")
+    for (key in listOf("paperWidth", "paperHeight", "contentWidth")) {
+      if (number(layout, key) <= 0 || number(layout, key) > 1e7) fail("纸面尺寸无效")
+    }
+    if (number(layout, "contentWidth") > number(layout, "paperWidth")) fail("正文宽度超出纸面")
+    if (layout.has("geometry")) {
+      val geometry = layout.getJSONArray("geometry")
+      if (geometry.length() > 200000) fail("纸面几何信息超限")
+      for (index in 0 until geometry.length()) {
+        val box = geometry.getJSONObject(index)
+        for (key in listOf("x", "y", "width", "height")) {
+          val value = number(box, key)
+          if (kotlin.math.abs(value) > 1e7 || (key in listOf("width", "height") && value < 0)) fail("纸面几何信息无效")
+        }
+      }
+    }
+    var existing: String? = null
+    var kind = ""
+    database.rawQuery("SELECT layout IS NULL,kind FROM documents WHERE id=?", arrayOf(id)).use { it.moveToFirst(); existing = if (it.getInt(0) == 1) null else readTextColumn(database, "documents", "layout", "id=?", arrayOf(id)); kind = it.getString(1) }
+    val memoHeight = memoTemplate?.let { number(it, "bodyHeight") + number(it, "bodyOffsetY") } ?: 10000.0
+    if (kind == "memo" && (number(layout, "paperWidth") != 1600.0 || number(layout, "paperHeight") != memoHeight)) fail("Memo纸面边界不可修改")
+    if (memoTemplate != null && (str(layout, "fingerprint") != "memo-template:${memoTemplate.getString("id")}" || layout.optJSONArray("geometry")?.length() != 0)) fail("Memo template排版无效")
+    if (existing != null) {
+      val saved = JSONObject(existing)
+      if (!compatibleLayout(saved, layout)) {
+        if (!canUpgradeEmptyLayout(database, id, saved, layout)) fail("已保存纸面排版不可静默修改")
+        val revision = database.rawQuery("SELECT revision FROM documents WHERE id=?", arrayOf(id)).use { it.moveToFirst(); it.getLong(0) }
+        // The current empty state must be recoverable without replaying ink from the old layout.
+        writeSnapshot(database, id, revision)
+        database.execSQL("UPDATE documents SET layout=? WHERE id=?", arrayOf(layout.toString(), id))
+      }
+    } else {
+      database.execSQL("UPDATE documents SET layout=? WHERE id=?", arrayOf(layout.toString(), id))
+    }
+    if (mappedViewport != null) database.execSQL("UPDATE viewports SET payload=? WHERE document_id=?", arrayOf(mappedViewport.toString(), id))
+    "{}"
+  }
+  /** Only empty current ink can reflow; existing operation receipts remain authoritative. */
+  private fun canUpgradeEmptyLayout(database: SQLiteDatabase, id: String, saved: JSONObject, candidate: JSONObject): Boolean {
+    if (str(saved, "styleProfileId") != "paper-v1" || str(candidate, "styleProfileId") != "paper-v2") return false
+    for (key in listOf("rendererVersion", "fontAssetVersion")) {
+      if (str(saved, key) != str(candidate, key)) return false
+    }
+    for (key in listOf("layoutVersion", "paperWidth", "contentWidth")) {
+      if (number(saved, key) != number(candidate, key)) return false
+    }
+    return database.rawQuery(
+      "SELECT NOT EXISTS(SELECT 1 FROM strokes WHERE document_id=?)",
+      arrayOf(id)
+    ).use { cursor ->
+      cursor.moveToFirst() && cursor.getInt(0) == 1
+    }
+  }
+  private fun compatibleLayout(saved: JSONObject, candidate: JSONObject): Boolean {
+    if (saved.opt("memoTemplateId") != candidate.opt("memoTemplateId")) return false
+    for (key in listOf("rendererVersion", "fontAssetVersion", "styleProfileId")) {
+      if (str(saved, key) != str(candidate, key)) return false
+    }
+    if (number(saved, "layoutVersion") != number(candidate, "layoutVersion")) return false
+    for (key in listOf("paperWidth", "paperHeight", "contentWidth")) {
+      if (kotlin.math.abs(number(saved, key) - number(candidate, key)) > 1) return false
+    }
+    if (!saved.has("geometry") || !candidate.has("geometry")) return str(saved, "fingerprint") == str(candidate, "fingerprint")
+    val first = saved.getJSONArray("geometry")
+    val second = candidate.getJSONArray("geometry")
+    if (first.length() != second.length()) return false
+    if (first.length() == 0) return str(saved, "fingerprint") == str(candidate, "fingerprint")
+    for (index in 0 until first.length()) {
+      for (key in listOf("x", "y", "width", "height")) {
+        if (kotlin.math.abs(number(first.getJSONObject(index), key) - number(second.getJSONObject(index), key)) > 1) return false
+      }
+    }
+    return true
+  }
+  fun setActiveDocument(payload: String): String = transaction { database ->
+    val request = JSONObject(payload)
+    val id = validateDocument(database, request)
+    val scope = request.getJSONObject("context")
+    database.execSQL("UPDATE workspaces SET active_id=? WHERE account_id=? AND session_id=?", arrayOf(id, str(scope, "accountId"), str(scope, "sessionId")))
+    "{}"
+  }
+  fun deleteSession(payload: String): String = transaction { database ->
+    val request = JSONObject(payload)
+    val account = str(request, "accountId")
+    val session = str(request, "sessionId")
+    database.execSQL("DELETE FROM documents WHERE account_id=? AND session_id=?", arrayOf(account, session))
+    database.execSQL("INSERT OR REPLACE INTO workspaces(account_id,session_id,generation,active_id,deleted) VALUES(?,?,?,NULL,1)", arrayOf(account, session, UUID.randomUUID().toString()))
+    "{}"
+  }
+  fun readImport(payload: String): String {
+    val request = JSONObject(payload)
+    val uri = Uri.parse(str(request, "uri", 8192))
+    if (uri.scheme != "file") fail("请选择系统已缓存的 Markdown 文件")
+    val file = File(uri.path ?: fail("导入缓存路径无效")).canonicalFile
+    if (!file.canonicalPath.startsWith(context.cacheDir.canonicalPath + File.separator)) fail("导入来源不属于应用缓存")
+    if (!file.isFile || file.length() > maxFileBytes) fail("Markdown 文件不可读或超过 16 MiB")
+    val bytes = file.inputStream().use { stream ->
+      val result = java.io.ByteArrayOutputStream()
+      val buffer = ByteArray(8192)
+      var size = 0
+      while (true) {
+        val read = stream.read(buffer)
+        if (read < 0) break
+        size += read
+        if (size > maxFileBytes) fail("Markdown 文件超过 16 MiB")
+        result.write(buffer, 0, read)
+      }
+      result.toByteArray()
+    }
+    val decoder = StandardCharsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT)
+    val decoded = try { decoder.decode(ByteBuffer.wrap(bytes)).toString() } catch (_: Exception) { fail("文件编码无效，请转换为 UTF-8") }
+    val markdown = decoded.removePrefix("\uFEFF")
+    if (markdown.any { it.code < 32 && it != '\n' && it != '\r' && it != '\t' }) fail("文件包含二进制或损坏内容")
+    return JSONObject().put("markdown", markdown).put("sizeBytes", bytes.size).toString()
+  }
+  fun flush(): String { database?.let { if (it.inTransaction()) fail("手记事务仍在执行") }; return "{}" }
+  fun close() { database?.close(); database = null }
+}