@pineliner/odb-client 1.1.5 → 1.4.0

package/src/database/adapters/odblite-socket.ts

@@ -0,0 +1,335 @@
+import type { BackendType, Connection, DatabaseAdapter, PreparedStatement, QueryResult } from '../types'
+import { ODBLiteAdapter } from './odblite'
+import { SocketClient, type SocketTarget } from './socket/client'
+import {
+  toHrana,
+  fromHrana,
+  toBatch,
+  mightReturnRows,
+  type AtomicStep,
+  type BatchResult,
+  type StmtResult,
+  type StreamRequest,
+  type StreamResult,
+} from './socket/protocol'
+
+/**
+ * odblite-socket — the FAST cross-process backend: raw socket + JSON framing to
+ * router_v2 (bun:sqlite engine). REPLACES the HTTP `odblite` backend (one hop, no
+ * HTTP parse) — it does NOT layer on it. Same `Connection` interface, so it's a
+ * drop-in: app-router flips `backend: 'odblite'` → `'odblite-socket'`.
+ *
+ * Write discipline (the separate-process model forces it): a unit of write work
+ * is ONE batch in ONE round-trip — the server runs BEGIN…COMMIT on its side, the
+ * client never holds the write slot across the wire. So `atomic(steps)` is the
+ * write primitive; `transaction(fn)` BUFFERS writes and flushes them as one
+ * atomic batch on commit (no read-your-own-uncommitted-writes mid-tx — that would
+ * re-create the slot-starvation the design avoids). Read-compute-write → read
+ * first, compute, write one atomic().
+ */
+function toQueryResult(res: StreamResult): QueryResult {
+  if (res.type === 'error') throw new Error(res.error.message)
+  const r = (res as any).response.result as StmtResult
+  const rows = r.rows.map((row) => {
+    const obj: Record<string, any> = {}
+    r.cols.forEach((c, i) => {
+      obj[c.name ?? `c${i}`] = fromHrana(row[i] ?? { type: 'null' })
+    })
+    return obj
+  })
+  return { rows, rowsAffected: r.affected_row_count, lastInsertRowid: r.last_insert_rowid ? Number(r.last_insert_rowid) : undefined }
+}
+
+class OdbliteSocketConnection implements Connection {
+  databaseName?: string
+  databaseHash?: string
+  public sql: any
+  /** A fresh stream tx whose BEGIN hasn't been flushed yet — it's folded into the first statement's
+   *  frame to save a round-trip (and an empty tx that issues no statements sends nothing at all). */
+  private beginPending = false
+
+  constructor(
+    private readonly client: SocketClient,
+    private readonly tenant: string,
+    /** Set → this connection is scoped to an interactive transaction STREAM: every query/execute runs
+     *  on the server's PINNED connection (read-your-own-writes), not autocommit. */
+    private readonly streamId?: number,
+  ) {
+    this.databaseName = tenant
+    this.databaseHash = tenant
+    const self = this
+    this.sql = function (strings: any, ...values: any[]): any {
+      if (strings && typeof strings === 'object' && 'raw' in strings) {
+        const text = (strings as string[]).reduce((a, s, i) => a + s + (i < values.length ? '?' : ''), '')
+        const returns = mightReturnRows(text)
+        return (returns ? self.query(text, values) : self.execute(text, values)).then((r: any) => r.rows)
+      }
+      throw new Error('sql() fragment helper not implemented in odblite-socket')
+    }
+  }
+
+  /** One request → its single result, failing loud on an empty response. */
+  private async one(requests: StreamRequest[]): Promise<StreamResult> {
+    const [res] = await this.client.pipeline(this.tenant, requests)
+    if (!res) throw new Error('odblite-socket: empty pipeline response')
+    return res
+  }
+
+  /** Run one statement on this connection's interactive STREAM — the server's pinned connection, so a
+   *  read sees this tx's own uncommitted writes. Throws on error (incl. a poisoned COMMIT). */
+  private async streamExec(sql: string, params: any[] = []): Promise<QueryResult> {
+    const reqs: StreamRequest[] = []
+    if (this.beginPending) {
+      reqs.push({ type: 'execute', stmt: { sql: 'BEGIN' } }) // fold BEGIN into this first statement's frame
+      this.beginPending = false
+    }
+    reqs.push({ type: 'execute', stmt: { sql, args: params.map(toHrana) } })
+    const results = await this.client.pipeline(this.tenant, reqs, this.streamId)
+    if (reqs.length > 1 && results[0]?.type === 'error') throw new Error(results[0].error.message) // the folded BEGIN failed
+    const res = results[results.length - 1]
+    if (!res) throw new Error('odblite-socket: empty stream response')
+    return toQueryResult(res)
+  }
+
+  async query<T = any>(sql: string, params: any[] = []): Promise<QueryResult<T>> {
+    if (this.streamId != null) return (await this.streamExec(sql, params)) as QueryResult<T>
+    return toQueryResult(await this.one([{ type: 'execute', stmt: { sql, args: params.map(toHrana) } }])) as QueryResult<T>
+  }
+
+  async execute(sql: string | { sql: string; args?: any[] }, params: any[] = []): Promise<QueryResult> {
+    const s = typeof sql === 'string' ? sql : sql.sql
+    const p = typeof sql === 'string' ? params : (sql.args ?? [])
+    if (this.streamId != null) return this.streamExec(s, p) // on the pinned stream — runs immediately, NOT buffered
+    return toQueryResult(await this.one([{ type: 'execute', stmt: { sql: s, args: p.map(toHrana) } }]))
+  }
+
+  /** Guarded atomic batch — the primary remote write primitive (one round-trip). */
+  async atomic(steps: AtomicStep[]): Promise<BatchResult> {
+    const res = await this.one([{ type: 'batch', batch: toBatch(steps) }])
+    if (res.type === 'error') throw new Error(res.error.message)
+    return (res as any).response.result as BatchResult
+  }
+
+  prepare(sql: string): PreparedStatement {
+    return {
+      execute: async (params = []) => this.execute(sql, params),
+      all: async (params = []) => (await this.query(sql, params)).rows,
+      get: async (params = []) => (await this.query(sql, params)).rows[0] ?? null,
+    }
+  }
+
+  /**
+   * Interactive transaction over a STREAM (one pinned server connection): BEGIN → fn's reads+writes →
+   * COMMIT, all on the same connection. Reads see their own writes, and the engine enforces atomicity
+   * (a failed statement poisons the tx → a later COMMIT is forced to ROLLBACK). Replaces the old
+   * buffered model, which couldn't read its own writes and only flushed at commit.
+   */
+  async transaction<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    if (this.streamId != null) return fn(this) // nested → join the already-open stream
+    const tx = new OdbliteSocketConnection(this.client, this.tenant, this.client.allocStream())
+    tx.beginPending = true // BEGIN folds into the first statement's frame (one fewer round-trip)
+    try {
+      const out = await fn(tx)
+      if (!tx.beginPending) await tx.streamExec('COMMIT') // a statement ran → BEGIN was sent → COMMIT it
+      return out // else fn issued no statements → empty tx, BEGIN never sent, zero round-trips
+    } catch (e) {
+      if (!tx.beginPending) await tx.streamExec('ROLLBACK').catch(() => {}) // best-effort; server also reaps
+      throw e
+    }
+  }
+  begin<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    return this.transaction(fn)
+  }
+  /** Nested partial-rollback scope. Inside a stream → a real SAVEPOINT (a ROLLBACK TO SAVEPOINT clears
+   *  the engine's poison); at top level → a full transaction. */
+  async savepoint<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    if (this.streamId == null) return this.transaction(fn)
+    const name = `sp_${this.client.allocStream()}`
+    await this.streamExec(`SAVEPOINT ${name}`)
+    try {
+      const out = await fn(this)
+      await this.streamExec(`RELEASE SAVEPOINT ${name}`)
+      return out
+    } catch (e) {
+      await this.streamExec(`ROLLBACK TO SAVEPOINT ${name}`).catch(() => {})
+      throw e
+    }
+  }
+
+  // router_v2 auto-ATTACHes a tenant's namespaces on open → these are no-ops.
+  async ensureNamespaces(namespaces: string[]) {
+    return { success: true, databaseName: this.tenant, namespaces }
+  }
+  async getNamespaces() {
+    const ns = (await this.query("SELECT name FROM pragma_database_list WHERE name != 'main'")).rows.map((r: any) => r.name)
+    return { success: true, databaseName: this.tenant, exists: true, namespaces: ns, registered: true, registeredNamespaces: ns }
+  }
+
+  async close(): Promise<void> {
+    /* the SocketClient is shared + owned by the adapter; per-connection close is a no-op */
+  }
+}
+
+export interface OdbliteSocketConfig extends SocketTarget {}
+
+export class OdbliteSocketAdapter implements DatabaseAdapter {
+  readonly type: BackendType = 'odblite-socket'
+  private readonly client: SocketClient
+
+  constructor(config: OdbliteSocketConfig) {
+    this.client = new SocketClient(config)
+  }
+
+  async connect(config: any): Promise<Connection> {
+    const tenant = config?.databaseHash ?? config?.databaseName
+    if (!tenant) throw new Error('odblite-socket: databaseHash (or databaseName) required')
+    return new OdbliteSocketConnection(this.client, String(tenant))
+  }
+
+  async disconnect(): Promise<void> {
+    this.client.close()
+  }
+
+  async isHealthy(): Promise<boolean> {
+    try {
+      const res: any = await Promise.race([
+        this.client.pipeline('_health', [{ type: 'get_version' }]),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('probe timeout')), 1500)),
+      ])
+      // Connect-time HANDSHAKE: adopt the socket only if the server speaks our wire protocol. A different
+      // generation — or a server too old to answer get_version — falls back to HTTP instead of letting a
+      // mismatched client mis-speak the binary port (the 1.2.0 ↔ rebuilt-server skew).
+      const proto = res?.[0]?.response?.protocol
+      if (proto !== CLIENT_SOCKET_PROTOCOL) {
+        console.warn(`[odb-client] socket protocol mismatch (server=${proto ?? 'none'}, client=${CLIENT_SOCKET_PROTOCOL}) → using HTTP`)
+        return false
+      }
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+/** Socket wire-protocol version this client speaks. The connect-time handshake (isHealthy → get_version)
+ *  requires the server to match; on mismatch the auto-adapter falls back to HTTP. Keep in lockstep with
+ *  router_v2's SOCKET_PROTOCOL. */
+export const CLIENT_SOCKET_PROTOCOL = 2
+
+/** Default same-host unix socket (free — v1 only uses /tmp/odblite-internal.sock). */
+export const DEFAULT_UNIX_SOCKET = '/tmp/odblite.sock'
+
+/**
+ * Resolve the odblite-socket target from a string. `ODB_SOCKET` may be:
+ *   - a UNIX path  (`/tmp/odblite.sock`)        — same host, or a SHARED VOLUME mount
+ *   - `host:port`  (`odblite:8787`)             — TCP, the CROSS-CONTAINER Docker case
+ *   - `:port` / `port`                          — TCP on localhost
+ * A /tmp unix socket does NOT cross Docker containers, so container-to-container
+ * deployments set `ODB_SOCKET=odblite:8787` (TCP over the Docker network).
+ */
+export function parseSocketTarget(s?: string): SocketTarget {
+  const v = (s ?? '').trim()
+  if (!v) return { unix: DEFAULT_UNIX_SOCKET }
+  if (v.includes('/')) return { unix: v } // a path → unix socket
+  const m = v.match(/^(?:([^:]+):)?(\d+)$/) // host:port | :port | port → TCP
+  if (m) return { hostname: m[1] || '127.0.0.1', port: Number(m[2]) }
+  return { unix: v }
+}
+
+/**
+ * OdbliteAutoAdapter — the default for the `odblite` backend: ZERO config change,
+ * autodetected as a cascade  unix socket → TCP socket → HTTP. At startup it probes
+ * each in order and uses the FIRST that answers:
+ *   1. unix socket  /tmp/odblite.sock        — same host (fastest)
+ *   2. TCP socket   <ODB_LITE_URL host>:8787 — cross-container Docker; host is
+ *      DERIVED from the existing ODB_LITE_URL, so Docker needs no new config
+ *   3. HTTP         ODB_LITE_URL              — the universal fallback
+ * Explicit `ODB_SOCKET` (unix path or host:port) or an `odbliteSocket` config
+ * pins a single socket target instead of the cascade. So same-host dev and
+ * cross-container prod both "just work", and a missing/down socket → HTTP.
+ * (Browser / non-Bun → straight to HTTP.)
+ */
+export class OdbliteAutoAdapter implements DatabaseAdapter {
+  readonly type: BackendType = 'odblite'
+  private readonly opts: { socket?: OdbliteSocketConfig; http: any }
+  private chosen: Promise<DatabaseAdapter>
+  private onHttp = false
+  private nextRetryAt = 0
+
+  constructor(opts: { socket?: OdbliteSocketConfig; http: any }) {
+    this.opts = opts
+    this.chosen = this.pick()
+  }
+
+  private async pick(): Promise<DatabaseAdapter> {
+    const hasBun = typeof (globalThis as any).Bun !== 'undefined' && !!(globalThis as any).Bun.connect
+    if (hasBun) {
+      const socket = await this.trySocket()
+      if (socket) return socket
+    }
+    this.onHttp = true
+    console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)')
+    return new ODBLiteAdapter(this.opts.http)
+  }
+
+  /** Probe the cascade once; return a live socket adapter or null. */
+  private async trySocket(): Promise<DatabaseAdapter | null> {
+    for (const target of this.candidates()) {
+      try {
+        const socket = new OdbliteSocketAdapter(target)
+        if (await socket.isHealthy()) {
+          console.log(`[odb-client] transport → SOCKET (router_v2 @ ${target.unix ?? `${target.hostname}:${target.port}`})`)
+          return socket
+        }
+        await socket.disconnect()
+      } catch {
+        /* try the next candidate */
+      }
+    }
+    return null
+  }
+
+  /** When we fell back to HTTP, re-probe the socket on a cooldown so a socket that
+   *  comes up LATER (server started after the app) is picked up without a restart —
+   *  subsequent connections then use it. */
+  private async maybeUpgrade(): Promise<void> {
+    if (!this.onHttp) return
+    const now = Date.now()
+    if (now < this.nextRetryAt) return
+    this.nextRetryAt = now + 15_000
+    const socket = await this.trySocket()
+    if (socket) {
+      this.chosen = Promise.resolve(socket)
+      this.onHttp = false
+    }
+  }
+
+  /** Ordered socket targets to probe. Explicit override → a single target; else the
+   *  zero-config cascade unix (same host) → TCP (host derived from ODB_LITE_URL). */
+  private candidates(): SocketTarget[] {
+    const { socket, http } = this.opts
+    if (socket?.unix || socket?.port) return [socket]
+    const env = (globalThis as any).process?.env?.ODB_SOCKET
+    if (env) return [parseSocketTarget(env)]
+    const out: SocketTarget[] = [{ unix: DEFAULT_UNIX_SOCKET }]
+    try {
+      const host = new URL(http?.serviceUrl).hostname // e.g. odb-lite from http://odb-lite:8671
+      const port = Number((globalThis as any).process?.env?.ODB_SOCKET_PORT ?? 8787)
+      if (host) out.push({ hostname: host, port })
+    } catch {
+      /* serviceUrl unparseable → no TCP candidate, HTTP will catch it */
+    }
+    return out
+  }
+
+  async connect(config: any): Promise<Connection> {
+    await this.maybeUpgrade()
+    return (await this.chosen).connect(config)
+  }
+  async disconnect(tenantId?: string): Promise<void> {
+    return (await this.chosen).disconnect(tenantId)
+  }
+  async isHealthy(): Promise<boolean> {
+    return (await this.chosen).isHealthy()
+  }
+}

