@g9tm/lynxcontrols-native 0.0.0-stage → 1.4.0

package/android/src/main/java/com/g9lynx/g9native/sqlite/androidx/AndroidxSqlEngine.kt

@@ -0,0 +1,88 @@
+package com.g9lynx.g9native.sqlite.androidx
+
+import androidx.sqlite.SQLiteConnection
+import androidx.sqlite.SQLiteException
+import androidx.sqlite.SQLiteStatement
+import androidx.sqlite.driver.bundled.BundledSQLiteDriver
+import androidx.sqlite.driver.bundled.SQLITE_OPEN_CREATE
+import androidx.sqlite.driver.bundled.SQLITE_OPEN_FULLMUTEX
+import androidx.sqlite.driver.bundled.SQLITE_OPEN_READONLY
+import androidx.sqlite.driver.bundled.SQLITE_OPEN_READWRITE
+import com.g9lynx.g9native.sqlite.core.G9SqlConnection
+import com.g9lynx.g9native.sqlite.core.G9SqlEngine
+import com.g9lynx.g9native.sqlite.core.G9SqlEngineException
+import com.g9lynx.g9native.sqlite.core.G9SqlStatement
+
+/**
+ * The production engine: androidx.sqlite `BundledSQLiteDriver` (`sqlite-bundled` 2.7.1), which ships its own SQLite so
+ * every Android version runs the same engine (framework SQLite on API 26 is 3.18 and lacks UPSERT). The same class runs
+ * on the JVM over `sqlite-bundled-jvm` in the contract tests.
+ */
+class AndroidxSqlEngine : G9SqlEngine {
+  private val driver = BundledSQLiteDriver()
+
+  override val name = "androidx-bundled"
+
+  override fun open(path: String, readOnly: Boolean, create: Boolean): G9SqlConnection {
+    val flags =
+      (if (readOnly) SQLITE_OPEN_READONLY else SQLITE_OPEN_READWRITE) or
+        (if (create && !readOnly) SQLITE_OPEN_CREATE else 0) or
+        SQLITE_OPEN_FULLMUTEX
+    return translate { Connection(driver.open(path, flags)) }
+  }
+
+  private class Connection(private val connection: SQLiteConnection) : G9SqlConnection {
+    override fun prepare(sql: String): G9SqlStatement = translate { Statement(connection.prepare(sql)) }
+
+    override fun close() = connection.close()
+  }
+
+  private class Statement(private val statement: SQLiteStatement) : G9SqlStatement {
+    override fun bindNull(index: Int) = translate { statement.bindNull(index) }
+
+    override fun bindLong(index: Int, value: Long) = translate { statement.bindLong(index, value) }
+
+    override fun bindDouble(index: Int, value: Double) = translate { statement.bindDouble(index, value) }
+
+    override fun bindText(index: Int, value: String) = translate { statement.bindText(index, value) }
+
+    override fun bindBlob(index: Int, value: ByteArray) = translate { statement.bindBlob(index, value) }
+
+    override fun step(): Boolean = translate { statement.step() }
+
+    override fun columnCount(): Int = statement.getColumnCount()
+
+    override fun columnName(index: Int): String = statement.getColumnName(index)
+
+    // androidx returns the SQLITE_INTEGER … SQLITE_NULL values that G9SqlType mirrors.
+    override fun columnType(index: Int): Int = statement.getColumnType(index)
+
+    override fun getLong(index: Int): Long = statement.getLong(index)
+
+    override fun getDouble(index: Int): Double = statement.getDouble(index)
+
+    override fun getText(index: Int): String = statement.getText(index)
+
+    override fun getBlob(index: Int): ByteArray = statement.getBlob(index)
+
+    override fun reset() = translate { statement.reset() }
+
+    override fun clearBindings() = translate { statement.clearBindings() }
+
+    override fun close() = statement.close()
+  }
+
+  companion object {
+    private val CODE = Regex("""[Ee]rror code: (\d+)""")
+
+    /** androidx reports failures as `SQLiteException("Error code: N, message: …")`; N is SQLite's result code. */
+    inline fun <T> translate(block: () -> T): T =
+      try {
+        block()
+      } catch (error: SQLiteException) {
+        throw G9SqlEngineException(codeOf(error.message), error.message ?: "SQLite error")
+      }
+
+    fun codeOf(message: String?): Int = message?.let { CODE.find(it)?.groupValues?.get(1)?.toIntOrNull() } ?: 1
+  }
+}

