s3db.js 11.2.2 → 11.2.4

package/dist/s3db.cjs.js

@@ -15,6 +15,7 @@ var jsonStableStringify = require('json-stable-stringify');
 var stream = require('stream');
 var promisePool = require('@supercharge/promise-pool');
 var web = require('node:stream/web');
+var os$1 = require('node:os');
 var lodashEs = require('lodash-es');
 var http = require('http');
 var https = require('https');
@@ -221,7 +222,7 @@ function calculateEffectiveLimit(config = {}) {
 }
 
 class BaseError extends Error {
-  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, suggestion, ...rest }) {
+  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, description, ...rest }) {
     if (verbose) message = message + `
 
 Verbose:
@@ -246,7 +247,7 @@ ${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 };
   }
   toJson() {
@@ -263,7 +264,7 @@ ${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,
       stack: this.stack
@@ -403,26 +404,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()}`,
@@ -430,33 +431,388 @@ 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);
   }
 }
 class PartitionError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: details.suggestion || "Check partition definition, fields, and input values." });
+    let description = details.description;
+    if (!description && details.resourceName && details.partitionName && details.fieldName) {
+      const { resourceName, partitionName, fieldName, availableFields = [] } = details;
+      description = `
+Partition Field Validation Error
+
+Resource: ${resourceName}
+Partition: ${partitionName}
+Missing Field: ${fieldName}
+
+Available fields in schema:
+${availableFields.map((f) => `  \u2022 ${f}`).join("\n") || "  (no fields defined)"}
+
+Possible causes:
+1. Field was removed from schema but partition still references it
+2. Typo in partition field name
+3. Nested field path is incorrect (use dot notation like 'utm.source')
+
+Solution:
+${details.strictValidation === false ? "  \u2022 Update partition definition to use existing fields" : `  \u2022 Add missing field to schema, OR
+  \u2022 Update partition definition to use existing fields, OR
+  \u2022 Use strictValidation: false to skip this check during testing`}
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partitions
+`.trim();
+    }
+    super(message, {
+      ...details,
+      description
+    });
+  }
+}
+class AnalyticsNotEnabledError extends S3dbError {
+  constructor(details = {}) {
+    const {
+      pluginName = "EventualConsistency",
+      resourceName = "unknown",
+      field = "unknown",
+      configuredResources = [],
+      registeredResources = [],
+      pluginInitialized = false,
+      ...rest
+    } = details;
+    const message = `Analytics not enabled for ${resourceName}.${field}`;
+    const description = `
+Analytics Not Enabled
+
+Plugin: ${pluginName}
+Resource: ${resourceName}
+Field: ${field}
+
+Diagnostics:
+  \u2022 Plugin initialized: ${pluginInitialized ? "\u2713 Yes" : "\u2717 No"}
+  \u2022 Analytics resources created: ${registeredResources.length}/${configuredResources.length}
+${configuredResources.map((r) => {
+      const exists = registeredResources.includes(r);
+      return `    ${exists ? "\u2713" : "\u2717"} ${r}${!exists ? " (missing)" : ""}`;
+    }).join("\n")}
+
+Possible causes:
+1. Resource not created yet - Analytics resources are created when db.createResource() is called
+2. Resource created before plugin initialization - Plugin must be initialized before resources
+3. Field not configured in analytics.resources config
+
+Correct initialization order:
+  1. Create database: const db = new Database({ ... })
+  2. Install plugins: await db.connect() (triggers plugin.install())
+  3. Create resources: await db.createResource({ name: '${resourceName}', ... })
+  4. Analytics resources are auto-created by plugin
+
+Example fix:
+  const db = new Database({
+    bucket: 'my-bucket',
+    plugins: [new EventualConsistencyPlugin({
+      resources: {
+        '${resourceName}': {
+          fields: {
+            '${field}': { type: 'counter', analytics: true }
+          }
+        }
+      }
+    })]
+  });
+
+  await db.connect();  // Plugin initialized here
+  await db.createResource({ name: '${resourceName}', ... });  // Analytics resource created here
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/eventual-consistency.md
+`.trim();
+    super(message, {
+      ...rest,
+      pluginName,
+      resourceName,
+      field,
+      configuredResources,
+      registeredResources,
+      pluginInitialized,
+      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
+    });
   }
 }
 
