tina4-nodejs 3.13.43 → 3.13.45

package/packages/core/src/queueBackends/rabbitmqBackend.ts

@@ -242,6 +242,8 @@ export class RabbitMQBackend implements QueueBackend {
       let buffer = Buffer.alloc(0);
       let step = "handshake";
       let deliveryTag = null;
+      let expectedBody = 0;
+      let receivedBody = 0;
 
       sock.on("data", (chunk) => {
         buffer = Buffer.concat([buffer, chunk]);
@@ -264,11 +266,29 @@ export class RabbitMQBackend implements QueueBackend {
             const methodId = payload.readUInt16BE(2);
             handleMethod(classId, methodId, payload.subarray(4), channel);
           } else if (frameType === 2) { // HEADER frame
-            // Content header — skip for basic.get
+            // Content header — capture the declared body size so we know when the
+            // body is complete (a body may arrive in several frames).
+            if (operation === "get") {
+              // body-size is a 64-bit field at offset 4 of the header payload;
+              // the low 32 bits are enough for our JSON payloads.
+              expectedBody = payload.readUInt32BE(8);
+              receivedBody = 0;
+            }
           } else if (frameType === 3) { // BODY frame
             // Content body
             const body = payload.toString("utf-8");
             process.stdout.write(body);
+            if (operation === "get") {
+              receivedBody += payload.length;
+              // Once the whole body has arrived, cleanly close the connection so
+              // the child exits 0 with the body on stdout. Without this the get
+              // handler fell through to the 10s watchdog (exit 1), so pop()
+              // always saw a failed child and returned null even though the
+              // message body had been written to stdout.
+              if (receivedBody >= expectedBody) {
+                closeConnection();
+              }
+            }
           }
         }
       }
@@ -310,11 +330,29 @@ export class RabbitMQBackend implements QueueBackend {
           sendMethod(0, 10, 11, payload.subarray(0, offset));
         }
         else if (classId === 10 && methodId === 30) {
-          // Connection.Tune → send Connection.Tune-Ok + Connection.Open
-          const tuneOk = Buffer.alloc(12);
-          tuneOk.writeUInt16BE(0, 0);     // channel-max
-          tuneOk.writeUInt32BE(131072, 2); // frame-max
-          tuneOk.writeUInt16BE(60, 6);     // heartbeat
+          // Connection.Tune → send Connection.Tune-Ok + Connection.Open.
+          // AMQP 0-9-1 requires TuneOk values to NOT exceed the server's proposal.
+          // The broker's Tune args are channel-max:short, frame-max:long,
+          // heartbeat:short. Hardcoding channel-max=0 means "no limit", which
+          // RabbitMQ treats as exceeding its proposed channel-max (e.g. 2047) and
+          // it aborts the connection right after Open — so negotiate instead.
+          const desiredFrameMax = 131072;
+          const desiredHeartbeat = 60;
+          const serverChannelMax = args.length >= 2 ? args.readUInt16BE(0) : 0;
+          const serverFrameMax = args.length >= 6 ? args.readUInt32BE(2) : 0;
+          const serverHeartbeat = args.length >= 8 ? args.readUInt16BE(6) : 0;
+
+          // channel-max: echo the server's value (its cap); 0 = unlimited.
+          const channelMax = serverChannelMax;
+          // frame-max: min(desired, server), treating 0 as unlimited on either side.
+          const frameMax = serverFrameMax === 0 ? desiredFrameMax : Math.min(desiredFrameMax, serverFrameMax);
+          // heartbeat: our choice, clamped to the server's if it proposed a non-zero one.
+          const heartbeat = serverHeartbeat === 0 ? desiredHeartbeat : Math.min(desiredHeartbeat, serverHeartbeat);
+
+          const tuneOk = Buffer.alloc(8);
+          tuneOk.writeUInt16BE(channelMax, 0); // channel-max (negotiated)
+          tuneOk.writeUInt32BE(frameMax, 2);   // frame-max (negotiated)
+          tuneOk.writeUInt16BE(heartbeat, 6);  // heartbeat (negotiated)
           sendMethod(0, 10, 31, tuneOk);
 
           // Connection.Open
@@ -334,8 +372,13 @@ export class RabbitMQBackend implements QueueBackend {
         }
         else if (classId === 20 && methodId === 11) {
           // Channel.Open-Ok → declare queue
+          // Payload: reserved(2) + queue short-string(1 + len) + flags(1) +
+          // arguments empty-table(4) = 8 + len bytes. (Was 7 + len, which
+          // overflowed the 4-byte empty-table write at offset 4 + len and threw
+          // ERR_OUT_OF_RANGE — swallowed by the catch, so publish/get/size all
+          // silently failed even once the handshake succeeded.)
           const qBuf = Buffer.from(queueName, "utf-8");
-          const declPayload = Buffer.alloc(7 + qBuf.length);
+          const declPayload = Buffer.alloc(8 + qBuf.length);
           declPayload.writeUInt16BE(0, 0); // reserved
           declPayload.writeUInt8(qBuf.length, 2);
           qBuf.copy(declPayload, 3);
@@ -357,25 +400,21 @@ export class RabbitMQBackend implements QueueBackend {
 
             sendMethod(1, 60, 40, pubPayload);
 
-            // Content header
+            // Content header frame. AMQP 0-9-1 content header body is:
+            // class-id(2) + weight(2) + body-size(8) + property-flags(2), then
+            // one entry per set property flag. With property-flags = 0 (no
+            // properties) the header is EXACTLY 14 bytes. The previous code
+            // allocated 14 + 1 + ct.length + 1 = 32 bytes but only wrote the
+            // first 14, leaving 18 trailing zero bytes that the broker parsed as
+            // bogus property data — it replied INTERNAL_ERROR (541) and closed
+            // the connection, so no message was ever stored. Allocate exactly 14.
             const bodyBuf = Buffer.from(data, "utf-8");
-            const header = Buffer.alloc(18);
-            header.writeUInt16BE(60, 0); // class = basic
-            header.writeUInt16BE(0, 2);  // weight
-            // body size (64-bit, we only use lower 32)
-            header.writeUInt32BE(0, 4);
-            header.writeUInt32BE(bodyBuf.length, 8);
-            header.writeUInt16BE(0x6000, 12); // property flags: delivery-mode + content-type
-            // content-type
-            const ct = Buffer.from("application/json");
-            header.writeUInt8(ct.length, 14);
-
-            const fullHeader = Buffer.alloc(14 + 1 + ct.length + 1);
-            fullHeader.writeUInt16BE(60, 0);
-            fullHeader.writeUInt16BE(0, 2);
-            fullHeader.writeUInt32BE(0, 4);
-            fullHeader.writeUInt32BE(bodyBuf.length, 8);
-            fullHeader.writeUInt16BE(0x0000, 12); // no properties for simplicity
+            const fullHeader = Buffer.alloc(14);
+            fullHeader.writeUInt16BE(60, 0);          // class = basic
+            fullHeader.writeUInt16BE(0, 2);           // weight
+            fullHeader.writeUInt32BE(0, 4);           // body-size high 32 bits
+            fullHeader.writeUInt32BE(bodyBuf.length, 8); // body-size low 32 bits
+            fullHeader.writeUInt16BE(0x0000, 12);     // property flags: none set
 
             // Send header frame
             const hFrame = Buffer.alloc(7 + fullHeader.length + 1);
@@ -440,9 +479,21 @@ export class RabbitMQBackend implements QueueBackend {
           closeConnection();
         }
         else if (classId === 10 && methodId === 50) {
-          // Connection.Close → send Connection.Close-Ok
+          // Connection.Close (server-initiated, e.g. a channel/protocol error)
+          // → send Connection.Close-Ok and exit non-zero so the caller sees the
+          // failure rather than a half-completed operation.
           sendMethod(0, 10, 51, Buffer.alloc(0));
           sock.destroy();
+          process.exit(1);
+        }
+        else if (classId === 10 && methodId === 51) {
+          // Connection.Close-Ok — the broker has acknowledged our Close, which
+          // means it has fully processed everything we sent (incl. a Basic.Publish
+          // and its content frames). Only now is it safe to drop the socket. The
+          // previous code destroyed the socket on a blind 200ms timer right after
+          // writing the body frame, racing the broker and dropping the message.
+          sock.destroy();
+          process.exit(0);
         }
       }
 
@@ -482,14 +533,26 @@ export class RabbitMQBackend implements QueueBackend {
       }
 
       function closeConnection() {
-        // Send Connection.Close
-        const closePayload = Buffer.alloc(6);
+        // Send Connection.Close — payload is reply-code(2) + reply-text
+        // short-string(1 + 0) + class-id(2) + method-id(2) = 7 bytes. (Was
+        // Buffer.alloc(6), so the method-id write at offset 5 overflowed and
+        // threw ERR_OUT_OF_RANGE right after "__PUBLISHED__" was written —
+        // swallowed by the parent catch, so push() reported "publish failed"
+        // even though the message had already reached the broker.)
+        const closePayload = Buffer.alloc(7);
         closePayload.writeUInt16BE(200, 0); // reply code
-        closePayload.writeUInt8(0, 2); // reply text (empty)
+        closePayload.writeUInt8(0, 2); // reply text (empty short-string)
         closePayload.writeUInt16BE(0, 3); // class
         closePayload.writeUInt16BE(0, 5); // method
         sendMethod(0, 10, 50, closePayload);
-        setTimeout(() => sock.destroy(), 500);
+        // Do NOT destroy the socket here — wait for the broker's
+        // Connection.Close-Ok (10/51), which confirms it has fully processed
+        // everything we sent (the Basic.Publish + content frames in particular).
+        // The 10/51 handler exits 0. This safety net only fires if the broker
+        // never replies, and still exits 0 because stdout already carries the
+        // operation's result (the message was flushed to the socket before
+        // Close was sent).
+        setTimeout(() => { sock.destroy(); process.exit(0); }, 3000).unref();
       }
 
       sock.on("error", (err) => {
@@ -497,7 +560,10 @@ export class RabbitMQBackend implements QueueBackend {
         process.exit(1);
       });
 
-      setTimeout(() => { sock.destroy(); process.exit(1); }, 10000);
+      // Watchdog: only fires if an operation never completes (handshake hangs).
+      // unref() so a completed operation's pending timer can't keep the event
+      // loop alive and delay/override the clean exit above.
+      setTimeout(() => { sock.destroy(); process.exit(1); }, 10000).unref();
     `;
 
     try {

package/packages/core/src/server.ts

@@ -937,8 +937,13 @@ ${reset}
           console.log(`    \x1b[35m${definition.tableName}\x1b[0m (${Object.keys(definition.fields).length} fields)`);
         }
 
-        // Generate auto-CRUD routes for all discovered models
-        const crudRoutes = orm.generateCrudRoutes(models);
+        // Generate auto-CRUD routes ONLY for models that explicitly opted in via
+        // `static autoCrud = true` (the documented opt-in gate; default false). The
+        // server previously generated the 5 CRUD endpoints for every discovered model
+        // regardless of the flag, contradicting the documented contract. (Python's
+        // AutoCrud is opt-in too — via an explicit AutoCrud.register/discover call.)
+        const crudModels = orm.crudEligibleModels(models);
+        const crudRoutes = crudModels.length > 0 ? orm.generateCrudRoutes(crudModels) : [];
         for (const route of crudRoutes) {
           // Only add if no file-based route already handles this
           const existing = router.match(route.method, route.pattern.replace(/\{(\w+)\}/g, "test").replace(/\[(\w+)\]/g, "test"));
@@ -947,9 +952,11 @@ ${reset}
           }
         }
 
-        console.log(`\n  Auto-CRUD endpoints:`);
-        for (const route of crudRoutes) {
-          console.log(`    \x1b[33m${route.method.padEnd(7)}\x1b[0m ${route.pattern}`);
+        if (crudRoutes.length > 0) {
+          console.log(`\n  Auto-CRUD endpoints:`);
+          for (const route of crudRoutes) {
+            console.log(`    \x1b[33m${route.method.padEnd(7)}\x1b[0m ${route.pattern}`);
+          }
         }
       }
     } catch (err) {

package/packages/core/src/session.ts

@@ -27,9 +27,9 @@
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { execFileSync } from "node:child_process";
 import { Log } from "./logger.js";
 import { isTruthy } from "./dotenv.js";
+import { respCommandSync } from "./sessionHandlers/respClient.js";
 import { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
 import { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
 import { MongoSessionHandler } from "./sessionHandlers/mongoHandler.js";
@@ -196,103 +196,19 @@ export class RedisSessionHandler implements SessionHandler {
   }
 
   /**
-   * Execute a Redis command synchronously via a short-lived TCP connection.
+   * Execute a Redis command synchronously against the live server.
    *
-   * 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.
+   * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
+   * yields `""`, and 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). Backend-failure parity.
    */
   private execSync(args: string[]): string {
-    const script = `
-      const net = require("node:net");
-      const host = ${JSON.stringify(this.host)};
-      const port = ${this.port};
-      const password = ${JSON.stringify(this.password)};
-      const db = ${this.db};
-      const args = ${JSON.stringify(args)};
-
-      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;
-      }
-
-      function parseResp(buf) {
-        const str = buf.toString("utf-8");
-        if (str.startsWith("+")) return str.slice(1).split("\\r\\n")[0];
-        if (str.startsWith("-")) return "ERR:" + str.slice(1).split("\\r\\n")[0];
-        if (str.startsWith(":")) return str.slice(1).split("\\r\\n")[0];
-        if (str.startsWith("$-1")) return null;
-        if (str.startsWith("$")) {
-          const nl = str.indexOf("\\r\\n");
-          const len = parseInt(str.slice(1, nl), 10);
-          const start = nl + 2;
-          return str.slice(start, start + len);
-        }
-        return str;
-      }
-
-      const sock = net.createConnection({ host, port }, () => {
-        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", () => {
-        // Parse last response (skip AUTH/SELECT responses)
-        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++; }
-        }
-        // The last response is our actual command result
-        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);
-        process.exit(1);
-      });
-      setTimeout(() => { sock.destroy(); process.exit(1); }, 3000);
-    `;
-
-    let result: string;
-    try {
-      result = execFileSync(process.execPath, ["-e", script], {
-        encoding: "utf-8",
-        timeout: 5000,
-        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)}`);
-    }
-    return result;
+    return respCommandSync(
+      { host: this.host, port: this.port, password: this.password, db: this.db },
+      args,
+      "Redis",
+    );
   }
 
   private key(sessionId: string): string {

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

@@ -0,0 +1,238 @@
+/**
+ * Tina4 synchronous MongoDB transport — used by the MongoDB session handler.
+ *
+ * The session-handler interface is synchronous, but every Mongo client is async,
+ * so a command runs in a short-lived `node -e` child (execFileSync) that blocks
+ * the caller until it exits. Two transports, mirroring the Python master's
+ * pymongo-first design:
+ *
+ *   1. The official `mongodb` driver when it resolves (robust, the normal path —
+ *      @tina4/orm depends on it, so it is present in any app that uses the ORM).
+ *   2. A raw MongoDB wire-protocol (OP_MSG) fallback over node:net with a minimal
+ *      BSON codec — zero dependencies.
+ *
+ * The bugs this replaces (raw path): the old encoder put `$db` FIRST in the command
+ * document, so the server read `$db` as the command name and answered
+ * CommandNotFound; doubles were written big-endian; arrays/booleans were not encoded
+ * at all (so `updates: [{... upsert: true}]` was malformed); and the response was
+ * "parsed" by regex-matching `"data":{...}` against binary BSON, which can never
+ * match. Here the command name comes first and `$db` last (matching the Python
+ * master), the BSON codec is little-endian and handles every type the commands use,
+ * and the OP_MSG response is decoded properly (cursor.firstBatch for find, `ok` for
+ * writes).
+ */
+import { execFileSync } from "node:child_process";
+
+export interface MongoTarget {
+  host: string;
+  port: number;
+  database: string;
+  collection: string;
+}
+
+/** Command args: `filter` (always), plus `data`/`last_accessed` for an update. */
+export interface MongoCommandArgs {
+  filter: Record<string, unknown>;
+  data?: unknown;
+  last_accessed?: number;
+}
+
+/**
+ * Run a session Mongo command synchronously and return the raw child stdout.
+ *
+ * - command "find"   -> the matched document as a JSON string, or "__EMPTY__".
+ * - command "update" -> "__OK__" (upsert of `{_id, data, last_accessed}`).
+ * - command "delete" -> "__OK__".
+ *
+ * THROWS `<label> command failed: ...` on a transport failure (server unreachable,
+ * timeout) OR a Mongo command error (`ok != 1`), so the Session boundary can
+ * log-loud + degrade (or re-throw under strict mode).
+ */
+export function mongoCommandSync(
+  target: MongoTarget,
+  command: "find" | "update" | "delete",
+  args: MongoCommandArgs,
+  label = "MongoDB",
+): string {
+  const script = `
+    const net = require("node:net");
+    const host = ${JSON.stringify(target.host)};
+    const port = ${target.port};
+    const database = ${JSON.stringify(target.database)};
+    const collection = ${JSON.stringify(target.collection)};
+    const command = ${JSON.stringify(command)};
+    const args = ${JSON.stringify(args)};
+
+    // ── driver path (preferred — matches the Python master's pymongo-first) ──
+    let hasDriver = false;
+    try { require.resolve("mongodb"); hasDriver = true; } catch (e) {}
+
+    if (hasDriver) {
+      (async () => {
+        let client;
+        try {
+          const { MongoClient } = require("mongodb");
+          client = new MongoClient("mongodb://" + host + ":" + port, { serverSelectionTimeoutMS: 4000 });
+          await client.connect();
+          const coll = client.db(database).collection(collection);
+          let out;
+          if (command === "find") {
+            const doc = await coll.findOne(args.filter);
+            out = doc ? JSON.stringify(doc) : "__EMPTY__";
+          } else if (command === "update") {
+            await coll.updateOne(args.filter, { $set: { data: args.data, last_accessed: args.last_accessed } }, { upsert: true });
+            out = "__OK__";
+          } else {
+            await coll.deleteOne(args.filter);
+            out = "__OK__";
+          }
+          await client.close();
+          process.stdout.write(out, () => process.exit(0));
+        } catch (err) {
+          try { if (client) await client.close(); } catch (e) {}
+          process.stderr.write(String((err && err.message) || err));
+          process.exit(1);
+        }
+      })();
+    } else {
+
+    // ── raw OP_MSG fallback (zero-dep, mirrors the Python master codec) ──
+    function encElem(key, value) {
+      const ck = Buffer.concat([Buffer.from(key, "utf-8"), Buffer.from([0])]);
+      if (value === null || value === undefined) return Buffer.concat([Buffer.from([0x0a]), ck]);
+      if (typeof value === "boolean") return Buffer.concat([Buffer.from([0x08]), ck, Buffer.from([value ? 1 : 0])]);
+      if (typeof value === "number") {
+        if (Number.isInteger(value) && value >= -2147483648 && value <= 2147483647) {
+          const b = Buffer.alloc(4); b.writeInt32LE(value, 0);
+          return Buffer.concat([Buffer.from([0x10]), ck, b]);
+        }
+        if (Number.isInteger(value)) {
+          const b = Buffer.alloc(8); b.writeBigInt64LE(BigInt(value), 0);
+          return Buffer.concat([Buffer.from([0x12]), ck, b]);
+        }
+        const b = Buffer.alloc(8); b.writeDoubleLE(value, 0);
+        return Buffer.concat([Buffer.from([0x01]), ck, b]);
+      }
+      if (typeof value === "string") {
+        const s = Buffer.from(value, "utf-8");
+        const len = Buffer.alloc(4); len.writeInt32LE(s.length + 1, 0);
+        return Buffer.concat([Buffer.from([0x02]), ck, len, s, Buffer.from([0])]);
+      }
+      if (Array.isArray(value)) {
+        const indexed = {};
+        value.forEach((v, i) => { indexed[String(i)] = v; });
+        return Buffer.concat([Buffer.from([0x04]), ck, encDoc(indexed)]);
+      }
+      if (typeof value === "object") return Buffer.concat([Buffer.from([0x03]), ck, encDoc(value)]);
+      const s = Buffer.from(String(value), "utf-8");
+      const len = Buffer.alloc(4); len.writeInt32LE(s.length + 1, 0);
+      return Buffer.concat([Buffer.from([0x02]), ck, len, s, Buffer.from([0])]);
+    }
+    function encDoc(obj) {
+      let body = Buffer.alloc(0);
+      for (const k of Object.keys(obj)) body = Buffer.concat([body, encElem(k, obj[k])]);
+      body = Buffer.concat([body, Buffer.from([0])]);
+      const out = Buffer.alloc(4 + body.length);
+      out.writeInt32LE(out.length, 0);
+      body.copy(out, 4);
+      return out;
+    }
+    function decDoc(buf, pos) {
+      const docLen = buf.readInt32LE(pos.i); pos.i += 4;
+      const end = pos.i + docLen - 5;
+      const doc = {};
+      while (pos.i < end) {
+        const type = buf[pos.i]; pos.i += 1;
+        const keyEnd = buf.indexOf(0, pos.i);
+        const key = buf.toString("utf-8", pos.i, keyEnd);
+        pos.i = keyEnd + 1;
+        doc[key] = decVal(buf, pos, type, end);
+      }
+      pos.i += 1;
+      return doc;
+    }
+    function decVal(buf, pos, type, end) {
+      if (type === 0x01) { const v = buf.readDoubleLE(pos.i); pos.i += 8; return v; }
+      if (type === 0x02) { const len = buf.readInt32LE(pos.i); pos.i += 4; const v = buf.toString("utf-8", pos.i, pos.i + len - 1); pos.i += len; return v; }
+      if (type === 0x03) return decDoc(buf, pos);
+      if (type === 0x04) { const d = decDoc(buf, pos); return Object.keys(d).map((k) => d[k]); }
+      if (type === 0x05) { const len = buf.readInt32LE(pos.i); pos.i += 4; pos.i += 1; const v = buf.subarray(pos.i, pos.i + len); pos.i += len; return v; }
+      if (type === 0x07) { const v = buf.toString("hex", pos.i, pos.i + 12); pos.i += 12; return v; }
+      if (type === 0x08) { const v = buf[pos.i] !== 0; pos.i += 1; return v; }
+      if (type === 0x09) { const v = Number(buf.readBigInt64LE(pos.i)); pos.i += 8; return v; }
+      if (type === 0x0a) return null;
+      if (type === 0x10) { const v = buf.readInt32LE(pos.i); pos.i += 4; return v; }
+      if (type === 0x11) { const v = Number(buf.readBigUInt64LE(pos.i)); pos.i += 8; return v; }
+      if (type === 0x12) { const v = Number(buf.readBigInt64LE(pos.i)); pos.i += 8; return v; }
+      // Unknown type: cannot size it — stop at the document boundary to avoid a loop.
+      pos.i = end;
+      return null;
+    }
+
+    let cmdDoc;
+    if (command === "find") {
+      cmdDoc = { find: collection, filter: args.filter, limit: 1, "$db": database };
+    } else if (command === "update") {
+      const u = { _id: args.filter._id, data: args.data, last_accessed: args.last_accessed };
+      cmdDoc = { update: collection, updates: [{ q: args.filter, u: u, upsert: true }], "$db": database };
+    } else {
+      cmdDoc = { delete: collection, deletes: [{ q: args.filter, limit: 1 }], "$db": database };
+    }
+
+    const bodyDoc = encDoc(cmdDoc);
+    const section = Buffer.concat([Buffer.from([0]), bodyDoc]); // section kind 0 = body
+    const flags = Buffer.alloc(4);                              // flagBits = 0
+    const payload = Buffer.concat([flags, section]);
+    const header = Buffer.alloc(16);
+    header.writeInt32LE(16 + payload.length, 0);                // messageLength
+    header.writeInt32LE(1, 4);                                  // requestID
+    header.writeInt32LE(0, 8);                                  // responseTo
+    header.writeInt32LE(2013, 12);                              // opCode = OP_MSG
+    const message = Buffer.concat([header, payload]);
+
+    const sock = net.createConnection({ host, port });
+    sock.setNoDelay(true);
+    let buffer = Buffer.alloc(0);
+    let done = false;
+    const timer = setTimeout(() => { if (!done) { done = true; try { sock.destroy(); } catch (e) {} process.stderr.write("timeout"); process.exitCode = 1; } }, 5000);
+    function emit(s) {
+      if (done) return; done = true; clearTimeout(timer);
+      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", () => sock.write(message));
+    sock.on("data", (chunk) => {
+      buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+      if (buffer.length < 4) return;
+      const msgLen = buffer.readInt32LE(0);
+      if (buffer.length < msgLen) return;
+      let doc;
+      try { doc = decDoc(buffer, { i: 21 }); } catch (e) { fail("decode error: " + e.message); return; }
+      const ok = doc && (doc.ok === 1 || doc.ok === 1.0);
+      if (!ok) { fail("command error: " + ((doc && doc.errmsg) || JSON.stringify(doc))); return; }
+      if (command === "find") {
+        const batch = (doc.cursor && doc.cursor.firstBatch) || [];
+        emit(batch.length ? JSON.stringify(batch[0]) : "__EMPTY__");
+      } else {
+        emit("__OK__");
+      }
+    });
+    sock.on("error", (err) => fail(err.message));
+    sock.on("close", () => { if (!done) fail("connection closed before reply"); });
+    }
+  `;
+
+  try {
+    return execFileSync(process.execPath, ["-e", script], {
+      encoding: "utf-8",
+      timeout: 8000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (err) {
+    throw new Error(`${label} command failed: ${(err as Error).message}`);
+  }
+}