package/android/src/main/java/com/g9lynx/g9native/sqlite/core/G9SqlEngine.kt

@@ -0,0 +1,61 @@
+package com.g9lynx.g9native.sqlite.core
+
+/**
+ * The SQLite engine the core runs on, shaped like the androidx.sqlite KMP API (`SQLiteDriver` / `SQLiteConnection` /
+ * `SQLiteStatement`) so the Android adapter is one call per method. Production: [com.g9lynx.g9native.sqlite.AndroidxSqlEngine]
+ * over `BundledSQLiteDriver`. JVM tests: the same adapter over `sqlite-bundled-jvm`, or a JDBC adapter where Google
+ * Maven is unreachable (plan/execution/Cloud-Runbook.md §8).
+ */
+interface G9SqlEngine {
+  /** Short name for reports (`androidx-bundled`, `jdbc`). */
+  val name: String
+
+  /** Opens a connection. The core has already checked existence and created parent directories. */
+  fun open(path: String, readOnly: Boolean, create: Boolean): G9SqlConnection
+}
+
+interface G9SqlConnection : AutoCloseable {
+  fun prepare(sql: String): G9SqlStatement
+}
+
+/** One prepared statement. Bind indexes are 1-based, column indexes 0-based (as in SQLite and androidx). */
+interface G9SqlStatement : AutoCloseable {
+  fun bindNull(index: Int)
+  fun bindLong(index: Int, value: Long)
+  fun bindDouble(index: Int, value: Double)
+  fun bindText(index: Int, value: String)
+  fun bindBlob(index: Int, value: ByteArray)
+
+  /** Advances; `true` while a row is available. Throws [G9SqlEngineException]. */
+  fun step(): Boolean
+
+  fun columnCount(): Int
+  fun columnName(index: Int): String
+
+  /** One of [G9SqlType]; valid after a `step()` that returned `true`. */
+  fun columnType(index: Int): Int
+  fun getLong(index: Int): Long
+  fun getDouble(index: Int): Double
+  fun getText(index: Int): String
+  fun getBlob(index: Int): ByteArray
+
+  fun reset()
+  fun clearBindings()
+}
+
+/** SQLite fundamental datatypes (`SQLITE_INTEGER` … `SQLITE_NULL`, the androidx `SQLITE_DATA_*` values). */
+object G9SqlType {
+  const val INTEGER = 1
+  const val FLOAT = 2
+  const val TEXT = 3
+  const val BLOB = 4
+  const val NULL = 5
+}
+
+/** An engine failure with SQLite's (extended) result code. */
+class G9SqlEngineException(val resultCode: Int, message: String) : RuntimeException(message)
+
+/** Runs a statement that returns nothing (or whose rows are ignored, as a PRAGMA's). */
+fun G9SqlConnection.exec(sql: String) {
+  prepare(sql).use { statement -> while (statement.step()) Unit }
+}

package/android/src/main/java/com/g9lynx/g9native/sqlite/core/G9SqliteCore.kt