package/src/database/adapters/socket/client.ts

@@ -0,0 +1,134 @@
+import { FrameReader, FrameWriter, type StreamRequest, type StreamResult } from './protocol'
+
+/**
+ * Persistent socket client for the odblite-socket transport. One connection,
+ * length-prefixed frames, replies correlated by id. Batch many statements into
+ * one `requests[]` so N statements cost one round-trip.
+ *
+ * Bun-only (uses `Bun.connect`). app-router runs on Bun; the HTTP `odblite`
+ * backend remains the universal fallback for non-Bun environments.
+ *
+ * Liveness invariant: an in-flight request must ALWAYS terminate. If the
+ * connection drops (close/error) or a reply never arrives, the pending promise
+ * is REJECTED — never left hanging. A hung pending request would wedge the
+ * caller's transaction, hold its write lane, and cascade into a 30s timeout.
+ */
+export interface SocketTarget {
+  unix?: string
+  hostname?: string
+  port?: number
+}
+
+// Backstop: a request that gets neither a reply nor a disconnect (server wedged on
+// it) is rejected after this long, so the caller fails fast + can retry rather than
+// hang forever. Generous by default; tune via ODB_SOCKET_REQUEST_TIMEOUT_MS.
+const REQUEST_TIMEOUT_MS = Number((globalThis as any).process?.env?.ODB_SOCKET_REQUEST_TIMEOUT_MS) || 30000
+
+interface Pending {
+  resolve: (r: StreamResult[]) => void
+  reject: (e: any) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+export class SocketClient {
+  private socket: any
+  private reader = new FrameReader()
+  private writer!: FrameWriter
+  private readonly pending = new Map<number, Pending>()
+  private nextId = 1
+  private nextStreamId = 1
+  private ready: Promise<void>
+
+  constructor(private readonly target: SocketTarget) {
+    this.ready = this.connect()
+    // A failed initial connect (e.g. socket not up) surfaces via pipeline()'s
+    // await — don't let the orphaned promise become an unhandled rejection.
+    void this.ready.catch(() => {})
+  }
+
+  /** Reject + clear every in-flight request — called on disconnect/error/close so a
+   *  dropped connection FAILS its requests (the caller retries) instead of hanging. */
+  private failPending(err: Error): void {
+    for (const p of this.pending.values()) {
+      clearTimeout(p.timer)
+      p.reject(err)
+    }
+    this.pending.clear()
+  }
+
+  private async connect(): Promise<void> {
+    const Bun = (globalThis as any).Bun
+    if (!Bun?.connect) throw new Error('odblite-socket backend requires Bun (Bun.connect)')
+    const opts: any = this.target.unix
+      ? { unix: this.target.unix }
+      : { hostname: this.target.hostname ?? '127.0.0.1', port: this.target.port ?? 8787 }
+    this.socket = await Bun.connect({
+      ...opts,
+      socket: {
+        data: (_s: any, chunk: Buffer) => {
+          for (const frame of this.reader.push(chunk)) {
+            const msg = JSON.parse(frame.toString('utf8')) as { id: number; results: StreamResult[] }
+            const p = this.pending.get(msg.id)
+            if (p) {
+              this.pending.delete(msg.id)
+              clearTimeout(p.timer)
+              p.resolve(msg.results)
+            }
+          }
+        },
+        drain: (_s: any) => this.writer.flush(),
+        close: () => {
+          // Connection gone → reconnect lazily on next pipeline(). A half-read frame
+          // in the buffer is invalid now, and EVERY in-flight request must fail (not
+          // hang) so its caller's transaction unwinds + releases the write lane.
+          this.socket = undefined
+          this.reader = new FrameReader()
+          this.failPending(new Error('odblite socket disconnected — request not completed'))
+        },
+        error: (_s: any, err: any) => {
+          this.socket = undefined
+          this.reader = new FrameReader()
+          this.failPending(err instanceof Error ? err : new Error(`odblite socket error: ${err}`))
+        },
+      },
+    })
+    this.writer = new FrameWriter(this.socket)
+  }
+
+  /** Allocate a fresh stream id for an interactive transaction (unique per connection). The server
+   *  pins one SQLite connection per stream id, so all of a tx's statements run on it (read-your-own-
+   *  writes). The id is carried in every frame of that tx via pipeline()'s `stream` arg. */
+  allocStream(): number {
+    return this.nextStreamId++
+  }
+
+  async pipeline(tenant: string, requests: StreamRequest[], stream?: number): Promise<StreamResult[]> {
+    // Await the in-flight connect FIRST — only reconnect if it's actually gone
+    // (closed/failed). Checking `!this.socket` before awaiting would start a
+    // second connect while the first is still resolving (a leaked connection).
+    await this.ready
+    if (!this.socket) {
+      this.ready = this.connect()
+      void this.ready.catch(() => {})
+      await this.ready
+    }
+    const id = this.nextId++
+    return new Promise<StreamResult[]>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        // No reply AND no disconnect (server wedged) → reject so we never hang forever.
+        if (this.pending.delete(id)) reject(new Error(`odblite socket request ${id} timed out after ${REQUEST_TIMEOUT_MS}ms`))
+      }, REQUEST_TIMEOUT_MS)
+      ;(timer as any).unref?.()
+      this.pending.set(id, { resolve, reject, timer })
+      // `stream` present → the server routes this frame to that interactive tx's pinned connection.
+      const payload = stream != null ? { id, tenant, stream, requests } : { id, tenant, requests }
+      this.writer.send(Buffer.from(JSON.stringify(payload), 'utf8'))
+    })
+  }
+
+  close(): void {
+    this.socket?.end?.()
+    this.socket = undefined
+    this.failPending(new Error('odblite socket closed'))
+  }
+}

