tina4-nodejs 3.13.43 → 3.13.44

package/packages/core/src/sessionHandlers/mongoHandler.ts

@@ -13,8 +13,8 @@
  *   TINA4_SESSION_MONGO_DB         (default: "tina4_sessions")
  *   TINA4_SESSION_MONGO_COLLECTION (default: "sessions")
  */
-import { execFileSync } from "node:child_process";
 import type { SessionHandler } from "../session.js";
+import { mongoCommandSync, type MongoTarget } from "./mongoClient.js";
 
 interface SessionData {
   _created: number;
@@ -85,221 +85,42 @@ export class MongoSessionHandler implements SessionHandler {
       ?? "sessions";
   }
 
-  /**
-   * Execute a MongoDB command synchronously via a child process.
-   *
-   * Uses the MongoDB wire protocol (OP_MSG) to communicate with the server.
-   * For simplicity, we use the `runCommand` approach with JSON serialization
-   * of BSON documents using a minimal BSON encoder.
-   *
-   * Returns the command response string (or `__EMPTY__` for an absent doc).
-   * A transport/connection FAILURE (server unreachable, socket error, timeout)
-   * THROWS so the Session boundary can distinguish "not found" (silent) from
-   * "backend failed" (log-loud + degrade). Backend-failure policy parity.
-   */
-  private execSync(command: string, args: string): string {
-    const script = `
-      const net = require("node:net");
-      const host = ${JSON.stringify(this.uri ? this.parseUri().host : this.host)};
-      const port = ${this.uri ? this.parseUri().port : this.port};
-      const database = ${JSON.stringify(this.database)};
-      const collection = ${JSON.stringify(this.collection)};
-      const command = ${JSON.stringify(command)};
-      const args = ${JSON.stringify(args)};
-
-      // Minimal BSON encoder/decoder for session operations
-      function encodeBsonDocument(obj) {
-        const parts = [];
-        for (const [key, value] of Object.entries(obj)) {
-          if (typeof value === "string") {
-            const keyBuf = Buffer.from(key + "\\0", "utf-8");
-            const valBuf = Buffer.from(value, "utf-8");
-            const entry = Buffer.alloc(1 + keyBuf.length + 4 + valBuf.length + 1);
-            entry.writeUInt8(2, 0); // string type
-            keyBuf.copy(entry, 1);
-            entry.writeInt32LE(valBuf.length + 1, 1 + keyBuf.length);
-            valBuf.copy(entry, 1 + keyBuf.length + 4);
-            entry.writeUInt8(0, entry.length - 1);
-            parts.push(entry);
-          } else if (typeof value === "number") {
-            const keyBuf = Buffer.from(key + "\\0", "utf-8");
-            if (Number.isInteger(value)) {
-              const entry = Buffer.alloc(1 + keyBuf.length + 4);
-              entry.writeUInt8(16, 0); // int32 type
-              keyBuf.copy(entry, 1);
-              entry.writeInt32LE(value, 1 + keyBuf.length);
-              parts.push(entry);
-            } else {
-              const entry = Buffer.alloc(1 + keyBuf.length + 8);
-              entry.writeUInt8(1, 0); // double type
-              keyBuf.copy(entry, 1);
-              entry.writeDoubleBE(value, 1 + keyBuf.length);
-              parts.push(entry);
-            }
-          } else if (typeof value === "object" && value !== null) {
-            const keyBuf = Buffer.from(key + "\\0", "utf-8");
-            const subDoc = encodeBsonDocument(value);
-            const entry = Buffer.alloc(1 + keyBuf.length + subDoc.length);
-            entry.writeUInt8(3, 0); // document type
-            keyBuf.copy(entry, 1);
-            subDoc.copy(entry, 1 + keyBuf.length);
-            parts.push(entry);
-          }
-        }
-        const body = Buffer.concat(parts);
-        const doc = Buffer.alloc(4 + body.length + 1);
-        doc.writeInt32LE(doc.length, 0);
-        body.copy(doc, 4);
-        doc.writeUInt8(0, doc.length - 1);
-        return doc;
-      }
-
-      // Use MongoDB OP_MSG (opcode 2013) with runCommand
-      function buildOpMsg(dbName, cmd) {
-        const cmdDoc = Object.assign({ "$db": dbName }, cmd);
-        const body = encodeBsonDocument(cmdDoc);
-
-        // OP_MSG: flagBits(4) + kind(1) + body
-        const section = Buffer.alloc(1 + body.length);
-        section.writeUInt8(0, 0); // kind 0 = body
-        body.copy(section, 1);
-
-        const msgHeader = Buffer.alloc(16 + 4 + section.length);
-        msgHeader.writeInt32LE(msgHeader.length, 0); // messageLength
-        msgHeader.writeInt32LE(1, 4); // requestID
-        msgHeader.writeInt32LE(0, 8); // responseTo
-        msgHeader.writeInt32LE(2013, 12); // opCode = OP_MSG
-        msgHeader.writeUInt32LE(0, 16); // flagBits
-        section.copy(msgHeader, 20);
-
-        return msgHeader;
-      }
-
-      // For this simplified implementation, we use a TCP connection
-      // and send/receive raw OP_MSG frames
-      const sock = net.createConnection({ host, port }, () => {
-        let cmd;
-        const parsedArgs = JSON.parse(args);
-
-        if (command === "find") {
-          cmd = {
-            find: collection,
-            filter: parsedArgs.filter,
-            limit: 1
-          };
-        } else if (command === "update") {
-          cmd = {
-            update: collection,
-            updates: [{ q: parsedArgs.filter, u: { "$set": parsedArgs.data }, upsert: true }]
-          };
-        } else if (command === "delete") {
-          cmd = {
-            delete: collection,
-            deletes: [{ q: parsedArgs.filter, limit: 1 }]
-          };
-        }
-
-        const msg = buildOpMsg(database, cmd);
-        sock.write(msg);
-      });
-
-      let buffer = Buffer.alloc(0);
-      sock.on("data", (chunk) => {
-        buffer = Buffer.concat([buffer, chunk]);
-        if (buffer.length >= 4) {
-          const msgLen = buffer.readInt32LE(0);
-          if (buffer.length >= msgLen) {
-            // Parse response — extract body section
-            // Header is 16 bytes + 4 bytes flagBits + 1 byte section kind + BSON doc
-            if (buffer.length > 21) {
-              const bsonStart = 21;
-              const bsonLen = buffer.readInt32LE(bsonStart);
-              const bsonDoc = buffer.subarray(bsonStart, bsonStart + bsonLen);
-
-              // Simple BSON parser — just look for the session data string
-              const rawStr = bsonDoc.toString("utf-8", 4);
-
-              if (command === "find") {
-                // Look for cursor.firstBatch documents
-                // For simplicity, extract JSON-like data from response
-                process.stdout.write(rawStr);
-              } else {
-                process.stdout.write("__OK__");
-              }
-            } else {
-              process.stdout.write("__EMPTY__");
-            }
-            sock.destroy();
-          }
-        }
-      });
-
-      sock.on("error", (err) => {
-        process.stderr.write(err.message);
-        process.exit(1);
-      });
-
-      setTimeout(() => { sock.destroy(); process.exit(1); }, 5000);
-    `;
-
-    try {
-      return execFileSync(process.execPath, ["-e", script], {
-        encoding: "utf-8",
-        timeout: 8000,
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-    } catch (err) {
-      // Non-zero exit = the child hit a socket error / timeout. That is a
-      // transport FAILURE, not an absent document — surface it so the Session
-      // boundary logs + degrades (or re-throws under strict mode).
-      throw new Error(`MongoDB command failed: ${(err as Error).message}`);
-    }
-  }
-
-  private parseUri(): { host: string; port: number } {
-    if (!this.uri) return { host: this.host, port: this.port };
-    try {
-      // mongodb://host:port/db
-      const match = this.uri.match(/mongodb:\/\/([^/:]+):?(\d+)?/);
+  /** Resolve the effective host/port (honours a configured mongodb:// URI). */
+  private target(): MongoTarget {
+    let host = this.host;
+    let port = this.port;
+    if (this.uri) {
+      const match = this.uri.match(/mongodb:\/\/(?:[^@/]+@)?([^/:]+):?(\d+)?/);
       if (match) {
-        return {
-          host: match[1],
-          port: match[2] ? parseInt(match[2], 10) : 27017,
-        };
+        host = match[1];
+        port = match[2] ? parseInt(match[2], 10) : 27017;
       }
-    } catch { /* ignore */ }
-    return { host: this.host, port: this.port };
+    }
+    return { host, port, database: this.database, collection: this.collection };
   }
 
   read(sessionId: string): SessionData | null {
-    const result = this.execSync("find", JSON.stringify({
-      filter: { _id: sessionId },
-    }));
-
-    if (!result || result === "__EMPTY__") return null;
-
-    // Try to extract session data from the BSON response
+    const result = mongoCommandSync(this.target(), "find", { filter: { _id: sessionId } });
+    if (!result || result === "__EMPTY__") return null;   // genuine miss
     try {
-      // Look for the JSON data pattern in the response
-      const dataMatch = result.match(/"data"\s*:\s*(\{[^}]+\})/);
-      if (dataMatch) {
-        return JSON.parse(dataMatch[1]) as SessionData;
-      }
-    } catch { /* ignore */ }
-
-    return null;
+      const doc = JSON.parse(result) as { data?: unknown };
+      const data = doc?.data;
+      // Stored as a nested document (parity with the Python master); read returns it.
+      return data && typeof data === "object" ? (data as SessionData) : null;
+    } catch {
+      return null;
+    }
   }
 
   write(sessionId: string, data: SessionData, _ttl: number): void {
-    this.execSync("update", JSON.stringify({
+    mongoCommandSync(this.target(), "update", {
       filter: { _id: sessionId },
-      data: { _id: sessionId, data: JSON.stringify(data), updatedAt: new Date().toISOString() },
-    }));
+      data,
+      last_accessed: Date.now() / 1000,
+    });
   }
 
   destroy(sessionId: string): void {
-    this.execSync("delete", JSON.stringify({
-      filter: { _id: sessionId },
-    }));
+    mongoCommandSync(this.target(), "delete", { filter: { _id: sessionId } });
   }
 }

package/packages/core/src/sessionHandlers/redisHandler.ts

@@ -17,7 +17,21 @@
  *   TINA4_SESSION_REDIS_DB       (default: 0)
  */
 import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
 import type { SessionHandler } from "../session.js";
+import { respCommandSync } from "./respClient.js";
+
+// Resolve packages relative to this module so the optional `redis` driver is
+// detected exactly as a consumer would resolve it (createRequire works in ESM).
+const moduleRequire = createRequire(import.meta.url);
+function redisDriverAvailable(): boolean {
+  try {
+    moduleRequire.resolve("redis");
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 interface SessionData {
   _created: number;
@@ -83,125 +97,72 @@ export class RedisNpmSessionHandler implements SessionHandler {
         : 0);
   }
 
+  /** Resolve a host/port for the raw-RESP path (parses TINA4_SESSION_REDIS_URL if set). */
+  private resolveHostPort(): { host: string; port: number } {
+    if (this.url) {
+      try {
+        const u = new URL(this.url);
+        return { host: u.hostname || "127.0.0.1", port: parseInt(u.port, 10) || 6379 };
+      } catch {
+        return { host: this.host, port: this.port };
+      }
+    }
+    return { host: this.host, port: this.port };
+  }
+
   /**
-   * Execute a Redis command synchronously via a short-lived child process.
+   * Execute a Redis command synchronously.
    *
-   * Attempts to use the `redis` npm package first. If unavailable, falls
-   * back to raw TCP (RESP protocol) — same as valkeyHandler.ts.
+   * Prefers the official `redis` driver when it is installed (the class's reason
+   * to exist); otherwise speaks raw RESP via the shared {@link respCommandSync}
+   * transport — same correct path as the Valkey handler, no `redis` dependency.
    *
-   * Returns the command result string. A genuine key miss yields `""`. A
-   * transport/connection FAILURE (server unreachable, AUTH error, timeout)
-   * THROWS so the Session boundary can distinguish "not found" (silent) from
-   * "backend failed" (log-loud + degrade). Backend-failure policy parity.
+   * A genuine key miss yields `""`; a transport/connection FAILURE (server
+   * unreachable, rejected AUTH, timeout) THROWS so the Session boundary can
+   * distinguish "not found" (silent) from "backend failed" (log-loud + degrade).
    */
   private execSync(args: string[]): string {
+    if (redisDriverAvailable()) {
+      return this.execViaNpm(args);
+    }
+    const { host, port } = this.resolveHostPort();
+    return respCommandSync({ host, port, password: this.password, db: this.db }, args, "Redis");
+  }
+
+  /** Drive the command through the `redis` npm client in a short-lived child. */
+  private execViaNpm(args: string[]): string {
     const script = `
-      const net = require("node:net");
-      const host = ${JSON.stringify(this.url || this.host)};
+      const useUrl = ${JSON.stringify(!!this.url)};
+      const url = ${JSON.stringify(this.url)};
+      const host = ${JSON.stringify(this.host)};
       const port = ${this.port};
       const password = ${JSON.stringify(this.password)};
       const db = ${this.db};
-      const useUrl = ${JSON.stringify(!!this.url)};
-      const url = ${JSON.stringify(this.url)};
       const args = ${JSON.stringify(args)};
-
-      // Try the redis npm package first
-      let redisAvailable = false;
-      try {
-        require.resolve("redis");
-        redisAvailable = true;
-      } catch {}
-
-      if (redisAvailable) {
-        const redis = require("redis");
-        (async () => {
-          try {
-            const clientOpts = useUrl
-              ? { url }
-              : { socket: { host, port }, password: password || undefined, database: db };
-            const client = redis.createClient(clientOpts);
-            client.on("error", () => {});
-            await client.connect();
-
-            const cmd = args[0].toUpperCase();
-            let result;
-            if (cmd === "GET") {
-              result = await client.get(args[1]);
-            } else if (cmd === "SET") {
-              result = await client.set(args[1], args[2]);
-            } else if (cmd === "SETEX") {
-              result = await client.setEx(args[1], parseInt(args[2], 10), args[3]);
-            } else if (cmd === "DEL") {
-              result = await client.del(args[1]);
-            }
-            await client.quit();
-
-            if (result === null || result === undefined) {
-              process.stdout.write("__NULL__");
-            } else {
-              process.stdout.write(String(result));
-            }
-          } catch (err) {
-            process.stderr.write(err.message);
-            process.exit(1);
-          }
-        })();
-      } else {
-        // Fallback: raw TCP RESP protocol (no redis package needed)
-        const actualHost = useUrl ? (() => {
-          try { const u = new URL(url); return u.hostname || "127.0.0.1"; } catch { return "127.0.0.1"; }
-        })() : host;
-        const actualPort = useUrl ? (() => {
-          try { const u = new URL(url); return parseInt(u.port, 10) || 6379; } catch { return 6379; }
-        })() : port;
-
-        function buildCommand(a) {
-          let cmd = "*" + a.length + "\\r\\n";
-          for (const s of a) cmd += "$" + Buffer.byteLength(s) + "\\r\\n" + s + "\\r\\n";
-          return cmd;
-        }
-
-        const sock = net.createConnection({ host: actualHost, port: actualPort }, () => {
-          let commands = "";
-          if (password) commands += buildCommand(["AUTH", password]);
-          if (db !== 0) commands += buildCommand(["SELECT", String(db)]);
-          commands += buildCommand(args);
-          sock.write(commands);
-        });
-
-        let buffer = Buffer.alloc(0);
-        sock.on("data", (chunk) => {
-          buffer = Buffer.concat([buffer, chunk]);
-        });
-        sock.on("end", () => {
-          const lines = buffer.toString("utf-8").split("\\r\\n");
-          let responses = [];
-          let i = 0;
-          while (i < lines.length) {
-            const line = lines[i];
-            if (!line) { i++; continue; }
-            if (line.startsWith("+") || line.startsWith("-") || line.startsWith(":")) {
-              responses.push(line);
-              i++;
-            } else if (line.startsWith("$")) {
-              const len = parseInt(line.slice(1), 10);
-              if (len === -1) { responses.push(null); i++; }
-              else { responses.push(lines[i+1] || ""); i += 2; }
-            } else { i++; }
-          }
-          const result = responses[responses.length - 1];
-          if (result === null) process.stdout.write("__NULL__");
-          else if (typeof result === "string" && result.startsWith("-")) process.stdout.write("__ERR__" + result);
-          else process.stdout.write(String(result ?? "__NULL__"));
-        });
-        sock.on("error", (err) => {
-          process.stderr.write(err.message);
+      (async () => {
+        try {
+          const redis = require("redis");
+          const clientOpts = useUrl
+            ? { url }
+            : { socket: { host, port }, password: password || undefined, database: db };
+          const client = redis.createClient(clientOpts);
+          client.on("error", () => {});
+          await client.connect();
+          const cmd = args[0].toUpperCase();
+          let result;
+          if (cmd === "GET") result = await client.get(args[1]);
+          else if (cmd === "SET") result = await client.set(args[1], args[2]);
+          else if (cmd === "SETEX") result = await client.setEx(args[1], parseInt(args[2], 10), args[3]);
+          else if (cmd === "DEL") result = await client.del(args[1]);
+          await client.quit();
+          const out = (result === null || result === undefined) ? "__NULL__" : String(result);
+          process.stdout.write(out, () => process.exit(0));
+        } catch (err) {
+          process.stderr.write(String((err && err.message) || err));
           process.exit(1);
-        });
-        setTimeout(() => { sock.destroy(); process.exit(1); }, 3000);
-      }
+        }
+      })();
     `;
-
     let result: string;
     try {
       result = execFileSync(process.execPath, ["-e", script], {
@@ -210,15 +171,9 @@ export class RedisNpmSessionHandler implements SessionHandler {
         stdio: ["pipe", "pipe", "pipe"],
       });
     } catch (err) {
-      // Non-zero exit = the child hit a socket error / AUTH failure / timeout.
-      // That is a transport FAILURE, not a key miss — surface it so the
-      // Session boundary logs + degrades (or re-throws under strict mode).
       throw new Error(`Redis command failed: ${(err as Error).message}`);
     }
-    if (result === "__NULL__") return "";        // genuine key miss
-    if (result.startsWith("__ERR__")) {
-      throw new Error(`Redis error: ${result.slice("__ERR__".length)}`);
-    }
+    if (result === "__NULL__") return "";       // genuine key miss
     return result;
   }
 

package/packages/core/src/sessionHandlers/respClient.ts

@@ -0,0 +1,171 @@
+/**
+ * Tina4 synchronous RESP transport — shared by every Redis/Valkey session handler.
+ *
+ * The session-handler interface is synchronous, but node:net is async-only, so a
+ * command runs in a short-lived `node -e` child (execFileSync) that blocks the
+ * caller until it exits. This module is the ONE correct implementation of that
+ * child; the Redis/Valkey handlers delegate here instead of inlining their own.
+ *
+ * The bug this replaces: the old child parsed the reply on the socket "end" event.
+ * Redis/Valkey keep the connection OPEN after a reply (they never half-close for a
+ * GET/SET/DEL), so "end" never fires — the child waited out its timeout, exited
+ * non-zero, and execFileSync re-threw it as a "transport failure". EVERY command
+ * failed against a reachable server. Here the child parses replies INCREMENTALLY on
+ * the "data" event (the same proven RESP parser cache.ts's RespClient uses): it
+ * reads exactly the replies it sent commands for (AUTH? + SELECT? + the command),
+ * then returns the LAST (command) reply.
+ */
+import { execFileSync } from "node:child_process";
+
+export interface RespTarget {
+  host: string;
+  port: number;
+  /** AUTH password (empty/undefined = no AUTH sent). */
+  password?: string;
+  /** SELECT db index (0/undefined = no SELECT sent). */
+  db?: number;
+}
+
+/**
+ * Run a single RESP command synchronously against host:port and return the reply.
+ *
+ * - A genuine nil / key-miss returns `""` (callers treat "" as "no session yet").
+ * - A transport FAILURE (server unreachable, timeout, connection closed before a
+ *   reply) THROWS `<label> command failed: ...`.
+ * - A RESP error reply — including a rejected AUTH/SELECT handshake — THROWS
+ *   `<label> error: ...`. A rejected handshake is a transport failure, not a
+ *   result, so it is surfaced ahead of the command reply.
+ *
+ * Session values are JSON strings (they start with `{`), so they never collide
+ * with the `__NULL__` / `__ERR__` sentinels the child uses on stdout.
+ */
+export function respCommandSync(target: RespTarget, args: string[], label = "Redis"): string {
+  const host = target.host;
+  const port = target.port;
+  const password = target.password ?? "";
+  const db = target.db ?? 0;
+
+  const script = `
+    const net = require("node:net");
+    const host = ${JSON.stringify(host)};
+    const port = ${port};
+    const password = ${JSON.stringify(password)};
+    const db = ${db};
+    const args = ${JSON.stringify(args)};
+    // Replies to consume = AUTH? + SELECT? + the command. The LAST is our result.
+    const expected = (password ? 1 : 0) + (db !== 0 ? 1 : 0) + 1;
+
+    function encode(a) {
+      let c = "*" + a.length + "\\r\\n";
+      for (const s of a) c += "$" + Buffer.byteLength(s) + "\\r\\n" + s + "\\r\\n";
+      return c;
+    }
+
+    // Parse one RESP value at offset. Returns { value, next } or null if more bytes
+    // are needed (so a bulk string split across TCP chunks is handled correctly).
+    function parse(buf, off) {
+      if (off >= buf.length) return null;
+      const type = buf[off];
+      const crlf = buf.indexOf("\\r\\n", off + 1, "utf-8");
+      if (crlf === -1) return null;
+      const line = buf.toString("utf-8", off + 1, crlf);
+      const after = crlf + 2;
+      if (type === 0x2b) return { value: line, next: after };             // '+' simple string
+      if (type === 0x3a) return { value: line, next: after };             // ':' integer
+      if (type === 0x2d) return { value: { __err: line }, next: after };  // '-' error
+      if (type === 0x24) {                                                // '$' bulk string
+        const len = parseInt(line, 10);
+        if (len === -1) return { value: null, next: after };
+        if (after + len + 2 > buf.length) return null;
+        return { value: buf.toString("utf-8", after, after + len), next: after + len + 2 };
+      }
+      if (type === 0x2a) {                                                // '*' array
+        const count = parseInt(line, 10);
+        if (count === -1) return { value: null, next: after };
+        const arr = [];
+        let pos = after;
+        for (let i = 0; i < count; i++) {
+          const el = parse(buf, pos);
+          if (!el) return null;
+          arr.push(el.value);
+          pos = el.next;
+        }
+        return { value: arr, next: pos };
+      }
+      return { value: line, next: after };
+    }
+
+    const sock = net.createConnection({ host, port });
+    sock.setNoDelay(true);
+    let buffer = Buffer.alloc(0);
+    const replies = [];
+    let done = false;
+    const timer = setTimeout(() => { if (!done) { done = true; try { sock.destroy(); } catch (e) {} process.stderr.write("timeout"); process.exitCode = 1; } }, 3000);
+
+    function emit(s) {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      // The write callback guarantees stdout is flushed before exit (a bare
+      // process.exit can truncate piped stdout).
+      process.stdout.write(s, () => { try { sock.destroy(); } catch (e) {} });
+    }
+    function fail(msg) {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try { sock.destroy(); } catch (e) {}
+      process.stderr.write(msg || "");
+      process.exitCode = 1;
+    }
+
+    sock.on("connect", () => {
+      let cmds = "";
+      if (password) cmds += encode(["AUTH", password]);
+      if (db !== 0) cmds += encode(["SELECT", String(db)]);
+      cmds += encode(args);
+      sock.write(cmds);
+    });
+    sock.on("data", (chunk) => {
+      buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+      while (true) {
+        const p = parse(buffer, 0);
+        if (!p) break;
+        buffer = buffer.subarray(p.next);
+        replies.push(p.value);
+        if (replies.length < expected) continue;
+        // A rejected AUTH/SELECT is a transport failure — surface it first.
+        for (let i = 0; i < expected - 1; i++) {
+          const r = replies[i];
+          if (r && typeof r === "object" && r.__err !== undefined) { emit("__ERR__" + r.__err); return; }
+        }
+        const result = replies[expected - 1];
+        if (result && typeof result === "object" && result.__err !== undefined) emit("__ERR__" + result.__err);
+        else if (result === null || result === undefined) emit("__NULL__");
+        else emit(String(result));
+        return;
+      }
+    });
+    sock.on("error", (err) => fail(err.message));
+    sock.on("close", () => { if (!done) fail("connection closed before reply"); });
+  `;
+
+  let result: string;
+  try {
+    result = execFileSync(process.execPath, ["-e", script], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (err) {
+    // Non-zero exit = socket error / timeout / closed connection: a transport
+    // FAILURE, not a key miss. Surface it so the Session boundary logs + degrades
+    // (or re-throws under strict mode).
+    throw new Error(`${label} command failed: ${(err as Error).message}`);
+  }
+  if (result === "__NULL__") return "";       // genuine key miss
+  if (result.startsWith("__ERR__")) {
+    throw new Error(`${label} error: ${result.slice("__ERR__".length)}`);
+  }
+  return result;
+}