@@ -0,0 +1,260 @@
+package com.g9lynx.g9native.sqlite.core
+
+import java.io.File
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicLong
+
+/** One statement of a batch: SQL and bridge-shaped parameters (see [fromBridge]). */
+class G9Statement(val sql: String, val params: List<Any?>)
+
+/** One statement's outcome. Row values are `null`, `Long`, `Double`, `String` or `ByteArray`. */
+class G9SqlResult(
+  val columns: List<String>,
+  val rows: List<Array<Any?>>,
+  val changes: Long,
+  val lastInsertRowId: Long,
+)
+
+class G9OpenOptions(
+  val path: String,
+  val readOnly: Boolean = false,
+  val create: Boolean = false,
+  /** PRAGMA statements built by `pragmaStatements` on the JS side. */
+  val pragmas: List<String> = emptyList(),
+)
+
+class G9RunOptions(val tx: String? = null, val maxRows: Int? = null, val atomic: Boolean = false)
+
+class G9Capabilities(
+  val sqliteVersion: String,
+  val maxVariables: Int,
+  val json1: Boolean,
+  val returning: Boolean,
+  val upsert: Boolean,
+  val interrupt: Boolean,
+)
+
+/**
+ * The Android SQLite driver core (plan/specs/06 §4): sessions, transaction tokens, a statement cache per session,
+ * value conversion and error mapping, over a [G9SqlEngine]. Not thread-safe per session: [G9SqliteDispatcher] runs
+ * every request of one session on that session's single thread. Cancellation applies to queued work only: androidx
+ * connections expose no `sqlite3_interrupt` (capabilities report `interrupt: false`).
+ */
+class G9SqliteCore(private val engine: G9SqlEngine, private val statementCacheSize: Int = 64) {
+  private class Session(val connection: G9SqlConnection) {
+    // Access order: the first entry is the least recently used (evicted and closed past the cache size).
+    val statements = LinkedHashMap<String, G9SqlStatement>(16, 0.75f, true)
+    var tx: String? = null
+    var lastInsertRowId = 0L
+  }
+
+  private val sessions = ConcurrentHashMap<String, Session>()
+  private val txSessions = ConcurrentHashMap<String, String>()
+  private val counter = AtomicLong()
+
+  val engineName: String
+    get() = engine.name
+
+  /** The session a transaction token belongs to (the dispatcher queues tx work there), or `null`. */
+  fun sessionOfTx(tx: String): String? = txSessions[tx]
+
+  fun capabilities(): G9Capabilities {
+    val connection = engine.open(":memory:", readOnly = false, create = true)
+    try {
+      val version = connection.prepare("SELECT sqlite_version()").use { s -> s.step(); s.getText(0) }
+      val parts = version.split('.').map { it.toIntOrNull() ?: 0 }
+      val atLeast = { major: Int, minor: Int ->
+        (parts.getOrElse(0) { 0 } > major) || (parts.getOrElse(0) { 0 } == major && parts.getOrElse(1) { 0 } >= minor)
+      }
+      return G9Capabilities(version, 32766, json1 = true, returning = atLeast(3, 35), upsert = atLeast(3, 24), interrupt = false)
+    } finally {
+      connection.close()
+    }
+  }
+
+  fun open(options: G9OpenOptions): String {
+    val memory = options.path == "" || options.path == ":memory:"
+    if (!memory) {
+      val file = File(options.path)
+      if (!options.create && !file.exists()) {
+        throw G9SqliteException("not-found", "Database file does not exist: ${options.path}")
+      }
+      if (options.create) file.absoluteFile.parentFile?.mkdirs()
+    }
+    val connection =
+      try {
+        engine.open(if (memory) ":memory:" else options.path, options.readOnly, options.create)
+      } catch (error: Throwable) {
+        throw toG9Error(error)
+      }
+    for (sql in options.pragmas) {
+      try {
+        connection.exec(sql)
+      } catch (error: Throwable) {
+        // journal_mode cannot change on a read-only or in-memory database; tuning never fails an open.
+        if (!sql.startsWith("PRAGMA journal_mode")) {
+          connection.close()
+          throw toG9Error(error, sql)
+        }
+      }
+    }
+    val token = "s${counter.incrementAndGet()}"
+    sessions[token] = Session(connection)
+    return token
+  }
+
+  private fun session(token: String): Session =
+    sessions[token] ?: misuse("The database session is closed or unknown.")
+
+  private fun prepare(session: Session, sql: String): G9SqlStatement {
+    session.statements[sql]?.let { return it }
+    val statement = session.connection.prepare(sql)
+    session.statements[sql] = statement
+    if (session.statements.size > statementCacheSize) {
+      val eldest = session.statements.entries.iterator().next()
+      session.statements.remove(eldest.key)
+      runCatching { eldest.value.close() }
+    }
+    return statement
+  }
+
+  private fun bind(statement: G9SqlStatement, index: Int, raw: Any?, sql: String) {
+    when (val value = fromBridge(raw)) {
+      null -> statement.bindNull(index)
+      is String -> {
+        if (value.indexOf('\u0000') >= 0) misuse("Parameter $index is text containing NUL; use a BLOB.", sql)
+        statement.bindText(index, value)
+      }
+      is Long -> statement.bindLong(index, value)
+      is Double ->
+        when {
+          value.isNaN() -> misuse("Parameter $index is NaN.", sql)
+          value == Math.rint(value) && Math.abs(value) <= MAX_SAFE_INTEGER.toDouble() -> statement.bindLong(index, value.toLong())
+          else -> statement.bindDouble(index, value)
+        }
+      is ByteArray -> statement.bindBlob(index, value)
+      is G9Int64 -> statement.bindLong(index, value.decimal.toLongOrNull() ?: misuse("Parameter $index is not a 64-bit integer.", sql))
+      G9Undefined -> misuse("undefined is not a SQL value (use null).", sql)
+      else -> misuse("Parameter $index is not a SQL value (${value::class.java.simpleName}).", sql)
+    }
+  }
+
+  private fun read(statement: G9SqlStatement, column: Int): Any? =
+    when (statement.columnType(column)) {
+      G9SqlType.NULL -> null
+      G9SqlType.INTEGER -> statement.getLong(column)
+      G9SqlType.FLOAT -> statement.getDouble(column)
+      G9SqlType.TEXT -> statement.getText(column)
+      else -> statement.getBlob(column)
+    }
+
+  private fun execute(session: Session, statement: G9Statement, maxRows: Int?): G9SqlResult {
+    val prepared = prepare(session, statement.sql)
+    try {
+      statement.params.forEachIndexed { i, value -> bind(prepared, i + 1, value, statement.sql) }
+      val count = prepared.columnCount()
+      if (count > 0) {
+        val columns = List(count) { prepared.columnName(it) }
+        val rows = ArrayList<Array<Any?>>()
+        while (prepared.step()) {
+          if (maxRows != null && rows.size >= maxRows) {
+            throw G9SqliteException("too-many-rows", "The statement returned more than $maxRows rows.", sql = statement.sql)
+          }
+          rows.add(Array(count) { read(prepared, it) })
+        }
+        return G9SqlResult(columns, rows, 0, session.lastInsertRowId)
+      }
+      while (prepared.step()) Unit
+      val (changes, rowId) =
+        session.connection.prepare("SELECT changes(), last_insert_rowid()").use { s ->
+          s.step()
+          s.getLong(0) to s.getLong(1)
+        }
+      session.lastInsertRowId = rowId
+      return G9SqlResult(emptyList(), emptyList(), changes, rowId)
+    } finally {
+      runCatching { prepared.reset() }
+      runCatching { prepared.clearBindings() }
+    }
+  }
+
+  fun run(token: String, statements: List<G9Statement>, options: G9RunOptions): List<G9SqlResult> {
+    val session = session(token)
+    if (options.tx != null && session.tx != options.tx) {
+      misuse("The transaction is finished or belongs to another session.")
+    }
+    if (options.tx == null && session.tx != null) misuse("A transaction is open on this session; pass its token (tx).")
+    val atomic = options.atomic && options.tx == null && statements.isNotEmpty()
+    if (atomic) session.connection.exec("BEGIN")
+    val results = ArrayList<G9SqlResult>(statements.size)
+    try {
+      for (statement in statements) {
+        try {
+          results.add(execute(session, statement, options.maxRows))
+        } catch (error: Throwable) {
+          throw toG9Error(error, statement.sql, results.size)
+        }
+      }
+      if (atomic) session.connection.exec("COMMIT")
+    } catch (error: Throwable) {
+      if (atomic) runCatching { session.connection.exec("ROLLBACK") } // SQLite may already have rolled back.
+      throw toG9Error(error)
+    }
+    return results
+  }
+
+  fun begin(token: String, mode: String): String {
+    val session = session(token)
+    if (session.tx != null) misuse("A transaction is already open on this session.")
+    try {
+      session.connection.exec(if (mode == "immediate") "BEGIN IMMEDIATE" else "BEGIN DEFERRED")
+    } catch (error: Throwable) {
+      throw toG9Error(error)
+    }
+    val tx = "x${counter.incrementAndGet()}"
+    session.tx = tx
+    txSessions[tx] = token
+    return tx
+  }
+
+  private fun sessionForTx(tx: String): Session {
+    val token = txSessions[tx] ?: misuse("The transaction is finished or unknown.")
+    val session = sessions[token]
+    if (session == null || session.tx != tx) misuse("The transaction is finished or unknown.")
+    return session
+  }
+
+  fun commit(tx: String) {
+    val session = sessionForTx(tx)
+    try {
+      session.connection.exec("COMMIT")
+    } catch (error: Throwable) {
+      // A failed COMMIT (busy) leaves the transaction open: the caller may retry or roll back.
+      throw toG9Error(error)
+    }
+    session.tx = null
+    txSessions.remove(tx)
+  }
+
+  fun rollback(tx: String) {
+    val session = sessionForTx(tx)
+    session.tx = null
+    txSessions.remove(tx)
+    // SQLite may already have rolled back on an error; the transaction is over either way.
+    runCatching { session.connection.exec("ROLLBACK") }
+  }
+
+  fun close(token: String) {
+    val session = sessions.remove(token) ?: misuse("The database session is closed or unknown.")
+    session.tx?.let { txSessions.remove(it) }
+    session.tx = null
+    for (statement in session.statements.values) runCatching { statement.close() }
+    session.statements.clear()
+    session.connection.close()
+  }
+
+  /** Closes every session (module teardown). */
+  fun closeAll() {
+    for (token in sessions.keys.toList()) runCatching { close(token) }
+  }
+}

