s3db.js 11.2.3 → 11.2.5

package/dist/s3db.cjs.js

@@ -81,6 +81,41 @@ const decodeDecimal = (s) => {
   const num = decPart ? Number(decodedInt + "." + decPart) : decodedInt;
   return negative ? -num : num;
 };
+const encodeFixedPoint = (n, precision = 6) => {
+  if (typeof n !== "number" || isNaN(n)) return "undefined";
+  if (!isFinite(n)) return "undefined";
+  const scale = Math.pow(10, precision);
+  const scaled = Math.round(n * scale);
+  if (scaled === 0) return "^0";
+  const negative = scaled < 0;
+  let num = Math.abs(scaled);
+  let s = "";
+  while (num > 0) {
+    s = alphabet[num % base] + s;
+    num = Math.floor(num / base);
+  }
+  return "^" + (negative ? "-" : "") + s;
+};
+const decodeFixedPoint = (s, precision = 6) => {
+  if (typeof s !== "string") return NaN;
+  if (!s.startsWith("^")) return NaN;
+  s = s.slice(1);
+  if (s === "0") return 0;
+  let negative = false;
+  if (s[0] === "-") {
+    negative = true;
+    s = s.slice(1);
+  }
+  let r = 0;
+  for (let i = 0; i < s.length; i++) {
+    const idx = charToValue[s[i]];
+    if (idx === void 0) return NaN;
+    r = r * base + idx;
+  }
+  const scale = Math.pow(10, precision);
+  const scaled = negative ? -r : r;
+  return scaled / scale;
+};
 
 const utf8BytesMemory = /* @__PURE__ */ new Map();
 const UTF8_MEMORY_MAX_SIZE = 1e4;
@@ -222,7 +257,7 @@ function calculateEffectiveLimit(config = {}) {
 }
 
 class BaseError extends Error {
-  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, suggestion, description, ...rest }) {
+  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, description, ...rest }) {
     if (verbose) message = message + `
 
 Verbose:
@@ -247,7 +282,6 @@ ${JSON.stringify(rest, null, 2)}`;
     this.commandName = commandName;
     this.commandInput = commandInput;
     this.metadata = metadata;
-    this.suggestion = suggestion;
     this.description = description;
     this.data = { bucket, key, ...rest, verbose, message };
   }
@@ -265,7 +299,6 @@ ${JSON.stringify(rest, null, 2)}`;
       commandName: this.commandName,
       commandInput: this.commandInput,
       metadata: this.metadata,
-      suggestion: this.suggestion,
       description: this.description,
       data: this.data,
       original: this.original,
@@ -406,26 +439,26 @@ function mapAwsError(err, context = {}) {
   const metadata = err.$metadata ? { ...err.$metadata } : void 0;
   const commandName = context.commandName;
   const commandInput = context.commandInput;
-  let suggestion;
+  let description;
   if (code === "NoSuchKey" || code === "NotFound") {
-    suggestion = "Check if the key exists in the specified bucket and if your credentials have permission.";
-    return new NoSuchKey({ ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "The specified key does not exist in the bucket. Check if the key exists and if your credentials have permission to access it.";
+    return new NoSuchKey({ ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === "NoSuchBucket") {
-    suggestion = "Check if the bucket exists and if your credentials have permission.";
-    return new NoSuchBucket({ ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "The specified bucket does not exist. Check if the bucket name is correct and if your credentials have permission to access it.";
+    return new NoSuchBucket({ ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === "AccessDenied" || err.statusCode === 403 || code === "Forbidden") {
-    suggestion = "Check your credentials and bucket policy.";
-    return new PermissionError("Access denied", { ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "Access denied. Check your AWS credentials, IAM permissions, and bucket policy.";
+    return new PermissionError("Access denied", { ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === "ValidationError" || err.statusCode === 400) {
-    suggestion = "Check the request parameters and payload.";
-    return new ValidationError("Validation error", { ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "Validation error. Check the request parameters and payload format.";
+    return new ValidationError("Validation error", { ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === "MissingMetadata") {
-    suggestion = "Check if the object metadata is present and valid.";
-    return new MissingMetadata({ ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "Object metadata is missing or invalid. Check if the object was uploaded correctly.";
+    return new MissingMetadata({ ...context, original: err, metadata, commandName, commandInput, description });
   }
   const errorDetails = [
     `Unknown error: ${err.message || err.toString()}`,
@@ -433,27 +466,31 @@ function mapAwsError(err, context = {}) {
     err.statusCode && `Status: ${err.statusCode}`,
     err.stack && `Stack: ${err.stack.split("\n")[0]}`
   ].filter(Boolean).join(" | ");
-  suggestion = `Check the error details and AWS documentation. Original error: ${err.message || err.toString()}`;
-  return new UnknownError(errorDetails, { ...context, original: err, metadata, commandName, commandInput, suggestion });
+  description = `Check the error details and AWS documentation. Original error: ${err.message || err.toString()}`;
+  return new UnknownError(errorDetails, { ...context, original: err, metadata, commandName, commandInput, description });
 }
 class ConnectionStringError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: "Check the connection string format and credentials." });
+    const description = details.description || "Invalid connection string format. Check the connection string syntax and credentials.";
+    super(message, { ...details, description });
   }
 }
 class CryptoError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: "Check if the crypto library is available and input is valid." });
+    const description = details.description || "Cryptography operation failed. Check if the crypto library is available and input is valid.";
+    super(message, { ...details, description });
   }
 }
 class SchemaError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: "Check schema definition and input data." });
+    const description = details.description || "Schema validation failed. Check schema definition and input data format.";
+    super(message, { ...details, description });
   }
 }
 class ResourceError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: details.suggestion || "Check resource configuration, attributes, and operation context." });
+    const description = details.description || "Resource operation failed. Check resource configuration, attributes, and operation context.";
+    super(message, { ...details, description });
     Object.assign(this, details);
   }
 }
@@ -482,13 +519,12 @@ ${details.strictValidation === false ? "  \u2022 Update partition definition to
   \u2022 Update partition definition to use existing fields, OR
   \u2022 Use strictValidation: false to skip this check during testing`}
 
-Docs: https://docs.s3db.js.org/resources/partitions#validation
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partitions
 `.trim();
     }
     super(message, {
       ...details,
-      description,
-      suggestion: details.suggestion || "Check partition definition, fields, and input values."
+      description
     });
   }
 }
@@ -547,7 +583,7 @@ Example fix:
   await db.connect();  // Plugin initialized here
   await db.createResource({ name: '${resourceName}', ... });  // Analytics resource created here
 
-Docs: https://docs.s3db.js.org/plugins/eventual-consistency#troubleshooting
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/eventual-consistency.md
 `.trim();
     super(message, {
       ...rest,
@@ -557,8 +593,260 @@ Docs: https://docs.s3db.js.org/plugins/eventual-consistency#troubleshooting
       configuredResources,
       registeredResources,
       pluginInitialized,
-      description,
-      suggestion: "Ensure resources are created after plugin initialization. Check plugin configuration and resource creation order."
+      description
+    });
+  }
+}
+class PluginError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      pluginName = "Unknown",
+      operation = "unknown",
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Plugin Error
+
+Plugin: ${pluginName}
+Operation: ${operation}
+
+Possible causes:
+1. Plugin not properly initialized
+2. Plugin configuration is invalid
+3. Plugin dependencies not met
+4. Plugin method called before installation
+
+Solution:
+Ensure plugin is added to database and connect() is called before usage.
+
+Example:
+  const db = new Database({
+    bucket: 'my-bucket',
+    plugins: [new ${pluginName}({ /* config */ })]
+  });
+
+  await db.connect();  // Plugin installed here
+  // Now plugin methods are available
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/README.md
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      pluginName,
+      operation,
+      description
+    });
+  }
+}
+class PluginStorageError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      pluginSlug = "unknown",
+      key = "",
+      operation = "unknown",
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Plugin Storage Error
+
+Plugin: ${pluginSlug}
+Key: ${key}
+Operation: ${operation}
+
+Possible causes:
+1. Storage not initialized (plugin not installed)
+2. Invalid key format
+3. S3 operation failed
+4. Permissions issue
+
+Solution:
+Ensure plugin has access to storage and key is valid.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/README.md#plugin-storage
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      pluginSlug,
+      key,
+      operation,
+      description
+    });
+  }
+}
+class PartitionDriverError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      driver = "unknown",
+      operation = "unknown",
+      queueSize,
+      maxQueueSize,
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description && queueSize !== void 0 && maxQueueSize !== void 0) {
+      description = `
+Partition Driver Error
+
+Driver: ${driver}
+Operation: ${operation}
+Queue Status: ${queueSize}/${maxQueueSize}
+
+Possible causes:
+1. Queue is full (backpressure)
+2. Driver not properly configured
+3. SQS permissions issue (if using SQS driver)
+
+Solution:
+${queueSize >= maxQueueSize ? "Wait for queue to drain or increase maxQueueSize" : "Check driver configuration and permissions"}
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partition-drivers
+`.trim();
+    } else if (!description) {
+      description = `
+Partition Driver Error
+
+Driver: ${driver}
+Operation: ${operation}
+
+Check driver configuration and permissions.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partition-drivers
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      driver,
+      operation,
+      queueSize,
+      maxQueueSize,
+      description
+    });
+  }
+}
+class BehaviorError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      behavior = "unknown",
+      availableBehaviors = [],
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Behavior Error
+
+Requested: ${behavior}
+Available: ${availableBehaviors.join(", ") || "body-overflow, body-only, truncate-data, enforce-limits, user-managed"}
+
+Possible causes:
+1. Behavior name misspelled
+2. Custom behavior not registered
+
+Solution:
+Use one of the available behaviors or register custom behavior.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#behaviors
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      behavior,
+      availableBehaviors,
+      description
+    });
+  }
+}
+class StreamError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      operation = "unknown",
+      resource,
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Stream Error
+
+Operation: ${operation}
+${resource ? `Resource: ${resource}` : ""}
+
+Possible causes:
+1. Stream not properly initialized
+2. Resource not available
+3. Network error during streaming
+
+Solution:
+Check stream configuration and resource availability.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#streaming
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      operation,
+      resource,
+      description
+    });
+  }
+}
+class MetadataLimitError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit = 2047,
+      excess,
+      resourceName,
+      operation,
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description && totalSize && effectiveLimit) {
+      description = `
+S3 Metadata Size Limit Exceeded
+
+Current Size: ${totalSize} bytes
+Effective Limit: ${effectiveLimit} bytes
+Absolute Limit: ${absoluteLimit} bytes
+${excess ? `Excess: ${excess} bytes` : ""}
+${resourceName ? `Resource: ${resourceName}` : ""}
+${operation ? `Operation: ${operation}` : ""}
+
+S3 has a hard limit of 2KB (2047 bytes) for object metadata.
+
+Solutions:
+1. Use 'body-overflow' behavior to store excess in body
+2. Use 'body-only' behavior to store everything in body
+3. Reduce number of fields
+4. Use shorter field values
+5. Enable advanced metadata encoding
+
+Example:
+  await db.createResource({
+    name: '${resourceName || "myResource"}',
+    behavior: 'body-overflow',  // Automatically handles overflow
+    attributes: { ... }
+  });
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#metadata-size-limits
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      totalSize,
+      effectiveLimit,
+      absoluteLimit,
+      excess,
+      resourceName,
+      operation,
+      description
     });
   }
 }
