@frogfish/k2db 2.0.6 → 3.0.1

package/{dist/db.js → db.js}

@@ -1,14 +1,161 @@
 // src/db.ts
-import { K2Error, ServiceError } from "@frogfish/k2error"; // Keep the existing error structure
+import { K2Error, ServiceError, wrap } from "@frogfish/k2error"; // Keep the existing error structure
 import { MongoClient, } from "mongodb";
-import { v4 as uuidv4 } from "uuid";
-import debugLib from "debug";
+import { randomBytes, createHash } from "crypto";
+// import debugLib from "debug";
+import { Topic } from '@frogfish/ratatouille';
 import { z } from "zod";
-const debug = debugLib("k2:db");
+// const debug = debugLib("k2:db");
+const debug = Topic('k2db#random');
+function _hashSecret(secret) {
+    return createHash("sha256").update(secret).digest("hex");
+}
+// ---- Shared MongoClient pool (per cluster+auth), reused across DB names ----
+const _clientByKey = new Map();
+const _connectingByKey = new Map();
+const _refCountByKey = new Map();
+function _hostsKey(hosts) {
+    const hs = hosts ?? [];
+    return hs
+        .map((h) => `${h.host}:${h.port ?? ""}`)
+        .sort()
+        .join(",");
+}
+/**
+ * Cache key for a MongoClient pool. Intentionally excludes `conf.name` (db name),
+ * so multiple DBs share the same connection pool.
+ */
+function _clientCacheKey(conf) {
+    const user = conf.user ?? "";
+    const pass = conf.password ?? "";
+    const passKey = pass ? `sha256:${_hashSecret(pass)}` : "";
+    const authSource = user && pass ? (conf.authSource ?? "admin") : "";
+    const rs = conf.replicaset ?? "";
+    const hosts = _hostsKey(conf.hosts);
+    return `hosts=${hosts}|user=${user}|pass=${passKey}|authSource=${authSource}|rs=${rs}`;
+}
+async function _acquireClient(key, uri, options) {
+    const existing = _clientByKey.get(key);
+    if (existing)
+        return existing;
+    const inflight = _connectingByKey.get(key);
+    if (inflight)
+        return inflight;
+    const p = MongoClient.connect(uri, options)
+        .then((client) => {
+        _clientByKey.set(key, client);
+        _connectingByKey.delete(key);
+        return client;
+    })
+        .catch((err) => {
+        _connectingByKey.delete(key);
+        throw err;
+    });
+    _connectingByKey.set(key, p);
+    return p;
+}
+function _increfClient(key) {
+    _refCountByKey.set(key, (_refCountByKey.get(key) ?? 0) + 1);
+}
+async function _decrefClient(key) {
+    const next = (_refCountByKey.get(key) ?? 0) - 1;
+    if (next <= 0) {
+        _refCountByKey.delete(key);
+        const client = _clientByKey.get(key);
+        if (client) {
+            _clientByKey.delete(key);
+            try {
+                await client.close();
+            }
+            catch (err) {
+                // Best-effort shutdown: never throw from release/close paths.
+                debug(`MongoClient close failed for key=${key}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return;
+    }
+    _refCountByKey.set(key, next);
+}
+// ---- End shared MongoClient pool helpers ----
+// Crockford Base32 alphabet (no I, L, O, U)
+const CROCKFORD32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * Generates a UUIDv7 (time-ordered) and encodes it as Crockford Base32 with hyphens.
+ * Format: 26 base32 chars grouped as 8-4-4-4-6 (total 26)
+ */
+function uuidv7Base32Hyphenated() {
+    // 1) Build UUIDv7 bytes
+    // Layout per RFC: time_low(32) | time_mid(16) | time_hi_and_version(16) | clock_seq(16) | node(48)
+    // Encode 60-bit ms timestamp across time_* fields, version 7, RFC4122 variant in clock_seq_hi.
+    const ts = BigInt(Date.now()); // milliseconds
+    const timeLow = Number((ts >> 28n) & 0xffffffffn);
+    const timeMid = Number((ts >> 12n) & 0xffffn);
+    const timeHi = Number(ts & 0xfffn); // lower 12 bits
+    const bytes = new Uint8Array(16);
+    // time_low (big-endian)
+    bytes[0] = (timeLow >>> 24) & 0xff;
+    bytes[1] = (timeLow >>> 16) & 0xff;
+    bytes[2] = (timeLow >>> 8) & 0xff;
+    bytes[3] = timeLow & 0xff;
+    // time_mid (big-endian)
+    bytes[4] = (timeMid >>> 8) & 0xff;
+    bytes[5] = timeMid & 0xff;
+    // time_high_and_version: version 7 in high nibble + top 4 bits of timeHi
+    bytes[6] = 0x70 | ((timeHi >>> 8) & 0x0f); // 0x7- version
+    bytes[7] = timeHi & 0xff;
+    // clock_seq + node: 8 random bytes; set RFC4122 variant (10xxxxxx)
+    const rnd = randomBytes(8);
+    bytes.set(rnd, 8);
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // set variant 10xxxxxx
+    // 2) Encode as Crockford Base32 (26 chars). 128 bits -> 26*5 bits (pad 2 high bits)
+    let value = 0n;
+    for (let i = 0; i < 16; i++) {
+        value = (value << 8n) | BigInt(bytes[i]);
+    }
+    value <<= 2n; // pad to 130 bits so we can take 26 groups cleanly
+    let encoded = "";
+    for (let i = 25; i >= 0; i--) {
+        const idx = Number((value >> BigInt(i * 5)) & 0x1fn);
+        encoded += CROCKFORD32[idx];
+    }
+    // 3) Insert hyphens in groups: 8-4-4-4-6
+    return (encoded.slice(0, 8) +
+        "-" +
+        encoded.slice(8, 12) +
+        "-" +
+        encoded.slice(12, 16) +
+        "-" +
+        encoded.slice(16, 20) +
+        "-" +
+        encoded.slice(20));
+}
+/**
+ * Test helper: fully reset the shared MongoClient pool.
+ *
+ * Not for production usage; intended for test runners to clean up
+ * between suites without restarting the process.
+ */
+export async function resetSharedMongoClientsForTests() {
+    const entries = Array.from(_clientByKey.entries());
+    for (const [key, client] of entries) {
+        try {
+            await client.close();
+        }
+        catch (err) {
+            debug(`MongoClient close failed during reset for key=${key}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    _clientByKey.clear();
+    _connectingByKey.clear();
+    _refCountByKey.clear();
+}
 export class K2DB {
     conf;
     db;
     connection;
+    clientKey;
+    initialized = false;
+    initPromise;
     schemas = new Map();
     constructor(conf) {
         this.conf = conf;
@@ -17,22 +164,41 @@ export class K2DB {
      * Initializes the MongoDB connection.
      */
     async init() {
-        // Build URI and options
-        const { uri, options } = this.buildMongoUri();
-        const dbName = this.conf.name;
-        // Mask sensitive information in logs
-        const safeConnectUrl = uri.replace(/\/\/.*?:.*?@/, "//*****:*****@");
-        debug(`Connecting to MongoDB: ${safeConnectUrl}`);
-        try {
-            // 8. Establish MongoDB connection
-            this.connection = await MongoClient.connect(uri, options);
-            this.db = this.connection.db(dbName);
-            debug("Successfully connected to MongoDB");
-        }
-        catch (err) {
-            // 9. Handle connection error
-            throw new K2Error(ServiceError.SYSTEM_ERROR, `Failed to connect to MongoDB: ${err.message}`, "sys_mdb_init", this.normalizeError(err));
-        }
+        if (this.initialized)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = (async () => {
+            // Build URI and options
+            const { uri, options } = this.buildMongoUri();
+            // Mask sensitive information in logs
+            const safeConnectUrl = uri.replace(/\/\/.*?:.*?@/, "//*****:*****@");
+            debug(`Connecting to MongoDB: ${safeConnectUrl}`);
+            try {
+                // Establish (or reuse) a shared MongoClient pool per cluster+auth (NOT per db name)
+                const key = _clientCacheKey(this.conf);
+                const client = await _acquireClient(key, uri, options);
+                this.connection = client;
+                this.db = this.connection.db(this.conf.name);
+                this.clientKey = key;
+                if (!this.initialized) {
+                    _increfClient(key);
+                    this.initialized = true;
+                }
+                debug("Successfully connected to MongoDB");
+            }
+            catch (err) {
+                // Handle connection error
+                const msg = err instanceof Error
+                    ? `Failed to connect to MongoDB: ${err.message}`
+                    : `Failed to connect to MongoDB: ${String(err)}`;
+                throw wrap(err, ServiceError.SERVICE_UNAVAILABLE, "sys_mdb_init", msg);
+            }
+        })().finally(() => {
+            // Allow retry after failure; once initialized, subsequent calls return early.
+            this.initPromise = undefined;
+        });
+        return this.initPromise;
     }
     /**
      * Build a robust MongoDB URI based on config (supports SRV and standard).
@@ -50,7 +216,7 @@ export class K2DB {
         let uri;
         if (useSrv) {
             const host = this.conf.hosts[0].host;
-            uri = `mongodb+srv://${auth}${host}/${dbName}?retryWrites=true&w=majority`;
+            uri = `mongodb+srv://${auth}${host}/?retryWrites=true&w=majority`;
         }
         else {
             const hostList = this.conf.hosts
@@ -59,11 +225,16 @@ export class K2DB {
             const params = ["retryWrites=true", "w=majority"];
             if (this.conf.replicaset)
                 params.push(`replicaSet=${this.conf.replicaset}`);
-            uri = `mongodb://${auth}${hostList}/${dbName}?${params.join("&")}`;
+            uri = `mongodb://${auth}${hostList}/?${params.join("&")}`;
         }
+        // Determine authSource based on user and password presence
+        const authSource = this.conf.user && this.conf.password
+            ? this.conf.authSource ?? "admin"
+            : undefined;
         const options = {
             connectTimeoutMS: 2000,
             serverSelectionTimeoutMS: 2000,
+            ...(authSource ? { authSource } : {}),
         };
         return { uri, options };
     }
@@ -84,6 +255,7 @@ export class K2DB {
             hosts,
             user: get("USER"),
             password: get("PASSWORD"),
+            authSource: get("AUTH_SOURCE"),
             replicaset: get("REPLICASET"),
         };
         const slow = get("SLOW_MS");
@@ -102,16 +274,13 @@ export class K2DB {
             return collection;
         }
         catch (err) {
-            // If the error is already an K2Error, rethrow it
-            if (err instanceof K2Error) {
-                throw err;
-            }
-            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error getting collection: ${collectionName}`, "sys_mdb_gc", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_gc", `Error getting collection: ${collectionName}`);
         }
     }
     async get(collectionName, uuid) {
+        const id = K2DB.normalizeId(uuid);
         const res = await this.findOne(collectionName, {
-            _uuid: uuid,
+            _uuid: id,
             _deleted: { $ne: true },
         });
         if (!res) {
@@ -130,8 +299,9 @@ export class K2DB {
         const collection = await this.getCollection(collectionName);
         const projection = {};
         // Exclude soft-deleted documents by default unless caller specifies otherwise
+        const normalizedCriteria = K2DB.normalizeCriteriaIds(criteria || {});
         const query = {
-            ...criteria,
+            ...normalizedCriteria,
             ...(criteria && Object.prototype.hasOwnProperty.call(criteria, "_deleted")
                 ? {}
                 : { _deleted: { $ne: true } }),
@@ -150,7 +320,7 @@ export class K2DB {
             return null;
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error finding document", "sys_mdb_fo", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_fo", "Error finding document");
         }
     }
     /**
@@ -164,7 +334,8 @@ export class K2DB {
     async find(collectionName, filter, params = {}, skip = 0, limit = 100) {
         const collection = await this.getCollection(collectionName);
         // Ensure filter is valid, defaulting to an empty object
-        const criteria = { ...(filter || {}) };
+        let criteria = { ...(filter || {}) };
+        criteria = K2DB.normalizeCriteriaIds(criteria);
         // Handle the _deleted field if params specify not to include deleted documents
         if (!params?.includeDeleted && !Object.prototype.hasOwnProperty.call(criteria, "_deleted")) {
             if (params?.deleted === true) {
@@ -219,7 +390,7 @@ export class K2DB {
             return result;
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error executing find query", "sys_mdb_find_error", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_find_error", "Error executing find query");
         }
     }
     /**
@@ -257,7 +428,7 @@ export class K2DB {
             return data.map((doc) => doc);
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Aggregation failed", "sys_mdb_ag", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_ag", "Aggregation failed");
         }
     }
     /**
@@ -358,8 +529,8 @@ export class K2DB {
         }
         const collection = await this.getCollection(collectionName);
         const timestamp = Date.now();
-        // Generate a new UUID
-        const newUuid = uuidv4();
+        // Generate a new UUIDv7 encoded as Crockford Base32 with hyphens
+        const newUuid = uuidv7Base32Hyphenated();
         // Remove reserved fields from user data, then validate/transform via schema if present
         const safeData = K2DB.stripReservedFields(data);
         const validated = this.applySchema(collectionName, safeData, /*partial*/ false);
@@ -372,7 +543,7 @@ export class K2DB {
             _uuid: newUuid,
         };
         try {
-            const result = await this.runTimed("insertOne", { collectionName }, async () => await collection.insertOne(document));
+            await this.runTimed("insertOne", { collectionName }, async () => await collection.insertOne(document));
             return { id: document._uuid };
         }
         catch (err) {
@@ -384,7 +555,7 @@ export class K2DB {
             // Log the error details for debugging
             debug(`Was trying to insert into collection ${collectionName}, data: ${JSON.stringify(document)}`);
             debug(err);
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error saving object to database", "sys_mdb_sav", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_sav", "Error saving object to database");
         }
     }
     /**
@@ -411,6 +582,7 @@ export class K2DB {
         if (deletedFlag !== undefined) {
             values._deleted = deletedFlag;
         }
+        criteria = K2DB.normalizeCriteriaIds(criteria || {});
         criteria = {
             ...criteria,
             _deleted: { $ne: true },
@@ -422,7 +594,7 @@ export class K2DB {
             };
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_update1", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_update1", `Error updating ${collectionName}`);
         }
     }
     /**
@@ -434,6 +606,7 @@ export class K2DB {
      * @param replace - If true, replaces the entire document (PUT), otherwise patches (PATCH).
      */
     async update(collectionName, id, data, replace = false) {
+        id = K2DB.normalizeId(id);
         this.validateCollectionName(collectionName);
         const collection = await this.getCollection(collectionName);
         data = K2DB.stripReservedFields(data);
@@ -469,11 +642,7 @@ export class K2DB {
             return { updated: res.modifiedCount };
         }
         catch (err) {
-            if (err instanceof K2Error) {
-                throw err;
-            }
-            // Catch any other unhandled errors and throw a system error
-            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_update_error", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_update_error", `Error updating ${collectionName}`);
         }
     }
     /**
@@ -484,13 +653,13 @@ export class K2DB {
     async deleteAll(collectionName, criteria) {
         this.validateCollectionName(collectionName);
         try {
-            let result = await this.updateAll(collectionName, criteria, {
+            const result = await this.updateAll(collectionName, criteria, {
                 _deleted: true,
             });
             return { deleted: result.updated };
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_deleteall_update", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_deleteall_update", `Error updating ${collectionName}`);
         }
     }
     /**
@@ -499,6 +668,7 @@ export class K2DB {
      * @param id - UUID of the document.
      */
     async delete(collectionName, id) {
+        id = K2DB.normalizeId(id);
         try {
             // Call deleteAll to soft delete the document by UUID
             const result = await this.deleteAll(collectionName, { _uuid: id });
@@ -517,11 +687,7 @@ export class K2DB {
             }
         }
         catch (err) {
-            // Preserve existing K2Error classifications (e.g., NOT_FOUND)
-            if (err instanceof K2Error) {
-                throw err;
-            }
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error removing object from collection", "sys_mdb_remove_upd", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_remove_upd", "Error removing object from collection");
         }
     }
     /**
@@ -530,6 +696,7 @@ export class K2DB {
      * @param id - UUID of the document.
      */
     async purge(collectionName, id) {
+        id = K2DB.normalizeId(id);
         const collection = await this.getCollection(collectionName);
         try {
             const item = await this.runTimed("findOne", { collectionName, _uuid: id, _deleted: true }, async () => await collection.findOne({
@@ -543,10 +710,7 @@ export class K2DB {
             return { id };
         }
         catch (err) {
-            if (err instanceof K2Error) {
-                throw err;
-            }
-            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error purging item with id: ${id}`, "sys_mdb_pg", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_pg", `Error purging item with id: ${id}`);
         }
     }
     /**
@@ -571,7 +735,7 @@ export class K2DB {
             return { purged: res.deletedCount ?? 0 };
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, 'Error purging deleted items by age', 'sys_mdb_purge_older', this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, 'sys_mdb_purge_older', 'Error purging deleted items by age');
         }
     }
     /**
@@ -581,7 +745,8 @@ export class K2DB {
      */
     async restore(collectionName, criteria) {
         const collection = await this.getCollection(collectionName);
-        const query = { ...(criteria || {}), _deleted: true };
+        const crit = K2DB.normalizeCriteriaIds(criteria || {});
+        const query = { ...crit, _deleted: true };
         try {
             const res = await this.runTimed("updateMany", { collectionName, query }, async () => await collection.updateMany(query, {
                 // Restoring is a data change: flip _deleted and bump _updated
@@ -590,7 +755,7 @@ export class K2DB {
             return { status: "restored", modified: res.modifiedCount };
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error restoring a deleted item", "sys_mdb_pres", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_pres", "Error restoring a deleted item");
         }
     }
     /**
@@ -601,8 +766,9 @@ export class K2DB {
     async count(collectionName, criteria) {
         const collection = await this.getCollection(collectionName);
         try {
+            const norm = K2DB.normalizeCriteriaIds(criteria || {});
             const query = {
-                ...criteria,
+                ...norm,
                 ...(criteria && Object.prototype.hasOwnProperty.call(criteria, "_deleted")
                     ? {}
                     : { _deleted: { $ne: true } }),
@@ -611,7 +777,7 @@ export class K2DB {
             return { count: cnt };
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error counting objects with given criteria", "sys_mdb_cn", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_cn", "Error counting objects with given criteria");
         }
     }
     /**
@@ -625,7 +791,7 @@ export class K2DB {
             return { status: "ok" };
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error dropping collection", "sys_mdb_drop", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_drop", "Error dropping collection");
         }
     }
     /**
@@ -634,6 +800,8 @@ export class K2DB {
      */
     static sanitiseCriteria(criteria) {
         if (criteria.$match) {
+            // Normalize any _uuid values in the match object to uppercase
+            criteria.$match = K2DB.normalizeCriteriaIds(criteria.$match);
             for (const key of Object.keys(criteria.$match)) {
                 if (typeof criteria.$match[key] !== "string") {
                     criteria.$match[key] = K2DB.sanitiseCriteria({
@@ -649,6 +817,45 @@ export class K2DB {
         }
         return criteria;
     }
+    /** Recursively uppercases any values for fields named `_uuid` within a query object. */
+    static normalizeCriteriaIds(obj) {
+        if (!obj || typeof obj !== "object")
+            return obj;
+        if (Array.isArray(obj))
+            return obj.map((v) => K2DB.normalizeCriteriaIds(v));
+        const out = Array.isArray(obj) ? [] : { ...obj };
+        for (const [k, v] of Object.entries(obj)) {
+            if (k === "_uuid") {
+                out[k] = K2DB.normalizeUuidField(v);
+            }
+            else if (v && typeof v === "object") {
+                out[k] = K2DB.normalizeCriteriaIds(v);
+            }
+            else if (Array.isArray(v)) {
+                out[k] = v.map((x) => K2DB.normalizeCriteriaIds(x));
+            }
+            else {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    /** Uppercase helper for `_uuid` field supporting operators like $in/$nin/$eq/$ne and arrays. */
+    static normalizeUuidField(val) {
+        if (typeof val === "string")
+            return val.toUpperCase();
+        if (Array.isArray(val))
+            return val.map((x) => (typeof x === "string" ? x.toUpperCase() : x));
+        if (val && typeof val === "object") {
+            const out = { ...val };
+            for (const op of ["$in", "$nin", "$eq", "$ne", "$all"]) {
+                if (op in out)
+                    out[op] = K2DB.normalizeUuidField(out[op]);
+            }
+            return out;
+        }
+        return val;
+    }
     /** Strip any user-provided fields that start with '_' (reserved). */
     static stripReservedFields(obj) {
         const out = {};
@@ -658,6 +865,18 @@ export class K2DB {
         }
         return out;
     }
+    /** True if string matches K2 ID format (Crockford Base32, 8-4-4-4-6, uppercase). */
+    static isK2ID(id) {
+        if (typeof id !== "string")
+            return false;
+        const s = id.trim().toUpperCase();
+        const CROCK_RE = /^[0-9A-HJKMNPQRSTVWXYZ]{8}-[0-9A-HJKMNPQRSTVWXYZ]{4}-[0-9A-HJKMNPQRSTVWXYZ]{4}-[0-9A-HJKMNPQRSTVWXYZ]{4}-[0-9A-HJKMNPQRSTVWXYZ]{6}$/;
+        return CROCK_RE.test(s);
+    }
+    /** Uppercase incoming IDs for case-insensitive lookups. */
+    static normalizeId(id) {
+        return id.toUpperCase();
+    }
     /**
      * Run an async DB operation with timing, slow logging, and hooks.
      */
@@ -723,7 +942,7 @@ export class K2DB {
         }
         catch (error) {
             await session.abortTransaction();
-            throw this.normalizeError(error);
+            throw wrap(error, ServiceError.BAD_GATEWAY, "sys_mdb_txn", "Transaction failed");
         }
         finally {
             session.endSession();
@@ -742,21 +961,29 @@ export class K2DB {
             debug(`Index created on ${collectionName}: ${JSON.stringify(indexSpec)}`);
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error creating index on ${collectionName}`, "sys_mdb_idx", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_idx", `Error creating index on ${collectionName}`);
         }
     }
     /**
      * Releases the MongoDB connection.
      */
     async release() {
-        await this.connection.close();
+        if (this.initialized && this.clientKey) {
+            const key = this.clientKey;
+            this.initialized = false;
+            this.clientKey = undefined;
+            await _decrefClient(key);
+            debug("MongoDB connection released");
+            return;
+        }
         debug("MongoDB connection released");
     }
     /**
      * Closes the MongoDB connection.
      */
     close() {
-        this.connection.close();
+        // Fire-and-forget async release (shared pool is refcounted)
+        void this.release();
     }
     /**
      * Drops the entire database.
@@ -767,7 +994,7 @@ export class K2DB {
             debug("Database dropped successfully");
         }
         catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error dropping database", "sys_mdb_drop_db", this.normalizeError(err));
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_drop_db", "Error dropping database");
         }
     }
     /**
@@ -802,14 +1029,6 @@ export class K2DB {
             return false;
         }
     }
-    /**
-     * Utility to normalize the error type.
-     * @param err - The caught error of type `unknown`.
-     * @returns A normalized error of type `Error`.
-     */
-    normalizeError(err) {
-        return err instanceof Error ? err : new Error(String(err));
-    }
     // ===== Versioning helpers and APIs =====
     /** Name of the history collection for a given collection. */
     historyName(collectionName) {
@@ -846,7 +1065,7 @@ export class K2DB {
         }
         const parsed = s.safeParse(data);
         if (!parsed.success) {
-            throw new K2Error(ServiceError.BAD_REQUEST, "Validation failed", "sys_mdb_schema_validation", new Error(parsed.error.message));
+            throw new K2Error(ServiceError.VALIDATION_ERROR, parsed.error.message, "sys_mdb_schema_validation", parsed.error);
         }
         return parsed.data;
     }
@@ -862,6 +1081,7 @@ export class K2DB {
     }
     /** Compute the next version number for a document. */
     async nextVersion(collectionName, id) {
+        id = K2DB.normalizeId(id);
         const hc = await this.getHistoryCollection(collectionName);
         const last = await hc
             .find({ _uuid: id })
@@ -888,6 +1108,7 @@ export class K2DB {
      * If maxVersions is provided, prunes oldest snapshots beyond that number.
      */
     async updateVersioned(collectionName, id, data, replace = false, maxVersions) {
+        id = K2DB.normalizeId(id);
         // Get current doc (excludes deleted) and snapshot it
         const current = await this.get(collectionName, id);
         await this.ensureHistoryIndexes(collectionName);
@@ -916,6 +1137,7 @@ export class K2DB {
     }
     /** List versions (latest first). */
     async listVersions(collectionName, id, skip = 0, limit = 20) {
+        id = K2DB.normalizeId(id);
         const hc = await this.getHistoryCollection(collectionName);
         const rows = await hc
             .find({ _uuid: id })
@@ -928,6 +1150,7 @@ export class K2DB {
     }
     /** Revert the current document to a specific historical version (preserves metadata). */
     async revertToVersion(collectionName, id, version) {
+        id = K2DB.normalizeId(id);
         const hc = await this.getHistoryCollection(collectionName);
         const row = await hc.findOne({ _uuid: id, _v: version });
         if (!row) {