package/android/src/main/java/com/g9lynx/g9native/sqlite/core/G9SqliteService.kt

@@ -0,0 +1,131 @@
+package com.g9lynx.g9native.sqlite.core
+
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.LinkedBlockingQueue
+import java.util.concurrent.RejectedExecutionException
+import java.util.concurrent.ThreadPoolExecutor
+import java.util.concurrent.TimeUnit
+
+/** Where a reply goes (the Lynx module invokes the JS callback; Lynx marshals it to the JS thread). */
+typealias G9Reply = (Map<String, Any?>) -> Unit
+
+/**
+ * The bridge-facing SQLite service: requests arrive as bridge data (`Map` / `List` from `toHashMap()` /
+ * `toArrayList()`), run on one single-thread executor per session (all statements of a connection on one thread) with
+ * a bounded queue, and reply with an envelope `{ ok, value | error }`. Opening and capability probes share one thread.
+ * Pure JVM: the Lynx module is a thin adapter around it.
+ */
+class G9SqliteService(private val core: G9SqliteCore, private val queueCapacity: Int = 256) {
+  private val executors = ConcurrentHashMap<String, ExecutorService>()
+  private val shared = newExecutor("g9-sqlite-open")
+  @Volatile private var shutDown = false
+
+  private fun newExecutor(name: String): ThreadPoolExecutor =
+    ThreadPoolExecutor(1, 1, 0L, TimeUnit.MILLISECONDS, LinkedBlockingQueue(queueCapacity)) { runnable ->
+      Thread(runnable, name).apply { isDaemon = true }
+    }
+
+  private fun executorFor(session: String?): ExecutorService =
+    if (session == null) shared else executors.computeIfAbsent(session) { newExecutor("g9-sqlite-$it") }
+
+  private fun submit(session: String?, reply: G9Reply, work: () -> Any?) {
+    if (shutDown) {
+      reply(G9SqliteTransport.failure(G9SqliteException("misuse", "The SQLite module is shut down.")))
+      return
+    }
+    try {
+      executorFor(session).execute {
+        val envelope =
+          try {
+            G9SqliteTransport.ok(work())
+          } catch (error: Throwable) {
+            G9SqliteTransport.failure(error)
+          }
+        reply(envelope)
+      }
+    } catch (_: RejectedExecutionException) {
+      reply(G9SqliteTransport.failure(G9SqliteException("busy", "Too many queued requests for this database session.")))
+    }
+  }
+
+  fun capabilities(reply: G9Reply) =
+    submit(null, reply) {
+      val c = core.capabilities()
+      mapOf(
+        "sqliteVersion" to c.sqliteVersion,
+        "maxVariables" to c.maxVariables.toDouble(),
+        "json1" to c.json1,
+        "returning" to c.returning,
+        "upsert" to c.upsert,
+        "interrupt" to c.interrupt,
+      )
+    }
+
+  fun open(options: Map<*, *>, reply: G9Reply) =
+    submit(null, reply) {
+      core.open(
+        G9OpenOptions(
+          path = options["path"] as? String ?: misuse("open needs a path."),
+          readOnly = options["readOnly"] == true,
+          create = options["create"] == true,
+          pragmas = (options["pragmas"] as? List<*>)?.map { it as String } ?: emptyList(),
+        ),
+      )
+    }
+
+  fun run(session: String, statements: List<*>, options: Map<*, *>, reply: G9Reply) =
+    submit(session, reply) {
+      val batch =
+        statements.map { raw ->
+          val s = raw as? Map<*, *> ?: misuse("A statement must be an object { sql, params }.")
+          G9Statement(s["sql"] as? String ?: misuse("A statement needs sql."), (s["params"] as? List<*>) ?: emptyList<Any?>())
+        }
+      val results =
+        core.run(
+          session,
+          batch,
+          G9RunOptions(
+            tx = options["tx"] as? String,
+            maxRows = (options["maxRows"] as? Number)?.toInt(),
+            atomic = options["atomic"] == true,
+          ),
+        )
+      G9SqliteTransport.encode(results, options["transport"] as? String ?: G9SqliteTransport.COLUMNAR)
+    }
+
+  fun begin(session: String, mode: String, reply: G9Reply) = submit(session, reply) { core.begin(session, mode) }
+
+  fun commit(tx: String, reply: G9Reply) =
+    submit(core.sessionOfTx(tx), reply) {
+      core.commit(tx)
+      null
+    }
+
+  fun rollback(tx: String, reply: G9Reply) =
+    submit(core.sessionOfTx(tx), reply) {
+      core.rollback(tx)
+      null
+    }
+
+  fun close(session: String, reply: G9Reply) =
+    submit(session, reply) {
+      try {
+        core.close(session)
+      } finally {
+        // This task is the executor's last: later requests for the token get a fresh executor and a `misuse` reply.
+        executors.remove(session)?.shutdown()
+      }
+      null
+    }
+
+  /** Closes every database and stops the threads (module destroy). Queued requests still run first. */
+  fun shutdown() {
+    shutDown = true
+    for (executor in executors.values) executor.shutdown()
+    for (executor in executors.values) executor.awaitTermination(5, TimeUnit.SECONDS)
+    executors.clear()
+    shared.shutdown()
+    core.closeAll()
+  }
+}