package/src/database/adapters/socket/protocol.ts

@@ -0,0 +1,157 @@
+/**
+ * odblite-socket wire protocol (CLIENT side).
+ *
+ * ⚠️ COUPLING: this must stay byte-compatible with the SERVER in
+ * `packages/odb-lite/router_v2/protocol/{hrana,framing}.ts`. They are deliberately
+ * separate copies (the client lib must not import the server engine) — same rule
+ * as the /ext test-service mirror: change one wire shape, change the other.
+ *
+ * Transport: `[u32 LE length][utf8 JSON]` frames over a unix socket / TCP. Each
+ * request is `{ id, tenant, requests }`; the reply is `{ id, results }`. The
+ * payload stays JSON on purpose (native JSON.parse beats a hand-rolled JS codec;
+ * a binary payload only pays off remote, via a native codec).
+ */
+
+// ── value encoding (64-bit-safe: integers travel as strings) ──────────────────
+export type HranaValue =
+  | { type: 'null' }
+  | { type: 'integer'; value: string }
+  | { type: 'float'; value: number }
+  | { type: 'text'; value: string }
+  | { type: 'blob'; base64: string }
+
+export function toHrana(v: any): HranaValue {
+  if (v === null || v === undefined) return { type: 'null' }
+  if (typeof v === 'bigint') return { type: 'integer', value: v.toString() }
+  if (typeof v === 'number') return Number.isInteger(v) ? { type: 'integer', value: String(v) } : { type: 'float', value: v }
+  if (typeof v === 'string') return { type: 'text', value: v }
+  if (v instanceof Uint8Array) return { type: 'blob', base64: Buffer.from(v).toString('base64') }
+  if (typeof v === 'boolean') return { type: 'integer', value: v ? '1' : '0' }
+  return { type: 'text', value: String(v) }
+}
+
+export function fromHrana(v: HranaValue): any {
+  switch (v.type) {
+    case 'null':
+      return null
+    case 'integer': {
+      const n = Number(v.value)
+      return Number.isSafeInteger(n) ? n : BigInt(v.value)
+    }
+    case 'float':
+      return v.value
+    case 'text':
+      return v.value
+    case 'blob':
+      return new Uint8Array(Buffer.from(v.base64, 'base64'))
+  }
+}
+
+// ── message types ─────────────────────────────────────────────────────────────
+export interface Stmt {
+  sql?: string
+  args?: HranaValue[]
+  named_args?: { name: string; value: HranaValue }[]
+  want_rows?: boolean
+}
+export type BatchCond =
+  | { type: 'ok'; step: number }
+  | { type: 'error'; step: number }
+  | { type: 'not'; cond: BatchCond }
+  | { type: 'and'; conds: BatchCond[] }
+  | { type: 'or'; conds: BatchCond[] }
+  | { type: 'is_autocommit' }
+export interface BatchStep {
+  condition?: BatchCond | null
+  stmt: Stmt
+  expect?: { affected: 'one' | 'atLeastOne' | number }
+}
+export interface Batch {
+  steps: BatchStep[]
+}
+export interface StmtResult {
+  cols: { name: string | null }[]
+  rows: HranaValue[][]
+  affected_row_count: number
+  last_insert_rowid: string | null
+}
+export interface BatchResult {
+  step_results: (StmtResult | null)[]
+  step_errors: ({ message: string; code?: string } | null)[]
+}
+export interface HranaError {
+  message: string
+  code?: string
+}
+export type StreamRequest =
+  | { type: 'execute'; stmt: Stmt }
+  | { type: 'batch'; batch: Batch }
+  | { type: 'sequence'; sql: string }
+  | { type: 'get_autocommit' }
+  | { type: 'get_version' } // connect-time wire-protocol handshake
+  | { type: 'close' }
+export type StreamResult =
+  | { type: 'ok'; response: any }
+  | { type: 'error'; error: HranaError }
+
+// ── guarded-batch helper (the §8g atomic primitive) ───────────────────────────
+export interface AtomicStep {
+  sql: string
+  params?: any[]
+  expect?: 'one' | 'atLeastOne' | number
+}
+export function toBatch(steps: AtomicStep[]): Batch {
+  return {
+    steps: steps.map((s, i) => ({
+      condition: i === 0 ? undefined : { type: 'ok', step: i - 1 },
+      stmt: { sql: s.sql, args: (s.params ?? []).map(toHrana) },
+      expect: s.expect ? { affected: s.expect } : undefined,
+    })),
+  }
+}
+
+// ── SQL classification (client-side heuristic) ────────────────────────────────
+// Mirrors router_v2/engine/sql-kind.ts (kept in lockstep, like the wire types).
+// The SERVER is authoritative (it checks the prepared statement's column count);
+// this only picks the `sql``` convenience tag's shape before the round-trip.
+const READ_ONLY_RE = /^\s*(?:SELECT|EXPLAIN|VALUES)\b/i
+export function mightReturnRows(sql: string): boolean {
+  return READ_ONLY_RE.test(sql) || /\bRETURNING\b/i.test(sql)
+}
+
+// ── length-prefixed framing with backpressure-safe writes ─────────────────────
+interface Writable {
+  write(data: Uint8Array): number
+}
+export class FrameWriter {
+  private pending: Buffer = Buffer.alloc(0)
+  constructor(private readonly socket: Writable) {}
+  send(payload: Buffer): void {
+    const header = Buffer.allocUnsafe(4)
+    header.writeUInt32LE(payload.length, 0)
+    const frame = Buffer.concat([header, payload])
+    this.pending = this.pending.length ? Buffer.concat([this.pending, frame]) : frame
+    this.flush()
+  }
+  flush(): void {
+    while (this.pending.length > 0) {
+      const n = this.socket.write(this.pending)
+      if (n <= 0) return // backpressured — drain() re-calls flush()
+      this.pending = n < this.pending.length ? this.pending.subarray(n) : Buffer.alloc(0)
+    }
+  }
+}
+export class FrameReader {
+  private buf: Buffer = Buffer.alloc(0)
+  push(chunk: Buffer): Buffer[] {
+    this.buf = this.buf.length ? Buffer.concat([this.buf, chunk]) : chunk
+    const out: Buffer[] = []
+    while (this.buf.length >= 4) {
+      const len = this.buf.readUInt32LE(0)
+      if (this.buf.length < 4 + len) break
+      out.push(this.buf.subarray(4, 4 + len))
+      this.buf = this.buf.subarray(4 + len)
+    }
+    return out
+  }
+}