@@ -799,10 +1155,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;
@@ -855,7 +1218,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"
+      });
     }
   }
   /**
@@ -877,7 +1248,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);
@@ -890,7 +1267,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;
@@ -951,7 +1334,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);
@@ -971,7 +1362,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);
@@ -1111,7 +1511,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"
+      });
     }
   }
   /**
@@ -1298,16 +1704,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 };
   }
@@ -1872,6 +2290,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 = {
@@ -1902,7 +2349,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
@@ -1912,7 +2364,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
@@ -1920,7 +2377,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
@@ -1928,7 +2390,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
@@ -1938,14 +2404,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
@@ -1987,7 +2462,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}`);
   }
@@ -2011,11 +2490,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(
@@ -2026,7 +2520,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;
@@ -2045,13 +2546,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;
@@ -2068,7 +2583,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}`);
   }
@@ -2173,10 +2695,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}`);
   }
@@ -2218,7 +2748,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({
@@ -2239,7 +2777,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 {
@@ -2262,7 +2808,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;
@@ -2283,7 +2838,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`);
   }
@@ -2396,11 +2959,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 || {});
@@ -2412,7 +2986,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) {
@@ -2441,7 +3023,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(
@@ -2471,10 +3061,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;
   }
@@ -2494,7 +3102,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];
@@ -2516,7 +3131,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("; ")}`);
@@ -2616,32 +3238,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 || {});
@@ -3297,6 +3949,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();
@@ -3313,7 +3995,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
@@ -3400,7 +4088,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;
@@ -3524,7 +4216,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));
@@ -3605,6 +4300,24 @@ class MemoryCache extends Cache {
     this.cache = {};
     this.meta = {};
     this.maxSize = config.maxSize !== void 0 ? config.maxSize : 1e3;
+    if (config.maxMemoryBytes && config.maxMemoryBytes > 0 && config.maxMemoryPercent && config.maxMemoryPercent > 0) {
+      throw new Error(
+        "[MemoryCache] Cannot use both maxMemoryBytes and maxMemoryPercent. Choose one: maxMemoryBytes (absolute) or maxMemoryPercent (0...1 fraction)."
+      );
+    }
+    if (config.maxMemoryPercent && config.maxMemoryPercent > 0) {
+      if (config.maxMemoryPercent > 1) {
+        throw new Error(
+          `[MemoryCache] maxMemoryPercent must be between 0 and 1 (e.g., 0.1 for 10%). Received: ${config.maxMemoryPercent}`
+        );
+      }
+      const totalMemory = os$1.totalmem();
+      this.maxMemoryBytes = Math.floor(totalMemory * config.maxMemoryPercent);
+      this.maxMemoryPercent = config.maxMemoryPercent;
+    } else {
+      this.maxMemoryBytes = config.maxMemoryBytes !== void 0 ? config.maxMemoryBytes : 0;
+      this.maxMemoryPercent = 0;
+    }
     this.ttl = config.ttl !== void 0 ? config.ttl : 3e5;
     this.enableCompression = config.enableCompression !== void 0 ? config.enableCompression : false;
     this.compressionThreshold = config.compressionThreshold !== void 0 ? config.compressionThreshold : 1024;
@@ -3614,23 +4327,18 @@ class MemoryCache extends Cache {
       totalCompressedSize: 0,
       compressionRatio: 0
     };
+    this.currentMemoryBytes = 0;
+    this.evictedDueToMemory = 0;
   }
   async _set(key, data) {
-    if (this.maxSize > 0 && Object.keys(this.cache).length >= this.maxSize) {
-      const oldestKey = Object.entries(this.meta).sort((a, b) => a[1].ts - b[1].ts)[0]?.[0];
-      if (oldestKey) {
-        delete this.cache[oldestKey];
-        delete this.meta[oldestKey];
-      }
-    }
     let finalData = data;
     let compressed = false;
     let originalSize = 0;
     let compressedSize = 0;
+    const serialized = JSON.stringify(data);
+    originalSize = Buffer.byteLength(serialized, "utf8");
     if (this.enableCompression) {
       try {
-        const serialized = JSON.stringify(data);
-        originalSize = Buffer.byteLength(serialized, "utf8");
         if (originalSize >= this.compressionThreshold) {
           const compressedBuffer = zlib.gzipSync(Buffer.from(serialized, "utf8"));
           finalData = {
@@ -3649,13 +4357,42 @@ class MemoryCache extends Cache {
         console.warn(`[MemoryCache] Compression failed for key '${key}':`, error.message);
       }
     }
+    const itemSize = compressed ? compressedSize : originalSize;
+    if (Object.prototype.hasOwnProperty.call(this.cache, key)) {
+      const oldSize = this.meta[key]?.compressedSize || 0;
+      this.currentMemoryBytes -= oldSize;
+    }
+    if (this.maxMemoryBytes > 0) {
+      while (this.currentMemoryBytes + itemSize > this.maxMemoryBytes && Object.keys(this.cache).length > 0) {
+        const oldestKey = Object.entries(this.meta).sort((a, b) => a[1].ts - b[1].ts)[0]?.[0];
+        if (oldestKey) {
+          const evictedSize = this.meta[oldestKey]?.compressedSize || 0;
+          delete this.cache[oldestKey];
+          delete this.meta[oldestKey];
+          this.currentMemoryBytes -= evictedSize;
+          this.evictedDueToMemory++;
+        } else {
+          break;
+        }
+      }
+    }
+    if (this.maxSize > 0 && Object.keys(this.cache).length >= this.maxSize) {
+      const oldestKey = Object.entries(this.meta).sort((a, b) => a[1].ts - b[1].ts)[0]?.[0];
+      if (oldestKey) {
+        const evictedSize = this.meta[oldestKey]?.compressedSize || 0;
+        delete this.cache[oldestKey];
+        delete this.meta[oldestKey];
+        this.currentMemoryBytes -= evictedSize;
+      }
+    }
     this.cache[key] = finalData;
     this.meta[key] = {
       ts: Date.now(),
       compressed,
       originalSize,
-      compressedSize: compressed ? compressedSize : originalSize
+      compressedSize: itemSize
     };
+    this.currentMemoryBytes += itemSize;
     return data;
   }
   async _get(key) {
@@ -3663,7 +4400,9 @@ class MemoryCache extends Cache {
     if (this.ttl > 0) {
       const now = Date.now();
       const meta = this.meta[key];
-      if (meta && now - meta.ts > this.ttl * 1e3) {
+      if (meta && now - meta.ts > this.ttl) {
+        const itemSize = meta.compressedSize || 0;
+        this.currentMemoryBytes -= itemSize;
         delete this.cache[key];
         delete this.meta[key];
         return null;
@@ -3685,6 +4424,10 @@ class MemoryCache extends Cache {
     return rawData;
   }
   async _del(key) {
+    if (Object.prototype.hasOwnProperty.call(this.cache, key)) {
+      const itemSize = this.meta[key]?.compressedSize || 0;
+      this.currentMemoryBytes -= itemSize;
+    }
     delete this.cache[key];
     delete this.meta[key];
     return true;
@@ -3693,10 +4436,13 @@ class MemoryCache extends Cache {
     if (!prefix) {
       this.cache = {};
       this.meta = {};
+      this.currentMemoryBytes = 0;
       return true;
     }
     for (const key of Object.keys(this.cache)) {
       if (key.startsWith(prefix)) {
+        const itemSize = this.meta[key]?.compressedSize || 0;
+        this.currentMemoryBytes -= itemSize;
         delete this.cache[key];
         delete this.meta[key];
       }
@@ -3734,6 +4480,53 @@ class MemoryCache extends Cache {
       }
     };
   }
+  /**
+   * Get memory usage statistics
+   * @returns {Object} Memory stats including current usage, limits, and eviction counts
+   */
+  getMemoryStats() {
+    const totalItems = Object.keys(this.cache).length;
+    const memoryUsagePercent = this.maxMemoryBytes > 0 ? (this.currentMemoryBytes / this.maxMemoryBytes * 100).toFixed(2) : 0;
+    const systemMemory = {
+      total: os$1.totalmem(),
+      free: os$1.freemem(),
+      used: os$1.totalmem() - os$1.freemem()
+    };
+    const cachePercentOfTotal = systemMemory.total > 0 ? (this.currentMemoryBytes / systemMemory.total * 100).toFixed(2) : 0;
+    return {
+      currentMemoryBytes: this.currentMemoryBytes,
+      maxMemoryBytes: this.maxMemoryBytes,
+      maxMemoryPercent: this.maxMemoryPercent,
+      memoryUsagePercent: parseFloat(memoryUsagePercent),
+      cachePercentOfSystemMemory: parseFloat(cachePercentOfTotal),
+      totalItems,
+      maxSize: this.maxSize,
+      evictedDueToMemory: this.evictedDueToMemory,
+      averageItemSize: totalItems > 0 ? Math.round(this.currentMemoryBytes / totalItems) : 0,
+      memoryUsage: {
+        current: this._formatBytes(this.currentMemoryBytes),
+        max: this.maxMemoryBytes > 0 ? this._formatBytes(this.maxMemoryBytes) : "unlimited",
+        available: this.maxMemoryBytes > 0 ? this._formatBytes(this.maxMemoryBytes - this.currentMemoryBytes) : "unlimited"
+      },
+      systemMemory: {
+        total: this._formatBytes(systemMemory.total),
+        free: this._formatBytes(systemMemory.free),
+        used: this._formatBytes(systemMemory.used),
+        cachePercent: `${cachePercentOfTotal}%`
+      }
+    };
+  }
+  /**
+   * Format bytes to human-readable format
+   * @private
+   */
+  _formatBytes(bytes) {
+    if (bytes === 0) return "0 B";
+    const k = 1024;
+    const sizes = ["B", "KB", "MB", "GB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
+  }
 }
 
 class FilesystemCache extends Cache {
@@ -4563,8 +5356,10 @@ class CachePlugin extends Plugin {
       config: {
         ttl: options.ttl,
         maxSize: options.maxSize,
+        maxMemoryBytes: options.maxMemoryBytes,
+        maxMemoryPercent: options.maxMemoryPercent,
         ...options.config
-        // Driver-specific config (can override ttl/maxSize)
+        // Driver-specific config (can override ttl/maxSize/maxMemoryBytes/maxMemoryPercent)
       },
       // Resource filtering
       include: options.include || null,
@@ -4918,7 +5713,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) {
@@ -7023,6 +7824,80 @@ async function getLastNMonths(resourceName, field, months = 12, options, fieldHa
   }
   return data;
 }
+async function getRawEvents(resourceName, field, options, fieldHandlers) {
+  const resourceHandlers = fieldHandlers.get(resourceName);
+  if (!resourceHandlers) {
+    throw new Error(`No eventual consistency configured for resource: ${resourceName}`);
+  }
+  const handler = resourceHandlers.get(field);
+  if (!handler) {
+    throw new Error(`No eventual consistency configured for field: ${resourceName}.${field}`);
+  }
+  if (!handler.transactionResource) {
+    throw new Error("Transaction resource not initialized");
+  }
+  const {
+    recordId,
+    startDate,
+    endDate,
+    cohortDate,
+    cohortHour,
+    cohortMonth,
+    applied,
+    operation,
+    limit
+  } = options;
+  const query = {};
+  if (recordId !== void 0) {
+    query.originalId = recordId;
+  }
+  if (applied !== void 0) {
+    query.applied = applied;
+  }
+  const [ok, err, allTransactions] = await tryFn(
+    () => handler.transactionResource.query(query)
+  );
+  if (!ok || !allTransactions) {
+    return [];
+  }
+  let filtered = allTransactions;
+  if (operation !== void 0) {
+    filtered = filtered.filter((t) => t.operation === operation);
+  }
+  if (cohortDate) {
+    filtered = filtered.filter((t) => t.cohortDate === cohortDate);
+  }
+  if (cohortHour) {
+    filtered = filtered.filter((t) => t.cohortHour === cohortHour);
+  }
+  if (cohortMonth) {
+    filtered = filtered.filter((t) => t.cohortMonth === cohortMonth);
+  }
+  if (startDate && endDate) {
+    const isHourly = startDate.length > 10;
+    const cohortField = isHourly ? "cohortHour" : "cohortDate";
+    filtered = filtered.filter(
+      (t) => t[cohortField] && t[cohortField] >= startDate && t[cohortField] <= endDate
+    );
+  } else if (startDate) {
+    const isHourly = startDate.length > 10;
+    const cohortField = isHourly ? "cohortHour" : "cohortDate";
+    filtered = filtered.filter((t) => t[cohortField] && t[cohortField] >= startDate);
+  } else if (endDate) {
+    const isHourly = endDate.length > 10;
+    const cohortField = isHourly ? "cohortHour" : "cohortDate";
+    filtered = filtered.filter((t) => t[cohortField] && t[cohortField] <= endDate);
+  }
+  filtered.sort((a, b) => {
+    const aTime = new Date(a.timestamp || a.createdAt).getTime();
+    const bTime = new Date(b.timestamp || b.createdAt).getTime();
+    return bTime - aTime;
+  });
+  if (limit && limit > 0) {
+    filtered = filtered.slice(0, limit);
+  }
+  return filtered;
+}
 
 function addHelperMethods(resource, plugin, config) {
   resource.set = async (id, field, value) => {
@@ -7780,6 +8655,214 @@ class EventualConsistencyPlugin extends Plugin {
   async getLastNMonths(resourceName, field, months = 12, options = {}) {
     return await getLastNMonths(resourceName, field, months, options, this.fieldHandlers);
   }
+  /**
+   * Get raw transaction events for custom aggregation
+   *
+   * This method provides direct access to the underlying transaction events,
+   * allowing developers to perform custom aggregations beyond the pre-built analytics.
+   * Useful for complex queries, custom metrics, or when you need the raw event data.
+   *
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {Object} options - Query options
+   * @param {string} options.recordId - Filter by specific record ID
+   * @param {string} options.startDate - Start date filter (YYYY-MM-DD or YYYY-MM-DDTHH)
+   * @param {string} options.endDate - End date filter (YYYY-MM-DD or YYYY-MM-DDTHH)
+   * @param {string} options.cohortDate - Filter by cohort date (YYYY-MM-DD)
+   * @param {string} options.cohortHour - Filter by cohort hour (YYYY-MM-DDTHH)
+   * @param {string} options.cohortMonth - Filter by cohort month (YYYY-MM)
+   * @param {boolean} options.applied - Filter by applied status (true/false/undefined for both)
+   * @param {string} options.operation - Filter by operation type ('add', 'sub', 'set')
+   * @param {number} options.limit - Maximum number of events to return
+   * @returns {Promise<Array>} Raw transaction events
+   *
+   * @example
+   * // Get all events for a specific record
+   * const events = await plugin.getRawEvents('wallets', 'balance', {
+   *   recordId: 'wallet1'
+   * });
+   *
+   * @example
+   * // Get events for a specific time range
+   * const events = await plugin.getRawEvents('wallets', 'balance', {
+   *   startDate: '2025-10-01',
+   *   endDate: '2025-10-31'
+   * });
+   *
+   * @example
+   * // Get only pending (unapplied) transactions
+   * const pending = await plugin.getRawEvents('wallets', 'balance', {
+   *   applied: false
+   * });
+   */
+  async getRawEvents(resourceName, field, options = {}) {
+    return await getRawEvents(resourceName, field, options, this.fieldHandlers);
+  }
+  /**
+   * Get diagnostics information about the plugin state
+   *
+   * This method provides comprehensive diagnostic information about the EventualConsistencyPlugin,
+   * including configured resources, field handlers, timers, and overall health status.
+   * Useful for debugging initialization issues, configuration problems, or runtime errors.
+   *
+   * @param {Object} options - Diagnostic options
+   * @param {string} options.resourceName - Optional: limit diagnostics to specific resource
+   * @param {string} options.field - Optional: limit diagnostics to specific field
+   * @param {boolean} options.includeStats - Include transaction statistics (default: false)
+   * @returns {Promise<Object>} Diagnostic information
+   *
+   * @example
+   * // Get overall plugin diagnostics
+   * const diagnostics = await plugin.getDiagnostics();
+   * console.log(diagnostics);
+   *
+   * @example
+   * // Get diagnostics for specific resource/field with stats
+   * const diagnostics = await plugin.getDiagnostics({
+   *   resourceName: 'wallets',
+   *   field: 'balance',
+   *   includeStats: true
+   * });
+   */
+  async getDiagnostics(options = {}) {
+    const { resourceName, field, includeStats = false } = options;
+    const diagnostics = {
+      plugin: {
+        name: "EventualConsistencyPlugin",
+        initialized: this.database !== null && this.database !== void 0,
+        verbose: this.config.verbose || false,
+        timezone: this.config.cohort?.timezone || "UTC",
+        consolidation: {
+          mode: this.config.consolidation?.mode || "timer",
+          interval: this.config.consolidation?.interval || 6e4,
+          batchSize: this.config.consolidation?.batchSize || 100
+        },
+        garbageCollection: {
+          enabled: this.config.garbageCollection?.enabled !== false,
+          retentionDays: this.config.garbageCollection?.retentionDays || 30,
+          interval: this.config.garbageCollection?.interval || 36e5
+        }
+      },
+      resources: [],
+      errors: [],
+      warnings: []
+    };
+    for (const [resName, resourceHandlers] of this.fieldHandlers.entries()) {
+      if (resourceName && resName !== resourceName) {
+        continue;
+      }
+      const resourceDiag = {
+        name: resName,
+        fields: []
+      };
+      for (const [fieldName, handler] of resourceHandlers.entries()) {
+        if (field && fieldName !== field) {
+          continue;
+        }
+        const fieldDiag = {
+          name: fieldName,
+          type: handler.type || "counter",
+          analyticsEnabled: handler.analyticsResource !== null && handler.analyticsResource !== void 0,
+          resources: {
+            transaction: handler.transactionResource?.name || null,
+            target: handler.targetResource?.name || null,
+            analytics: handler.analyticsResource?.name || null
+          },
+          timers: {
+            consolidation: handler.consolidationTimer !== null && handler.consolidationTimer !== void 0,
+            garbageCollection: handler.garbageCollectionTimer !== null && handler.garbageCollectionTimer !== void 0
+          }
+        };
+        if (!handler.transactionResource) {
+          diagnostics.errors.push({
+            resource: resName,
+            field: fieldName,
+            issue: "Missing transaction resource",
+            suggestion: "Ensure plugin is installed and resources are created after plugin installation"
+          });
+        }
+        if (!handler.targetResource) {
+          diagnostics.warnings.push({
+            resource: resName,
+            field: fieldName,
+            issue: "Missing target resource",
+            suggestion: "Target resource may not have been created yet"
+          });
+        }
+        if (handler.analyticsResource && !handler.analyticsResource.name) {
+          diagnostics.errors.push({
+            resource: resName,
+            field: fieldName,
+            issue: "Invalid analytics resource",
+            suggestion: "Analytics resource exists but has no name - possible initialization failure"
+          });
+        }
+        if (includeStats && handler.transactionResource) {
+          try {
+            const [okPending, errPending, pendingTxns] = await handler.transactionResource.query({ applied: false }).catch(() => [false, null, []]);
+            const [okApplied, errApplied, appliedTxns] = await handler.transactionResource.query({ applied: true }).catch(() => [false, null, []]);
+            fieldDiag.stats = {
+              pendingTransactions: okPending ? pendingTxns?.length || 0 : "error",
+              appliedTransactions: okApplied ? appliedTxns?.length || 0 : "error",
+              totalTransactions: okPending && okApplied ? (pendingTxns?.length || 0) + (appliedTxns?.length || 0) : "error"
+            };
+            if (handler.analyticsResource) {
+              const [okAnalytics, errAnalytics, analyticsRecords] = await handler.analyticsResource.list().catch(() => [false, null, []]);
+              fieldDiag.stats.analyticsRecords = okAnalytics ? analyticsRecords?.length || 0 : "error";
+            }
+          } catch (error) {
+            diagnostics.warnings.push({
+              resource: resName,
+              field: fieldName,
+              issue: "Failed to fetch statistics",
+              error: error.message
+            });
+          }
+        }
+        resourceDiag.fields.push(fieldDiag);
+      }
+      if (resourceDiag.fields.length > 0) {
+        diagnostics.resources.push(resourceDiag);
+      }
+    }
+    diagnostics.health = {
+      status: diagnostics.errors.length === 0 ? diagnostics.warnings.length === 0 ? "healthy" : "warning" : "error",
+      totalResources: diagnostics.resources.length,
+      totalFields: diagnostics.resources.reduce((sum, r) => sum + r.fields.length, 0),
+      errorCount: diagnostics.errors.length,
+      warningCount: diagnostics.warnings.length
+    };
+    return diagnostics;
+  }
+}
+
+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 {
@@ -8088,7 +9171,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);
@@ -8105,7 +9194,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}:`)) {
@@ -8890,6 +9984,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);
@@ -8950,13 +10073,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") {
@@ -8967,7 +10109,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;
     });
@@ -8980,6 +10129,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();
@@ -9005,7 +10183,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
@@ -9014,14 +10197,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
@@ -10193,7 +11386,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;
   }
@@ -10907,7 +12110,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: "" };
 }
@@ -10922,7 +12132,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) };
 }
@@ -10937,7 +12155,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: "" };
 }
@@ -11279,7 +12505,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;
 }
@@ -11401,6 +12631,7 @@ ${errorDetails}`,
       idGenerator: customIdGenerator,
       idSize = 22,
       versioningEnabled = false,
+      strictValidation = true,
       events = {},
       asyncEvents = true,
       asyncPartitions = true,
@@ -11414,6 +12645,7 @@ ${errorDetails}`,
     this.parallelism = parallelism;
     this.passphrase = passphrase ?? "secret";
     this.versioningEnabled = versioningEnabled;
+    this.strictValidation = strictValidation;
     this.setAsyncMode(asyncEvents);
     this.idGenerator = this.configureIdGenerator(customIdGenerator, idSize);
     if (typeof customIdGenerator === "number" && customIdGenerator > 0) {
@@ -11661,9 +12893,12 @@ ${errorDetails}`,
   }
   /**
    * Validate that all partition fields exist in current resource attributes
-   * @throws {Error} If partition fields don't exist in current schema
+   * @throws {Error} If partition fields don't exist in current schema (only when strictValidation is true)
    */
   validatePartitions() {
+    if (!this.strictValidation) {
+      return;
+    }
     if (!this.config.partitions) {
       return;
     }
@@ -13798,7 +15033,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "11.2.2" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "11.2.4" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};
@@ -13813,6 +15048,7 @@ class Database extends EventEmitter {
     this.passphrase = options.passphrase || "secret";
     this.versioningEnabled = options.versioningEnabled || false;
     this.persistHooks = options.persistHooks || false;
+    this.strictValidation = options.strictValidation !== false;
     this._initHooks();
     let connectionString = options.connectionString;
     if (!connectionString && (options.bucket || options.accessKeyId || options.secretAccessKey)) {
@@ -13934,6 +15170,7 @@ class Database extends EventEmitter {
           asyncEvents: versionData.asyncEvents !== void 0 ? versionData.asyncEvents : true,
           hooks: this.persistHooks ? this._deserializeHooks(versionData.hooks || {}) : versionData.hooks || {},
           versioningEnabled: this.versioningEnabled,
+          strictValidation: this.strictValidation,
           map: versionData.map,
           idGenerator: restoredIdGenerator,
           idSize: restoredIdSize
@@ -14141,7 +15378,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();
@@ -14595,6 +15837,7 @@ class Database extends EventEmitter {
       autoDecrypt: config.autoDecrypt !== void 0 ? config.autoDecrypt : true,
       hooks: hooks || {},
       versioningEnabled: this.versioningEnabled,
+      strictValidation: this.strictValidation,
       map: config.map,
       idGenerator: config.idGenerator,
       idSize: config.idSize,
@@ -14773,10 +16016,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);
   }
@@ -14914,7 +16167,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,
@@ -14945,7 +16202,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 = [];
@@ -15013,7 +16276,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;
   }
@@ -15081,7 +16351,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];
   }