package/android/src/main/java/com/g9lynx/g9native/sqlite/core/G9SqliteTransport.kt

@@ -0,0 +1,125 @@
+package com.g9lynx.g9native.sqlite.core
+
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+
+/**
+ * How results cross to JS (plan/specs/06 §6). The contract is fixed; these bytes are not.
+ *
+ * - **C, `columnar` (default):** per result `columns`, `rowCount`, `changes`, `lastInsertRowId`, and the cells in row
+ *   order as one tag byte each in `types` (0 null, 1 number, 2 int64 text, 3 text, 4 blob); numbers (and each blob's
+ *   length) as little-endian float64 in `numbers`; text and int64 decimals in `strings`; blob bytes back to back in
+ *   `blobs`. No per-cell boxing, no UTF-8 decoding in JS.
+ * - **A, `rows`:** `rows` as arrays of tagged cells (`null`, number, string, `{ int64 }`, ArrayBuffer).
+ *
+ * Output is plain Kotlin data (`Map`, `List`, `String`, `Double`, `Boolean`, `ByteArray`, `null`); the Lynx module
+ * copies it into bridge maps.
+ */
+object G9SqliteTransport {
+  const val COLUMNAR = "columnar"
+  const val ROWS = "rows"
+
+  const val TAG_NULL: Byte = 0
+  const val TAG_NUMBER: Byte = 1
+  const val TAG_INT64: Byte = 2
+  const val TAG_TEXT: Byte = 3
+  const val TAG_BLOB: Byte = 4
+
+  fun wireNumber(value: Long): Any = when (val n = toBridgeNumber(value)) {
+    is G9Int64 -> mapOf("int64" to n.decimal)
+    else -> n
+  }
+
+  fun encode(results: List<G9SqlResult>, transport: String): Map<String, Any?> =
+    mapOf(
+      "transport" to (if (transport == ROWS) ROWS else COLUMNAR),
+      "results" to results.map { if (transport == ROWS) rows(it) else columnar(it) },
+    )
+
+  fun rows(result: G9SqlResult): Map<String, Any?> =
+    mapOf(
+      "columns" to result.columns,
+      "rows" to result.rows.map { row -> row.map { cell -> if (cell is Long) wireNumber(cell) else cell } },
+      "changes" to result.changes.toDouble(),
+      "lastInsertRowId" to wireNumber(result.lastInsertRowId),
+    )
+
+  fun columnar(result: G9SqlResult): Map<String, Any?> {
+    val cells = result.rows.sumOf { it.size }
+    val types = ByteArray(cells)
+    var numberCount = 0
+    var blobBytes = 0
+    for (row in result.rows) {
+      for (cell in row) {
+        when (cell) {
+          is Double -> numberCount++
+          is Long -> if (toBridgeNumber(cell) is Double) numberCount++
+          is ByteArray -> {
+            numberCount++
+            blobBytes += cell.size
+          }
+        }
+      }
+    }
+    val numbers = ByteBuffer.allocate(numberCount * 8).order(ByteOrder.LITTLE_ENDIAN)
+    val blobs = ByteBuffer.allocate(blobBytes)
+    val strings = ArrayList<String>()
+    var i = 0
+    for (row in result.rows) {
+      for (cell in row) {
+        types[i++] =
+          when (cell) {
+            null -> TAG_NULL
+            is Double -> {
+              numbers.putDouble(cell)
+              TAG_NUMBER
+            }
+            is Long ->
+              when (val n = toBridgeNumber(cell)) {
+                is Double -> {
+                  numbers.putDouble(n)
+                  TAG_NUMBER
+                }
+                else -> {
+                  strings.add((n as G9Int64).decimal)
+                  TAG_INT64
+                }
+              }
+            is String -> {
+              strings.add(cell)
+              TAG_TEXT
+            }
+            is ByteArray -> {
+              numbers.putDouble(cell.size.toDouble())
+              blobs.put(cell)
+              TAG_BLOB
+            }
+            else -> throw IllegalStateException("Unexpected cell ${cell::class.java.simpleName}")
+          }
+      }
+    }
+    return mapOf(
+      "columns" to result.columns,
+      "rowCount" to result.rows.size.toDouble(),
+      "changes" to result.changes.toDouble(),
+      "lastInsertRowId" to wireNumber(result.lastInsertRowId),
+      "types" to types,
+      "numbers" to numbers.array(),
+      "strings" to strings,
+      "blobs" to blobs.array(),
+    )
+  }
+
+  fun ok(value: Any?): Map<String, Any?> = mapOf("ok" to true, "value" to value)
+
+  fun failure(error: Throwable): Map<String, Any?> {
+    val e = toG9Error(error)
+    val fields = LinkedHashMap<String, Any?>()
+    fields["code"] = e.code
+    fields["message"] = e.message ?: e.code
+    e.sqliteCode?.let { fields["sqliteCode"] = it.toDouble() }
+    e.sql?.let { fields["sql"] = it }
+    e.completedStatements?.let { fields["completedStatements"] = it.toDouble() }
+    return mapOf("ok" to false, "error" to fields)
+  }
+}