strata-storage 2.5.0 → 2.6.0

package/dist/ios/Plugin/StrataStoragePlugin.swift

@@ -13,11 +13,42 @@ import Capacitor
 public class StrataStoragePlugin: CAPPlugin {
     private let userDefaultsStorage = UserDefaultsStorage()
     private let keychainStorage = KeychainStorage()
-    private let sqliteStorage = SQLiteStorage()
+    private let filesystemStorage = FilesystemStorage()
 
     /// Storage types that have a real native backend on iOS.
-    /// `filesystem` is intentionally absent — see isAvailable / resolveUnsupported.
-    private let supportedStorageTypes: Set<String> = ["preferences", "secure", "sqlite"]
+    private let supportedStorageTypes: Set<String> = ["preferences", "secure", "sqlite", "filesystem"]
+
+    // MARK: - SQLite multi-store helpers
+
+    /// Default database name (→ file `strata_storage.db`) and table.
+    private static let defaultDatabase = "strata_storage"
+    private static let defaultTable = "storage"
+
+    /// Sanitizes a database name into a safe `.db` filename. Strips everything
+    /// outside `[A-Za-z0-9_]` (which also blocks path separators / traversal),
+    /// then appends `.db`. Empty input falls back to the default. The filename
+    /// CANNOT be a bound parameter, so it must be sanitized before use.
+    private func sqliteFileName(from database: String?) -> String {
+        let raw = database ?? StrataStoragePlugin.defaultDatabase
+        let cleaned = String(raw.unicodeScalars.filter { CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_").contains($0) })
+        let safe = cleaned.isEmpty ? StrataStoragePlugin.defaultDatabase : cleaned
+        return "\(safe).db"
+    }
+
+    /// Sanitizes a table name to a safe SQL identifier matching `^[A-Za-z0-9_]+$`.
+    /// Disallowed characters are removed; empty input falls back to the default.
+    /// The table name is interpolated into SQL (it cannot be bound), so this is
+    /// the single point that guarantees injection-safety for the identifier.
+    private func sqliteTableName(from table: String?) -> String {
+        let raw = table ?? StrataStoragePlugin.defaultTable
+        let cleaned = String(raw.unicodeScalars.filter { CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_").contains($0) })
+        return cleaned.isEmpty ? StrataStoragePlugin.defaultTable : cleaned
+    }
+
+    /// Returns the cached SQLite store for the call's `database` option.
+    private func sqliteStore(for call: CAPPluginCall) -> SQLiteStorage {
+        return SQLiteStorageManager.shared.store(forFile: sqliteFileName(from: call.getString("database")))
+    }
 
     /**
      * Check if a specific storage type is available.
@@ -30,16 +61,10 @@ public class StrataStoragePlugin: CAPPlugin {
         ])
     }
 
-    private func rejectUnsupportedFilesystem(_ call: CAPPluginCall) {
-        call.reject(
-            "Filesystem storage is not implemented in the native iOS plugin. " +
-            "Use the 'preferences', 'secure', or 'sqlite' storage types, or a " +
-            "web/Capacitor Filesystem-backed adapter."
-        )
-    }
-
     /**
-     * Get value from storage
+     * Get value from storage.
+     * For sqlite/filesystem the resolved `value` is the full StorageValue
+     * wrapper object (or NSNull on a miss).
      */
     @objc func get(_ call: CAPPluginCall) {
         guard let key = call.getString("key") else {
@@ -56,10 +81,9 @@ public class StrataStoragePlugin: CAPPlugin {
             case "secure":
                 value = try keychainStorage.get(key: key)
             case "sqlite":
-                value = sqliteStorage.get(key: key)
+                value = sqliteStore(for: call).get(table: sqliteTableName(from: call.getString("table")), key: key)
             case "filesystem":
-                rejectUnsupportedFilesystem(call)
-                return
+                value = filesystemStorage.get(key: key)
             case "preferences":
                 fallthrough
             default:
@@ -75,7 +99,9 @@ public class StrataStoragePlugin: CAPPlugin {
     }
 
     /**
-     * Set value in storage
+     * Set value in storage.
+     * For sqlite/filesystem the `value` option is the full StorageValue
+     * wrapper object and is stored verbatim (JSON) for a perfect round-trip.
      */
     @objc func set(_ call: CAPPluginCall) {
         guard let key = call.getString("key") else {
@@ -83,25 +109,44 @@ public class StrataStoragePlugin: CAPPlugin {
             return
         }
 
-        let value = call.getValue("value") ?? NSNull()
         let storage = call.getString("storage") ?? "preferences"
 
         do {
             switch storage {
             case "secure":
+                let value = call.getValue("value") ?? NSNull()
                 _ = try keychainStorage.set(key: key, value: value)
             case "sqlite":
-                let ok = try sqliteStorage.set(key: key, value: value)
+                // getObject returns JSObject ([String: JSValue]); upcast each
+                // value to Any (the canonical Capacitor pattern) so the bridged
+                // Foundation values are JSONSerialization-compatible.
+                guard let jsObject = call.getObject("value") else {
+                    call.reject("SQLite value must be a StorageValue object")
+                    return
+                }
+                let ok = try sqliteStore(for: call).set(
+                    table: sqliteTableName(from: call.getString("table")),
+                    key: key,
+                    wrapper: jsObject as [String: Any]
+                )
                 if !ok {
                     call.reject("Failed to write value to SQLite")
                     return
                 }
             case "filesystem":
-                rejectUnsupportedFilesystem(call)
-                return
+                guard let jsObject = call.getObject("value") else {
+                    call.reject("Filesystem value must be a StorageValue object")
+                    return
+                }
+                let ok = try filesystemStorage.set(key: key, wrapper: jsObject as [String: Any])
+                if !ok {
+                    call.reject("Failed to write value to filesystem")
+                    return
+                }
             case "preferences":
                 fallthrough
             default:
+                let value = call.getValue("value") ?? NSNull()
                 userDefaultsStorage.set(key: key, value: value)
             }
 
@@ -127,10 +172,9 @@ public class StrataStoragePlugin: CAPPlugin {
             case "secure":
                 _ = try keychainStorage.remove(key: key)
             case "sqlite":
-                _ = sqliteStorage.remove(key: key)
+                _ = sqliteStore(for: call).remove(table: sqliteTableName(from: call.getString("table")), key: key)
             case "filesystem":
-                rejectUnsupportedFilesystem(call)
-                return
+                _ = filesystemStorage.remove(key: key)
             case "preferences":
                 fallthrough
             default:
@@ -158,10 +202,9 @@ public class StrataStoragePlugin: CAPPlugin {
             case "secure":
                 _ = try keychainStorage.clear(prefix: prefix)
             case "sqlite":
-                _ = sqliteStorage.clear(prefix: prefix)
+                _ = sqliteStore(for: call).clear(table: sqliteTableName(from: call.getString("table")), prefix: prefix)
             case "filesystem":
-                rejectUnsupportedFilesystem(call)
-                return
+                _ = filesystemStorage.clear(prefix: prefix)
             case "preferences":
                 fallthrough
             default:
@@ -188,10 +231,9 @@ public class StrataStoragePlugin: CAPPlugin {
             case "secure":
                 keys = try keychainStorage.keys(pattern: pattern)
             case "sqlite":
-                keys = sqliteStorage.keys(pattern: pattern)
+                keys = sqliteStore(for: call).keys(table: sqliteTableName(from: call.getString("table")), pattern: pattern)
             case "filesystem":
-                rejectUnsupportedFilesystem(call)
-                return
+                keys = filesystemStorage.keys(pattern: pattern)
             case "preferences":
                 fallthrough
             default:
@@ -207,32 +249,45 @@ public class StrataStoragePlugin: CAPPlugin {
     }
 
     /**
-     * Get storage size information
+     * Get storage size information.
+     * When `detailed` is true, resolves `{ total, count, detailed: { keys,
+     * values, metadata } }`; otherwise `{ total, count }`.
      */
     @objc func size(_ call: CAPPluginCall) {
         let storage = call.getString("storage") ?? "preferences"
+        let detailed = call.getBool("detailed") ?? false
 
         do {
-            let sizeInfo: (total: Int, count: Int)
+            // segments carries total/count/keys/values/metadata in bytes.
+            let segments: [String: Int]
 
             switch storage {
             case "secure":
-                sizeInfo = try keychainStorage.size()
+                let info = try keychainStorage.size()
+                segments = ["total": info.total, "count": info.count, "keys": 0, "values": info.total, "metadata": 0]
             case "sqlite":
-                sizeInfo = try sqliteStorage.size()
+                segments = try sqliteStore(for: call).size(table: sqliteTableName(from: call.getString("table")))
             case "filesystem":
-                rejectUnsupportedFilesystem(call)
-                return
+                segments = filesystemStorage.size()
             case "preferences":
                 fallthrough
             default:
-                sizeInfo = userDefaultsStorage.size()
+                let info = userDefaultsStorage.size()
+                segments = ["total": info.total, "count": info.count, "keys": 0, "values": info.total, "metadata": 0]
             }
 
-            call.resolve([
-                "total": sizeInfo.total,
-                "count": sizeInfo.count
-            ])
+            var result: [String: Any] = [
+                "total": segments["total"] ?? 0,
+                "count": segments["count"] ?? 0
+            ]
+            if detailed {
+                result["detailed"] = [
+                    "keys": segments["keys"] ?? 0,
+                    "values": segments["values"] ?? 0,
+                    "metadata": segments["metadata"] ?? 0
+                ]
+            }
+            call.resolve(result)
         } catch {
             call.reject("Failed to get size", nil, error)
         }
@@ -241,7 +296,7 @@ public class StrataStoragePlugin: CAPPlugin {
     /**
      * Query SQLite-backed storage.
      * Matches the optional `query` method in the JS contract:
-     * resolves `{ results: [{ key, value }] }`.
+     * resolves `{ results: [{ key }] }` (JS re-fetches each value via get).
      */
     @objc func query(_ call: CAPPluginCall) {
         let storage = call.getString("storage") ?? "sqlite"
@@ -252,7 +307,10 @@ public class StrataStoragePlugin: CAPPlugin {
         }
 
         let condition = call.getObject("condition") ?? [:]
-        let results = sqliteStorage.query(condition: condition)
+        let results = sqliteStore(for: call).query(
+            table: sqliteTableName(from: call.getString("table")),
+            condition: condition
+        )
         call.resolve([
             "results": results
         ])

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strata-storage",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms",
   "type": "module",
   "main": "./index.js",

package/ios/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — ios/
 
-Last Updated: 2026-04-03
+Last Updated: 2026-05-27
 
 > Agent instructions for iOS native development.
 
@@ -11,7 +11,16 @@ Last Updated: 2026-04-03
 | `Plugin/StrataStoragePlugin.swift` | Capacitor plugin entry |
 | `Plugin/UserDefaultsStorage.swift` | General key-value storage |
 | `Plugin/KeychainStorage.swift` | Secure storage |
-| `Plugin/SQLiteStorage.swift` | Database storage (~11KB) |
+| `Plugin/SQLiteStorage.swift` | SQLite database storage — multi-store (v2.6.0), `database`/`table` options honoured, full `StorageValue` wrapper round-trip, `size(detailed)` supported |
+| `Plugin/FilesystemStorage.swift` | File-per-key native storage under `NSDocumentsDirectory/strata_storage/` (new in v2.6.0); atomic writes via staging rename; `isAvailable()` returns `true` |
+
+## v2.6.0 Notes
+
+- **SQLite multi-store:** `database` option → distinct `.db` file. `table` option → sanitised table identifier `[A-Za-z0-9_]`. Previously both were ignored and all adapters shared one table.
+- **SQLite value shape:** `get` now returns the full `StorageValue` wrapper (`value`, `created`, `updated`, `expires`, `tags`, `metadata`). Corrupt rows are treated as a miss.
+- **SQLite bind safety:** text/blob binds use `SQLITE_TRANSIENT` — removes a latent use-after-free for transient Swift buffers.
+- **FilesystemStorage.swift:** new file. Writes are atomic (staging temp → rename). `keys()` excludes `.staging/` artifacts. `size(detailed: true)` returns `{ keys, values, metadata }`.
+- **Pending on-device verification** — see `docs/guides/platforms/device-verification.md`.
 
 ## Agent Rules
 
@@ -20,14 +29,20 @@ Last Updated: 2026-04-03
 - NEVER store secrets in `UserDefaultsStorage`
 
 ### SQL Safety
-- ALWAYS use parameterized queries in SQLiteStorage
+- ALWAYS use parameterized queries in `SQLiteStorage`
 - NEVER string-interpolate SQL values
+- Use `SQLITE_TRANSIENT` for text/blob binds
+
+### Filesystem Safety
+- NEVER read from `strata_storage/.staging/` — staging files are transient
+- Key sanitisation must be consistent between `set`, `get`, `remove`, and `keys`
 
 ### Plugin Architecture
 - Methods exposed through `StrataStoragePlugin.swift`
 - Each storage backend is a separate Swift file
 - Bridges Capacitor JS calls to native Swift
+- The `CAP_PLUGIN` macro must include every callable method name
 
 ### Before Modifying
 - Understand Capacitor plugin protocol
-- Test on iOS simulator after changes
+- Test on iOS simulator after changes; follow device-verification guide

package/ios/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md — ios/
 
-Last Updated: 2026-04-03
+Last Updated: 2026-05-27
 
 ## iOS Native Plugin
 
@@ -13,7 +13,8 @@ Swift implementation of native storage backends for Capacitor.
 | `Plugin/StrataStoragePlugin.swift` | Main Capacitor plugin entry point |
 | `Plugin/UserDefaultsStorage.swift` | UserDefaults-based general storage |
 | `Plugin/KeychainStorage.swift` | Keychain-based secure storage |
-| `Plugin/SQLiteStorage.swift` | SQLite database storage (~11KB) |
+| `Plugin/SQLiteStorage.swift` | SQLite database storage (multi-store, v2.6.0) |
+| `Plugin/FilesystemStorage.swift` | File-per-key storage under `NSDocumentsDirectory/strata_storage/` (new in v2.6.0) |
 
 ### Configuration
 
@@ -21,6 +22,30 @@ Swift implementation of native storage backends for Capacitor.
 - Minimum iOS version: defined in podspec
 - Language: Swift
 
+## v2.6.0 Changes
+
+### SQLite multi-store
+`SQLiteStorage.swift` now accepts `database` and `table` parameters from the
+Capacitor call options. Each unique `(database, table)` pair opens a separate
+`.db` file in the app's documents directory. Table identifiers are sanitised to
+`[A-Za-z0-9_]` before use in SQL. The full `StorageValue` wrapper is serialised
+to JSON and stored in a single `value` column; native `get` deserialises and
+returns the full wrapper so TTL, tags, and metadata survive the round-trip.
+Text/blob binds use `SQLITE_TRANSIENT` (removes a latent use-after-free for
+transient Swift buffers). `size(detailed: true)` returns per-column byte
+breakdown.
+
+### FilesystemStorage.swift (new)
+Stores each key as `NSDocumentsDirectory/strata_storage/<sanitised-key>.json`.
+Writes are atomic: the value is first written to
+`strata_storage/.staging/<key>.tmp`, then renamed into place. Temp files live in
+the staging subdirectory, so they are never exposed by `keys()` and are not
+deleted by a targeted `remove()`. `isAvailable()` returns `true` on device.
+`size(detailed: true)` supported.
+
+> **Pending on-device verification** — native code is complete and reviewed; see
+> `docs/guides/platforms/device-verification.md` for the test matrix.
+
 ## Rules
 
 ### Security (IRON-SOLID)
@@ -32,15 +57,25 @@ Swift implementation of native storage backends for Capacitor.
 - All native methods are exposed through `StrataStoragePlugin.swift`
 - Plugin bridges Capacitor JS calls to native Swift implementations
 - Each storage backend is a separate Swift file
+- The `CAP_PLUGIN` macro must list every callable method; missing entries cause
+  silent `undefined` returns on the JS side
 
 ### SQLite
-- `SQLiteStorage.swift` is the largest file (~11KB)
+- `SQLiteStorage.swift` opens or creates the `.db` file identified by the
+  `database` call option (default `strata_storage.db`)
 - Handles table creation, migrations, and CRUD operations
 - Use parameterized queries — NEVER string-interpolate SQL
+- Use `SQLITE_TRANSIENT` for text/blob binds
+
+### Filesystem
+- Key strings are sanitised before use as filenames (`/` → `_`, etc.)
+- Staging renames ensure atomic writes; never read from `.staging/`
+- `keys()` lists `.json` files only, ignoring staging artifacts
 
 ### Testing
 - Native code is tested through the Capacitor bridge
-- Test via the demo app on iOS simulator
+- Test via the demo app on iOS simulator following
+  `docs/guides/platforms/device-verification.md`
 - Verify all adapter methods work end-to-end
 
 ### Before Modifying

package/ios/Plugin/FilesystemStorage.swift

@@ -0,0 +1,218 @@
+import Foundation
+import os.log
+
+/**
+ * Filesystem-backed storage: one file per key under
+ * `<Documents>/strata_storage/`.
+ *
+ * Value-shape contract (matches src/plugin/definitions.ts, same as SQLite):
+ * - File contents are the JSON-serialized FULL `StorageValue` wrapper
+ *   `{ value, created, updated, expires?, tags?, metadata?, ... }`.
+ * - `get` parses the bytes back into the wrapper object; the plugin resolves
+ *   `{ value: wrapper }`. Missing file OR non-object bytes → miss (no crash).
+ *
+ * File naming: the storage key is percent-encoded with an allowed set that
+ * EXCLUDES `/` (and `%`), so the encoding is reversible and never escapes the
+ * storage directory. `decodeFileName` reverses it for `keys()`.
+ *
+ * Durability: writes go to a temp file in the same directory and are then
+ * atomically replaced into place, so a crash mid-write cannot leave a torn
+ * file at the real path.
+ */
+@objc public class FilesystemStorage: NSObject {
+    private let directory: URL
+    private let stagingDirectory: URL
+    private let logger = OSLog(subsystem: "com.strata.storage", category: "FilesystemStorage")
+
+    /// Reserved staging subdirectory name (inside the storage dir) holding
+    /// in-flight temp files for atomic writes. Enumeration skips it by name, so
+    /// a temp file can never collide with an encoded key file (e.g. a real key
+    /// literally named ".tmp-x").
+    private static let stagingDirName = ".strata-staging"
+
+    /// Characters allowed verbatim in an on-disk file name. Anything else
+    /// (notably `/` and `%`) is percent-escaped, keeping the name reversible
+    /// and confined to a single path component.
+    private static let fileNameAllowed: CharacterSet = {
+        var set = CharacterSet.alphanumerics
+        set.insert(charactersIn: "-_. ")
+        return set
+    }()
+
+    @objc public override init() {
+        let base = (try? FileManager.default.url(
+            for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: true
+        )) ?? URL(fileURLWithPath: NSTemporaryDirectory())
+        let storageDir = base.appendingPathComponent("strata_storage", isDirectory: true)
+        self.directory = storageDir
+        self.stagingDirectory = storageDir.appendingPathComponent(FilesystemStorage.stagingDirName, isDirectory: true)
+        super.init()
+        ensureDirectory()
+    }
+
+    private func ensureDirectory() {
+        for dir in [directory, stagingDirectory] {
+            if !FileManager.default.fileExists(atPath: dir.path) {
+                do {
+                    try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+                } catch {
+                    os_log("Failed to create filesystem storage dir: %{public}@", log: logger, type: .error, error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    /// Reversible encoding of a storage key → safe single-component file name.
+    private func encodeFileName(_ key: String) -> String {
+        // addingPercentEncoding only returns nil for invalid unichar sequences,
+        // which a Swift String key cannot contain; fall back defensively.
+        return key.addingPercentEncoding(withAllowedCharacters: FilesystemStorage.fileNameAllowed) ?? key
+    }
+
+    /// Reverses `encodeFileName`. Returns nil if the name cannot be decoded.
+    private func decodeFileName(_ name: String) -> String? {
+        return name.removingPercentEncoding
+    }
+
+    private func fileURL(forKey key: String) -> URL {
+        return directory.appendingPathComponent(encodeFileName(key), isDirectory: false)
+    }
+
+    /**
+     * Persist the full `StorageValue` wrapper for `key`. The wrapper is
+     * JSON-encoded and written atomically (temp file + replace).
+     */
+    @objc public func set(key: String, wrapper: [String: Any]) throws -> Bool {
+        ensureDirectory()
+        let data = try JSONSerialization.data(withJSONObject: wrapper, options: [])
+        let target = fileURL(forKey: key)
+
+        // Atomic write: stage to a unique temp file in the reserved staging
+        // subdir (same volume → atomic rename), then replace. The staging subdir
+        // keeps temp names out of the key namespace entirely.
+        let temp = stagingDirectory.appendingPathComponent(UUID().uuidString, isDirectory: false)
+        do {
+            try data.write(to: temp, options: .atomic)
+            if FileManager.default.fileExists(atPath: target.path) {
+                _ = try FileManager.default.replaceItemAt(target, withItemAt: temp)
+            } else {
+                try FileManager.default.moveItem(at: temp, to: target)
+            }
+        } catch {
+            // Clean up the temp file on any failure so we don't leak partials.
+            try? FileManager.default.removeItem(at: temp)
+            throw error
+        }
+        return true
+    }
+
+    /**
+     * Read the wrapper object for `key`. Missing file OR bytes that are not a
+     * JSON object → nil (treated as a miss; never throws on corrupt data).
+     */
+    @objc public func get(key: String) -> [String: Any]? {
+        let url = fileURL(forKey: key)
+        guard let data = try? Data(contentsOf: url) else {
+            return nil
+        }
+        guard let wrapper = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] else {
+            return nil
+        }
+        return wrapper
+    }
+
+    @objc public func remove(key: String) -> Bool {
+        let url = fileURL(forKey: key)
+        if !FileManager.default.fileExists(atPath: url.path) {
+            return true // already absent — treat as success/idempotent
+        }
+        do {
+            try FileManager.default.removeItem(at: url)
+            return true
+        } catch {
+            os_log("Failed to remove filesystem key: %{public}@", log: logger, type: .error, error.localizedDescription)
+            return false
+        }
+    }
+
+    /// Clears stored entries. When `prefix` is set, only keys starting with it
+    /// are removed; otherwise the whole storage directory contents are removed.
+    @objc public func clear(prefix: String? = nil) -> Bool {
+        let names = (try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []
+        var ok = true
+        for name in names {
+            // Skip the staging subdirectory (never a key).
+            if name == FilesystemStorage.stagingDirName { continue }
+            guard let key = decodeFileName(name) else { continue }
+            if let prefix = prefix, !key.hasPrefix(prefix) { continue }
+            do {
+                try FileManager.default.removeItem(at: directory.appendingPathComponent(name, isDirectory: false))
+            } catch {
+                ok = false
+            }
+        }
+        // On a full clear, also drop any orphaned in-flight temp files.
+        if prefix == nil, let temps = try? FileManager.default.contentsOfDirectory(atPath: stagingDirectory.path) {
+            for temp in temps {
+                try? FileManager.default.removeItem(at: stagingDirectory.appendingPathComponent(temp, isDirectory: false))
+            }
+        }
+        return ok
+    }
+
+    /// Lists stored keys, decoding file names back to their original keys.
+    /// When `pattern` is set, applies the same prefix/contains matching the
+    /// other backends use.
+    @objc public func keys(pattern: String? = nil) -> [String] {
+        let names = (try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []
+        var keys: [String] = []
+        for name in names {
+            if name == FilesystemStorage.stagingDirName { continue }
+            guard let key = decodeFileName(name) else { continue }
+            keys.append(key)
+        }
+        guard let pattern = pattern else { return keys }
+        return keys.filter { $0.hasPrefix(pattern) || $0.contains(pattern) }
+    }
+
+    /**
+     * Aggregate sizes over the storage directory.
+     *
+     * `count` = number of entry files; `values` = sum of file byte sizes;
+     * `keys` = sum of decoded-key UTF-8 byte lengths; `metadata` = sum of the
+     * serialized `metadata` segment per file (0 when absent or unparseable);
+     * `total` = `keys` + `values`.
+     */
+    @objc public func size() -> [String: Int] {
+        let names = (try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []
+        var count = 0
+        var keysSize = 0
+        var valuesSize = 0
+        var metadataSize = 0
+
+        for name in names {
+            if name == FilesystemStorage.stagingDirName { continue }
+            guard let key = decodeFileName(name) else { continue }
+            let url = directory.appendingPathComponent(name, isDirectory: false)
+            count += 1
+            keysSize += key.data(using: .utf8)?.count ?? 0
+
+            if let data = try? Data(contentsOf: url) {
+                valuesSize += data.count
+                if let wrapper = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
+                   let metadata = wrapper["metadata"],
+                   let metadataData = try? JSONSerialization.data(withJSONObject: metadata, options: []) {
+                    metadataSize += metadataData.count
+                }
+            }
+        }
+
+        return [
+            "count": count,
+            "keys": keysSize,
+            "values": valuesSize,
+            "metadata": metadataSize,
+            "total": keysSize + valuesSize
+        ]
+    }
+}