@@ -15130,7 +16406,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();
       }
@@ -15517,7 +16799,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);
 }
@@ -15529,12 +16816,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 || [],
@@ -15960,7 +17275,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) {
@@ -16490,6 +17811,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();
@@ -16523,17 +17873,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)"
+        });
       }
     }
   }
@@ -16831,10 +18200,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);
   }
@@ -16844,7 +18223,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);
@@ -16856,7 +18240,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);
@@ -16955,13 +18344,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,
@@ -16995,7 +18399,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) {
@@ -17049,6 +18458,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();
@@ -17069,17 +18508,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"
+        });
       }
     }
   }
@@ -17136,12 +18594,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]) {
@@ -17152,7 +18623,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"
+          });
         }
       }
     }
@@ -17262,7 +18742,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);
@@ -17288,7 +18773,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]) {
@@ -17337,7 +18827,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);
@@ -17356,7 +18851,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];
@@ -17385,7 +18887,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} {
 `;
@@ -17430,10 +18937,12 @@ class StateMachinePlugin extends Plugin {
 }
 
 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;
@@ -17448,15 +18957,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;
@@ -17473,6 +18986,7 @@ exports.SchedulerPlugin = SchedulerPlugin;
 exports.Schema = Schema;
 exports.SchemaError = SchemaError;
 exports.StateMachinePlugin = StateMachinePlugin;
+exports.StreamError = StreamError;
 exports.UnknownError = UnknownError;
 exports.ValidationError = ValidationError;
 exports.Validator = Validator;