@@ -902,10 +1190,17 @@ class PluginStorage {
    */
   constructor(client, pluginSlug) {
     if (!client) {
-      throw new Error("PluginStorage requires a client instance");
+      throw new PluginStorageError("PluginStorage requires a client instance", {
+        operation: "constructor",
+        pluginSlug,
+        suggestion: "Pass a valid S3db Client instance when creating PluginStorage"
+      });
     }
     if (!pluginSlug) {
-      throw new Error("PluginStorage requires a pluginSlug");
+      throw new PluginStorageError("PluginStorage requires a pluginSlug", {
+        operation: "constructor",
+        suggestion: 'Provide a plugin slug (e.g., "eventual-consistency", "cache", "audit")'
+      });
     }
     this.client = client;
     this.pluginSlug = pluginSlug;
@@ -958,7 +1253,15 @@ class PluginStorage {
     }
     const [ok, err] = await tryFn(() => this.client.putObject(putParams));
     if (!ok) {
-      throw new Error(`PluginStorage.set failed for key ${key}: ${err.message}`);
+      throw new PluginStorageError(`Failed to save plugin data`, {
+        pluginSlug: this.pluginSlug,
+        key,
+        operation: "set",
+        behavior,
+        ttl,
+        original: err,
+        suggestion: "Check S3 permissions and key format"
+      });
     }
   }
   /**
@@ -980,7 +1283,13 @@ class PluginStorage {
       if (err.name === "NoSuchKey" || err.Code === "NoSuchKey") {
         return null;
       }
-      throw new Error(`PluginStorage.get failed for key ${key}: ${err.message}`);
+      throw new PluginStorageError(`Failed to retrieve plugin data`, {
+        pluginSlug: this.pluginSlug,
+        key,
+        operation: "get",
+        original: err,
+        suggestion: "Check if the key exists and S3 permissions are correct"
+      });
     }
     const metadata = response.Metadata || {};
     const parsedMetadata = this._parseMetadataValues(metadata);
@@ -993,7 +1302,13 @@ class PluginStorage {
           data = { ...parsedMetadata, ...body };
         }
       } catch (parseErr) {
-        throw new Error(`PluginStorage.get failed to parse body for key ${key}: ${parseErr.message}`);
+        throw new PluginStorageError(`Failed to parse JSON body`, {
+          pluginSlug: this.pluginSlug,
+          key,
+          operation: "get",
+          original: parseErr,
+          suggestion: "Body content may be corrupted. Check S3 object integrity"
+        });
       }
     }
     const expiresAt = data._expiresat || data._expiresAt;
@@ -1054,7 +1369,15 @@ class PluginStorage {
       () => this.client.listObjects({ prefix: fullPrefix, maxKeys: limit })
     );
     if (!ok) {
-      throw new Error(`PluginStorage.list failed: ${err.message}`);
+      throw new PluginStorageError(`Failed to list plugin data`, {
+        pluginSlug: this.pluginSlug,
+        operation: "list",
+        prefix,
+        fullPrefix,
+        limit,
+        original: err,
+        suggestion: "Check S3 permissions and bucket configuration"
+      });
     }
     const keys = result.Contents?.map((item) => item.Key) || [];
     return this._removeKeyPrefix(keys);
@@ -1074,7 +1397,16 @@ class PluginStorage {
       () => this.client.listObjects({ prefix: fullPrefix, maxKeys: limit })
     );
     if (!ok) {
-      throw new Error(`PluginStorage.listForResource failed: ${err.message}`);
+      throw new PluginStorageError(`Failed to list resource data`, {
+        pluginSlug: this.pluginSlug,
+        operation: "listForResource",
+        resourceName,
+        subPrefix,
+        fullPrefix,
+        limit,
+        original: err,
+        suggestion: "Check resource name and S3 permissions"
+      });
     }
     const keys = result.Contents?.map((item) => item.Key) || [];
     return this._removeKeyPrefix(keys);
@@ -1214,7 +1546,13 @@ class PluginStorage {
   async delete(key) {
     const [ok, err] = await tryFn(() => this.client.deleteObject(key));
     if (!ok) {
-      throw new Error(`PluginStorage.delete failed for key ${key}: ${err.message}`);
+      throw new PluginStorageError(`Failed to delete plugin data`, {
+        pluginSlug: this.pluginSlug,
+        key,
+        operation: "delete",
+        original: err,
+        suggestion: "Check S3 delete permissions"
+      });
     }
   }
   /**
@@ -1401,16 +1739,28 @@ class PluginStorage {
           const valueSize = calculateUTF8Bytes(encoded);
           currentSize += keySize + valueSize;
           if (currentSize > effectiveLimit) {
-            throw new Error(
-              `Data exceeds metadata limit (${currentSize} > ${effectiveLimit} bytes). Use 'body-overflow' or 'body-only' behavior.`
-            );
+            throw new MetadataLimitError(`Data exceeds metadata limit with enforce-limits behavior`, {
+              totalSize: currentSize,
+              effectiveLimit,
+              absoluteLimit: S3_METADATA_LIMIT,
+              excess: currentSize - effectiveLimit,
+              operation: "PluginStorage.set",
+              pluginSlug: this.pluginSlug,
+              suggestion: "Use 'body-overflow' or 'body-only' behavior to handle large data"
+            });
           }
           metadata[key] = jsonValue;
         }
         break;
       }
       default:
-        throw new Error(`Unknown behavior: ${behavior}. Use 'body-overflow', 'body-only', or 'enforce-limits'.`);
+        throw new BehaviorError(`Unknown behavior: ${behavior}`, {
+          behavior,
+          availableBehaviors: ["body-overflow", "body-only", "enforce-limits"],
+          operation: "PluginStorage._applyBehavior",
+          pluginSlug: this.pluginSlug,
+          suggestion: "Use 'body-overflow', 'body-only', or 'enforce-limits'"
+        });
     }
     return { metadata, body };
   }
@@ -1975,6 +2325,35 @@ class AuditPlugin extends Plugin {
   }
 }
 
+class BackupError extends S3dbError {
+  constructor(message, details = {}) {
+    const { driver = "unknown", operation = "unknown", backupId, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Backup Operation Error
+
+Driver: ${driver}
+Operation: ${operation}
+${backupId ? `Backup ID: ${backupId}` : ""}
+
+Common causes:
+1. Invalid backup driver configuration
+2. Destination storage not accessible
+3. Insufficient permissions
+4. Network connectivity issues
+5. Invalid backup file format
+
+Solution:
+Check driver configuration and ensure destination storage is accessible.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/backup.md
+`.trim();
+    }
+    super(message, { ...rest, driver, operation, backupId, description });
+  }
+}
+
 class BaseBackupDriver {
   constructor(config = {}) {
     this.config = {
@@ -2005,7 +2384,12 @@ class BaseBackupDriver {
    * @returns {Object} Upload result with destination info
    */
   async upload(filePath, backupId, manifest) {
-    throw new Error("upload() method must be implemented by subclass");
+    throw new BackupError("upload() method must be implemented by subclass", {
+      operation: "upload",
+      driver: this.constructor.name,
+      backupId,
+      suggestion: "Extend BaseBackupDriver and implement the upload() method"
+    });
   }
   /**
    * Download a backup file from the destination
@@ -2015,7 +2399,12 @@ class BaseBackupDriver {
    * @returns {string} Path to downloaded file
    */
   async download(backupId, targetPath, metadata) {
-    throw new Error("download() method must be implemented by subclass");
+    throw new BackupError("download() method must be implemented by subclass", {
+      operation: "download",
+      driver: this.constructor.name,
+      backupId,
+      suggestion: "Extend BaseBackupDriver and implement the download() method"
+    });
   }
   /**
    * Delete a backup from the destination
@@ -2023,7 +2412,12 @@ class BaseBackupDriver {
    * @param {Object} metadata - Backup metadata
    */
   async delete(backupId, metadata) {
-    throw new Error("delete() method must be implemented by subclass");
+    throw new BackupError("delete() method must be implemented by subclass", {
+      operation: "delete",
+      driver: this.constructor.name,
+      backupId,
+      suggestion: "Extend BaseBackupDriver and implement the delete() method"
+    });
   }
   /**
    * List backups available in the destination
@@ -2031,7 +2425,11 @@ class BaseBackupDriver {
    * @returns {Array} List of backup metadata
    */
   async list(options = {}) {
-    throw new Error("list() method must be implemented by subclass");
+    throw new BackupError("list() method must be implemented by subclass", {
+      operation: "list",
+      driver: this.constructor.name,
+      suggestion: "Extend BaseBackupDriver and implement the list() method"
+    });
   }
   /**
    * Verify backup integrity
@@ -2041,14 +2439,23 @@ class BaseBackupDriver {
    * @returns {boolean} True if backup is valid
    */
   async verify(backupId, expectedChecksum, metadata) {
-    throw new Error("verify() method must be implemented by subclass");
+    throw new BackupError("verify() method must be implemented by subclass", {
+      operation: "verify",
+      driver: this.constructor.name,
+      backupId,
+      suggestion: "Extend BaseBackupDriver and implement the verify() method"
+    });
   }
   /**
    * Get driver type identifier
    * @returns {string} Driver type
    */
   getType() {
-    throw new Error("getType() method must be implemented by subclass");
+    throw new BackupError("getType() method must be implemented by subclass", {
+      operation: "getType",
+      driver: this.constructor.name,
+      suggestion: "Extend BaseBackupDriver and implement the getType() method"
+    });
   }
   /**
    * Get driver-specific storage info
@@ -2090,7 +2497,11 @@ class FilesystemBackupDriver extends BaseBackupDriver {
   }
   async onSetup() {
     if (!this.config.path) {
-      throw new Error("FilesystemBackupDriver: path configuration is required");
+      throw new BackupError("FilesystemBackupDriver: path configuration is required", {
+        operation: "onSetup",
+        driver: "filesystem",
+        suggestion: 'Provide a path in config: new FilesystemBackupDriver({ path: "/path/to/backups" })'
+      });
     }
     this.log(`Initialized with path: ${this.config.path}`);
   }
@@ -2114,11 +2525,26 @@ class FilesystemBackupDriver extends BaseBackupDriver {
       () => promises.mkdir(targetDir, { recursive: true, mode: this.config.directoryPermissions })
     );
     if (!createDirOk) {
-      throw new Error(`Failed to create backup directory: ${createDirErr.message}`);
+      throw new BackupError("Failed to create backup directory", {
+        operation: "upload",
+        driver: "filesystem",
+        backupId,
+        targetDir,
+        original: createDirErr,
+        suggestion: "Check directory permissions and disk space"
+      });
     }
     const [copyOk, copyErr] = await tryFn(() => promises.copyFile(filePath, targetPath));
     if (!copyOk) {
-      throw new Error(`Failed to copy backup file: ${copyErr.message}`);
+      throw new BackupError("Failed to copy backup file", {
+        operation: "upload",
+        driver: "filesystem",
+        backupId,
+        filePath,
+        targetPath,
+        original: copyErr,
+        suggestion: "Check file permissions and disk space"
+      });
     }
     const [manifestOk, manifestErr] = await tryFn(
       () => import('fs/promises').then((fs) => fs.writeFile(
@@ -2129,7 +2555,14 @@ class FilesystemBackupDriver extends BaseBackupDriver {
     );
     if (!manifestOk) {
       await tryFn(() => promises.unlink(targetPath));
-      throw new Error(`Failed to write manifest: ${manifestErr.message}`);
+      throw new BackupError("Failed to write manifest file", {
+        operation: "upload",
+        driver: "filesystem",
+        backupId,
+        manifestPath,
+        original: manifestErr,
+        suggestion: "Check directory permissions and disk space"
+      });
     }
     const [statOk, , stats] = await tryFn(() => promises.stat(targetPath));
     const size = statOk ? stats.size : 0;
@@ -2148,13 +2581,27 @@ class FilesystemBackupDriver extends BaseBackupDriver {
     );
     const [existsOk] = await tryFn(() => promises.access(sourcePath));
     if (!existsOk) {
-      throw new Error(`Backup file not found: ${sourcePath}`);
+      throw new BackupError("Backup file not found", {
+        operation: "download",
+        driver: "filesystem",
+        backupId,
+        sourcePath,
+        suggestion: "Check if backup exists using list() method"
+      });
     }
     const targetDir = path.dirname(targetPath);
     await tryFn(() => promises.mkdir(targetDir, { recursive: true }));
     const [copyOk, copyErr] = await tryFn(() => promises.copyFile(sourcePath, targetPath));
     if (!copyOk) {
-      throw new Error(`Failed to download backup: ${copyErr.message}`);
+      throw new BackupError("Failed to download backup", {
+        operation: "download",
+        driver: "filesystem",
+        backupId,
+        sourcePath,
+        targetPath,
+        original: copyErr,
+        suggestion: "Check file permissions and disk space"
+      });
     }
     this.log(`Downloaded backup ${backupId} from ${sourcePath} to ${targetPath}`);
     return targetPath;
@@ -2171,7 +2618,14 @@ class FilesystemBackupDriver extends BaseBackupDriver {
     const [deleteBackupOk] = await tryFn(() => promises.unlink(backupPath));
     const [deleteManifestOk] = await tryFn(() => promises.unlink(manifestPath));
     if (!deleteBackupOk && !deleteManifestOk) {
-      throw new Error(`Failed to delete backup files for ${backupId}`);
+      throw new BackupError("Failed to delete backup files", {
+        operation: "delete",
+        driver: "filesystem",
+        backupId,
+        backupPath,
+        manifestPath,
+        suggestion: "Check file permissions"
+      });
     }
     this.log(`Deleted backup ${backupId}`);
   }
@@ -2276,10 +2730,18 @@ class S3BackupDriver extends BaseBackupDriver {
       this.config.bucket = this.database.bucket;
     }
     if (!this.config.client) {
-      throw new Error("S3BackupDriver: client is required (either via config or database)");
+      throw new BackupError("S3BackupDriver: client is required", {
+        operation: "onSetup",
+        driver: "s3",
+        suggestion: "Provide a client in config or ensure database has a client configured"
+      });
     }
     if (!this.config.bucket) {
-      throw new Error("S3BackupDriver: bucket is required (either via config or database)");
+      throw new BackupError("S3BackupDriver: bucket is required", {
+        operation: "onSetup",
+        driver: "s3",
+        suggestion: "Provide a bucket in config or ensure database has a bucket configured"
+      });
     }
     this.log(`Initialized with bucket: ${this.config.bucket}, path: ${this.config.path}`);
   }
@@ -2321,7 +2783,15 @@ class S3BackupDriver extends BaseBackupDriver {
       });
     });
     if (!uploadOk) {
-      throw new Error(`Failed to upload backup file: ${uploadErr.message}`);
+      throw new BackupError("Failed to upload backup file to S3", {
+        operation: "upload",
+        driver: "s3",
+        backupId,
+        bucket: this.config.bucket,
+        key: backupKey,
+        original: uploadErr,
+        suggestion: "Check S3 permissions and bucket configuration"
+      });
     }
     const [manifestOk, manifestErr] = await tryFn(
       () => this.config.client.uploadObject({
@@ -2342,7 +2812,15 @@ class S3BackupDriver extends BaseBackupDriver {
         bucket: this.config.bucket,
         key: backupKey
       }));
-      throw new Error(`Failed to upload manifest: ${manifestErr.message}`);
+      throw new BackupError("Failed to upload manifest to S3", {
+        operation: "upload",
+        driver: "s3",
+        backupId,
+        bucket: this.config.bucket,
+        manifestKey,
+        original: manifestErr,
+        suggestion: "Check S3 permissions and bucket configuration"
+      });
     }
     this.log(`Uploaded backup ${backupId} to s3://${this.config.bucket}/${backupKey} (${fileSize} bytes)`);
     return {
@@ -2365,7 +2843,16 @@ class S3BackupDriver extends BaseBackupDriver {
       })
     );
     if (!downloadOk) {
-      throw new Error(`Failed to download backup: ${downloadErr.message}`);
+      throw new BackupError("Failed to download backup from S3", {
+        operation: "download",
+        driver: "s3",
+        backupId,
+        bucket: this.config.bucket,
+        key: backupKey,
+        targetPath,
+        original: downloadErr,
+        suggestion: "Check if backup exists and S3 permissions are correct"
+      });
     }
     this.log(`Downloaded backup ${backupId} from s3://${this.config.bucket}/${backupKey} to ${targetPath}`);
     return targetPath;
@@ -2386,7 +2873,15 @@ class S3BackupDriver extends BaseBackupDriver {
       })
     );
     if (!deleteBackupOk && !deleteManifestOk) {
-      throw new Error(`Failed to delete backup objects for ${backupId}`);
+      throw new BackupError("Failed to delete backup from S3", {
+        operation: "delete",
+        driver: "s3",
+        backupId,
+        bucket: this.config.bucket,
+        backupKey,
+        manifestKey,
+        suggestion: "Check S3 delete permissions"
+      });
     }
     this.log(`Deleted backup ${backupId} from S3`);
   }
@@ -2499,11 +2994,22 @@ class MultiBackupDriver extends BaseBackupDriver {
   }
   async onSetup() {
     if (!Array.isArray(this.config.destinations) || this.config.destinations.length === 0) {
-      throw new Error("MultiBackupDriver: destinations array is required and must not be empty");
+      throw new BackupError("MultiBackupDriver requires non-empty destinations array", {
+        operation: "onSetup",
+        driver: "multi",
+        destinationsProvided: this.config.destinations,
+        suggestion: 'Provide destinations array: { destinations: [{ driver: "s3", config: {...} }, { driver: "filesystem", config: {...} }] }'
+      });
     }
     for (const [index, destConfig] of this.config.destinations.entries()) {
       if (!destConfig.driver) {
-        throw new Error(`MultiBackupDriver: destination[${index}] must have a driver type`);
+        throw new BackupError(`Destination ${index} missing driver type`, {
+          operation: "onSetup",
+          driver: "multi",
+          destinationIndex: index,
+          destination: destConfig,
+          suggestion: 'Each destination must have a driver property: { driver: "s3", config: {...} } or { driver: "filesystem", config: {...} }'
+        });
       }
       try {
         const driver = createBackupDriver(destConfig.driver, destConfig.config || {});
@@ -2515,7 +3021,15 @@ class MultiBackupDriver extends BaseBackupDriver {
         });
         this.log(`Setup destination ${index}: ${destConfig.driver}`);
       } catch (error) {
-        throw new Error(`Failed to setup destination ${index} (${destConfig.driver}): ${error.message}`);
+        throw new BackupError(`Failed to setup destination ${index}`, {
+          operation: "onSetup",
+          driver: "multi",
+          destinationIndex: index,
+          destinationDriver: destConfig.driver,
+          destinationConfig: destConfig.config,
+          original: error,
+          suggestion: "Check destination driver configuration and ensure dependencies are available"
+        });
       }
     }
     if (this.config.requireAll === false) {
@@ -2544,7 +3058,15 @@ class MultiBackupDriver extends BaseBackupDriver {
           this.log(`Priority upload failed to destination ${index}: ${err.message}`);
         }
       }
-      throw new Error(`All priority destinations failed: ${errors.map((e) => `${e.destination}: ${e.error}`).join("; ")}`);
+      throw new BackupError("All priority destinations failed", {
+        operation: "upload",
+        driver: "multi",
+        strategy: "priority",
+        backupId,
+        totalDestinations: this.drivers.length,
+        failures: errors,
+        suggestion: "Check destination configurations and ensure at least one destination is accessible"
+      });
     }
     const uploadPromises = this.drivers.map(async ({ driver, config, index }) => {
       const [ok, err, result] = await tryFn(
@@ -2574,10 +3096,28 @@ class MultiBackupDriver extends BaseBackupDriver {
     const successResults = allResults.filter((r) => r.status === "success");
     const failedResults = allResults.filter((r) => r.status === "failed");
     if (strategy === "all" && failedResults.length > 0) {
-      throw new Error(`Some destinations failed: ${failedResults.map((r) => `${r.destination}: ${r.error}`).join("; ")}`);
+      throw new BackupError('Some destinations failed with strategy "all"', {
+        operation: "upload",
+        driver: "multi",
+        strategy: "all",
+        backupId,
+        totalDestinations: this.drivers.length,
+        successCount: successResults.length,
+        failedCount: failedResults.length,
+        failures: failedResults,
+        suggestion: 'All destinations must succeed with "all" strategy. Use "any" strategy to tolerate failures, or fix failing destinations.'
+      });
     }
     if (strategy === "any" && successResults.length === 0) {
-      throw new Error(`All destinations failed: ${failedResults.map((r) => `${r.destination}: ${r.error}`).join("; ")}`);
+      throw new BackupError('All destinations failed with strategy "any"', {
+        operation: "upload",
+        driver: "multi",
+        strategy: "any",
+        backupId,
+        totalDestinations: this.drivers.length,
+        failures: failedResults,
+        suggestion: 'At least one destination must succeed with "any" strategy. Check all destination configurations.'
+      });
     }
     return allResults;
   }
@@ -2597,7 +3137,14 @@ class MultiBackupDriver extends BaseBackupDriver {
         this.log(`Download failed from destination ${destMetadata.destination}: ${err.message}`);
       }
     }
-    throw new Error(`Failed to download backup from any destination`);
+    throw new BackupError("Failed to download backup from any destination", {
+      operation: "download",
+      driver: "multi",
+      backupId,
+      targetPath,
+      attemptedDestinations: destinations.length,
+      suggestion: "Check if backup exists in at least one destination and destinations are accessible"
+    });
   }
   async delete(backupId, metadata) {
     const destinations = Array.isArray(metadata.destinations) ? metadata.destinations : [metadata];
@@ -2619,7 +3166,14 @@ class MultiBackupDriver extends BaseBackupDriver {
       }
     }
     if (successCount === 0 && errors.length > 0) {
-      throw new Error(`Failed to delete from any destination: ${errors.join("; ")}`);
+      throw new BackupError("Failed to delete from any destination", {
+        operation: "delete",
+        driver: "multi",
+        backupId,
+        attemptedDestinations: destinations.length,
+        failures: errors,
+        suggestion: "Check if backup exists in destinations and destinations are accessible with delete permissions"
+      });
     }
     if (errors.length > 0) {
       this.log(`Partial delete success, some errors: ${errors.join("; ")}`);
@@ -2719,32 +3273,62 @@ const BACKUP_DRIVERS = {
 function createBackupDriver(driver, config = {}) {
   const DriverClass = BACKUP_DRIVERS[driver];
   if (!DriverClass) {
-    throw new Error(`Unknown backup driver: ${driver}. Available drivers: ${Object.keys(BACKUP_DRIVERS).join(", ")}`);
+    throw new BackupError(`Unknown backup driver: ${driver}`, {
+      operation: "createBackupDriver",
+      driver,
+      availableDrivers: Object.keys(BACKUP_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(BACKUP_DRIVERS).join(", ")}`
+    });
   }
   return new DriverClass(config);
 }
 function validateBackupConfig(driver, config = {}) {
   if (!driver || typeof driver !== "string") {
-    throw new Error("Driver type must be a non-empty string");
+    throw new BackupError("Driver type must be a non-empty string", {
+      operation: "validateBackupConfig",
+      driver,
+      suggestion: "Provide a valid driver type string (filesystem, s3, or multi)"
+    });
   }
   if (!BACKUP_DRIVERS[driver]) {
-    throw new Error(`Unknown backup driver: ${driver}. Available drivers: ${Object.keys(BACKUP_DRIVERS).join(", ")}`);
+    throw new BackupError(`Unknown backup driver: ${driver}`, {
+      operation: "validateBackupConfig",
+      driver,
+      availableDrivers: Object.keys(BACKUP_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(BACKUP_DRIVERS).join(", ")}`
+    });
   }
   switch (driver) {
     case "filesystem":
       if (!config.path) {
-        throw new Error('FilesystemBackupDriver requires "path" configuration');
+        throw new BackupError('FilesystemBackupDriver requires "path" configuration', {
+          operation: "validateBackupConfig",
+          driver: "filesystem",
+          config,
+          suggestion: 'Provide a "path" property in config: { path: "/path/to/backups" }'
+        });
       }
       break;
     case "s3":
       break;
     case "multi":
       if (!Array.isArray(config.destinations) || config.destinations.length === 0) {
-        throw new Error('MultiBackupDriver requires non-empty "destinations" array');
+        throw new BackupError('MultiBackupDriver requires non-empty "destinations" array', {
+          operation: "validateBackupConfig",
+          driver: "multi",
+          config,
+          suggestion: 'Provide destinations array: { destinations: [{ driver: "s3", config: {...} }] }'
+        });
       }
       config.destinations.forEach((dest, index) => {
         if (!dest.driver) {
-          throw new Error(`Destination ${index} must have a "driver" property`);
+          throw new BackupError(`Destination ${index} must have a "driver" property`, {
+            operation: "validateBackupConfig",
+            driver: "multi",
+            destinationIndex: index,
+            destination: dest,
+            suggestion: 'Each destination must have a driver property: { driver: "s3", config: {...} }'
+          });
         }
         if (dest.driver !== "multi") {
           validateBackupConfig(dest.driver, dest.config || {});
@@ -3400,6 +3984,36 @@ class BackupPlugin extends Plugin {
   }
 }
 
+class CacheError extends S3dbError {
+  constructor(message, details = {}) {
+    const { driver = "unknown", operation = "unknown", resourceName, key, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Cache Operation Error
+
+Driver: ${driver}
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ""}
+${key ? `Key: ${key}` : ""}
+
+Common causes:
+1. Invalid cache key format
+2. Cache driver not properly initialized
+3. Resource not found or not cached
+4. Memory limits exceeded
+5. Filesystem permissions issues
+
+Solution:
+Check cache configuration and ensure the cache driver is properly initialized.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/cache.md
+`.trim();
+    }
+    super(message, { ...rest, driver, operation, resourceName, key, description });
+  }
+}
+
 class Cache extends EventEmitter {
   constructor(config = {}) {
     super();
@@ -3416,7 +4030,13 @@ class Cache extends EventEmitter {
   }
   validateKey(key) {
     if (key === null || key === void 0 || typeof key !== "string" || !key) {
-      throw new Error("Invalid key");
+      throw new CacheError("Invalid cache key", {
+        operation: "validateKey",
+        driver: this.constructor.name,
+        key,
+        keyType: typeof key,
+        suggestion: "Cache key must be a non-empty string"
+      });
     }
   }
   // generic class methods
@@ -3503,7 +4123,11 @@ class ResourceReader extends EventEmitter {
   constructor({ resource, batchSize = 10, concurrency = 5 }) {
     super();
     if (!resource) {
-      throw new Error("Resource is required for ResourceReader");
+      throw new StreamError("Resource is required for ResourceReader", {
+        operation: "constructor",
+        resource: resource?.name,
+        suggestion: "Pass a valid Resource instance when creating ResourceReader"
+      });
     }
     this.resource = resource;
     this.client = resource.client;
@@ -3627,7 +4251,10 @@ class ResourceWriter extends EventEmitter {
 function streamToString(stream) {
   return new Promise((resolve, reject) => {
     if (!stream) {
-      return reject(new Error("streamToString: stream is undefined"));
+      return reject(new StreamError("Stream is undefined", {
+        operation: "streamToString",
+        suggestion: "Ensure a valid stream is passed to streamToString()"
+      }));
     }
     const chunks = [];
     stream.on("data", (chunk) => chunks.push(chunk));
@@ -5121,7 +5748,13 @@ class CachePlugin extends Plugin {
   async warmCache(resourceName, options = {}) {
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new CacheError("Resource not found for cache warming", {
+        operation: "warmCache",
+        driver: this.driver?.constructor.name,
+        resourceName,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: "Check resource name spelling or ensure resource has been created"
+      });
     }
     const { includePartitions = true, sampleSize = 100 } = options;
     if (this.driver instanceof PartitionAwareFilesystemCache && resource.warmPartitionCache) {
@@ -8238,6 +8871,35 @@ class EventualConsistencyPlugin extends Plugin {
   }
 }
 
+class FulltextError extends S3dbError {
+  constructor(message, details = {}) {
+    const { resourceName, query, operation = "unknown", ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Fulltext Search Operation Error
+
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ""}
+${query ? `Query: ${query}` : ""}
+
+Common causes:
+1. Resource not indexed for fulltext search
+2. Invalid query syntax
+3. Index not built yet
+4. Search configuration missing
+5. Field not indexed
+
+Solution:
+Ensure resource is configured for fulltext search and index is built.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/fulltext.md
+`.trim();
+    }
+    super(message, { ...rest, resourceName, query, operation, description });
+  }
+}
+
 class FullTextPlugin extends Plugin {
   constructor(options = {}) {
     super();
@@ -8544,7 +9206,13 @@ class FullTextPlugin extends Plugin {
     }
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new FulltextError(`Resource '${resourceName}' not found`, {
+        operation: "searchRecords",
+        resourceName,
+        query,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: "Check resource name or ensure resource is created before searching"
+      });
     }
     const recordIds = searchResults.map((result2) => result2.recordId);
     const records = await resource.getMany(recordIds);
@@ -8561,7 +9229,12 @@ class FullTextPlugin extends Plugin {
   async rebuildIndex(resourceName) {
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new FulltextError(`Resource '${resourceName}' not found`, {
+        operation: "rebuildIndex",
+        resourceName,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: "Check resource name or ensure resource is created before rebuilding index"
+      });
     }
     for (const [key] of this.indexes.entries()) {
       if (key.startsWith(`${resourceName}:`)) {
@@ -9346,6 +10019,35 @@ function createConsumer(driver, config) {
   return new ConsumerClass(config);
 }
 
+class QueueError extends S3dbError {
+  constructor(message, details = {}) {
+    const { queueName, operation = "unknown", messageId, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Queue Operation Error
+
+Operation: ${operation}
+${queueName ? `Queue: ${queueName}` : ""}
+${messageId ? `Message ID: ${messageId}` : ""}
+
+Common causes:
+1. Queue not properly configured
+2. Message handler not registered
+3. Queue resource not found
+4. SQS/RabbitMQ connection failed
+5. Message processing timeout
+
+Solution:
+Check queue configuration and message handler registration.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/queue.md
+`.trim();
+    }
+    super(message, { ...rest, queueName, operation, messageId, description });
+  }
+}
+
 class QueueConsumerPlugin extends Plugin {
   constructor(options = {}) {
     super(options);
@@ -9406,13 +10108,32 @@ class QueueConsumerPlugin extends Plugin {
     let action = body.action || msg.action;
     let data = body.data || msg.data;
     if (!resource) {
-      throw new Error("QueueConsumerPlugin: resource not found in message");
+      throw new QueueError("Resource not found in message", {
+        operation: "handleMessage",
+        queueName: configuredResource,
+        messageBody: body,
+        suggestion: 'Ensure message includes a "resource" field specifying the target resource name'
+      });
     }
     if (!action) {
-      throw new Error("QueueConsumerPlugin: action not found in message");
+      throw new QueueError("Action not found in message", {
+        operation: "handleMessage",
+        queueName: configuredResource,
+        resource,
+        messageBody: body,
+        suggestion: 'Ensure message includes an "action" field (insert, update, or delete)'
+      });
     }
     const resourceObj = this.database.resources[resource];
-    if (!resourceObj) throw new Error(`QueueConsumerPlugin: resource '${resource}' not found`);
+    if (!resourceObj) {
+      throw new QueueError(`Resource '${resource}' not found`, {
+        operation: "handleMessage",
+        queueName: configuredResource,
+        resource,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: "Check resource name or ensure resource is created before consuming messages"
+      });
+    }
     let result;
     const [ok, err, res] = await tryFn(async () => {
       if (action === "insert") {
@@ -9423,7 +10144,14 @@ class QueueConsumerPlugin extends Plugin {
       } else if (action === "delete") {
         result = await resourceObj.delete(data.id);
       } else {
-        throw new Error(`QueueConsumerPlugin: unsupported action '${action}'`);
+        throw new QueueError(`Unsupported action '${action}'`, {
+          operation: "handleMessage",
+          queueName: configuredResource,
+          resource,
+          action,
+          supportedActions: ["insert", "update", "delete"],
+          suggestion: "Use one of the supported actions: insert, update, or delete"
+        });
       }
       return result;
     });
@@ -9436,6 +10164,35 @@ class QueueConsumerPlugin extends Plugin {
   }
 }
 
+class ReplicationError extends S3dbError {
+  constructor(message, details = {}) {
+    const { replicatorClass = "unknown", operation = "unknown", resourceName, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Replication Operation Error
+
+Replicator: ${replicatorClass}
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ""}
+
+Common causes:
+1. Invalid replicator configuration
+2. Target system not accessible
+3. Resource not configured for replication
+4. Invalid operation type
+5. Transformation function errors
+
+Solution:
+Check replicator configuration and ensure target system is accessible.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/replicator.md
+`.trim();
+    }
+    super(message, { ...rest, replicatorClass, operation, resourceName, description });
+  }
+}
+
 class BaseReplicator extends EventEmitter {
   constructor(config = {}) {
     super();
@@ -9461,7 +10218,12 @@ class BaseReplicator extends EventEmitter {
    * @returns {Promise<Object>} replicator result
    */
   async replicate(resourceName, operation, data, id) {
-    throw new Error(`replicate() method must be implemented by ${this.name}`);
+    throw new ReplicationError("replicate() method must be implemented by subclass", {
+      operation: "replicate",
+      replicatorClass: this.name,
+      resourceName,
+      suggestion: "Extend BaseReplicator and implement the replicate() method"
+    });
   }
   /**
    * Replicate multiple records in batch
@@ -9470,14 +10232,24 @@ class BaseReplicator extends EventEmitter {
    * @returns {Promise<Object>} Batch replicator result
    */
   async replicateBatch(resourceName, records) {
-    throw new Error(`replicateBatch() method must be implemented by ${this.name}`);
+    throw new ReplicationError("replicateBatch() method must be implemented by subclass", {
+      operation: "replicateBatch",
+      replicatorClass: this.name,
+      resourceName,
+      batchSize: records?.length,
+      suggestion: "Extend BaseReplicator and implement the replicateBatch() method"
+    });
   }
   /**
    * Test the connection to the target
    * @returns {Promise<boolean>} True if connection is successful
    */
   async testConnection() {
-    throw new Error(`testConnection() method must be implemented by ${this.name}`);
+    throw new ReplicationError("testConnection() method must be implemented by subclass", {
+      operation: "testConnection",
+      replicatorClass: this.name,
+      suggestion: "Extend BaseReplicator and implement the testConnection() method"
+    });
   }
   /**
    * Get replicator status and statistics
@@ -10649,7 +11421,17 @@ class Client extends EventEmitter {
     });
     this.emit("moveAllObjects", { results, errors }, { prefixFrom, prefixTo });
     if (errors.length > 0) {
-      throw new Error("Some objects could not be moved");
+      throw new UnknownError("Some objects could not be moved", {
+        bucket: this.config.bucket,
+        operation: "moveAllObjects",
+        prefixFrom,
+        prefixTo,
+        totalKeys: keys.length,
+        failedCount: errors.length,
+        successCount: results.length,
+        errors: errors.map((e) => ({ message: e.message, raw: e.raw })),
+        suggestion: "Check S3 permissions and retry failed objects individually"
+      });
     }
     return results;
   }
@@ -10758,6 +11540,11 @@ class Validator extends FastestValidator {
       type: "any",
       custom: this.autoEncrypt ? jsonHandler : void 0
     });
+    this.alias("embedding", {
+      type: "array",
+      items: "number",
+      empty: false
+    });
   }
 }
 const ValidatorManager = new Proxy(Validator, {
@@ -11006,6 +11793,59 @@ const SchemaActions = {
       }
       return NaN;
     });
+  },
+  fromArrayOfEmbeddings: (value, { separator, precision = 6 }) => {
+    if (value === null || value === void 0 || !Array.isArray(value)) {
+      return value;
+    }
+    if (value.length === 0) {
+      return "";
+    }
+    const encodedItems = value.map((item) => {
+      if (typeof item === "number" && !isNaN(item)) {
+        return encodeFixedPoint(item, precision);
+      }
+      const n = Number(item);
+      return isNaN(n) ? "" : encodeFixedPoint(n, precision);
+    });
+    return encodedItems.join(separator);
+  },
+  toArrayOfEmbeddings: (value, { separator, precision = 6 }) => {
+    if (Array.isArray(value)) {
+      return value.map((v) => typeof v === "number" ? v : decodeFixedPoint(v, precision));
+    }
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (value === "") {
+      return [];
+    }
+    const str = String(value);
+    const items = [];
+    let current = "";
+    let i = 0;
+    while (i < str.length) {
+      if (str[i] === "\\" && i + 1 < str.length) {
+        current += str[i + 1];
+        i += 2;
+      } else if (str[i] === separator) {
+        items.push(current);
+        current = "";
+        i++;
+      } else {
+        current += str[i];
+        i++;
+      }
+    }
+    items.push(current);
+    return items.map((v) => {
+      if (typeof v === "number") return v;
+      if (typeof v === "string" && v !== "") {
+        const n = decodeFixedPoint(v, precision);
+        return isNaN(n) ? NaN : n;
+      }
+      return NaN;
+    });
   }
 };
 class Schema {
@@ -11075,18 +11915,89 @@ class Schema {
     }
     return objectKeys;
   }
+  _generateHooksFromOriginalAttributes(attributes, prefix = "") {
+    for (const [key, value] of Object.entries(attributes)) {
+      if (key.startsWith("$$")) continue;
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (typeof value === "object" && value !== null && !Array.isArray(value) && value.type) {
+        if (value.type === "array" && value.items) {
+          const itemsType = value.items;
+          const arrayLength = typeof value.length === "number" ? value.length : null;
+          if (itemsType === "string" || typeof itemsType === "string" && itemsType.includes("string")) {
+            this.addHook("beforeMap", fullKey, "fromArray");
+            this.addHook("afterUnmap", fullKey, "toArray");
+          } else if (itemsType === "number" || typeof itemsType === "string" && itemsType.includes("number")) {
+            const isIntegerArray = typeof itemsType === "string" && itemsType.includes("integer");
+            const isEmbedding = !isIntegerArray && arrayLength !== null && arrayLength >= 256;
+            if (isIntegerArray) {
+              this.addHook("beforeMap", fullKey, "fromArrayOfNumbers");
+              this.addHook("afterUnmap", fullKey, "toArrayOfNumbers");
+            } else if (isEmbedding) {
+              this.addHook("beforeMap", fullKey, "fromArrayOfEmbeddings");
+              this.addHook("afterUnmap", fullKey, "toArrayOfEmbeddings");
+            } else {
+              this.addHook("beforeMap", fullKey, "fromArrayOfDecimals");
+              this.addHook("afterUnmap", fullKey, "toArrayOfDecimals");
+            }
+          }
+        }
+      } else if (typeof value === "object" && value !== null && !Array.isArray(value) && !value.type) {
+        this._generateHooksFromOriginalAttributes(value, fullKey);
+      }
+    }
+  }
   generateAutoHooks() {
+    this._generateHooksFromOriginalAttributes(this.attributes);
     const schema = flat.flatten(lodashEs.cloneDeep(this.attributes), { safe: true });
     for (const [name, definition] of Object.entries(schema)) {
-      if (definition.includes("array")) {
-        if (definition.includes("items:string")) {
+      if (name.includes("$$")) continue;
+      if (this.options.hooks.beforeMap[name] || this.options.hooks.afterUnmap[name]) {
+        continue;
+      }
+      const defStr = typeof definition === "string" ? definition : "";
+      const defType = typeof definition === "object" && definition !== null ? definition.type : null;
+      const isEmbeddingType = defStr.includes("embedding") || defType === "embedding";
+      if (isEmbeddingType) {
+        const lengthMatch = defStr.match(/embedding:(\d+)/);
+        if (lengthMatch) {
+          parseInt(lengthMatch[1], 10);
+        } else if (defStr.includes("length:")) {
+          const match = defStr.match(/length:(\d+)/);
+          if (match) parseInt(match[1], 10);
+        }
+        this.addHook("beforeMap", name, "fromArrayOfEmbeddings");
+        this.addHook("afterUnmap", name, "toArrayOfEmbeddings");
+        continue;
+      }
+      const isArray = defStr.includes("array") || defType === "array";
+      if (isArray) {
+        let itemsType = null;
+        if (typeof definition === "object" && definition !== null && definition.items) {
+          itemsType = definition.items;
+        } else if (defStr.includes("items:string")) {
+          itemsType = "string";
+        } else if (defStr.includes("items:number")) {
+          itemsType = "number";
+        }
+        if (itemsType === "string" || typeof itemsType === "string" && itemsType.includes("string")) {
           this.addHook("beforeMap", name, "fromArray");
           this.addHook("afterUnmap", name, "toArray");
-        } else if (definition.includes("items:number")) {
-          const isIntegerArray = definition.includes("integer:true") || definition.includes("|integer:") || definition.includes("|integer");
+        } else if (itemsType === "number" || typeof itemsType === "string" && itemsType.includes("number")) {
+          const isIntegerArray = defStr.includes("integer:true") || defStr.includes("|integer:") || defStr.includes("|integer") || typeof itemsType === "string" && itemsType.includes("integer");
+          let arrayLength = null;
+          if (typeof definition === "object" && definition !== null && typeof definition.length === "number") {
+            arrayLength = definition.length;
+          } else if (defStr.includes("length:")) {
+            const match = defStr.match(/length:(\d+)/);
+            if (match) arrayLength = parseInt(match[1], 10);
+          }
+          const isEmbedding = !isIntegerArray && arrayLength !== null && arrayLength >= 256;
           if (isIntegerArray) {
             this.addHook("beforeMap", name, "fromArrayOfNumbers");
             this.addHook("afterUnmap", name, "toArrayOfNumbers");
+          } else if (isEmbedding) {
+            this.addHook("beforeMap", name, "fromArrayOfEmbeddings");
+            this.addHook("afterUnmap", name, "toArrayOfEmbeddings");
           } else {
             this.addHook("beforeMap", name, "fromArrayOfDecimals");
             this.addHook("afterUnmap", name, "toArrayOfDecimals");
@@ -11094,7 +12005,7 @@ class Schema {
         }
         continue;
       }
-      if (definition.includes("secret")) {
+      if (defStr.includes("secret") || defType === "secret") {
         if (this.options.autoEncrypt) {
           this.addHook("beforeMap", name, "encrypt");
         }
@@ -11103,8 +12014,8 @@ class Schema {
         }
         continue;
       }
-      if (definition.includes("number")) {
-        const isInteger = definition.includes("integer:true") || definition.includes("|integer:") || definition.includes("|integer");
+      if (defStr.includes("number") || defType === "number") {
+        const isInteger = defStr.includes("integer:true") || defStr.includes("|integer:") || defStr.includes("|integer");
         if (isInteger) {
           this.addHook("beforeMap", name, "toBase62");
           this.addHook("afterUnmap", name, "fromBase62");
@@ -11114,17 +12025,17 @@ class Schema {
         }
         continue;
       }
-      if (definition.includes("boolean")) {
+      if (defStr.includes("boolean") || defType === "boolean") {
         this.addHook("beforeMap", name, "fromBool");
         this.addHook("afterUnmap", name, "toBool");
         continue;
       }
-      if (definition.includes("json")) {
+      if (defStr.includes("json") || defType === "json") {
         this.addHook("beforeMap", name, "toJSON");
         this.addHook("afterUnmap", name, "fromJSON");
         continue;
       }
-      if (definition === "object" || definition.includes("object")) {
+      if (definition === "object" || defStr.includes("object") || defType === "object") {
         this.addHook("beforeMap", name, "toJSON");
         this.addHook("afterUnmap", name, "fromJSON");
         continue;
@@ -11266,7 +12177,8 @@ class Schema {
       const originalKey = reversedMap && reversedMap[key] ? reversedMap[key] : key;
       let parsedValue = value;
       const attrDef = this.getAttributeDefinition(originalKey);
-      if (typeof attrDef === "string" && attrDef.includes("number") && !attrDef.includes("array") && !attrDef.includes("decimal")) {
+      const hasAfterUnmapHook = this.options.hooks?.afterUnmap?.[originalKey];
+      if (!hasAfterUnmapHook && typeof attrDef === "string" && attrDef.includes("number") && !attrDef.includes("array") && !attrDef.includes("decimal")) {
         if (typeof parsedValue === "string" && parsedValue !== "") {
           parsedValue = decode(parsedValue);
         } else if (typeof parsedValue === "number") ; else {
@@ -11331,18 +12243,38 @@ class Schema {
   preprocessAttributesForValidation(attributes) {
     const processed = {};
     for (const [key, value] of Object.entries(attributes)) {
-      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-        const isExplicitRequired = value.$$type && value.$$type.includes("required");
-        const isExplicitOptional = value.$$type && value.$$type.includes("optional");
-        const objectConfig = {
-          type: "object",
-          properties: this.preprocessAttributesForValidation(value),
-          strict: false
-        };
-        if (isExplicitRequired) ; else if (isExplicitOptional || this.allNestedObjectsOptional) {
-          objectConfig.optional = true;
+      if (typeof value === "string") {
+        if (value.startsWith("embedding:")) {
+          const lengthMatch = value.match(/embedding:(\d+)/);
+          if (lengthMatch) {
+            const length = lengthMatch[1];
+            const rest = value.substring(`embedding:${length}`.length);
+            processed[key] = `array|items:number|length:${length}|empty:false${rest}`;
+            continue;
+          }
+        }
+        if (value.startsWith("embedding|") || value === "embedding") {
+          processed[key] = value.replace(/^embedding/, "array|items:number|empty:false");
+          continue;
+        }
+        processed[key] = value;
+      } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const hasValidatorType = value.type !== void 0 && key !== "$$type";
+        if (hasValidatorType) {
+          processed[key] = value;
+        } else {
+          const isExplicitRequired = value.$$type && value.$$type.includes("required");
+          const isExplicitOptional = value.$$type && value.$$type.includes("optional");
+          const objectConfig = {
+            type: "object",
+            properties: this.preprocessAttributesForValidation(value),
+            strict: false
+          };
+          if (isExplicitRequired) ; else if (isExplicitOptional || this.allNestedObjectsOptional) {
+            objectConfig.optional = true;
+          }
+          processed[key] = objectConfig;
         }
-        processed[key] = objectConfig;
       } else {
         processed[key] = value;
       }
@@ -11363,7 +12295,14 @@ async function handleInsert$4({ resource, data, mappedData, originalData }) {
     }
   });
   if (totalSize > effectiveLimit) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, effective limit: ${effectiveLimit} bytes, absolute limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
+    throw new MetadataLimitError("Metadata size exceeds 2KB limit on insert", {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - effectiveLimit,
+      resourceName: resource.name,
+      operation: "insert"
+    });
   }
   return { mappedData, body: "" };
 }
@@ -11378,7 +12317,15 @@ async function handleUpdate$4({ resource, id, data, mappedData, originalData })
     }
   });
   if (totalSize > effectiveLimit) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, effective limit: ${effectiveLimit} bytes, absolute limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
+    throw new MetadataLimitError("Metadata size exceeds 2KB limit on update", {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - effectiveLimit,
+      resourceName: resource.name,
+      operation: "update",
+      id
+    });
   }
   return { mappedData, body: JSON.stringify(mappedData) };
 }
@@ -11393,7 +12340,15 @@ async function handleUpsert$4({ resource, id, data, mappedData }) {
     }
   });
   if (totalSize > effectiveLimit) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, effective limit: ${effectiveLimit} bytes, absolute limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
+    throw new MetadataLimitError("Metadata size exceeds 2KB limit on upsert", {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - effectiveLimit,
+      resourceName: resource.name,
+      operation: "upsert",
+      id
+    });
   }
   return { mappedData, body: "" };
 }
@@ -11735,7 +12690,11 @@ const behaviors = {
 function getBehavior(behaviorName) {
   const behavior = behaviors[behaviorName];
   if (!behavior) {
-    throw new Error(`Unknown behavior: ${behaviorName}. Available behaviors: ${Object.keys(behaviors).join(", ")}`);
+    throw new BehaviorError(`Unknown behavior: ${behaviorName}`, {
+      behavior: behaviorName,
+      availableBehaviors: Object.keys(behaviors),
+      operation: "getBehavior"
+    });
   }
   return behavior;
 }
@@ -14259,7 +15218,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "11.2.3" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "11.2.5" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};
@@ -14604,7 +15563,12 @@ class Database extends EventEmitter {
     const pluginName = name.toLowerCase().replace("plugin", "");
     const plugin = this.plugins[pluginName] || this.pluginRegistry[pluginName];
     if (!plugin) {
-      throw new Error(`Plugin '${name}' not found`);
+      throw new DatabaseError(`Plugin '${name}' not found`, {
+        operation: "uninstallPlugin",
+        pluginName: name,
+        availablePlugins: Object.keys(this.pluginRegistry),
+        suggestion: "Check plugin name or list available plugins using Object.keys(db.pluginRegistry)"
+      });
     }
     if (plugin.stop) {
       await plugin.stop();
@@ -15237,10 +16201,20 @@ class Database extends EventEmitter {
   addHook(event, fn) {
     if (!this._hooks) this._initHooks();
     if (!this._hooks.has(event)) {
-      throw new Error(`Unknown hook event: ${event}. Available events: ${this._hookEvents.join(", ")}`);
+      throw new DatabaseError(`Unknown hook event: ${event}`, {
+        operation: "addHook",
+        invalidEvent: event,
+        availableEvents: this._hookEvents,
+        suggestion: `Use one of the available hook events: ${this._hookEvents.join(", ")}`
+      });
     }
     if (typeof fn !== "function") {
-      throw new Error("Hook function must be a function");
+      throw new DatabaseError("Hook function must be a function", {
+        operation: "addHook",
+        event,
+        receivedType: typeof fn,
+        suggestion: "Provide a function that will be called when the hook event occurs"
+      });
     }
     this._hooks.get(event).push(fn);
   }
@@ -15378,7 +16352,11 @@ class S3dbReplicator extends BaseReplicator {
         this.targetDatabase = new S3db(targetConfig);
         await this.targetDatabase.connect();
       } else {
-        throw new Error("S3dbReplicator: No client or connectionString provided");
+        throw new ReplicationError("S3dbReplicator requires client or connectionString", {
+          operation: "initialize",
+          replicatorClass: "S3dbReplicator",
+          suggestion: 'Provide either a client instance or connectionString in config: { client: db } or { connectionString: "s3://..." }'
+        });
       }
       this.emit("connected", {
         replicator: this.name,
@@ -15409,7 +16387,13 @@ class S3dbReplicator extends BaseReplicator {
     const normResource = normalizeResourceName$1(resource);
     const entry = this.resourcesMap[normResource];
     if (!entry) {
-      throw new Error(`[S3dbReplicator] Resource not configured: ${resource}`);
+      throw new ReplicationError("Resource not configured for replication", {
+        operation: "replicate",
+        replicatorClass: "S3dbReplicator",
+        resourceName: resource,
+        configuredResources: Object.keys(this.resourcesMap),
+        suggestion: 'Add resource to replicator resources map: { resources: { [resourceName]: "destination" } }'
+      });
     }
     if (Array.isArray(entry)) {
       const results = [];
@@ -15477,7 +16461,14 @@ class S3dbReplicator extends BaseReplicator {
     } else if (operation === "delete") {
       result = await destResourceObj.delete(recordId);
     } else {
-      throw new Error(`Invalid operation: ${operation}. Supported operations are: insert, update, delete`);
+      throw new ReplicationError(`Invalid replication operation: ${operation}`, {
+        operation: "replicate",
+        replicatorClass: "S3dbReplicator",
+        invalidOperation: operation,
+        supportedOperations: ["insert", "update", "delete"],
+        resourceName: sourceResource,
+        suggestion: "Use one of the supported operations: insert, update, delete"
+      });
     }
     return result;
   }
@@ -15545,7 +16536,13 @@ class S3dbReplicator extends BaseReplicator {
     const norm = normalizeResourceName$1(resource);
     const found = available.find((r) => normalizeResourceName$1(r) === norm);
     if (!found) {
-      throw new Error(`[S3dbReplicator] Destination resource not found: ${resource}. Available: ${available.join(", ")}`);
+      throw new ReplicationError("Destination resource not found in target database", {
+        operation: "_getDestResourceObj",
+        replicatorClass: "S3dbReplicator",
+        destinationResource: resource,
+        availableResources: available,
+        suggestion: "Create the resource in target database or check resource name spelling"
+      });
     }
     return db.resources[found];
   }
@@ -15594,7 +16591,13 @@ class S3dbReplicator extends BaseReplicator {
   }
   async testConnection() {
     const [ok, err] = await tryFn(async () => {
-      if (!this.targetDatabase) throw new Error("No target database configured");
+      if (!this.targetDatabase) {
+        throw new ReplicationError("No target database configured for connection test", {
+          operation: "testConnection",
+          replicatorClass: "S3dbReplicator",
+          suggestion: "Initialize replicator with client or connectionString before testing connection"
+        });
+      }
       if (typeof this.targetDatabase.connect === "function") {
         await this.targetDatabase.connect();
       }
@@ -15981,7 +16984,12 @@ const REPLICATOR_DRIVERS = {
 function createReplicator(driver, config = {}, resources = [], client = null) {
   const ReplicatorClass = REPLICATOR_DRIVERS[driver];
   if (!ReplicatorClass) {
-    throw new Error(`Unknown replicator driver: ${driver}. Available drivers: ${Object.keys(REPLICATOR_DRIVERS).join(", ")}`);
+    throw new ReplicationError(`Unknown replicator driver: ${driver}`, {
+      operation: "createReplicator",
+      driver,
+      availableDrivers: Object.keys(REPLICATOR_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(REPLICATOR_DRIVERS).join(", ")}`
+    });
   }
   return new ReplicatorClass(config, resources, client);
 }
@@ -15993,12 +17001,40 @@ class ReplicatorPlugin extends Plugin {
   constructor(options = {}) {
     super();
     if (!options.replicators || !Array.isArray(options.replicators)) {
-      throw new Error("ReplicatorPlugin: replicators array is required");
+      throw new ReplicationError("ReplicatorPlugin requires replicators array", {
+        operation: "constructor",
+        pluginName: "ReplicatorPlugin",
+        providedOptions: Object.keys(options),
+        suggestion: 'Provide replicators array: new ReplicatorPlugin({ replicators: [{ driver: "s3db", resources: [...] }] })'
+      });
     }
     for (const rep of options.replicators) {
-      if (!rep.driver) throw new Error("ReplicatorPlugin: each replicator must have a driver");
-      if (!rep.resources || typeof rep.resources !== "object") throw new Error("ReplicatorPlugin: each replicator must have resources config");
-      if (Object.keys(rep.resources).length === 0) throw new Error("ReplicatorPlugin: each replicator must have at least one resource configured");
+      if (!rep.driver) {
+        throw new ReplicationError("Each replicator must have a driver", {
+          operation: "constructor",
+          pluginName: "ReplicatorPlugin",
+          replicatorConfig: rep,
+          suggestion: 'Each replicator entry must specify a driver: { driver: "s3db", resources: {...} }'
+        });
+      }
+      if (!rep.resources || typeof rep.resources !== "object") {
+        throw new ReplicationError("Each replicator must have resources config", {
+          operation: "constructor",
+          pluginName: "ReplicatorPlugin",
+          driver: rep.driver,
+          replicatorConfig: rep,
+          suggestion: 'Provide resources as object or array: { driver: "s3db", resources: ["users"] } or { resources: { users: "people" } }'
+        });
+      }
+      if (Object.keys(rep.resources).length === 0) {
+        throw new ReplicationError("Each replicator must have at least one resource configured", {
+          operation: "constructor",
+          pluginName: "ReplicatorPlugin",
+          driver: rep.driver,
+          replicatorConfig: rep,
+          suggestion: 'Add at least one resource to replicate: { driver: "s3db", resources: ["users"] }'
+        });
+      }
     }
     this.config = {
       replicators: options.replicators || [],
@@ -16424,7 +17460,13 @@ class ReplicatorPlugin extends Plugin {
   async syncAllData(replicatorId) {
     const replicator = this.replicators.find((r) => r.id === replicatorId);
     if (!replicator) {
-      throw new Error(`Replicator not found: ${replicatorId}`);
+      throw new ReplicationError("Replicator not found", {
+        operation: "syncAllData",
+        pluginName: "ReplicatorPlugin",
+        replicatorId,
+        availableReplicators: this.replicators.map((r) => r.id),
+        suggestion: "Check replicator ID or use getReplicatorStats() to list available replicators"
+      });
     }
     this.stats.lastSync = (/* @__PURE__ */ new Date()).toISOString();
     for (const resourceName in this.database.resources) {
@@ -16954,6 +17996,35 @@ class S3QueuePlugin extends Plugin {
   }
 }
 
