@pineliner/odb-client 1.2.0 → 1.4.0

package/dist/database/adapters/odblite-socket.d.ts

@@ -10,6 +10,10 @@ export declare class OdbliteSocketAdapter implements DatabaseAdapter {
     disconnect(): Promise<void>;
     isHealthy(): Promise<boolean>;
 }
+/** 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 declare const CLIENT_SOCKET_PROTOCOL = 2;
 /** Default same-host unix socket (free — v1 only uses /tmp/odblite-internal.sock). */
 export declare const DEFAULT_UNIX_SOCKET = "/tmp/odblite.sock";
 /**
@@ -36,12 +40,21 @@ export declare function parseSocketTarget(s?: string): SocketTarget;
  */
 export declare class OdbliteAutoAdapter implements DatabaseAdapter {
     readonly type: BackendType;
-    private readonly chosen;
+    private readonly opts;
+    private chosen;
+    private onHttp;
+    private nextRetryAt;
     constructor(opts: {
         socket?: OdbliteSocketConfig;
         http: any;
     });
     private pick;
+    /** Probe the cascade once; return a live socket adapter or null. */
+    private trySocket;
+    /** 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 maybeUpgrade;
     /** 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;

package/dist/database/adapters/odblite-socket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"odblite-socket.d.ts","sourceRoot":"","sources":["../../../src/database/adapters/odblite-socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAkC,MAAM,UAAU,CAAA;AAExG,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAoIjE,MAAM,WAAW,mBAAoB,SAAQ,YAAY;CAAG;AAE5D,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,MAAM,EAAE,mBAAmB;IAIjC,OAAO,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC;IAMzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAWpC;AAED,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,CAO1D;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,mBAAmB,CAAC;QAAC,IAAI,EAAE,GAAG,CAAA;KAAE;YAI/C,IAAI;IAoBlB;uFACmF;IACnF,OAAO,CAAC,UAAU;IAeZ,OAAO,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC;IAGzC,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAG5C,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAGpC"}
+{"version":3,"file":"odblite-socket.d.ts","sourceRoot":"","sources":["../../../src/database/adapters/odblite-socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAkC,MAAM,UAAU,CAAA;AAExG,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AA0KjE,MAAM,WAAW,mBAAoB,SAAQ,YAAY;CAAG;AAE5D,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,MAAM,EAAE,mBAAmB;IAIjC,OAAO,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC;IAMzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAmBpC;AAED;;mCAEmC;AACnC,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,CAO1D;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6C;IAClE,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,WAAW,CAAI;gBAEX,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,mBAAmB,CAAC;QAAC,IAAI,EAAE,GAAG,CAAA;KAAE;YAK/C,IAAI;IAWlB,oEAAoE;YACtD,SAAS;IAgBvB;;8CAE0C;YAC5B,YAAY;IAY1B;uFACmF;IACnF,OAAO,CAAC,UAAU;IAgBZ,OAAO,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC;IAIzC,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAG5C,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAGpC"}

package/dist/database/adapters/socket/client.d.ts

@@ -6,6 +6,11 @@ import { type StreamRequest, type StreamResult } from './protocol';
  *
  * 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;
@@ -19,10 +24,18 @@ export declare class SocketClient {
     private writer;
     private readonly pending;
     private nextId;
+    private nextStreamId;
     private ready;
     constructor(target: SocketTarget);
+    /** 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;
     private connect;
-    pipeline(tenant: string, requests: StreamRequest[]): Promise<StreamResult[]>;
+    /** 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;
+    pipeline(tenant: string, requests: StreamRequest[], stream?: number): Promise<StreamResult[]>;
     close(): void;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/database/adapters/socket/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/database/adapters/socket/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAE5F;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,qBAAa,YAAY;IAQX,OAAO,CAAC,QAAQ,CAAC,MAAM;IAPnC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiD;IACzE,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,KAAK,CAAe;gBAEC,MAAM,EAAE,YAAY;YAOnC,OAAO;IA6Bf,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAalF,KAAK,IAAI,IAAI;CAId"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/database/adapters/socket/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAE5F;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAaD,qBAAa,YAAY;IASX,OAAO,CAAC,QAAQ,CAAC,MAAM;IARnC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,KAAK,CAAe;gBAEC,MAAM,EAAE,YAAY;IAOjD;yFACqF;IACrF,OAAO,CAAC,WAAW;YAQL,OAAO;IAuCrB;;8FAE0F;IAC1F,WAAW,IAAI,MAAM;IAIf,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAwBnG,KAAK,IAAI,IAAI;CAKd"}

package/dist/database/adapters/socket/protocol.d.ts

@@ -95,6 +95,8 @@ export type StreamRequest = {
     sql: string;
 } | {
     type: 'get_autocommit';
+} | {
+    type: 'get_version';
 } | {
     type: 'close';
 };
@@ -111,6 +113,7 @@ export interface AtomicStep {
     expect?: 'one' | 'atLeastOne' | number;
 }
 export declare function toBatch(steps: AtomicStep[]): Batch;
+export declare function mightReturnRows(sql: string): boolean;
 interface Writable {
     write(data: Uint8Array): number;
 }

package/dist/database/adapters/socket/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../../src/database/adapters/socket/protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../../src/database/adapters/socket/protocol.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -2204,6 +2204,10 @@ var __webpack_exports__ = {};
                 }))
         };
     }
+    const READ_ONLY_RE = /^\s*(?:SELECT|EXPLAIN|VALUES)\b/i;
+    function mightReturnRows(sql) {
+        return READ_ONLY_RE.test(sql) || /\bRETURNING\b/i.test(sql);
+    }
     class FrameWriter {
         socket;
         pending = Buffer.alloc(0);
@@ -2248,6 +2252,7 @@ var __webpack_exports__ = {};
             return out;
         }
     }
+    const REQUEST_TIMEOUT_MS = Number(globalThis.process?.env?.ODB_SOCKET_REQUEST_TIMEOUT_MS) || 30000;
     class SocketClient {
         target;
         socket;
@@ -2255,12 +2260,20 @@ var __webpack_exports__ = {};
         writer;
         pending = new Map();
         nextId = 1;
+        nextStreamId = 1;
         ready;
         constructor(target){
             this.target = target;
             this.ready = this.connect();
             this.ready.catch(()=>{});
         }
+        failPending(err) {
+            for (const p of this.pending.values()){
+                clearTimeout(p.timer);
+                p.reject(err);
+            }
+            this.pending.clear();
+        }
         async connect() {
             const Bun = globalThis.Bun;
             if (!Bun?.connect) throw new Error('odblite-socket backend requires Bun (Bun.connect)');
@@ -2276,40 +2289,67 @@ var __webpack_exports__ = {};
                     data: (_s, chunk)=>{
                         for (const frame of this.reader.push(chunk)){
                             const msg = JSON.parse(frame.toString('utf8'));
-                            const resolve = this.pending.get(msg.id);
-                            if (resolve) {
+                            const p = this.pending.get(msg.id);
+                            if (p) {
                                 this.pending.delete(msg.id);
-                                resolve(msg.results);
+                                clearTimeout(p.timer);
+                                p.resolve(msg.results);
                             }
                         }
                     },
                     drain: (_s)=>this.writer.flush(),
                     close: ()=>{
                         this.socket = void 0;
+                        this.reader = new FrameReader();
+                        this.failPending(new Error('odblite socket disconnected — request not completed'));
+                    },
+                    error: (_s, err)=>{
+                        this.socket = void 0;
+                        this.reader = new FrameReader();
+                        this.failPending(err instanceof Error ? err : new Error(`odblite socket error: ${err}`));
                     }
                 }
             });
             this.writer = new FrameWriter(this.socket);
         }
-        async pipeline(tenant, requests) {
+        allocStream() {
+            return this.nextStreamId++;
+        }
+        async pipeline(tenant, requests, stream) {
+            await this.ready;
             if (!this.socket) {
                 this.ready = this.connect();
                 this.ready.catch(()=>{});
+                await this.ready;
             }
-            await this.ready;
             const id = this.nextId++;
-            return new Promise((resolve)=>{
-                this.pending.set(id, resolve);
-                this.writer.send(Buffer.from(JSON.stringify({
+            return new Promise((resolve, reject)=>{
+                const timer = setTimeout(()=>{
+                    if (this.pending.delete(id)) reject(new Error(`odblite socket request ${id} timed out after ${REQUEST_TIMEOUT_MS}ms`));
+                }, REQUEST_TIMEOUT_MS);
+                timer.unref?.();
+                this.pending.set(id, {
+                    resolve,
+                    reject,
+                    timer
+                });
+                const payload = null != stream ? {
+                    id,
+                    tenant,
+                    stream,
+                    requests
+                } : {
                     id,
                     tenant,
                     requests
-                }), 'utf8'));
+                };
+                this.writer.send(Buffer.from(JSON.stringify(payload), 'utf8'));
             });
         }
         close() {
             this.socket?.end?.();
             this.socket = void 0;
+            this.failPending(new Error('odblite socket closed'));
         }
     }
     function toQueryResult(res) {
@@ -2333,21 +2373,22 @@ var __webpack_exports__ = {};
     class OdbliteSocketConnection {
         client;
         tenant;
+        streamId;
         databaseName;
         databaseHash;
         sql;
-        buffer;
-        constructor(client, tenant, buffer){
+        beginPending = false;
+        constructor(client, tenant, streamId){
             this.client = client;
             this.tenant = tenant;
+            this.streamId = streamId;
             this.databaseName = tenant;
             this.databaseHash = tenant;
-            this.buffer = buffer;
             const self = this;
             this.sql = function(strings, ...values) {
                 if (strings && 'object' == typeof strings && 'raw' in strings) {
                     const text = strings.reduce((a, s, i)=>a + s + (i < values.length ? '?' : ''), '');
-                    const returns = /^\s*SELECT/i.test(text) || /\bRETURNING\b/i.test(text);
+                    const returns = mightReturnRows(text);
                     return (returns ? self.query(text, values) : self.execute(text, values)).then((r)=>r.rows);
                 }
                 throw new Error('sql() fragment helper not implemented in odblite-socket');
@@ -2358,7 +2399,32 @@ var __webpack_exports__ = {};
             if (!res) throw new Error('odblite-socket: empty pipeline response');
             return res;
         }
+        async streamExec(sql, params = []) {
+            const reqs = [];
+            if (this.beginPending) {
+                reqs.push({
+                    type: 'execute',
+                    stmt: {
+                        sql: 'BEGIN'
+                    }
+                });
+                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);
+            const res = results[results.length - 1];
+            if (!res) throw new Error('odblite-socket: empty stream response');
+            return toQueryResult(res);
+        }
         async query(sql, params = []) {
+            if (null != this.streamId) return await this.streamExec(sql, params);
             return toQueryResult(await this.one([
                 {
                     type: 'execute',
@@ -2372,16 +2438,7 @@ var __webpack_exports__ = {};
         async execute(sql, params = []) {
             const s = 'string' == typeof sql ? sql : sql.sql;
             const p = 'string' == typeof sql ? params : sql.args ?? [];
-            if (this.buffer) {
-                this.buffer.push({
-                    sql: s,
-                    params: p
-                });
-                return {
-                    rows: [],
-                    rowsAffected: 0
-                };
-            }
+            if (null != this.streamId) return this.streamExec(s, p);
             return toQueryResult(await this.one([
                 {
                     type: 'execute',
@@ -2410,24 +2467,33 @@ var __webpack_exports__ = {};
             };
         }
         async transaction(fn) {
-            if (this.buffer) return fn(this);
-            const buffer = [];
-            const out = await fn(new OdbliteSocketConnection(this.client, this.tenant, buffer));
-            if (buffer.length) {
-                const res = await this.atomic(buffer.map((b)=>({
-                        sql: b.sql,
-                        params: b.params
-                    })));
-                const err = res.step_errors?.find((e)=>e);
-                if (err) throw new Error(`transaction batch failed: ${err.message}`);
+            if (null != this.streamId) return fn(this);
+            const tx = new OdbliteSocketConnection(this.client, this.tenant, this.client.allocStream());
+            tx.beginPending = true;
+            try {
+                const out = await fn(tx);
+                if (!tx.beginPending) await tx.streamExec('COMMIT');
+                return out;
+            } catch (e) {
+                if (!tx.beginPending) await tx.streamExec('ROLLBACK').catch(()=>{});
+                throw e;
             }
-            return out;
         }
         begin(fn) {
             return this.transaction(fn);
         }
-        savepoint(fn) {
-            return this.transaction(fn);
+        async savepoint(fn) {
+            if (null == this.streamId) 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;
+            }
         }
         async ensureNamespaces(namespaces) {
             return {
@@ -2465,20 +2531,26 @@ var __webpack_exports__ = {};
         }
         async isHealthy() {
             try {
-                await Promise.race([
+                const res = await Promise.race([
                     this.client.pipeline('_health', [
                         {
-                            type: 'get_autocommit'
+                            type: 'get_version'
                         }
                     ]),
                     new Promise((_, rej)=>setTimeout(()=>rej(new Error('probe timeout')), 1500))
                 ]);
+                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;
             }
         }
     }
+    const CLIENT_SOCKET_PROTOCOL = 2;
     const DEFAULT_UNIX_SOCKET = '/tmp/odblite.sock';
     function parseSocketTarget(s) {
         const v = (s ?? '').trim();
@@ -2499,13 +2571,26 @@ var __webpack_exports__ = {};
     }
     class OdbliteAutoAdapter {
         type = 'odblite';
+        opts;
         chosen;
+        onHttp = false;
+        nextRetryAt = 0;
         constructor(opts){
-            this.chosen = this.pick(opts);
+            this.opts = opts;
+            this.chosen = this.pick();
         }
-        async pick(opts) {
+        async pick() {
             const hasBun = void 0 !== globalThis.Bun && !!globalThis.Bun.connect;
-            if (hasBun) for (const target of this.candidates(opts))try {
+            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);
+        }
+        async trySocket() {
+            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}`})`);
@@ -2513,12 +2598,23 @@ var __webpack_exports__ = {};
                 }
                 await socket.disconnect();
             } catch  {}
-            console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)');
-            return new ODBLiteAdapter(opts.http);
-        }
-        candidates(opts) {
-            if (opts.socket?.unix || opts.socket?.port) return [
-                opts.socket
+            return null;
+        }
+        async maybeUpgrade() {
+            if (!this.onHttp) return;
+            const now = Date.now();
+            if (now < this.nextRetryAt) return;
+            this.nextRetryAt = now + 15000;
+            const socket = await this.trySocket();
+            if (socket) {
+                this.chosen = Promise.resolve(socket);
+                this.onHttp = false;
+            }
+        }
+        candidates() {
+            const { socket, http } = this.opts;
+            if (socket?.unix || socket?.port) return [
+                socket
             ];
             const env = globalThis.process?.env?.ODB_SOCKET;
             if (env) return [
@@ -2530,7 +2626,7 @@ var __webpack_exports__ = {};
                 }
             ];
             try {
-                const host = new URL(opts.http?.serviceUrl).hostname;
+                const host = new URL(http?.serviceUrl).hostname;
                 const port = Number(globalThis.process?.env?.ODB_SOCKET_PORT ?? 8787);
                 if (host) out.push({
                     hostname: host,
@@ -2540,6 +2636,7 @@ var __webpack_exports__ = {};
             return out;
         }
         async connect(config) {
+            await this.maybeUpgrade();
             return (await this.chosen).connect(config);
         }
         async disconnect(tenantId) {

package/dist/index.js

@@ -2114,6 +2114,10 @@ function toBatch(steps) {
             }))
     };
 }
+const READ_ONLY_RE = /^\s*(?:SELECT|EXPLAIN|VALUES)\b/i;
+function mightReturnRows(sql) {
+    return READ_ONLY_RE.test(sql) || /\bRETURNING\b/i.test(sql);
+}
 class FrameWriter {
     socket;
     pending = Buffer.alloc(0);
@@ -2158,6 +2162,7 @@ class FrameReader {
         return out;
     }
 }
+const REQUEST_TIMEOUT_MS = Number(globalThis.process?.env?.ODB_SOCKET_REQUEST_TIMEOUT_MS) || 30000;
 class SocketClient {
     target;
     socket;
@@ -2165,12 +2170,20 @@ class SocketClient {
     writer;
     pending = new Map();
     nextId = 1;
+    nextStreamId = 1;
     ready;
     constructor(target){
         this.target = target;
         this.ready = this.connect();
         this.ready.catch(()=>{});
     }
+    failPending(err) {
+        for (const p of this.pending.values()){
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+    }
     async connect() {
         const Bun = globalThis.Bun;
         if (!Bun?.connect) throw new Error('odblite-socket backend requires Bun (Bun.connect)');
@@ -2186,40 +2199,67 @@ class SocketClient {
                 data: (_s, chunk)=>{
                     for (const frame of this.reader.push(chunk)){
                         const msg = JSON.parse(frame.toString('utf8'));
-                        const resolve = this.pending.get(msg.id);
-                        if (resolve) {
+                        const p = this.pending.get(msg.id);
+                        if (p) {
                             this.pending.delete(msg.id);
-                            resolve(msg.results);
+                            clearTimeout(p.timer);
+                            p.resolve(msg.results);
                         }
                     }
                 },
                 drain: (_s)=>this.writer.flush(),
                 close: ()=>{
                     this.socket = void 0;
+                    this.reader = new FrameReader();
+                    this.failPending(new Error('odblite socket disconnected — request not completed'));
+                },
+                error: (_s, err)=>{
+                    this.socket = void 0;
+                    this.reader = new FrameReader();
+                    this.failPending(err instanceof Error ? err : new Error(`odblite socket error: ${err}`));
                 }
             }
         });
         this.writer = new FrameWriter(this.socket);
     }
-    async pipeline(tenant, requests) {
+    allocStream() {
+        return this.nextStreamId++;
+    }
+    async pipeline(tenant, requests, stream) {
+        await this.ready;
         if (!this.socket) {
             this.ready = this.connect();
             this.ready.catch(()=>{});
+            await this.ready;
         }
-        await this.ready;
         const id = this.nextId++;
-        return new Promise((resolve)=>{
-            this.pending.set(id, resolve);
-            this.writer.send(Buffer.from(JSON.stringify({
+        return new Promise((resolve, reject)=>{
+            const timer = setTimeout(()=>{
+                if (this.pending.delete(id)) reject(new Error(`odblite socket request ${id} timed out after ${REQUEST_TIMEOUT_MS}ms`));
+            }, REQUEST_TIMEOUT_MS);
+            timer.unref?.();
+            this.pending.set(id, {
+                resolve,
+                reject,
+                timer
+            });
+            const payload = null != stream ? {
+                id,
+                tenant,
+                stream,
+                requests
+            } : {
                 id,
                 tenant,
                 requests
-            }), 'utf8'));
+            };
+            this.writer.send(Buffer.from(JSON.stringify(payload), 'utf8'));
         });
     }
     close() {
         this.socket?.end?.();
         this.socket = void 0;
+        this.failPending(new Error('odblite socket closed'));
     }
 }
 function toQueryResult(res) {
@@ -2243,21 +2283,22 @@ function toQueryResult(res) {
 class OdbliteSocketConnection {
     client;
     tenant;
+    streamId;
     databaseName;
     databaseHash;
     sql;
-    buffer;
-    constructor(client, tenant, buffer){
+    beginPending = false;
+    constructor(client, tenant, streamId){
         this.client = client;
         this.tenant = tenant;
+        this.streamId = streamId;
         this.databaseName = tenant;
         this.databaseHash = tenant;
-        this.buffer = buffer;
         const self = this;
         this.sql = function(strings, ...values) {
             if (strings && 'object' == typeof strings && 'raw' in strings) {
                 const text = strings.reduce((a, s, i)=>a + s + (i < values.length ? '?' : ''), '');
-                const returns = /^\s*SELECT/i.test(text) || /\bRETURNING\b/i.test(text);
+                const returns = mightReturnRows(text);
                 return (returns ? self.query(text, values) : self.execute(text, values)).then((r)=>r.rows);
             }
             throw new Error('sql() fragment helper not implemented in odblite-socket');
@@ -2268,7 +2309,32 @@ class OdbliteSocketConnection {
         if (!res) throw new Error('odblite-socket: empty pipeline response');
         return res;
     }
+    async streamExec(sql, params = []) {
+        const reqs = [];
+        if (this.beginPending) {
+            reqs.push({
+                type: 'execute',
+                stmt: {
+                    sql: 'BEGIN'
+                }
+            });
+            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);
+        const res = results[results.length - 1];
+        if (!res) throw new Error('odblite-socket: empty stream response');
+        return toQueryResult(res);
+    }
     async query(sql, params = []) {
+        if (null != this.streamId) return await this.streamExec(sql, params);
         return toQueryResult(await this.one([
             {
                 type: 'execute',
@@ -2282,16 +2348,7 @@ class OdbliteSocketConnection {
     async execute(sql, params = []) {
         const s = 'string' == typeof sql ? sql : sql.sql;
         const p = 'string' == typeof sql ? params : sql.args ?? [];
-        if (this.buffer) {
-            this.buffer.push({
-                sql: s,
-                params: p
-            });
-            return {
-                rows: [],
-                rowsAffected: 0
-            };
-        }
+        if (null != this.streamId) return this.streamExec(s, p);
         return toQueryResult(await this.one([
             {
                 type: 'execute',
@@ -2320,24 +2377,33 @@ class OdbliteSocketConnection {
         };
     }
     async transaction(fn) {
-        if (this.buffer) return fn(this);
-        const buffer = [];
-        const out = await fn(new OdbliteSocketConnection(this.client, this.tenant, buffer));
-        if (buffer.length) {
-            const res = await this.atomic(buffer.map((b)=>({
-                    sql: b.sql,
-                    params: b.params
-                })));
-            const err = res.step_errors?.find((e)=>e);
-            if (err) throw new Error(`transaction batch failed: ${err.message}`);
+        if (null != this.streamId) return fn(this);
+        const tx = new OdbliteSocketConnection(this.client, this.tenant, this.client.allocStream());
+        tx.beginPending = true;
+        try {
+            const out = await fn(tx);
+            if (!tx.beginPending) await tx.streamExec('COMMIT');
+            return out;
+        } catch (e) {
+            if (!tx.beginPending) await tx.streamExec('ROLLBACK').catch(()=>{});
+            throw e;
         }
-        return out;
     }
     begin(fn) {
         return this.transaction(fn);
     }
-    savepoint(fn) {
-        return this.transaction(fn);
+    async savepoint(fn) {
+        if (null == this.streamId) 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;
+        }
     }
     async ensureNamespaces(namespaces) {
         return {
@@ -2375,20 +2441,26 @@ class OdbliteSocketAdapter {
     }
     async isHealthy() {
         try {
-            await Promise.race([
+            const res = await Promise.race([
                 this.client.pipeline('_health', [
                     {
-                        type: 'get_autocommit'
+                        type: 'get_version'
                     }
                 ]),
                 new Promise((_, rej)=>setTimeout(()=>rej(new Error('probe timeout')), 1500))
             ]);
+            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;
         }
     }
 }
+const CLIENT_SOCKET_PROTOCOL = 2;
 const DEFAULT_UNIX_SOCKET = '/tmp/odblite.sock';
 function parseSocketTarget(s) {
     const v = (s ?? '').trim();
@@ -2409,13 +2481,26 @@ function parseSocketTarget(s) {
 }
 class OdbliteAutoAdapter {
     type = 'odblite';
+    opts;
     chosen;
+    onHttp = false;
+    nextRetryAt = 0;
     constructor(opts){
-        this.chosen = this.pick(opts);
+        this.opts = opts;
+        this.chosen = this.pick();
     }
-    async pick(opts) {
+    async pick() {
         const hasBun = void 0 !== globalThis.Bun && !!globalThis.Bun.connect;
-        if (hasBun) for (const target of this.candidates(opts))try {
+        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);
+    }
+    async trySocket() {
+        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}`})`);
@@ -2423,12 +2508,23 @@ class OdbliteAutoAdapter {
             }
             await socket.disconnect();
         } catch  {}
-        console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)');
-        return new ODBLiteAdapter(opts.http);
-    }
-    candidates(opts) {
-        if (opts.socket?.unix || opts.socket?.port) return [
-            opts.socket
+        return null;
+    }
+    async maybeUpgrade() {
+        if (!this.onHttp) return;
+        const now = Date.now();
+        if (now < this.nextRetryAt) return;
+        this.nextRetryAt = now + 15000;
+        const socket = await this.trySocket();
+        if (socket) {
+            this.chosen = Promise.resolve(socket);
+            this.onHttp = false;
+        }
+    }
+    candidates() {
+        const { socket, http } = this.opts;
+        if (socket?.unix || socket?.port) return [
+            socket
         ];
         const env = globalThis.process?.env?.ODB_SOCKET;
         if (env) return [
@@ -2440,7 +2536,7 @@ class OdbliteAutoAdapter {
             }
         ];
         try {
-            const host = new URL(opts.http?.serviceUrl).hostname;
+            const host = new URL(http?.serviceUrl).hostname;
             const port = Number(globalThis.process?.env?.ODB_SOCKET_PORT ?? 8787);
             if (host) out.push({
                 hostname: host,
@@ -2450,6 +2546,7 @@ class OdbliteAutoAdapter {
         return out;
     }
     async connect(config) {
+        await this.maybeUpgrade();
         return (await this.chosen).connect(config);
     }
     async disconnect(tenantId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pineliner/odb-client",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Isomorphic client for ODB-Lite with postgres.js-like template string SQL support",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

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

@@ -5,6 +5,7 @@ import {
   toHrana,
   fromHrana,
   toBatch,
+  mightReturnRows,
   type AtomicStep,
   type BatchResult,
   type StmtResult,
@@ -43,21 +44,24 @@ class OdbliteSocketConnection implements Connection {
   databaseName?: string
   databaseHash?: string
   public sql: any
-  private readonly buffer?: { sql: string; params: 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,
-    buffer?: { sql: string; params: any[] }[],
+    /** 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
-    this.buffer = buffer
     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 = /^\s*SELECT/i.test(text) || /\bRETURNING\b/i.test(text)
+        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')
@@ -71,17 +75,31 @@ class OdbliteSocketConnection implements Connection {
     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.buffer) {
-      this.buffer.push({ sql: s, params: p }) // deferred → flushed as one batch on commit
-      return { rows: [], rowsAffected: 0 }
-    }
+    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) } }]))
   }
 
@@ -100,22 +118,42 @@ class OdbliteSocketConnection implements Connection {
     }
   }
 
+  /**
+   * 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.buffer) return fn(this) // nested → same buffer
-    const buffer: { sql: string; params: any[] }[] = []
-    const out = await fn(new OdbliteSocketConnection(this.client, this.tenant, buffer))
-    if (buffer.length) {
-      const res = await this.atomic(buffer.map((b) => ({ sql: b.sql, params: b.params })))
-      const err = res.step_errors?.find((e) => e)
-      if (err) throw new Error(`transaction batch failed: ${err.message}`)
+    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
     }
-    return out
   }
   begin<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
     return this.transaction(fn)
   }
-  savepoint<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.
@@ -154,10 +192,18 @@ export class OdbliteSocketAdapter implements DatabaseAdapter {
 
   async isHealthy(): Promise<boolean> {
     try {
-      await Promise.race([
-        this.client.pipeline('_health', [{ type: 'get_autocommit' }]),
+      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
@@ -165,6 +211,11 @@ export class OdbliteSocketAdapter implements DatabaseAdapter {
   }
 }
 
+/** 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'
 
@@ -200,41 +251,69 @@ export function parseSocketTarget(s?: string): SocketTarget {
  */
 export class OdbliteAutoAdapter implements DatabaseAdapter {
   readonly type: BackendType = 'odblite'
-  private readonly chosen: Promise<DatabaseAdapter>
+  private readonly opts: { socket?: OdbliteSocketConfig; http: any }
+  private chosen: Promise<DatabaseAdapter>
+  private onHttp = false
+  private nextRetryAt = 0
 
   constructor(opts: { socket?: OdbliteSocketConfig; http: any }) {
-    this.chosen = this.pick(opts)
+    this.opts = opts
+    this.chosen = this.pick()
   }
 
-  private async pick(opts: { socket?: OdbliteSocketConfig; http: any }): Promise<DatabaseAdapter> {
+  private async pick(): Promise<DatabaseAdapter> {
     const hasBun = typeof (globalThis as any).Bun !== 'undefined' && !!(globalThis as any).Bun.connect
     if (hasBun) {
-      for (const target of this.candidates(opts)) {
-        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 */
+      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 */
       }
     }
-    console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)')
-    return new ODBLiteAdapter(opts.http)
+    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(opts: { socket?: OdbliteSocketConfig; http: any }): SocketTarget[] {
-    if (opts.socket?.unix || opts.socket?.port) return [opts.socket]
+  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(opts.http?.serviceUrl).hostname // e.g. odb-lite from http://odb-lite:8671
+      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 {
@@ -244,6 +323,7 @@ export class OdbliteAutoAdapter implements DatabaseAdapter {
   }
 
   async connect(config: any): Promise<Connection> {
+    await this.maybeUpgrade()
     return (await this.chosen).connect(config)
   }
   async disconnect(tenantId?: string): Promise<void> {

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

@@ -7,6 +7,11 @@ import { FrameReader, FrameWriter, type StreamRequest, type StreamResult } from
  *
  * 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
@@ -14,12 +19,24 @@ export interface SocketTarget {
   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, (r: StreamResult[]) => void>()
+  private readonly pending = new Map<number, Pending>()
   private nextId = 1
+  private nextStreamId = 1
   private ready: Promise<void>
 
   constructor(private readonly target: SocketTarget) {
@@ -29,6 +46,16 @@ export class SocketClient {
     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)')
@@ -41,38 +68,67 @@ export class SocketClient {
         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 resolve = this.pending.get(msg.id)
-            if (resolve) {
+            const p = this.pending.get(msg.id)
+            if (p) {
               this.pending.delete(msg.id)
-              resolve(msg.results)
+              clearTimeout(p.timer)
+              p.resolve(msg.results)
             }
           }
         },
         drain: (_s: any) => this.writer.flush(),
         close: () => {
-          // reconnect lazily on next pipeline()
+          // 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)
   }
 
-  async pipeline(tenant: string, requests: StreamRequest[]): Promise<StreamResult[]> {
+  /** 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
     }
-    await this.ready
     const id = this.nextId++
-    return new Promise<StreamResult[]>((resolve) => {
-      this.pending.set(id, resolve)
-      this.writer.send(Buffer.from(JSON.stringify({ id, tenant, requests }), 'utf8'))
+    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

@@ -88,6 +88,7 @@ export type StreamRequest =
   | { 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 }
@@ -109,6 +110,15 @@ export function toBatch(steps: AtomicStep[]): Batch {
   }
 }
 
+// ── 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