package/src/database/manager.ts

@@ -9,6 +9,7 @@ import type {
 import { BunSQLiteAdapter } from './adapters/bun-sqlite'
 import { LibSQLAdapter } from './adapters/libsql'
 import { ODBLiteAdapter } from './adapters/odblite'
+import { OdbliteSocketAdapter, OdbliteAutoAdapter } from './adapters/odblite-socket'
 import { parseSQL } from './sql-parser'
 import fs from 'node:fs'
 
@@ -67,7 +68,17 @@ export class DatabaseManager {
         if (!config.odblite) {
           throw new Error('odblite config required for odblite backend')
         }
-        this.adapter = new ODBLiteAdapter(config.odblite)
+        // Autodetect, zero-config: prefer the router_v2 socket if it's reachable
+        // (convention path / ODB_SOCKET, or config.odbliteSocket override), else
+        // HTTP. App config is unchanged — start the socket server and it upgrades.
+        this.adapter = new OdbliteAutoAdapter({ socket: config.odbliteSocket, http: config.odblite })
+        break
+
+      case 'odblite-socket':
+        if (!config.odbliteSocket) {
+          throw new Error('odbliteSocket config required for odblite-socket backend')
+        }
+        this.adapter = new OdbliteSocketAdapter(config.odbliteSocket)
         break
 
       default:
@@ -308,6 +319,13 @@ export class DatabaseManager {
           ...this.config.odblite
         }
 
+      case 'odblite-socket':
+        return {
+          databaseName: name,
+          databaseHash: name,
+          ...this.config.odbliteSocket
+        }
+
       default:
         throw new Error(`Unknown backend: ${this.config.backend}`)
     }

package/src/database/types.ts

@@ -14,7 +14,7 @@ export type TenancyMode =
 /**
  * Backend database types
  */
-export type BackendType = 'bun-sqlite' | 'libsql' | 'odblite'
+export type BackendType = 'bun-sqlite' | 'libsql' | 'odblite' | 'odblite-socket'
 
 /**
  * Query result from any backend
@@ -161,6 +161,13 @@ export interface DatabaseManagerConfig {
     nodeId?: string  // Optional: specific node to create databases on (server selects if not provided)
   }
 
+  // router_v2 raw-socket transport (the fast path; Bun-only). One of unix OR host:port.
+  odbliteSocket?: {
+    unix?: string        // unix socket path, e.g. /tmp/odblite-v2.sock
+    hostname?: string    // or TCP host (cross-container Docker)
+    port?: number        // and TCP port
+  }
+
   // Connection pooling
   connectionPoolSize?: number // Max connections per database (default: 10)
 }