@frogfish/k2db 3.0.2 → 3.0.4

package/data.d.ts

@@ -1,5 +1,5 @@
 import { K2DB } from "./db.js";
-import type { BaseDocument, CreateResult, UpdateResult, DeleteResult, RestoreResult, CountResult, DropResult, VersionedUpdateResult, VersionInfo } from "./db.js";
+import type { BaseDocument, CreateResult, UpdateResult, DeleteResult, RestoreResult, CountResult, DropResult, PurgeResult, PurgeManyResult, VersionedUpdateResult, VersionInfo } from "./db.js";
 export declare class K2Data {
     private db;
     private owner;
@@ -68,9 +68,11 @@ export declare class K2Data {
     /**
      * Permanently deletes a document that has been soft-deleted.
      */
-    purge(collectionName: string, id: string): Promise<{
-        id: string;
-    }>;
+    purge(collectionName: string, id: string): Promise<PurgeResult>;
+    /**
+     * Permanently deletes all soft-deleted documents older than a threshold.
+     */
+    purgeDeletedOlderThan(collectionName: string, olderThanMs: number): Promise<PurgeManyResult>;
     /**
      * Restores a soft-deleted document.
      */
@@ -83,6 +85,15 @@ export declare class K2Data {
      * Drops an entire collection.
      */
     drop(collectionName: string): Promise<DropResult>;
+    /**
+     * Ensure commonly needed indexes exist.
+     */
+    ensureIndexes(collectionName: string, opts?: {
+        uuidUnique?: boolean;
+        uuidPartialUnique?: boolean;
+        ownerIndex?: boolean;
+        deletedIndex?: boolean;
+    }): Promise<void>;
     /**
      * Executes a transaction with the provided operations.
      */
@@ -95,6 +106,18 @@ export declare class K2Data {
      * Drops the entire database.
      */
     dropDatabase(): Promise<void>;
+    /**
+     * Releases the MongoDB connection.
+     */
+    release(): Promise<void>;
+    /**
+     * Closes the MongoDB connection.
+     */
+    close(): void;
+    /**
+     * Validates the MongoDB collection name.
+     */
+    validateCollectionName(collectionName: string): void;
     /**
      * Checks the health of the database connection.
      */
@@ -102,4 +125,4 @@ export declare class K2Data {
 }
 export { K2DB } from "./db.js";
 export declare const isK2ID: (id: string) => boolean;
-export type { DatabaseConfig, BaseDocument, CreateResult, UpdateResult, DeleteResult, RestoreResult, CountResult, DropResult, VersionedUpdateResult, VersionInfo, } from "./db.js";
+export type { DatabaseConfig, BaseDocument, CreateResult, UpdateResult, DeleteResult, RestoreResult, CountResult, DropResult, PurgeResult, PurgeManyResult, VersionedUpdateResult, VersionInfo, } from "./db.js";

package/data.js

@@ -12,7 +12,7 @@ export class K2Data {
      * @param uuid - UUID of the document.
      */
     async get(collectionName, uuid) {
-        return this.db.get(collectionName, uuid);
+        return this.db.get(collectionName, uuid, this.owner);
     }
     /**
      * Retrieves a single document matching the criteria.
@@ -21,19 +21,19 @@ export class K2Data {
      * @param fields - Optional fields to include.
      */
     async findOne(collectionName, criteria, fields) {
-        return this.db.findOne(collectionName, criteria, fields);
+        return this.db.findOne(collectionName, criteria, fields, this.owner);
     }
     /**
      * Finds documents based on filter with optional parameters and pagination.
      */
     async find(collectionName, filter, params, skip, limit) {
-        return this.db.find(collectionName, filter, params, skip, limit);
+        return this.db.find(collectionName, filter, params, skip, limit, this.owner);
     }
     /**
      * Aggregates documents based on criteria with pagination support.
      */
     async aggregate(collectionName, criteria, skip, limit) {
-        return this.db.aggregate(collectionName, criteria, skip, limit);
+        return this.db.aggregate(collectionName, criteria, skip, limit, this.owner);
     }
     /**
      * Creates a new document in the collection.
@@ -46,28 +46,28 @@ export class K2Data {
      */
     async updateAll(collectionName, criteria, values) {
         // Ensure it returns { updated: number }
-        return this.db.updateAll(collectionName, criteria, values);
+        return this.db.updateAll(collectionName, criteria, values, this.owner);
     }
     /**
      * Updates a single document by UUID.
      */
     async update(collectionName, id, data, replace = false) {
         // Ensure it returns { updated: number }
-        return this.db.update(collectionName, id, data, replace);
+        return this.db.update(collectionName, id, data, replace, this.owner);
     }
     /**
      * Updates a single document by UUID and saves the previous version to history.
      */
     async updateVersioned(collectionName, id, data, replace = false, maxVersions) {
-        return this.db.updateVersioned(collectionName, id, data, replace, maxVersions);
+        return this.db.updateVersioned(collectionName, id, data, replace, maxVersions, this.owner);
     }
     /** List versions for a document (latest first). */
     async listVersions(collectionName, id, skip, limit) {
-        return this.db.listVersions(collectionName, id, skip, limit);
+        return this.db.listVersions(collectionName, id, skip, limit, this.owner);
     }
     /** Revert a document to a prior version. */
     async revertToVersion(collectionName, id, version) {
-        return this.db.revertToVersion(collectionName, id, version);
+        return this.db.revertToVersion(collectionName, id, version, this.owner);
     }
     /** Ensure history collection indexes exist. */
     async ensureHistoryIndexes(collectionName) {
@@ -90,37 +90,49 @@ export class K2Data {
      */
     async deleteAll(collectionName, criteria) {
         // Ensure it returns { deleted: number }
-        return this.db.deleteAll(collectionName, criteria);
+        return this.db.deleteAll(collectionName, criteria, this.owner);
     }
     /**
      * Removes (soft deletes) a single document by UUID.
      */
     async delete(collectionName, id) {
-        return this.db.delete(collectionName, id);
+        return this.db.delete(collectionName, id, this.owner);
     }
     /**
      * Permanently deletes a document that has been soft-deleted.
      */
     async purge(collectionName, id) {
-        return this.db.purge(collectionName, id);
+        return this.db.purge(collectionName, id, this.owner);
+    }
+    /**
+     * Permanently deletes all soft-deleted documents older than a threshold.
+     */
+    async purgeDeletedOlderThan(collectionName, olderThanMs) {
+        return this.db.purgeDeletedOlderThan(collectionName, olderThanMs, this.owner);
     }
     /**
      * Restores a soft-deleted document.
      */
     async restore(collectionName, criteria) {
-        return this.db.restore(collectionName, criteria);
+        return this.db.restore(collectionName, criteria, this.owner);
     }
     /**
      * Counts documents based on criteria.
      */
     async count(collectionName, criteria) {
-        return this.db.count(collectionName, criteria);
+        return this.db.count(collectionName, criteria, this.owner);
     }
     /**
      * Drops an entire collection.
      */
     async drop(collectionName) {
-        return this.db.drop(collectionName);
+        return this.db.drop(collectionName, this.owner);
+    }
+    /**
+     * Ensure commonly needed indexes exist.
+     */
+    async ensureIndexes(collectionName, opts) {
+        return this.db.ensureIndexes(collectionName, opts);
     }
     /**
      * Executes a transaction with the provided operations.
@@ -140,6 +152,24 @@ export class K2Data {
     async dropDatabase() {
         return this.db.dropDatabase();
     }
+    /**
+     * Releases the MongoDB connection.
+     */
+    async release() {
+        return this.db.release();
+    }
+    /**
+     * Closes the MongoDB connection.
+     */
+    close() {
+        this.db.close();
+    }
+    /**
+     * Validates the MongoDB collection name.
+     */
+    validateCollectionName(collectionName) {
+        return this.db.validateCollectionName(collectionName);
+    }
     /**
      * Checks the health of the database connection.
      */

package/db.js

@@ -1,14 +1,214 @@
 // src/db.ts
-import { K2Error, ServiceError, wrap } from "@frogfish/k2error"; // Keep the existing error structure
+import { K2Error, ServiceError, wrap, chain } from "@frogfish/k2error"; // Keep the existing error structure
 import { MongoClient, } from "mongodb";
 import { randomBytes, createHash, createCipheriv, createDecipheriv } from "crypto";
 import { Topic } from '@frogfish/ratatouille';
 import { z } from "zod";
 // const debug = debugLib("k2:db");
-const debug = Topic('k2db#random');
+const debug = Topic('k2db:debug#random');
+const error = Topic('k2db:error#random');
+/**
+ * Emit a rich DB error event to Ratatouille.
+ * - Never throws (logging must not break request path)
+ * - Dedupes per error instance (avoid double logging on rethrow)
+ * - INTERNAL: may include sensitive diagnostics
+ */
+function emitDbError(err, meta = {}) {
+    try {
+        if (!error.enabled)
+            return;
+        // Deduplicate per error instance (non-enumerable marker)
+        const MARK = "__k2db_logged";
+        if (err && typeof err === "object") {
+            const anyErr = err;
+            if (anyErr[MARK])
+                return;
+            try {
+                Object.defineProperty(anyErr, MARK, {
+                    value: true,
+                    enumerable: false,
+                    configurable: true,
+                });
+            }
+            catch {
+                // ignore marker failures
+            }
+        }
+        const isErr = err instanceof Error;
+        const k2 = err instanceof K2Error ? err : undefined;
+        // `sensitive` is expected to be non-enumerable on K2Error
+        const sensitive = k2 ? k2.sensitive : (isErr ? err.sensitive : undefined);
+        const payload = {
+            kind: "k2db:error",
+            at: Date.now(),
+            ...meta,
+            k2: k2
+                ? {
+                    error: k2.error,
+                    code: k2.code,
+                    error_description: k2.error_description,
+                    trace: k2.trace,
+                    chain: k2.chain,
+                }
+                : undefined,
+            name: isErr ? err.name : undefined,
+            message: isErr ? err.message : String(err),
+            // If we don't have a K2Error yet, still include a compact Mongo-ish normalization
+            mongo: k2 ? undefined : normaliseMongoError(err),
+            // If K2Error has a cause (often the raw Mongo error), include it normalized too
+            cause: k2?.cause ? normaliseMongoError(k2.cause) : undefined,
+            sensitive,
+            stack: isErr ? err.stack : undefined,
+        };
+        // strip undefined
+        for (const k of Object.keys(payload))
+            if (payload[k] === undefined)
+                delete payload[k];
+        error(payload);
+    }
+    catch {
+        // never throw from logging
+    }
+}
 function _hashSecret(secret) {
     return createHash("sha256").update(secret).digest("hex");
 }
+/**
+ * Normalise MongoDB driver/server errors into a structured, log-friendly shape.
+ *
+ * This is intended for INTERNAL diagnostics (e.g. attach to K2Error.sensitive).
+ * Keep it compact and resilient to unknown error shapes.
+ */
+function normaliseMongoError(err) {
+    const MAX_STR = 2000;
+    const MAX_KEYS = 50;
+    const MAX_ARR = 50;
+    const MAX_DEPTH = 4;
+    const truncate = (s) => (s.length > MAX_STR ? s.slice(0, MAX_STR) + "…" : s);
+    const prune = (val, depth = 0) => {
+        if (val === null || val === undefined)
+            return val;
+        if (depth >= MAX_DEPTH)
+            return "[Truncated]";
+        const t = typeof val;
+        if (t === "string")
+            return truncate(val);
+        if (t === "number" || t === "boolean" || t === "bigint")
+            return val;
+        // Avoid serialising functions/symbols
+        if (t === "function")
+            return "[Function]";
+        if (t === "symbol")
+            return "[Symbol]";
+        if (Array.isArray(val)) {
+            const out = val.slice(0, MAX_ARR).map((x) => prune(x, depth + 1));
+            if (val.length > MAX_ARR)
+                out.push(`[+${val.length - MAX_ARR} more]`);
+            return out;
+        }
+        if (t === "object") {
+            const obj = val;
+            // Preserve Buffer in a safe way
+            if (typeof Buffer !== "undefined" && Buffer.isBuffer(obj)) {
+                return { type: "Buffer", length: obj.length };
+            }
+            const keys = Object.keys(obj).slice(0, MAX_KEYS);
+            const out = {};
+            for (const k of keys) {
+                // Basic redaction for common secret-ish keys
+                const lk = k.toLowerCase();
+                if (lk.includes("password") || lk === "pass" || lk.includes("secret") || lk.includes("token")) {
+                    out[k] = "[REDACTED]";
+                    continue;
+                }
+                try {
+                    out[k] = prune(obj[k], depth + 1);
+                }
+                catch (e) {
+                    out[k] = "[Unserialisable]";
+                }
+            }
+            if (Object.keys(obj).length > MAX_KEYS) {
+                out.__truncatedKeys = Object.keys(obj).length - MAX_KEYS;
+            }
+            return out;
+        }
+        try {
+            return truncate(String(val));
+        }
+        catch {
+            return "[Unknown]";
+        }
+    };
+    // MongoDB driver often provides these fields on thrown errors
+    const anyErr = err;
+    const base = {
+        name: anyErr?.name ?? (err instanceof Error ? err.name : "UnknownError"),
+        message: anyErr?.message ?? (err instanceof Error ? err.message : String(err)),
+    };
+    const out = {
+        ...base,
+        // common Mongo fields (present on MongoServerError and friends)
+        code: typeof anyErr?.code === "number" ? anyErr.code : undefined,
+        codeName: typeof anyErr?.codeName === "string" ? anyErr.codeName : undefined,
+        errorLabels: Array.isArray(anyErr?.errorLabels) ? anyErr.errorLabels.slice(0, MAX_ARR) : undefined,
+        errInfo: anyErr?.errInfo ? prune(anyErr.errInfo, 0) : undefined,
+    };
+    // Include a compact pruned view of any extra enumerable fields for diagnostics
+    if (anyErr && typeof anyErr === "object") {
+        out.extra = prune(anyErr, 0);
+    }
+    // Remove undefined fields for cleanliness
+    for (const k of Object.keys(out)) {
+        if (out[k] === undefined)
+            delete out[k];
+    }
+    return out;
+}
+/**
+ * Produce a compact summary of an arbitrary value for INTERNAL diagnostics.
+ * Prefer shapes/keys over full payloads to avoid accidental PII/secret logging.
+ */
+function summariseValueShape(val) {
+    try {
+        if (val === null)
+            return { type: "null" };
+        if (val === undefined)
+            return { type: "undefined" };
+        if (Array.isArray(val))
+            return { type: "array", length: val.length };
+        const t = typeof val;
+        if (t !== "object")
+            return { type: t };
+        const obj = val;
+        const keys = Object.keys(obj);
+        return { type: "object", keys: keys.slice(0, 50), keyCount: keys.length };
+    }
+    catch {
+        return { type: "unknown" };
+    }
+}
+/**
+ * Redact common secret-ish keys from a shallow object for INTERNAL diagnostics.
+ * (Still treat returned value as sensitive; this is only to reduce obvious footguns.)
+ */
+function redactShallowSecrets(obj) {
+    if (!obj || typeof obj !== "object" || Array.isArray(obj))
+        return obj;
+    const out = { ...obj };
+    for (const k of Object.keys(out)) {
+        const lk = k.toLowerCase();
+        if (lk.includes("password") ||
+            lk === "pass" ||
+            lk.includes("secret") ||
+            lk.includes("token") ||
+            lk.includes("apikey") ||
+            lk.includes("api_key")) {
+            out[k] = "[REDACTED]";
+        }
+    }
+    return out;
+}
 // ---- Shared MongoClient pool (per cluster+auth), reused across DB names ----
 const _clientByKey = new Map();
 const _connectingByKey = new Map();
@@ -339,7 +539,13 @@ export class K2DB {
             return collection;
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_gc", `Error getting collection: ${collectionName}`);
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            throw chain(err, "sys_mdb_gc", `Error getting collection: ${collectionName}`, sev, "k2db.getCollection")
+                .setSensitive({
+                op: "getCollection",
+                collection: collectionName,
+                mongo: normaliseMongoError(err),
+            });
         }
     }
     /**
@@ -421,7 +627,19 @@ export class K2DB {
             return null;
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_fo", "Error finding document");
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            throw chain(err, "sys_mdb_fo", "Error finding document", sev, "k2db.findOne")
+                .setSensitive({
+                op: "findOne",
+                collection: collectionName,
+                scope,
+                queryShape: summariseValueShape(query),
+                projectionShape: summariseValueShape(projection),
+                // Queries/projections may contain user identifiers and selectors; treat as sensitive.
+                queryPreview: redactShallowSecrets(query),
+                projectionPreview: redactShallowSecrets(projection),
+                mongo: normaliseMongoError(err),
+            });
         }
     }
     /**
@@ -501,7 +719,23 @@ export class K2DB {
             return result;
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_find_error", "Error executing find query");
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            throw chain(err, "sys_mdb_find_error", "Error executing find query", sev, "k2db.find")
+                .setSensitive({
+                op: "find",
+                collection: collectionName,
+                scope,
+                skip,
+                limit,
+                paramsShape: summariseValueShape(params),
+                criteriaShape: summariseValueShape(criteria),
+                projectionShape: summariseValueShape(projection),
+                sortShape: summariseValueShape(sort),
+                // Queries/projections may contain user identifiers and selectors; treat as sensitive.
+                criteriaPreview: redactShallowSecrets(criteria),
+                projectionPreview: redactShallowSecrets(projection),
+                mongo: normaliseMongoError(err),
+            });
         }
     }
     /**
@@ -513,34 +747,63 @@ export class K2DB {
      * @param scope - (optional) Owner selector; "*" means all owners.
      */
     async aggregate(collectionName, criteria, skip = 0, limit = 100, scope) {
-        if (criteria.length === 0) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, "Aggregation criteria cannot be empty", "sys_mdb_ag_empty");
-        }
-        // Prevent aggregation from reading/deriving values from secure-prefixed fields (when configured)
-        this.assertNoSecureFieldRefsInPipeline(criteria);
-        // Validate the aggregation pipeline for allowed/disallowed stages and safety caps
-        this.validateAggregationPipeline(criteria, skip, limit);
-        // Enforce soft-delete behavior: never return documents marked as deleted
-        criteria = K2DB.enforceNoDeletedInPipeline(criteria);
-        // Enforce ownership scope within the pipeline (and nested pipelines)
-        criteria = this.enforceScopeInPipeline(criteria, scope);
-        // Add pagination stages to the aggregation pipeline
-        if (skip > 0) {
-            criteria.push({ $skip: skip });
-        }
-        if (limit > 0) {
-            criteria.push({ $limit: limit });
-        }
-        debug(`Aggregating with criteria: ${JSON.stringify(criteria, null, 2)}`);
-        const collection = await this.getCollection(collectionName);
-        // Sanitize criteria
-        const sanitizedCriteria = criteria.map((stage) => {
-            if (stage.$match) {
-                return K2DB.sanitiseCriteria(stage);
-            }
-            return stage;
-        });
+        // --- BEGIN enhanced diagnostics/snapshots ---
+        const clonePipeline = (p) => {
+            if (!Array.isArray(p))
+                return [];
+            return p.map((stage) => {
+                try {
+                    return JSON.parse(JSON.stringify(stage));
+                }
+                catch {
+                    return stage;
+                }
+            });
+        };
+        const inputPipeline = clonePipeline(criteria);
+        const inputStageOps = this.collectStageOps(inputPipeline);
+        // --- END enhanced diagnostics/snapshots ---
+        // These are populated as we build/execute the pipeline so we can attach them on ANY failure.
+        let workingPipeline;
+        let sanitizedCriteria;
+        let finalStageOps;
         try {
+            if (criteria.length === 0) {
+                throw new K2Error(ServiceError.SYSTEM_ERROR, "Aggregation criteria cannot be empty", "sys_mdb_ag_empty");
+            }
+            // Prevent aggregation from reading/deriving values from secure-prefixed fields (when configured)
+            this.assertNoSecureFieldRefsInPipeline(criteria);
+            // Validate the aggregation pipeline for allowed/disallowed stages and safety caps
+            this.validateAggregationPipeline(criteria, skip, limit);
+            // Enforce soft-delete behavior: never return documents marked as deleted
+            workingPipeline = K2DB.enforceNoDeletedInPipeline(criteria);
+            // Enforce ownership scope within the pipeline (and nested pipelines)
+            workingPipeline = this.enforceScopeInPipeline(workingPipeline, scope);
+            // Add pagination stages to the aggregation pipeline
+            if (skip > 0) {
+                workingPipeline.push({ $skip: skip });
+            }
+            if (limit > 0) {
+                workingPipeline.push({ $limit: limit });
+            }
+            debug(`Aggregating with criteria: ${JSON.stringify(workingPipeline, null, 2)}`);
+            const collection = await this.getCollection(collectionName);
+            // Sanitize criteria (do not mutate the working pipeline)
+            sanitizedCriteria = workingPipeline.map((stage) => {
+                const clonedStage = (() => {
+                    try {
+                        return JSON.parse(JSON.stringify(stage));
+                    }
+                    catch {
+                        return stage;
+                    }
+                })();
+                if (clonedStage && clonedStage.$match) {
+                    return K2DB.sanitiseCriteria(clonedStage);
+                }
+                return clonedStage;
+            });
+            finalStageOps = this.collectStageOps(sanitizedCriteria);
             const data = await this.runTimed("aggregate", { collectionName, pipeline: sanitizedCriteria }, async () => {
                 const mode = this.aggregationMode ?? "loose";
                 const opts = {};
@@ -553,7 +816,54 @@ export class K2DB {
             return data.map((doc) => this.stripSecureFieldsDeep(doc));
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_ag", "Aggregation failed");
+            // If we already have a K2Error (e.g. validation/ownership/secure-field), preserve it.
+            // Otherwise chain into a SYSTEM_ERROR with rich internal diagnostics.
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            const k2 = err instanceof K2Error
+                ? err
+                : chain(err, "sys_mdb_ag", "Aggregation failed", sev, "k2db.aggregate");
+            // Merge/attach sensitive diagnostics without losing any existing sensitive payload.
+            const prevSensitive = k2.sensitive;
+            const mergedSensitive = prevSensitive && typeof prevSensitive === "object" ? { ...prevSensitive } : {};
+            // Build a rich diagnostic payload (internal-only)
+            Object.assign(mergedSensitive, {
+                op: "aggregate",
+                collection: collectionName,
+                scope,
+                skip,
+                limit,
+                ownershipMode: this.ownershipMode,
+                aggregationMode: this.aggregationMode,
+                // Caller input vs executed pipeline snapshots
+                inputStageOps,
+                finalStageOps,
+                inputPipelineShape: summariseValueShape(inputPipeline),
+                workingPipelineShape: summariseValueShape(workingPipeline),
+                finalPipelineShape: summariseValueShape(sanitizedCriteria),
+                // Full internal pipelines (may include identifiers/selectors)
+                inputPipeline,
+                workingPipeline,
+                pipeline: sanitizedCriteria,
+                // Compact at-a-glance previews (shallow key redaction only)
+                inputPipelinePreview: Array.isArray(inputPipeline)
+                    ? inputPipeline.map((s) => redactShallowSecrets(s))
+                    : inputPipeline,
+                workingPipelinePreview: Array.isArray(workingPipeline)
+                    ? workingPipeline.map((s) => redactShallowSecrets(s))
+                    : workingPipeline,
+                pipelinePreview: Array.isArray(sanitizedCriteria)
+                    ? sanitizedCriteria.map((s) => redactShallowSecrets(s))
+                    : sanitizedCriteria,
+                mongo: normaliseMongoError(err),
+            });
+            // setSensitive is expected to exist on K2Error (non-enumerable sensitive field)
+            k2.setSensitive?.(mergedSensitive);
+            // Emit once (deduped per error instance)
+            emitDbError(k2, {
+                op: "aggregate",
+                collection: collectionName,
+            });
+            throw k2;
         }
     }
     /**
@@ -1070,10 +1380,17 @@ export class K2DB {
             if (err.code === 11000 && err.keyPattern && err.keyPattern._uuid) {
                 throw new K2Error(ServiceError.ALREADY_EXISTS, `A document with _uuid ${document._uuid} already exists.`, "sys_mdb_crv3");
             }
-            // Log the error details for debugging
-            debug(`Was trying to insert into collection ${collectionName}, data: ${JSON.stringify(document)}`);
-            debug(err);
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_sav", "Error saving object to database");
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            throw chain(err, "sys_mdb_sav", "Error saving object to database", sev, "k2db.create")
+                .setSensitive({
+                op: "insertOne",
+                collection: collectionName,
+                owner: normalizedOwner,
+                uuid: document._uuid,
+                documentShape: summariseValueShape(document),
+                userFieldPreview: redactShallowSecrets(safeData),
+                mongo: normaliseMongoError(err),
+            });
         }
     }
     /**
@@ -1116,7 +1433,19 @@ export class K2DB {
             };
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_update1", `Error updating ${collectionName}`);
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            throw chain(err, "sys_mdb_update1", `Error updating ${collectionName}`, sev, "k2db.updateAll")
+                .setSensitive({
+                op: "updateMany",
+                collection: collectionName,
+                scope,
+                criteriaShape: summariseValueShape(criteria),
+                valuesShape: summariseValueShape(values),
+                // criteria may contain selectors; treat as sensitive. Keep it compact.
+                criteriaPreview: redactShallowSecrets(criteria),
+                valuesPreview: redactShallowSecrets(values),
+                mongo: normaliseMongoError(err),
+            });
         }
     }
     /**
@@ -1172,7 +1501,18 @@ export class K2DB {
             return { updated: res.modifiedCount };
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_update_error", `Error updating ${collectionName}`);
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            throw chain(err, "sys_mdb_update_error", `Error updating ${collectionName}`, sev, "k2db.update")
+                .setSensitive({
+                op: replace ? "replaceOne" : "updateOne",
+                collection: collectionName,
+                uuid: id,
+                replace,
+                scope,
+                dataShape: summariseValueShape(data),
+                dataPreview: redactShallowSecrets(data),
+                mongo: normaliseMongoError(err),
+            });
         }
     }
     /**
@@ -1190,7 +1530,16 @@ export class K2DB {
             return { deleted: result.updated };
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_deleteall_update", `Error updating ${collectionName}`);
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            throw chain(err, "sys_mdb_deleteall_update", `Error deleting from ${collectionName}`, sev, "k2db.deleteAll")
+                .setSensitive({
+                op: "softDeleteMany",
+                collection: collectionName,
+                scope,
+                criteriaShape: summariseValueShape(criteria),
+                criteriaPreview: redactShallowSecrets(criteria),
+                mongo: normaliseMongoError(err),
+            });
         }
     }
     /**
@@ -1219,7 +1568,15 @@ export class K2DB {
             }
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_remove_upd", "Error removing object from collection");
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            throw chain(err, "sys_mdb_remove_upd", "Error removing object from collection", sev, "k2db.delete")
+                .setSensitive({
+                op: "softDeleteOne",
+                collection: collectionName,
+                uuid: id,
+                scope,
+                mongo: normaliseMongoError(err),
+            });
         }
     }
     /**
@@ -1231,18 +1588,38 @@ export class K2DB {
     async purge(collectionName, id, scope) {
         id = K2DB.normalizeId(id);
         const collection = await this.getCollection(collectionName);
+        let findFilter;
+        let delFilter;
         try {
-            const findFilter = this.applyScopeToCriteria({ _uuid: id, _deleted: true }, scope);
+            findFilter = this.applyScopeToCriteria({ _uuid: id, _deleted: true }, scope);
             const item = await this.runTimed("findOne", { collectionName, ...findFilter }, async () => await collection.findOne(findFilter));
             if (!item) {
                 throw new K2Error(ServiceError.SYSTEM_ERROR, "Cannot purge item that is not deleted", "sys_mdb_gcol_pg2");
             }
-            const delFilter = this.applyScopeToCriteria({ _uuid: id }, scope);
+            delFilter = this.applyScopeToCriteria({ _uuid: id }, scope);
             await this.runTimed("deleteOne", { collectionName, ...delFilter }, async () => await collection.deleteOne(delFilter));
             return { id };
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_pg", `Error purging item with id: ${id}`);
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            const k2 = chain(err, "sys_mdb_pg", `Error purging item with id: ${id}`, sev, "k2db.purge")
+                .setSensitive({
+                op: "purge",
+                collection: collectionName,
+                uuid: id,
+                scope,
+                findFilterShape: summariseValueShape(findFilter),
+                delFilterShape: summariseValueShape(delFilter),
+                findFilterPreview: redactShallowSecrets(findFilter),
+                delFilterPreview: redactShallowSecrets(delFilter),
+                mongo: normaliseMongoError(err),
+            });
+            emitDbError(k2, {
+                op: "purge",
+                collection: collectionName,
+                uuid: id,
+            });
+            throw k2;
         }
     }
     /**
@@ -1302,9 +1679,10 @@ export class K2DB {
      */
     async count(collectionName, criteria, scope) {
         const collection = await this.getCollection(collectionName);
+        let query;
         try {
             const norm = K2DB.normalizeCriteriaIds(criteria || {});
-            let query = {
+            query = {
                 ...norm,
                 ...(criteria && Object.prototype.hasOwnProperty.call(criteria, "_deleted")
                     ? {}
@@ -1315,7 +1693,21 @@ export class K2DB {
             return { count: cnt };
         }
         catch (err) {
-            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_cn", "Error counting objects with given criteria");
+            const sev = err instanceof K2Error ? undefined : ServiceError.SYSTEM_ERROR;
+            const k2 = chain(err, "sys_mdb_cn", "Error counting objects with given criteria", sev, "k2db.count")
+                .setSensitive({
+                op: "countDocuments",
+                collection: collectionName,
+                scope,
+                queryShape: summariseValueShape(query),
+                queryPreview: redactShallowSecrets(query),
+                mongo: normaliseMongoError(err),
+            });
+            emitDbError(k2, {
+                op: "countDocuments",
+                collection: collectionName,
+            });
+            throw k2;
         }
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frogfish/k2db",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "A data handling library for K2 applications.",
   "type": "module",
   "main": "data.js",
@@ -18,8 +18,8 @@
   "license": "GPL-3.0-only",
   "author": "El'Diablo",
   "dependencies": {
-    "@frogfish/k2error": "^3.0.1",
-    "@frogfish/ratatouille": "^0.1.7",
+    "@frogfish/k2error": "^3.0.2",
+    "@frogfish/ratatouille": "^1.0.0",
     "debug": "^4.3.7",
     "mongodb": "^6.9.0",
     "uuid": "^10.0.0",