**feat(tests, docs, storage): add statistics storage tests and enhance documentation**

- **Tests**: Added new `statistics-storage.test.ts` to validate statistics storage functionality across scenarios including saving, retrieving, time-based partitioning, and backward compatibility. Ensured tests dynamically handle missing environment variables by skipping S3-related tests when credentials are unavailable.
- **Docs**: Enhanced `statistics.md` with detailed explanations of scalability improvements, including adaptive flush timing, batched updates, and time-based partitioning. Improved readability and structure.
- **Storage**: Updated all storage adapters to integrate time-based partitioning and maintain backward compatibility with legacy statistics storage formats.
- **Dependencies**: Added `dotenv` to support environmental variable management for storage adapter tests.

**Purpose**: Strengthen system reliability by adding comprehensive test coverage for statistics storage, improve scalability documentation, and ensure consistency across storage adapters with robust implementations.

package-lock.json

@@ -7,7 +7,6 @@
     "": {
       "name": "@soulcraft/brainy",
       "version": "0.20.0",
-      "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
         "@aws-sdk/client-s3": "^3.540.0",
@@ -33,6 +32,7 @@
         "@typescript-eslint/parser": "^7.4.0",
         "@vitest/coverage-v8": "^3.2.4",
         "@vitest/ui": "^3.2.4",
+        "dotenv": "^17.2.1",
         "eslint": "^8.57.0",
         "happy-dom": "^18.0.1",
         "jsdom": "^26.1.0",
@@ -4527,6 +4527,19 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/dotenv": {
+      "version": "17.2.1",
+      "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-17.2.1.tgz",
+      "integrity": "sha512-kQhDYKZecqnM0fCnzI5eIv5L4cAe/iRI+HqMbO/hbRdTAeXDG+M9FjipUxNfbARuEg4iHIbhnhs78BCHNbSxEQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://dotenvx.com"
+      }
+    },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",