+class SchedulerError extends S3dbError {
+  constructor(message, details = {}) {
+    const { taskId, operation = "unknown", cronExpression, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Scheduler Operation Error
+
+Operation: ${operation}
+${taskId ? `Task ID: ${taskId}` : ""}
+${cronExpression ? `Cron: ${cronExpression}` : ""}
+
+Common causes:
+1. Invalid cron expression format
+2. Task not found or already exists
+3. Scheduler not properly initialized
+4. Job execution failure
+5. Resource conflicts
+
+Solution:
+Check task configuration and ensure scheduler is properly initialized.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/scheduler.md
+`.trim();
+    }
+    super(message, { ...rest, taskId, operation, cronExpression, description });
+  }
+}
+
 class SchedulerPlugin extends Plugin {
   constructor(options = {}) {
     super();
@@ -16987,17 +18058,36 @@ class SchedulerPlugin extends Plugin {
   }
   _validateConfiguration() {
     if (Object.keys(this.config.jobs).length === 0) {
-      throw new Error("SchedulerPlugin: At least one job must be defined");
+      throw new SchedulerError("At least one job must be defined", {
+        operation: "validateConfiguration",
+        jobCount: 0,
+        suggestion: 'Provide at least one job in the jobs configuration: { jobs: { myJob: { schedule: "* * * * *", action: async () => {...} } } }'
+      });
     }
     for (const [jobName, job] of Object.entries(this.config.jobs)) {
       if (!job.schedule) {
-        throw new Error(`SchedulerPlugin: Job '${jobName}' must have a schedule`);
+        throw new SchedulerError(`Job '${jobName}' must have a schedule`, {
+          operation: "validateConfiguration",
+          taskId: jobName,
+          providedConfig: Object.keys(job),
+          suggestion: 'Add a schedule property with a valid cron expression: { schedule: "0 * * * *", action: async () => {...} }'
+        });
       }
       if (!job.action || typeof job.action !== "function") {
-        throw new Error(`SchedulerPlugin: Job '${jobName}' must have an action function`);
+        throw new SchedulerError(`Job '${jobName}' must have an action function`, {
+          operation: "validateConfiguration",
+          taskId: jobName,
+          actionType: typeof job.action,
+          suggestion: 'Provide an action function: { schedule: "...", action: async (db, ctx) => {...} }'
+        });
       }
       if (!this._isValidCronExpression(job.schedule)) {
-        throw new Error(`SchedulerPlugin: Job '${jobName}' has invalid cron expression: ${job.schedule}`);
+        throw new SchedulerError(`Job '${jobName}' has invalid cron expression`, {
+          operation: "validateConfiguration",
+          taskId: jobName,
+          cronExpression: job.schedule,
+          suggestion: "Use valid cron format (5 fields: minute hour day month weekday) or shortcuts (@hourly, @daily, @weekly, @monthly, @yearly)"
+        });
       }
     }
   }
@@ -17295,10 +18385,20 @@ class SchedulerPlugin extends Plugin {
   async runJob(jobName, context = {}) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: "runJob",
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: "Check job name or use getAllJobsStatus() to list available jobs"
+      });
     }
     if (this.activeJobs.has(jobName)) {
-      throw new Error(`Job '${jobName}' is already running`);
+      throw new SchedulerError(`Job '${jobName}' is already running`, {
+        operation: "runJob",
+        taskId: jobName,
+        executionId: this.activeJobs.get(jobName),
+        suggestion: "Wait for current execution to complete or check job status with getJobStatus()"
+      });
     }
     await this._executeJob(jobName);
   }
@@ -17308,7 +18408,12 @@ class SchedulerPlugin extends Plugin {
   enableJob(jobName) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: "enableJob",
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: "Check job name or use getAllJobsStatus() to list available jobs"
+      });
     }
     job.enabled = true;
     this._scheduleNextExecution(jobName);
@@ -17320,7 +18425,12 @@ class SchedulerPlugin extends Plugin {
   disableJob(jobName) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: "disableJob",
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: "Check job name or use getAllJobsStatus() to list available jobs"
+      });
     }
     job.enabled = false;
     const timer = this.timers.get(jobName);
@@ -17419,13 +18529,28 @@ class SchedulerPlugin extends Plugin {
    */
   addJob(jobName, jobConfig) {
     if (this.jobs.has(jobName)) {
-      throw new Error(`Job '${jobName}' already exists`);
+      throw new SchedulerError(`Job '${jobName}' already exists`, {
+        operation: "addJob",
+        taskId: jobName,
+        existingJobs: Array.from(this.jobs.keys()),
+        suggestion: "Use a different job name or remove the existing job first with removeJob()"
+      });
     }
     if (!jobConfig.schedule || !jobConfig.action) {
-      throw new Error("Job must have schedule and action");
+      throw new SchedulerError("Job must have schedule and action", {
+        operation: "addJob",
+        taskId: jobName,
+        providedConfig: Object.keys(jobConfig),
+        suggestion: 'Provide both schedule and action: { schedule: "0 * * * *", action: async (db, ctx) => {...} }'
+      });
     }
     if (!this._isValidCronExpression(jobConfig.schedule)) {
-      throw new Error(`Invalid cron expression: ${jobConfig.schedule}`);
+      throw new SchedulerError("Invalid cron expression", {
+        operation: "addJob",
+        taskId: jobName,
+        cronExpression: jobConfig.schedule,
+        suggestion: "Use valid cron format (5 fields) or shortcuts (@hourly, @daily, @weekly, @monthly, @yearly)"
+      });
     }
     const job = {
       ...jobConfig,
@@ -17459,7 +18584,12 @@ class SchedulerPlugin extends Plugin {
   removeJob(jobName) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: "removeJob",
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: "Check job name or use getAllJobsStatus() to list available jobs"
+      });
     }
     const timer = this.timers.get(jobName);
     if (timer) {
@@ -17513,6 +18643,36 @@ class SchedulerPlugin extends Plugin {
   }
 }
 
+class StateMachineError extends S3dbError {
+  constructor(message, details = {}) {
+    const { currentState, targetState, resourceName, operation = "unknown", ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+State Machine Operation Error
+
+Operation: ${operation}
+${currentState ? `Current State: ${currentState}` : ""}
+${targetState ? `Target State: ${targetState}` : ""}
+${resourceName ? `Resource: ${resourceName}` : ""}
+
+Common causes:
+1. Invalid state transition
+2. State machine not configured
+3. Transition conditions not met
+4. State not defined in configuration
+5. Missing transition handler
+
+Solution:
+Check state machine configuration and valid transitions.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/state-machine.md
+`.trim();
+    }
+    super(message, { ...rest, currentState, targetState, resourceName, operation, description });
+  }
+}
+
 class StateMachinePlugin extends Plugin {
   constructor(options = {}) {
     super();
@@ -17533,17 +18693,36 @@ class StateMachinePlugin extends Plugin {
   }
   _validateConfiguration() {
     if (!this.config.stateMachines || Object.keys(this.config.stateMachines).length === 0) {
-      throw new Error("StateMachinePlugin: At least one state machine must be defined");
+      throw new StateMachineError("At least one state machine must be defined", {
+        operation: "validateConfiguration",
+        machineCount: 0,
+        suggestion: "Provide at least one state machine in the stateMachines configuration"
+      });
     }
     for (const [machineName, machine] of Object.entries(this.config.stateMachines)) {
       if (!machine.states || Object.keys(machine.states).length === 0) {
-        throw new Error(`StateMachinePlugin: Machine '${machineName}' must have states defined`);
+        throw new StateMachineError(`Machine '${machineName}' must have states defined`, {
+          operation: "validateConfiguration",
+          machineId: machineName,
+          suggestion: "Define at least one state in the states configuration"
+        });
       }
       if (!machine.initialState) {
-        throw new Error(`StateMachinePlugin: Machine '${machineName}' must have an initialState`);
+        throw new StateMachineError(`Machine '${machineName}' must have an initialState`, {
+          operation: "validateConfiguration",
+          machineId: machineName,
+          availableStates: Object.keys(machine.states),
+          suggestion: "Specify an initialState property matching one of the defined states"
+        });
       }
       if (!machine.states[machine.initialState]) {
-        throw new Error(`StateMachinePlugin: Initial state '${machine.initialState}' not found in machine '${machineName}'`);
+        throw new StateMachineError(`Initial state '${machine.initialState}' not found in machine '${machineName}'`, {
+          operation: "validateConfiguration",
+          machineId: machineName,
+          initialState: machine.initialState,
+          availableStates: Object.keys(machine.states),
+          suggestion: "Set initialState to one of the defined states"
+        });
       }
     }
   }
@@ -17600,12 +18779,25 @@ class StateMachinePlugin extends Plugin {
   async send(machineId, entityId, event, context = {}) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "send",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     const currentState = await this.getState(machineId, entityId);
     const stateConfig = machine.config.states[currentState];
     if (!stateConfig || !stateConfig.on || !stateConfig.on[event]) {
-      throw new Error(`Event '${event}' not valid for state '${currentState}' in machine '${machineId}'`);
+      throw new StateMachineError(`Event '${event}' not valid for state '${currentState}' in machine '${machineId}'`, {
+        operation: "send",
+        machineId,
+        entityId,
+        event,
+        currentState,
+        validEvents: stateConfig && stateConfig.on ? Object.keys(stateConfig.on) : [],
+        suggestion: "Use getValidEvents() to check which events are valid for the current state"
+      });
     }
     const targetState = stateConfig.on[event];
     if (stateConfig.guards && stateConfig.guards[event]) {
@@ -17616,7 +18808,16 @@ class StateMachinePlugin extends Plugin {
           () => guard(context, event, { database: this.database, machineId, entityId })
         );
         if (!guardOk || !guardResult) {
-          throw new Error(`Transition blocked by guard '${guardName}': ${guardErr?.message || "Guard returned false"}`);
+          throw new StateMachineError(`Transition blocked by guard '${guardName}'`, {
+            operation: "send",
+            machineId,
+            entityId,
+            event,
+            currentState,
+            guardName,
+            guardError: guardErr?.message || "Guard returned false",
+            suggestion: "Check guard conditions or modify the context to satisfy guard requirements"
+          });
         }
       }
     }
@@ -17726,7 +18927,12 @@ class StateMachinePlugin extends Plugin {
   async getState(machineId, entityId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "getState",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     if (machine.currentStates.has(entityId)) {
       return machine.currentStates.get(entityId);
@@ -17752,7 +18958,12 @@ class StateMachinePlugin extends Plugin {
   async getValidEvents(machineId, stateOrEntityId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "getValidEvents",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     let state;
     if (machine.config.states[stateOrEntityId]) {
@@ -17801,7 +19012,12 @@ class StateMachinePlugin extends Plugin {
   async initializeEntity(machineId, entityId, context = {}) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "initializeEntity",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     const initialState = machine.config.initialState;
     machine.currentStates.set(entityId, initialState);
@@ -17820,7 +19036,14 @@ class StateMachinePlugin extends Plugin {
         })
       );
       if (!ok && err && !err.message?.includes("already exists")) {
-        throw new Error(`Failed to initialize entity state: ${err.message}`);
+        throw new StateMachineError("Failed to initialize entity state", {
+          operation: "initializeEntity",
+          machineId,
+          entityId,
+          initialState,
+          original: err,
+          suggestion: "Check state resource configuration and database permissions"
+        });
       }
     }
     const initialStateConfig = machine.config.states[initialState];
@@ -17849,7 +19072,12 @@ class StateMachinePlugin extends Plugin {
   visualize(machineId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "visualize",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     let dot = `digraph ${machineId} {
 `;
@@ -17893,12 +19121,1098 @@ class StateMachinePlugin extends Plugin {
   }
 }
 
+function cosineDistance(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`Dimension mismatch: ${a.length} vs ${b.length}`);
+  }
+  let dotProduct2 = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dotProduct2 += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denominator === 0) {
+    return a.every((v) => v === 0) && b.every((v) => v === 0) ? 0 : 1;
+  }
+  const similarity = dotProduct2 / denominator;
+  return 1 - similarity;
+}
+function euclideanDistance(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`Dimension mismatch: ${a.length} vs ${b.length}`);
+  }
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) {
+    const diff = a[i] - b[i];
+    sum += diff * diff;
+  }
+  return Math.sqrt(sum);
+}
+function manhattanDistance(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`Dimension mismatch: ${a.length} vs ${b.length}`);
+  }
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) {
+    sum += Math.abs(a[i] - b[i]);
+  }
+  return sum;
+}
+function dotProduct(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`Dimension mismatch: ${a.length} vs ${b.length}`);
+  }
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) {
+    sum += a[i] * b[i];
+  }
+  return sum;
+}
+function normalize(vector) {
+  const magnitude2 = Math.sqrt(
+    vector.reduce((sum, val) => sum + val * val, 0)
+  );
+  if (magnitude2 === 0) {
+    return vector.slice();
+  }
+  return vector.map((val) => val / magnitude2);
+}
+
+function kmeans(vectors, k, options = {}) {
+  const {
+    maxIterations = 100,
+    tolerance = 1e-4,
+    distanceFn = euclideanDistance,
+    seed = null,
+    onIteration = null
+  } = options;
+  if (vectors.length === 0) {
+    throw new Error("Cannot cluster empty vector array");
+  }
+  if (k < 1) {
+    throw new Error(`k must be at least 1, got ${k}`);
+  }
+  if (k > vectors.length) {
+    throw new Error(`k (${k}) cannot be greater than number of vectors (${vectors.length})`);
+  }
+  const dimensions = vectors[0].length;
+  for (let i = 1; i < vectors.length; i++) {
+    if (vectors[i].length !== dimensions) {
+      throw new Error(`All vectors must have same dimensions. Expected ${dimensions}, got ${vectors[i].length} at index ${i}`);
+    }
+  }
+  const centroids = initializeCentroidsKMeansPlusPlus(vectors, k, distanceFn, seed);
+  let assignments = new Array(vectors.length);
+  let iterations = 0;
+  let converged = false;
+  let previousInertia = Infinity;
+  while (!converged && iterations < maxIterations) {
+    const newAssignments = vectors.map((vector) => {
+      let minDist = Infinity;
+      let nearestCluster = 0;
+      for (let i = 0; i < k; i++) {
+        const dist = distanceFn(vector, centroids[i]);
+        if (dist < minDist) {
+          minDist = dist;
+          nearestCluster = i;
+        }
+      }
+      return nearestCluster;
+    });
+    let inertia2 = 0;
+    vectors.forEach((vector, i) => {
+      const dist = distanceFn(vector, centroids[newAssignments[i]]);
+      inertia2 += dist * dist;
+    });
+    const inertiaChange = Math.abs(previousInertia - inertia2);
+    converged = inertiaChange < tolerance;
+    assignments = newAssignments;
+    previousInertia = inertia2;
+    if (onIteration) {
+      onIteration(iterations + 1, inertia2, converged);
+    }
+    if (!converged) {
+      const clusterSums = Array(k).fill(null).map(() => new Array(dimensions).fill(0));
+      const clusterCounts = new Array(k).fill(0);
+      vectors.forEach((vector, i) => {
+        const cluster = assignments[i];
+        clusterCounts[cluster]++;
+        vector.forEach((val, j) => {
+          clusterSums[cluster][j] += val;
+        });
+      });
+      for (let i = 0; i < k; i++) {
+        if (clusterCounts[i] > 0) {
+          centroids[i] = clusterSums[i].map((sum) => sum / clusterCounts[i]);
+        } else {
+          const randomIdx = Math.floor(Math.random() * vectors.length);
+          centroids[i] = [...vectors[randomIdx]];
+        }
+      }
+    }
+    iterations++;
+  }
+  let inertia = 0;
+  vectors.forEach((vector, i) => {
+    const dist = distanceFn(vector, centroids[assignments[i]]);
+    inertia += dist * dist;
+  });
+  return {
+    centroids,
+    assignments,
+    iterations,
+    converged,
+    inertia
+  };
+}
+function initializeCentroidsKMeansPlusPlus(vectors, k, distanceFn, seed) {
+  const centroids = [];
+  const n = vectors.length;
+  const firstIndex = seed !== null ? seed % n : Math.floor(Math.random() * n);
+  centroids.push([...vectors[firstIndex]]);
+  for (let i = 1; i < k; i++) {
+    const distances = vectors.map((vector) => {
+      return Math.min(...centroids.map((c) => distanceFn(vector, c)));
+    });
+    const squaredDistances = distances.map((d) => d * d);
+    const totalSquared = squaredDistances.reduce((a, b) => a + b, 0);
+    if (totalSquared === 0) {
+      const randomIdx = Math.floor(Math.random() * n);
+      centroids.push([...vectors[randomIdx]]);
+      continue;
+    }
+    let threshold = Math.random() * totalSquared;
+    let cumulativeSum = 0;
+    for (let j = 0; j < n; j++) {
+      cumulativeSum += squaredDistances[j];
+      if (cumulativeSum >= threshold) {
+        centroids.push([...vectors[j]]);
+        break;
+      }
+    }
+  }
+  return centroids;
+}
+async function findOptimalK(vectors, options = {}) {
+  const {
+    minK = 2,
+    maxK = Math.min(10, Math.floor(Math.sqrt(vectors.length / 2))),
+    distanceFn = euclideanDistance,
+    nReferences = 10,
+    stabilityRuns = 5,
+    ...kmeansOptions
+  } = options;
+  const metricsModule = await Promise.resolve().then(function () { return metrics; });
+  const {
+    silhouetteScore,
+    daviesBouldinIndex,
+    calinskiHarabaszIndex,
+    gapStatistic,
+    clusteringStability
+  } = metricsModule;
+  const results = [];
+  for (let k = minK; k <= maxK; k++) {
+    const kmeansResult = kmeans(vectors, k, { ...kmeansOptions, distanceFn });
+    const silhouette = silhouetteScore(
+      vectors,
+      kmeansResult.assignments,
+      kmeansResult.centroids,
+      distanceFn
+    );
+    const daviesBouldin = daviesBouldinIndex(
+      vectors,
+      kmeansResult.assignments,
+      kmeansResult.centroids,
+      distanceFn
+    );
+    const calinskiHarabasz = calinskiHarabaszIndex(
+      vectors,
+      kmeansResult.assignments,
+      kmeansResult.centroids,
+      distanceFn
+    );
+    const gap = await gapStatistic(
+      vectors,
+      kmeansResult.assignments,
+      kmeansResult.centroids,
+      distanceFn,
+      nReferences
+    );
+    const stability = clusteringStability(
+      vectors,
+      k,
+      { ...kmeansOptions, distanceFn, nRuns: stabilityRuns }
+    );
+    results.push({
+      k,
+      inertia: kmeansResult.inertia,
+      silhouette,
+      daviesBouldin,
+      calinskiHarabasz,
+      gap: gap.gap,
+      gapSk: gap.sk,
+      stability: stability.stability,
+      cvInertia: stability.cvInertia,
+      iterations: kmeansResult.iterations,
+      converged: kmeansResult.converged
+    });
+  }
+  const elbowK = findElbowPoint(results.map((r) => r.inertia));
+  const recommendations = {
+    elbow: minK + elbowK,
+    silhouette: results.reduce(
+      (best, curr) => curr.silhouette > best.silhouette ? curr : best
+    ).k,
+    daviesBouldin: results.reduce(
+      (best, curr) => curr.daviesBouldin < best.daviesBouldin ? curr : best
+    ).k,
+    calinskiHarabasz: results.reduce(
+      (best, curr) => curr.calinskiHarabasz > best.calinskiHarabasz ? curr : best
+    ).k,
+    gap: results.reduce(
+      (best, curr) => curr.gap > best.gap ? curr : best
+    ).k,
+    stability: results.reduce(
+      (best, curr) => curr.stability > best.stability ? curr : best
+    ).k
+  };
+  const votes = Object.values(recommendations);
+  const consensus = votes.reduce((acc, k) => {
+    acc[k] = (acc[k] || 0) + 1;
+    return acc;
+  }, {});
+  const consensusK = parseInt(
+    Object.entries(consensus).reduce((a, b) => b[1] > a[1] ? b : a)[0]
+  );
+  return {
+    results,
+    recommendations,
+    consensus: consensusK,
+    summary: {
+      analysisRange: `${minK}-${maxK}`,
+      totalVectors: vectors.length,
+      dimensions: vectors[0].length,
+      recommendation: consensusK,
+      confidence: consensus[consensusK] / votes.length
+    }
+  };
+}
+function findElbowPoint(inertias) {
+  const n = inertias.length;
+  if (n < 3) return 0;
+  let maxCurvature = -Infinity;
+  let elbowIndex = 0;
+  for (let i = 1; i < n - 1; i++) {
+    const curvature = inertias[i - 1] - 2 * inertias[i] + inertias[i + 1];
+    if (curvature > maxCurvature) {
+      maxCurvature = curvature;
+      elbowIndex = i;
+    }
+  }
+  return elbowIndex;
+}
+
+class VectorError extends PluginError {
+  constructor(message, details = {}) {
+    super(message, {
+      pluginName: "VectorPlugin",
+      ...details,
+      description: details.description || `
+Vector Plugin Error
+
+Operation: ${details.operation || "unknown"}
+
+Common causes:
+1. Vector dimension mismatch between vectors
+2. Invalid distance metric specified (must be: cosine, euclidean, manhattan)
+3. Empty vector array provided for clustering
+4. k value larger than number of available vectors
+5. Vector field not found or invalid in resource
+6. Large vectors without proper behavior (use 'body-overflow' or 'body-only')
+
+Available distance metrics:
+- cosine: Best for normalized vectors, semantic similarity. Range: [0, 2]
+- euclidean: Standard L2 distance, geometric proximity. Range: [0, \u221E)
+- manhattan: L1 distance, faster computation. Range: [0, \u221E)
+
+Storage considerations:
+- Vectors > 250 dimensions may exceed S3 metadata limit (2KB)
+- Use behavior: 'body-overflow' or 'body-only' for large vectors
+- OpenAI ada-002 (1536 dims): ~10KB, requires body storage
+- Sentence Transformers (384 dims): ~2.7KB, requires body storage
+      `.trim()
+    });
+  }
+}
+
+class VectorPlugin extends Plugin {
+  constructor(options = {}) {
+    super(options);
+    this.config = {
+      dimensions: 1536,
+      // Default to OpenAI text-embedding-3-small/3-large
+      distanceMetric: "cosine",
+      // Default metric
+      storageThreshold: 1500,
+      // Bytes - warn if vectors exceed this
+      autoFixBehavior: false,
+      // Automatically set body-overflow
+      autoDetectVectorField: true,
+      // Auto-detect embedding:XXX fields
+      emitEvents: true,
+      // Emit events for monitoring
+      verboseEvents: false,
+      // Emit detailed progress events
+      eventThrottle: 100,
+      // Throttle progress events (ms)
+      ...options
+    };
+    this.distanceFunctions = {
+      cosine: cosineDistance,
+      euclidean: euclideanDistance,
+      manhattan: manhattanDistance
+    };
+    this._vectorFieldCache = /* @__PURE__ */ new Map();
+    this._throttleState = /* @__PURE__ */ new Map();
+  }
+  async onInstall() {
+    this.emit("installed", { plugin: "VectorPlugin" });
+    this.validateVectorStorage();
+    this.installResourceMethods();
+  }
+  async onStart() {
+    this.emit("started", { plugin: "VectorPlugin" });
+  }
+  async onStop() {
+    this.emit("stopped", { plugin: "VectorPlugin" });
+  }
+  async onUninstall(options) {
+    for (const resource of Object.values(this.database.resources)) {
+      delete resource.vectorSearch;
+      delete resource.cluster;
+      delete resource.vectorDistance;
+      delete resource.similarTo;
+      delete resource.findSimilar;
+      delete resource.distance;
+    }
+    this.emit("uninstalled", { plugin: "VectorPlugin" });
+  }
+  /**
+   * Validate vector storage configuration for all resources
+   *
+   * Detects large vector fields and warns if proper behavior is not set.
+   * Can optionally auto-fix by setting body-overflow behavior.
+   */
+  validateVectorStorage() {
+    for (const resource of Object.values(this.database.resources)) {
+      const vectorFields = this.findVectorFields(resource.schema.attributes);
+      if (vectorFields.length === 0) continue;
+      const totalVectorSize = vectorFields.reduce((sum, f) => sum + f.estimatedBytes, 0);
+      if (totalVectorSize > this.config.storageThreshold) {
+        const hasCorrectBehavior = ["body-overflow", "body-only"].includes(resource.behavior);
+        if (!hasCorrectBehavior) {
+          const warning = {
+            resource: resource.name,
+            vectorFields: vectorFields.map((f) => ({
+              field: f.name,
+              dimensions: f.length,
+              estimatedBytes: f.estimatedBytes
+            })),
+            totalEstimatedBytes: totalVectorSize,
+            metadataLimit: 2047,
+            currentBehavior: resource.behavior || "default",
+            recommendation: "body-overflow"
+          };
+          this.emit("vector:storage-warning", warning);
+          if (this.config.autoFixBehavior) {
+            resource.behavior = "body-overflow";
+            this.emit("vector:behavior-fixed", {
+              resource: resource.name,
+              newBehavior: "body-overflow"
+            });
+          } else {
+            console.warn(`\u26A0\uFE0F  VectorPlugin: Resource '${resource.name}' has large vector fields (${totalVectorSize} bytes estimated)`);
+            console.warn(`   Current behavior: '${resource.behavior || "default"}'`);
+            console.warn(`   Recommendation: Add behavior: 'body-overflow' or 'body-only' to resource configuration`);
+            console.warn(`   Large vectors will exceed S3 metadata limit (2047 bytes) and cause errors.`);
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Auto-detect vector field from resource schema
+   *
+   * Looks for fields with type 'embedding:XXX' pattern.
+   * Caches result per resource for performance.
+   *
+   * @param {Resource} resource - Resource instance
+   * @returns {string|null} Detected vector field name or null
+   */
+  detectVectorField(resource) {
+    if (this._vectorFieldCache.has(resource.name)) {
+      return this._vectorFieldCache.get(resource.name);
+    }
+    const vectorField = this._findEmbeddingField(resource.schema.attributes);
+    this._vectorFieldCache.set(resource.name, vectorField);
+    if (vectorField && this.config.emitEvents) {
+      this.emit("vector:field-detected", {
+        resource: resource.name,
+        vectorField,
+        timestamp: Date.now()
+      });
+    }
+    return vectorField;
+  }
+  /**
+   * Recursively find embedding:XXX field in attributes
+   *
+   * @param {Object} attributes - Resource attributes
+   * @param {string} path - Current path (for nested objects)
+   * @returns {string|null} Field path or null
+   */
+  _findEmbeddingField(attributes, path = "") {
+    for (const [key, attr] of Object.entries(attributes)) {
+      const fullPath = path ? `${path}.${key}` : key;
+      if (typeof attr === "string" && attr.startsWith("embedding:")) {
+        return fullPath;
+      }
+      if (attr.type === "array" && attr.items === "number" && attr.length) {
+        return fullPath;
+      }
+      if (attr.type === "object" && attr.props) {
+        const nested = this._findEmbeddingField(attr.props, fullPath);
+        if (nested) return nested;
+      }
+    }
+    return null;
+  }
+  /**
+   * Emit event with throttling support
+   *
+   * @param {string} eventName - Event name
+   * @param {Object} data - Event data
+   * @param {string} throttleKey - Unique key for throttling (optional)
+   */
+  _emitEvent(eventName, data, throttleKey = null) {
+    if (!this.config.emitEvents) return;
+    if (throttleKey) {
+      const now = Date.now();
+      const lastEmit = this._throttleState.get(throttleKey);
+      if (lastEmit && now - lastEmit < this.config.eventThrottle) {
+        return;
+      }
+      this._throttleState.set(throttleKey, now);
+    }
+    this.emit(eventName, data);
+  }
+  /**
+   * Find vector fields in resource attributes
+   *
+   * @param {Object} attributes - Resource attributes
+   * @param {string} path - Current path (for nested objects)
+   * @returns {Array} Array of vector field info
+   */
+  findVectorFields(attributes, path = "") {
+    const vectors = [];
+    for (const [key, attr] of Object.entries(attributes)) {
+      const fullPath = path ? `${path}.${key}` : key;
+      if (attr.type === "array" && attr.items === "number" && attr.length) {
+        vectors.push({
+          name: fullPath,
+          length: attr.length,
+          estimatedBytes: this.estimateVectorBytes(attr.length)
+        });
+      }
+      if (attr.type === "object" && attr.props) {
+        vectors.push(...this.findVectorFields(attr.props, fullPath));
+      }
+    }
+    return vectors;
+  }
+  /**
+   * Estimate bytes required to store a vector in JSON format
+   *
+   * Conservative estimate: ~7 bytes per number + array overhead
+   *
+   * @param {number} dimensions - Number of dimensions
+   * @returns {number} Estimated bytes
+   */
+  estimateVectorBytes(dimensions) {
+    return dimensions * 7 + 50;
+  }
+  /**
+   * Install vector methods on all resources
+   */
+  installResourceMethods() {
+    for (const resource of Object.values(this.database.resources)) {
+      const searchMethod = this.createVectorSearchMethod(resource);
+      const clusterMethod = this.createClusteringMethod(resource);
+      const distanceMethod = this.createDistanceMethod();
+      resource.vectorSearch = searchMethod;
+      resource.cluster = clusterMethod;
+      resource.vectorDistance = distanceMethod;
+      resource.similarTo = searchMethod;
+      resource.findSimilar = searchMethod;
+      resource.distance = distanceMethod;
+    }
+  }
+  /**
+   * Create vector search method for a resource
+   *
+   * Performs K-nearest neighbors search to find similar vectors.
+   *
+   * @param {Resource} resource - Resource instance
+   * @returns {Function} Vector search method
+   */
+  createVectorSearchMethod(resource) {
+    return async (queryVector, options = {}) => {
+      const startTime = Date.now();
+      let vectorField = options.vectorField;
+      if (!vectorField && this.config.autoDetectVectorField) {
+        vectorField = this.detectVectorField(resource);
+        if (!vectorField) {
+          vectorField = "vector";
+        }
+      } else if (!vectorField) {
+        vectorField = "vector";
+      }
+      const {
+        limit = 10,
+        distanceMetric = this.config.distanceMetric,
+        threshold = null,
+        partition = null
+      } = options;
+      const distanceFn = this.distanceFunctions[distanceMetric];
+      if (!distanceFn) {
+        const error = new VectorError(`Invalid distance metric: ${distanceMetric}`, {
+          operation: "vectorSearch",
+          availableMetrics: Object.keys(this.distanceFunctions),
+          providedMetric: distanceMetric
+        });
+        this._emitEvent("vector:search-error", {
+          resource: resource.name,
+          error: error.message,
+          timestamp: Date.now()
+        });
+        throw error;
+      }
+      this._emitEvent("vector:search-start", {
+        resource: resource.name,
+        vectorField,
+        limit,
+        distanceMetric,
+        partition,
+        threshold,
+        queryDimensions: queryVector.length,
+        timestamp: startTime
+      });
+      try {
+        let allRecords;
+        if (partition) {
+          this._emitEvent("vector:partition-filter", {
+            resource: resource.name,
+            partition,
+            timestamp: Date.now()
+          });
+          allRecords = await resource.list({ partition, partitionValues: partition });
+        } else {
+          allRecords = await resource.getAll();
+        }
+        const totalRecords = allRecords.length;
+        let processedRecords = 0;
+        let dimensionMismatches = 0;
+        const results = allRecords.filter((record) => record[vectorField] && Array.isArray(record[vectorField])).map((record, index) => {
+          try {
+            const distance = distanceFn(queryVector, record[vectorField]);
+            processedRecords++;
+            if (this.config.verboseEvents && processedRecords % 100 === 0) {
+              this._emitEvent("vector:search-progress", {
+                resource: resource.name,
+                processed: processedRecords,
+                total: totalRecords,
+                progress: processedRecords / totalRecords * 100,
+                timestamp: Date.now()
+              }, `search-${resource.name}`);
+            }
+            return { record, distance };
+          } catch (err) {
+            dimensionMismatches++;
+            if (this.config.verboseEvents) {
+              this._emitEvent("vector:dimension-mismatch", {
+                resource: resource.name,
+                recordIndex: index,
+                expected: queryVector.length,
+                got: record[vectorField]?.length,
+                timestamp: Date.now()
+              });
+            }
+            return null;
+          }
+        }).filter((result) => result !== null).filter((result) => threshold === null || result.distance <= threshold).sort((a, b) => a.distance - b.distance).slice(0, limit);
+        const duration = Date.now() - startTime;
+        const throughput = totalRecords / (duration / 1e3);
+        this._emitEvent("vector:search-complete", {
+          resource: resource.name,
+          vectorField,
+          resultsCount: results.length,
+          totalRecords,
+          processedRecords,
+          dimensionMismatches,
+          duration,
+          throughput: throughput.toFixed(2),
+          timestamp: Date.now()
+        });
+        if (this.config.verboseEvents) {
+          this._emitEvent("vector:performance", {
+            operation: "search",
+            resource: resource.name,
+            duration,
+            throughput: throughput.toFixed(2),
+            recordsPerSecond: (processedRecords / (duration / 1e3)).toFixed(2),
+            timestamp: Date.now()
+          });
+        }
+        return results;
+      } catch (error) {
+        this._emitEvent("vector:search-error", {
+          resource: resource.name,
+          error: error.message,
+          stack: error.stack,
+          timestamp: Date.now()
+        });
+        throw error;
+      }
+    };
+  }
+  /**
+   * Create clustering method for a resource
+   *
+   * Performs k-means clustering on resource vectors.
+   *
+   * @param {Resource} resource - Resource instance
+   * @returns {Function} Clustering method
+   */
+  createClusteringMethod(resource) {
+    return async (options = {}) => {
+      const startTime = Date.now();
+      let vectorField = options.vectorField;
+      if (!vectorField && this.config.autoDetectVectorField) {
+        vectorField = this.detectVectorField(resource);
+        if (!vectorField) {
+          vectorField = "vector";
+        }
+      } else if (!vectorField) {
+        vectorField = "vector";
+      }
+      const {
+        k = 5,
+        distanceMetric = this.config.distanceMetric,
+        partition = null,
+        ...kmeansOptions
+      } = options;
+      const distanceFn = this.distanceFunctions[distanceMetric];
+      if (!distanceFn) {
+        const error = new VectorError(`Invalid distance metric: ${distanceMetric}`, {
+          operation: "cluster",
+          availableMetrics: Object.keys(this.distanceFunctions),
+          providedMetric: distanceMetric
+        });
+        this._emitEvent("vector:cluster-error", {
+          resource: resource.name,
+          error: error.message,
+          timestamp: Date.now()
+        });
+        throw error;
+      }
+      this._emitEvent("vector:cluster-start", {
+        resource: resource.name,
+        vectorField,
+        k,
+        distanceMetric,
+        partition,
+        maxIterations: kmeansOptions.maxIterations || 100,
+        timestamp: startTime
+      });
+      try {
+        let allRecords;
+        if (partition) {
+          this._emitEvent("vector:partition-filter", {
+            resource: resource.name,
+            partition,
+            timestamp: Date.now()
+          });
+          allRecords = await resource.list({ partition, partitionValues: partition });
+        } else {
+          allRecords = await resource.getAll();
+        }
+        const recordsWithVectors = allRecords.filter(
+          (record) => record[vectorField] && Array.isArray(record[vectorField])
+        );
+        if (recordsWithVectors.length === 0) {
+          const error = new VectorError("No vectors found in resource", {
+            operation: "cluster",
+            resourceName: resource.name,
+            vectorField
+          });
+          this._emitEvent("vector:empty-dataset", {
+            resource: resource.name,
+            vectorField,
+            totalRecords: allRecords.length,
+            timestamp: Date.now()
+          });
+          throw error;
+        }
+        const vectors = recordsWithVectors.map((record) => record[vectorField]);
+        const result = kmeans(vectors, k, {
+          ...kmeansOptions,
+          distanceFn,
+          onIteration: this.config.verboseEvents ? (iteration, inertia, converged) => {
+            this._emitEvent("vector:cluster-iteration", {
+              resource: resource.name,
+              k,
+              iteration,
+              inertia,
+              converged,
+              timestamp: Date.now()
+            }, `cluster-${resource.name}`);
+          } : void 0
+        });
+        if (result.converged) {
+          this._emitEvent("vector:cluster-converged", {
+            resource: resource.name,
+            k,
+            iterations: result.iterations,
+            inertia: result.inertia,
+            timestamp: Date.now()
+          });
+        }
+        const clusters = Array(k).fill(null).map(() => []);
+        recordsWithVectors.forEach((record, i) => {
+          const clusterIndex = result.assignments[i];
+          clusters[clusterIndex].push(record);
+        });
+        const duration = Date.now() - startTime;
+        const clusterSizes = clusters.map((c) => c.length);
+        this._emitEvent("vector:cluster-complete", {
+          resource: resource.name,
+          vectorField,
+          k,
+          vectorCount: vectors.length,
+          iterations: result.iterations,
+          converged: result.converged,
+          inertia: result.inertia,
+          clusterSizes,
+          duration,
+          timestamp: Date.now()
+        });
+        if (this.config.verboseEvents) {
+          this._emitEvent("vector:performance", {
+            operation: "clustering",
+            resource: resource.name,
+            k,
+            duration,
+            iterationsPerSecond: (result.iterations / (duration / 1e3)).toFixed(2),
+            vectorsPerSecond: (vectors.length / (duration / 1e3)).toFixed(2),
+            timestamp: Date.now()
+          });
+        }
+        return {
+          clusters,
+          centroids: result.centroids,
+          inertia: result.inertia,
+          iterations: result.iterations,
+          converged: result.converged
+        };
+      } catch (error) {
+        this._emitEvent("vector:cluster-error", {
+          resource: resource.name,
+          error: error.message,
+          stack: error.stack,
+          timestamp: Date.now()
+        });
+        throw error;
+      }
+    };
+  }
+  /**
+   * Create distance calculation method
+   *
+   * @returns {Function} Distance method
+   */
+  createDistanceMethod() {
+    return (vector1, vector2, metric = this.config.distanceMetric) => {
+      const distanceFn = this.distanceFunctions[metric];
+      if (!distanceFn) {
+        throw new VectorError(`Invalid distance metric: ${metric}`, {
+          operation: "vectorDistance",
+          availableMetrics: Object.keys(this.distanceFunctions),
+          providedMetric: metric
+        });
+      }
+      return distanceFn(vector1, vector2);
+    };
+  }
+  /**
+   * Static utility: Normalize vector
+   *
+   * @param {number[]} vector - Input vector
+   * @returns {number[]} Normalized vector
+   */
+  static normalize(vector) {
+    return normalize(vector);
+  }
+  /**
+   * Static utility: Calculate dot product
+   *
+   * @param {number[]} vector1 - First vector
+   * @param {number[]} vector2 - Second vector
+   * @returns {number} Dot product
+   */
+  static dotProduct(vector1, vector2) {
+    return dotProduct(vector1, vector2);
+  }
+  /**
+   * Static utility: Find optimal K for clustering
+   *
+   * Analyzes clustering quality across a range of K values using
+   * multiple evaluation metrics.
+   *
+   * @param {number[][]} vectors - Vectors to analyze
+   * @param {Object} options - Configuration options
+   * @returns {Promise<Object>} Analysis results with recommendations
+   */
+  static async findOptimalK(vectors, options) {
+    return findOptimalK(vectors, options);
+  }
+}
+
+function silhouetteScore(vectors, assignments, centroids, distanceFn = euclideanDistance) {
+  const k = centroids.length;
+  const n = vectors.length;
+  const clusters = Array(k).fill(null).map(() => []);
+  vectors.forEach((vector, i) => {
+    clusters[assignments[i]].push(i);
+  });
+  let totalScore = 0;
+  let validPoints = 0;
+  if (clusters.every((c) => c.length <= 1)) {
+    return 0;
+  }
+  for (let i = 0; i < n; i++) {
+    const clusterIdx = assignments[i];
+    const cluster = clusters[clusterIdx];
+    if (cluster.length === 1) continue;
+    let a = 0;
+    for (const j of cluster) {
+      if (i !== j) {
+        a += distanceFn(vectors[i], vectors[j]);
+      }
+    }
+    a /= cluster.length - 1;
+    let b = Infinity;
+    for (let otherCluster = 0; otherCluster < k; otherCluster++) {
+      if (otherCluster === clusterIdx) continue;
+      const otherPoints = clusters[otherCluster];
+      if (otherPoints.length === 0) continue;
+      let avgDist = 0;
+      for (const j of otherPoints) {
+        avgDist += distanceFn(vectors[i], vectors[j]);
+      }
+      avgDist /= otherPoints.length;
+      b = Math.min(b, avgDist);
+    }
+    if (b === Infinity) continue;
+    const maxAB = Math.max(a, b);
+    const s = maxAB === 0 ? 0 : (b - a) / maxAB;
+    totalScore += s;
+    validPoints++;
+  }
+  return validPoints > 0 ? totalScore / validPoints : 0;
+}
+function daviesBouldinIndex(vectors, assignments, centroids, distanceFn = euclideanDistance) {
+  const k = centroids.length;
+  const scatters = new Array(k).fill(0);
+  const clusterCounts = new Array(k).fill(0);
+  vectors.forEach((vector, i) => {
+    const cluster = assignments[i];
+    scatters[cluster] += distanceFn(vector, centroids[cluster]);
+    clusterCounts[cluster]++;
+  });
+  for (let i = 0; i < k; i++) {
+    if (clusterCounts[i] > 0) {
+      scatters[i] /= clusterCounts[i];
+    }
+  }
+  let dbIndex = 0;
+  let validClusters = 0;
+  for (let i = 0; i < k; i++) {
+    if (clusterCounts[i] === 0) continue;
+    let maxRatio = 0;
+    for (let j = 0; j < k; j++) {
+      if (i === j || clusterCounts[j] === 0) continue;
+      const centroidDist = distanceFn(centroids[i], centroids[j]);
+      if (centroidDist === 0) continue;
+      const ratio = (scatters[i] + scatters[j]) / centroidDist;
+      maxRatio = Math.max(maxRatio, ratio);
+    }
+    dbIndex += maxRatio;
+    validClusters++;
+  }
+  return validClusters > 0 ? dbIndex / validClusters : 0;
+}
+function calinskiHarabaszIndex(vectors, assignments, centroids, distanceFn = euclideanDistance) {
+  const n = vectors.length;
+  const k = centroids.length;
+  if (k === 1 || k === n) return 0;
+  const dimensions = vectors[0].length;
+  const overallCentroid = new Array(dimensions).fill(0);
+  vectors.forEach((vector) => {
+    vector.forEach((val, dim) => {
+      overallCentroid[dim] += val;
+    });
+  });
+  overallCentroid.forEach((val, dim, arr) => {
+    arr[dim] = val / n;
+  });
+  const clusterCounts = new Array(k).fill(0);
+  vectors.forEach((vector, i) => {
+    clusterCounts[assignments[i]]++;
+  });
+  let bgss = 0;
+  for (let i = 0; i < k; i++) {
+    if (clusterCounts[i] === 0) continue;
+    const dist = distanceFn(centroids[i], overallCentroid);
+    bgss += clusterCounts[i] * dist * dist;
+  }
+  let wcss = 0;
+  vectors.forEach((vector, i) => {
+    const cluster = assignments[i];
+    const dist = distanceFn(vector, centroids[cluster]);
+    wcss += dist * dist;
+  });
+  if (wcss === 0) return 0;
+  return bgss / (k - 1) / (wcss / (n - k));
+}
+async function gapStatistic(vectors, assignments, centroids, distanceFn = euclideanDistance, nReferences = 10) {
+  const n = vectors.length;
+  const k = centroids.length;
+  const dimensions = vectors[0].length;
+  let wk = 0;
+  vectors.forEach((vector, i) => {
+    const dist = distanceFn(vector, centroids[assignments[i]]);
+    wk += dist * dist;
+  });
+  wk = Math.log(wk + 1e-10);
+  const referenceWks = [];
+  const mins = new Array(dimensions).fill(Infinity);
+  const maxs = new Array(dimensions).fill(-Infinity);
+  vectors.forEach((vector) => {
+    vector.forEach((val, dim) => {
+      mins[dim] = Math.min(mins[dim], val);
+      maxs[dim] = Math.max(maxs[dim], val);
+    });
+  });
+  for (let ref = 0; ref < nReferences; ref++) {
+    const refVectors = [];
+    for (let i = 0; i < n; i++) {
+      const refVector = new Array(dimensions);
+      for (let dim = 0; dim < dimensions; dim++) {
+        refVector[dim] = mins[dim] + Math.random() * (maxs[dim] - mins[dim]);
+      }
+      refVectors.push(refVector);
+    }
+    const refResult = kmeans(refVectors, k, { maxIterations: 50, distanceFn });
+    let refWk = 0;
+    refVectors.forEach((vector, i) => {
+      const dist = distanceFn(vector, refResult.centroids[refResult.assignments[i]]);
+      refWk += dist * dist;
+    });
+    referenceWks.push(Math.log(refWk + 1e-10));
+  }
+  const expectedWk = referenceWks.reduce((a, b) => a + b, 0) / nReferences;
+  const gap = expectedWk - wk;
+  const sdk = Math.sqrt(
+    referenceWks.reduce((sum, wk2) => sum + Math.pow(wk2 - expectedWk, 2), 0) / nReferences
+  );
+  const sk = sdk * Math.sqrt(1 + 1 / nReferences);
+  return { gap, sk, expectedWk, actualWk: wk };
+}
+function clusteringStability(vectors, k, options = {}) {
+  const {
+    nRuns = 10,
+    distanceFn = euclideanDistance,
+    ...kmeansOptions
+  } = options;
+  const inertias = [];
+  const allAssignments = [];
+  for (let run = 0; run < nRuns; run++) {
+    const result = kmeans(vectors, k, {
+      ...kmeansOptions,
+      distanceFn,
+      seed: run
+      // Different seed for each run
+    });
+    inertias.push(result.inertia);
+    allAssignments.push(result.assignments);
+  }
+  const assignmentSimilarities = [];
+  for (let i = 0; i < nRuns - 1; i++) {
+    for (let j = i + 1; j < nRuns; j++) {
+      const similarity = calculateAssignmentSimilarity(allAssignments[i], allAssignments[j]);
+      assignmentSimilarities.push(similarity);
+    }
+  }
+  const avgInertia = inertias.reduce((a, b) => a + b, 0) / nRuns;
+  const stdInertia = Math.sqrt(
+    inertias.reduce((sum, val) => sum + Math.pow(val - avgInertia, 2), 0) / nRuns
+  );
+  const avgSimilarity = assignmentSimilarities.length > 0 ? assignmentSimilarities.reduce((a, b) => a + b, 0) / assignmentSimilarities.length : 1;
+  return {
+    avgInertia,
+    stdInertia,
+    cvInertia: avgInertia !== 0 ? stdInertia / avgInertia : 0,
+    // Coefficient of variation
+    avgSimilarity,
+    stability: avgSimilarity
+    // Higher is more stable
+  };
+}
+function calculateAssignmentSimilarity(assignments1, assignments2) {
+  const n = assignments1.length;
+  let matches = 0;
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      const sameCluster1 = assignments1[i] === assignments1[j];
+      const sameCluster2 = assignments2[i] === assignments2[j];
+      if (sameCluster1 === sameCluster2) {
+        matches++;
+      }
+    }
+  }
+  const totalPairs = n * (n - 1) / 2;
+  return totalPairs > 0 ? matches / totalPairs : 1;
+}
+
+var metrics = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  calinskiHarabaszIndex: calinskiHarabaszIndex,
+  clusteringStability: clusteringStability,
+  daviesBouldinIndex: daviesBouldinIndex,
+  gapStatistic: gapStatistic,
+  silhouetteScore: silhouetteScore
+});
+
 exports.AVAILABLE_BEHAVIORS = AVAILABLE_BEHAVIORS;
 exports.AnalyticsNotEnabledError = AnalyticsNotEnabledError;
 exports.AuditPlugin = AuditPlugin;
 exports.AuthenticationError = AuthenticationError;
 exports.BackupPlugin = BackupPlugin;
 exports.BaseError = BaseError;
+exports.BehaviorError = BehaviorError;
 exports.CachePlugin = CachePlugin;
 exports.Client = Client;
 exports.ConnectionString = ConnectionString;
@@ -17913,15 +20227,19 @@ exports.ErrorMap = ErrorMap;
 exports.EventualConsistencyPlugin = EventualConsistencyPlugin;
 exports.FullTextPlugin = FullTextPlugin;
 exports.InvalidResourceItem = InvalidResourceItem;
+exports.MetadataLimitError = MetadataLimitError;
 exports.MetricsPlugin = MetricsPlugin;
 exports.MissingMetadata = MissingMetadata;
 exports.NoSuchBucket = NoSuchBucket;
 exports.NoSuchKey = NoSuchKey;
 exports.NotFound = NotFound;
+exports.PartitionDriverError = PartitionDriverError;
 exports.PartitionError = PartitionError;
 exports.PermissionError = PermissionError;
 exports.Plugin = Plugin;
+exports.PluginError = PluginError;
 exports.PluginObject = PluginObject;
+exports.PluginStorageError = PluginStorageError;
 exports.QueueConsumerPlugin = QueueConsumerPlugin;
 exports.ReplicatorPlugin = ReplicatorPlugin;
 exports.Resource = Resource;
@@ -17938,9 +20256,11 @@ exports.SchedulerPlugin = SchedulerPlugin;
 exports.Schema = Schema;
 exports.SchemaError = SchemaError;
 exports.StateMachinePlugin = StateMachinePlugin;
+exports.StreamError = StreamError;
 exports.UnknownError = UnknownError;
 exports.ValidationError = ValidationError;
 exports.Validator = Validator;
+exports.VectorPlugin = VectorPlugin;
 exports.behaviors = behaviors;
 exports.calculateAttributeNamesSize = calculateAttributeNamesSize;
 exports.calculateAttributeSizes = calculateAttributeSizes;
@@ -17953,10 +20273,12 @@ exports.clearUTF8Memo = clearUTF8Memo;
 exports.clearUTF8Memory = clearUTF8Memory;
 exports.decode = decode;
 exports.decodeDecimal = decodeDecimal;
+exports.decodeFixedPoint = decodeFixedPoint;
 exports.decrypt = decrypt;
 exports.default = S3db;
 exports.encode = encode;
 exports.encodeDecimal = encodeDecimal;
+exports.encodeFixedPoint = encodeFixedPoint;
 exports.encrypt = encrypt;
 exports.getBehavior = getBehavior;
 exports.getSizeBreakdown = getSizeBreakdown;