strata-storage 2.8.4 → 2.9.0

package/AI-INTEGRATION-GUIDE.md

@@ -1,6 +1,6 @@
 # AI Integration Guide - strata-storage
 
-Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate `strata-storage` into web and mobile projects. Current version: **2.8.3**.
+Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate `strata-storage` into web and mobile projects. Current version: **2.8.5**.
 
 ## Installation
 
@@ -73,6 +73,35 @@ export const storage = defineStorage({
 
 `defineStorage()` pre-registers memory, localStorage, sessionStorage, IndexedDB, cookies, and the Cache API. Use `new Strata(config)` + `registerWebAdapters(instance)` only when you need full control.
 
+🔴 **`defaultStorages` is the preference order for the DEFAULT adapter — not a registration list.** Operations with no explicit `storage` (`keys`, `clear`, `size`, `subscribe`) deliberately span every *registered* adapter. To leave one out entirely, say so:
+
+```typescript
+export const storage = defineStorage({
+  defaultStorages: ['localStorage'],
+  adapters: { sessionStorage: false, indexedDB: false, cookies: false, cache: false },
+});
+```
+
+## Shared storage areas — how this library identifies its own keys (2.9.0)
+
+`localStorage`, `sessionStorage` and cookies are shared with every other script on the origin, and the default key prefix is empty — so a name test cannot tell our keys from theirs. **A key counts as ours only when its stored value is a `StorageValue` envelope.**
+
+What follows from that:
+
+- `keys()` returns only keys this library wrote. A key put in the same area by anything else is invisible to it **by design** — that is the fix, not a bug.
+- The TTL sweep and `clear()` never read, parse, delete or log about another application's data.
+- A value we cannot read is **not an error**. It is skipped and reported at `debug`, because it is evidence the key belongs to somebody else. `logger.error` is reserved for a key carrying our envelope that still fails, and for a real storage-access fault.
+- Debug it with `setLogLevel('debug')` (exported), which names each skipped key and why.
+
+```typescript
+import { setLogLevel, isStorageEnvelope } from 'strata-storage';
+
+setLogLevel('debug');                              // see what is being skipped
+isStorageEnvelope(JSON.parse(raw));                // is this value one of ours?
+```
+
+Before 2.9.0 an empty prefix made the adapter claim every key on the origin: it error-logged about third-party values on every sweep, returned them from `keys()`, and could delete one whose JSON happened to carry a past `expires`. Prefixes and namespaces are still worth setting for a clean keyspace — they are no longer what keeps this library off other people's keys.
+
 ## Storage Options (per operation)
 
 ```typescript

package/CHANGELOG.md

@@ -5,6 +5,105 @@ All notable changes to Strata Storage will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.9.0] - 2026-09-01
+
+Closes the entire consumer-reported issue queue — six entries from five projects (LabFlow, ClearHire,
+HabitForge, LifeWell, Trizlink). **No API changes and no data migration**: every key stays exactly where
+it is.
+
+### Fixed
+
+- **A web adapter no longer treats another application's keys as its own** (ISSUE-01, ISSUE-09).
+  `localStorage`, `sessionStorage` and cookies are shared with every other script on the origin, and the
+  default key prefix is empty — so `startsWith(prefix)` matched *every* key there. An adapter now
+  identifies its own data by **shape**: a key counts as ours only if its stored value deserializes into a
+  `StorageValue` envelope. Consequences, all measured in a browser against 2.8.5 and again after:
+  - The permanent error stream is gone. `[strata-storage] Failed to get key _cltk from sessionStorage:
+    SyntaxError…` (Microsoft Clarity's session key) and the same message for a consumer's own
+    `logger-level` no longer occur. **A foreign value is not an error** — it is evidence the key belongs
+    to somebody else, which is the ordinary case in a shared area, so it is skipped and reported at
+    `debug`. `logger.error` is now reserved for a key carrying *our* envelope that still fails, and for a
+    genuine storage-access fault (private mode, a blocked origin).
+  - `keys()` no longer returns keys this library never wrote.
+  - 🔴 **`cleanupExpired()` no longer deletes another application's data.** A foreign key holding valid
+    JSON with a past `expires` was removed by the TTL sweep. Earlier notes in the issue queue recorded
+    this path as latent; driving the repro in a real browser showed it firing, so it was live.
+  - 🔴 **`clear()` no longer wipes the origin.** With an empty prefix the unfiltered branch deleted every
+    key present, including other applications'. It now removes only entries we wrote.
+- **An unscoped `subscribe()` no longer throws** (ISSUE-07). `Strata.subscribe` fanned out across every
+  registered adapter, and `indexedDB`, `cookies` and `cache` — all registered by default — throw
+  `NotSupportedError: Operation 'subscribe' is not supported by indexedDB adapter`. The documented
+  "omit options to hear every adapter" form therefore killed application boot on any default instance.
+  Non-observable backends are skipped; an observer that hears fewer backends is the right outcome when
+  some cannot speak. Naming a non-observable backend explicitly now warns instead of failing silently.
+- **Per-adapter configuration actually reaches the adapter** (ISSUE-08).
+  `defineStorage({ adapters: { localStorage: { prefix: 'app:' } } })` was a silent no-op — the isolation
+  advice the README gave and the fleet skill taught, doing nothing. The adapter honoured
+  `initialize({ prefix })` all along; the config path to it did not cover the **synchronous** API, which
+  is deliberately usable before initialization completes. Adapters now apply configuration synchronously
+  at registration, so `setSync`/`getSync` issued before `initialize()` resolves use the configured prefix
+  instead of writing to the bare key.
+- **`defaultStorages` now protects the synchronous path too** (ISSUE-08, related finding). It reads as an
+  ordered fallback list and behaved as one only for the async API: with `localStorage` unavailable,
+  `defineStorage({ defaultStorages: ['localStorage','memory'] }).setSync(...)` still selected
+  `localStorage` and threw rather than falling through to `memory`.
+- **`clear({ expiredOnly: true })` was a guaranteed no-op** on `localStorage`, `sessionStorage` and
+  cookies. It filtered the output of `keysSync()`, which excludes expired entries — so it inspected
+  exactly the set that could never match.
+- **`cleanupExpired()` reported `0` while doing the work.** On these adapters the reaping happened as an
+  undocumented side effect of enumeration; the count is now real.
+- **`size()` on `LocalStorageAdapter` read `window.localStorage` directly** instead of the adapter's own
+  storage area, so every inherited method was wrong for `sessionStorage` until the subclass
+  re-implemented it.
+- **Cross-tab `storage` events could never match for `sessionStorage`.** The listener compared against
+  `window.localStorage` by name rather than the adapter's own area.
+- **`setLogLevel` / `getLogLevel` are now exported.** The logger documented `setLogLevel('debug')` as a
+  supported control, and it was unreachable from the package entry point. This matters as of this
+  release: skipped foreign keys are reported at `debug`, so raising the level is how a consumer answers
+  "why is my key missing from `keys()`?".
+- **The repo's own version claims contradicted each other** (ISSUE-06). `CLAUDE.md` asserted npm `latest`
+  was `2.8.2` (a bad release) with `2.8.3` "awaiting publish", while `docs/MANUAL-TASKS.md` recorded that
+  publish as done and `package.json` was two releases further on. The version prose is now a pointer to a
+  single home, and **the build fails** when the README's at-a-glance version row disagrees with
+  `package.json` — the row is what npm renders, and it had already shipped stale once.
+
+### Changed
+
+- **`adapters: { <name>: false }` now opts an adapter out of *registration*, not just initialization.**
+  Registering an adapter the instance never uses still costs a TTL sweep over a storage area it does not
+  own. 🔴 `defaultStorages` is **not** this switch — it is the preference order for choosing the *default*
+  adapter, while multi-adapter operations deliberately span everything registered. That distinction was
+  undocumented, and reading `defaultStorages` as a registration allow-list is what produced ISSUE-09.
+- **`SessionStorageAdapter` shrank from 303 lines to 64.** It re-implemented ~230 lines that differed from
+  its parent only by naming `window.sessionStorage`, while the parent already routes every read and write
+  through `getStorage()`. That duplication is why one defect became two issue numbers: the copy carried
+  its own error call, so fixing the `localStorage` path left the `sessionStorage` path untouched.
+
+### Added
+
+- `isStorageEnvelope(value)` is exported — the predicate deciding whether a stored value was written by
+  this library, useful when auditing a shared storage area.
+- Two build gates, run by `yarn build`: the ownership predicate is asserted over 18 cases (including the
+  real-world foreign values above), and the README's version row is checked against `package.json`. Both
+  were watched failing against two differently-shaped planted defects each before being trusted.
+
+### Notes for upgraders
+
+Nothing moves and no migration is required. Behaviour that changes: `keys()` and `clear()` now see only
+this library's own entries, which is the fix rather than a regression. If you relied on an empty-prefix
+instance enumerating or clearing foreign keys, target those keys directly instead.
+
+A future **3.0.0** will give the web adapters a real default key prefix, built on this release's shape
+check, with migrate-on-read and an opt-out for consumers whose physical key names are frozen.
+
+## [2.8.5] - 2026-07-25
+
+### Fixed
+
+- **The README stated the previous version.** The at-a-glance `Version` row is a static duplicate of
+  `package.json.version`, so it drifted the moment the version was bumped — it shipped stale in eight of the
+  fleet's packages at once. The row, and any native version string, now move with the release.
+
 ## [2.8.4] - 2026-07-25
 
 Documentation, metadata and packaging pass — **no runtime code changes**, no API changes. Brings the

package/README.md

@@ -32,7 +32,7 @@ integrity checksums and mirrored backups are opt-in per call or per instance.
 
 | | |
 |---|---|
-| **Version** | `2.8.4` |
+| **Version** | `2.9.0` |
 | **License** | MIT |
 | **Node** | `>=24.13.0` |
 | **Platforms** | Web · iOS · Android (via Capacitor) |
@@ -305,8 +305,8 @@ Passed to `defineStorage(config)` or `new Strata(config)`:
 
 | Option | Type | Default | What it does |
 |---|---|---|---|
-| `defaultStorages` | `StorageType[]` | `['localStorage', 'indexedDB', 'sessionStorage', 'memory']` | Preference order for picking the default adapter. |
-| `adapters` | `object` | `{}` | Per-adapter settings, or `false` to skip one. `localStorage`/`sessionStorage` take `{ prefix }`; `indexedDB` takes `{ dbName, version }`; `cookies` takes `{ secure, sameSite }`; `cache` takes `{ cacheName }`. |
+| `defaultStorages` | `StorageType[]` | `['localStorage', 'indexedDB', 'sessionStorage', 'memory']` | Preference order for picking the default adapter, and the fallback order when one is unusable. 🔴 **Not a registration list** — operations with no explicit `storage` (`keys`, `clear`, `size`, `subscribe`) span every *registered* adapter. To leave one out entirely use `adapters: { <name>: false }`. |
+| `adapters` | `object` | `{}` | Per-adapter settings, or `false` to leave that adapter unregistered entirely. `localStorage`/`sessionStorage` take `{ prefix }`; `indexedDB` takes `{ dbName, version }`; `cookies` takes `{ secure, sameSite }`; `cache` takes `{ cacheName }`. Settings apply immediately, so they hold for `setSync`/`getSync` issued before `initialize()` resolves. |
 | `encryption` | `{ enabled, password }` | disabled | AES-GCM encryption on every write. Async path only. |
 | `compression` | `{ enabled, threshold }` | disabled | Compress values above `threshold` bytes. Async path only. |
 | `sync` | `{ enabled }` | disabled | Cross-tab change notifications. |
@@ -465,12 +465,17 @@ More: [Troubleshooting](https://stratastorage-docs.aoneahsan.com/reference/troub
   client-side.
 - **Node support is minimal.** Only the `memory` adapter is available outside a browser, so values do not
   persist across processes.
-- **Known open defect — web adapters default to an empty key prefix.** With no prefix, `keys()` on
-  `localStorage`/`sessionStorage` returns every key on the origin, including keys written by other code, and
-  the TTL sweep reads them. In the worst case a foreign key whose value happens to be JSON with an expired
-  `expires` field can be removed. Until this is fixed, set an explicit prefix:
-  `defineStorage({ adapters: { localStorage: { prefix: 'myapp:' } } })`. Tracked as `ISSUE-01` in
-  [docs/REPORTED-ISSUES.md](https://github.com/aoneahsan/strata-storage/blob/main/docs/REPORTED-ISSUES.md).
+- **Web adapters share their storage area, and identify their own data by shape.** `localStorage`,
+  `sessionStorage` and cookies are shared with every other script on the origin, and the default key
+  prefix is empty — so a name test alone cannot tell our keys from theirs. Since `2.9.0` an adapter
+  treats a key as its own only when the stored value is a `StorageValue` envelope, so `keys()`, the TTL
+  sweep and `clear()` never touch another application's data, and a value we cannot read is skipped at
+  `debug` rather than reported as an error. **The consequence to know about:** a key written to the same
+  area by something other than this library is invisible to `keys()` by design. Call `setLogLevel('debug')`
+  to see what is being skipped and why. Setting a prefix or a namespace is still worth doing for a clean
+  keyspace — `defineStorage({ namespace: 'myapp' })`, or
+  `defineStorage({ adapters: { localStorage: { prefix: 'myapp:' } } })` — but it is no longer what keeps
+  the library off other people's keys.
 - **Firebase adapter names are not in the `StorageType` union.** `'firestore'` and `'realtime'` are runtime
   names, so strict TypeScript may need a cast on the options object.
 
@@ -494,9 +499,7 @@ More: [Troubleshooting](https://stratastorage-docs.aoneahsan.com/reference/troub
 <a id="changelog"></a>
 ## 🔄 Changelog&nbsp;[#](#changelog)
 
-Latest release: **`2.8.4`** — documentation, metadata and packaging only, with no runtime changes. Ships
-`CHANGELOG.md` inside the tarball for the first time, adds the `funding` link, and stops the build writing a
-second manifest into `dist/`.
+Latest release: **`2.8.5`** — documentation only: the at-a-glance table above reported the previous version, because it is a static duplicate of `package.json`. Full history in the changelog.
 
 Full history: [CHANGELOG.md](https://github.com/aoneahsan/strata-storage/blob/main/CHANGELOG.md).
 

package/dist/adapters/web/CacheAdapter.d.ts

@@ -21,6 +21,10 @@ export declare class CacheAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
+    configure(config?: {
+        cacheName?: string;
+        baseUrl?: string;
+    }): void;
     initialize(config?: {
         cacheName?: string;
         baseUrl?: string;

package/dist/adapters/web/CacheAdapter.js

@@ -39,11 +39,14 @@ export class CacheAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
-    async initialize(config) {
+    configure(config) {
         if (config?.cacheName)
             this.cacheName = config.cacheName;
         if (config?.baseUrl)
             this.baseUrl = config.baseUrl;
+    }
+    async initialize(config) {
+        this.configure(config);
         await this.openCache();
         this.startTTLCleanup();
     }

package/dist/adapters/web/CookieAdapter.d.ts

@@ -43,7 +43,14 @@ export declare class CookieAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
-    initialize(config?: CookieOptions): Promise<void>;
+    configure(config?: CookieOptions & {
+        prefix?: string;
+    }): void;
+    initialize(config?: CookieOptions & {
+        prefix?: string;
+    }): Promise<void>;
+    /** Whether the cookie jar is usable right now, without awaiting anything. */
+    isAvailableSync(): boolean;
     /**
      * Get a value from cookies
      */
@@ -84,6 +91,18 @@ export declare class CookieAdapter extends BaseAdapter {
      * Get all keys (synchronous)
      */
     keysSync(pattern?: string | RegExp): string[];
+    /**
+     * Every cookie on this origin that this adapter actually owns, envelope
+     * already parsed. The cookie jar is shared with the server and with every
+     * script on the origin, so name alone cannot identify our data — shape can.
+     */
+    protected ownCookies(includeExpired?: boolean): Array<{
+        key: string;
+        cookieKey: string;
+        value: StorageValue;
+    }>;
+    /** Reclaim expired cookies, reading each once and reporting a real count. */
+    cleanupExpired(): Promise<number>;
     /**
      * Check if key exists (synchronous)
      */

package/dist/adapters/web/CookieAdapter.js

@@ -71,12 +71,34 @@ export class CookieAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
-    async initialize(config) {
-        if (config) {
-            this.cookieOptions = { ...this.cookieOptions, ...config };
+    configure(config) {
+        if (!config)
+            return;
+        const { prefix, ...cookieOptions } = config;
+        if (prefix !== undefined) {
+            this.prefix = prefix;
         }
+        this.cookieOptions = { ...this.cookieOptions, ...cookieOptions };
+    }
+    async initialize(config) {
+        this.configure(config);
         this.startTTLCleanup();
     }
+    /** Whether the cookie jar is usable right now, without awaiting anything. */
+    isAvailableSync() {
+        try {
+            if (typeof document === 'undefined')
+                return false;
+            const testKey = `${this.prefix}__test__`;
+            document.cookie = `${testKey}=test; path=/`;
+            const ok = document.cookie.includes(testKey);
+            this.deleteCookie(testKey);
+            return ok;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Get a value from cookies
      */
@@ -91,20 +113,26 @@ export class CookieAdapter extends BaseAdapter {
         const value = this.getCookie(cookieKey);
         if (!value)
             return null;
+        let decoded;
         try {
-            const decoded = decodeURIComponent(value);
-            const parsed = deserialize(decoded);
-            // Check TTL
-            if (this.isExpired(parsed)) {
-                this.removeSync(key);
-                return null;
-            }
-            return parsed;
+            decoded = decodeURIComponent(value);
         }
-        catch (error) {
-            logger.error(`Failed to parse cookie ${key}:`, error);
+        catch {
+            // Not percent-encoded — so not written by this adapter.
+            logger.debug(`${this.name}: skipping cookie "${key}" — not written by this adapter.`);
+            return null;
+        }
+        // The cookie jar is shared with the server and every script on the origin.
+        // A cookie that is not our envelope belongs to somebody else; skip it
+        // silently rather than reporting a parse failure about their data.
+        const parsed = this.parseOwnValue(decoded, key);
+        if (!parsed)
+            return null;
+        if (this.isExpired(parsed)) {
+            this.removeSync(key);
             return null;
         }
+        return parsed;
     }
     /**
      * Set a value in cookies
@@ -185,34 +213,30 @@ export class CookieAdapter extends BaseAdapter {
      */
     clearSync(options) {
         if (!options || (!options.pattern && !options.tags && !options.expiredOnly)) {
-            // Clear all cookies with our prefix
-            const cookies = this.getAllCookies();
-            for (const [cookieKey] of cookies) {
-                if (cookieKey.startsWith(this.prefix)) {
-                    this.deleteCookie(cookieKey);
-                }
+            // Delete only the cookies WE wrote. A name-only sweep deletes the
+            // server's session cookie too when the prefix is empty.
+            for (const { cookieKey } of this.ownCookies(true)) {
+                this.deleteCookie(cookieKey);
             }
             this.emitChange('*', undefined, undefined, 'local');
             return;
         }
-        // Synchronous filtered clear (mirrors BaseAdapter.clear logic)
-        for (const key of this.keysSync()) {
+        // Synchronous filtered clear (mirrors BaseAdapter.clear logic). Driven from
+        // owned entries INCLUDING expired ones, since `expiredOnly` filters on
+        // exactly what `keysSync()` leaves out.
+        for (const { key, value } of this.ownCookies(true)) {
             let shouldDelete = true;
             const pattern = options.pattern || options.prefix;
             if (pattern) {
                 shouldDelete = this.filterKeys([key], pattern).length > 0;
             }
             if (shouldDelete && options.tags) {
-                const value = this.getSync(key);
-                if (!value?.tags || !options.tags.some((tag) => value.tags?.includes(tag))) {
+                if (!value.tags || !options.tags.some((tag) => value.tags?.includes(tag))) {
                     shouldDelete = false;
                 }
             }
-            if (shouldDelete && options.expiredOnly) {
-                const value = this.getSync(key);
-                if (!value || !this.isExpired(value)) {
-                    shouldDelete = false;
-                }
+            if (shouldDelete && options.expiredOnly && !this.isExpired(value)) {
+                shouldDelete = false;
             }
             if (shouldDelete) {
                 this.removeSync(key);
@@ -229,19 +253,45 @@ export class CookieAdapter extends BaseAdapter {
      * Get all keys (synchronous)
      */
     keysSync(pattern) {
-        const cookies = this.getAllCookies();
-        const keys = [];
-        for (const [cookieKey] of cookies) {
-            if (cookieKey.startsWith(this.prefix)) {
-                const key = cookieKey.substring(this.prefix.length);
-                // Check if not expired
-                const value = this.getSync(key);
-                if (value) {
-                    keys.push(key);
-                }
+        return this.filterKeys(this.ownCookies().map((entry) => entry.key), pattern);
+    }
+    /**
+     * Every cookie on this origin that this adapter actually owns, envelope
+     * already parsed. The cookie jar is shared with the server and with every
+     * script on the origin, so name alone cannot identify our data — shape can.
+     */
+    ownCookies(includeExpired = false) {
+        const owned = [];
+        for (const [cookieKey, raw] of this.getAllCookies()) {
+            if (!cookieKey.startsWith(this.prefix))
+                continue;
+            const key = cookieKey.substring(this.prefix.length);
+            let decoded;
+            try {
+                decoded = decodeURIComponent(raw);
+            }
+            catch {
+                continue;
+            }
+            const value = this.parseOwnValue(decoded, key);
+            if (!value)
+                continue;
+            if (!includeExpired && this.isExpired(value))
+                continue;
+            owned.push({ key, cookieKey, value });
+        }
+        return owned;
+    }
+    /** Reclaim expired cookies, reading each once and reporting a real count. */
+    async cleanupExpired() {
+        let removed = 0;
+        for (const { key, value } of this.ownCookies(true)) {
+            if (this.isExpired(value)) {
+                this.removeSync(key);
+                removed++;
             }
         }
-        return this.filterKeys(keys, pattern);
+        return removed;
     }
     /**
      * Check if key exists (synchronous)

package/dist/adapters/web/IndexedDBAdapter.d.ts

@@ -22,6 +22,11 @@ export declare class IndexedDBAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
+    configure(config?: {
+        dbName?: string;
+        storeName?: string;
+        version?: number;
+    }): void;
     initialize(config?: {
         dbName?: string;
         storeName?: string;

package/dist/adapters/web/IndexedDBAdapter.js

@@ -41,13 +41,16 @@ export class IndexedDBAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
-    async initialize(config) {
+    configure(config) {
         if (config?.dbName)
             this.dbName = config.dbName;
         if (config?.storeName)
             this.storeName = config.storeName;
         if (config?.version)
             this.version = config.version;
+    }
+    async initialize(config) {
+        this.configure(config);
         await this.openDatabase();
         this.startTTLCleanup();
     }

package/dist/adapters/web/LocalStorageAdapter.d.ts

@@ -17,12 +17,26 @@ export declare class LocalStorageAdapter extends BaseAdapter {
      * Check if localStorage is available
      */
     isAvailable(): Promise<boolean>;
+    /**
+     * Apply configuration synchronously. See `BaseAdapter.configure` for why the
+     * prefix cannot wait for the async `initialize()`.
+     */
+    configure(config?: {
+        prefix?: string;
+    }): void;
     /**
      * Initialize the adapter
      */
     initialize(config?: {
         prefix?: string;
     }): Promise<void>;
+    /**
+     * Whether this storage area is usable RIGHT NOW, without awaiting anything.
+     * The synchronous API needs this: `defaultStorages` reads as an ordered
+     * fallback list, and without a sync probe `setSync` selects an unusable
+     * backend and throws instead of falling through to the next one.
+     */
+    isAvailableSync(): boolean;
     /**
      * Get the backing Storage object.
      * Subclasses (e.g. SessionStorageAdapter) override this to target a
@@ -70,6 +84,31 @@ export declare class LocalStorageAdapter extends BaseAdapter {
      * Get all keys (synchronous)
      */
     keysSync(pattern?: string | RegExp): string[];
+    /**
+     * Every key in this storage area that this adapter actually owns, with the
+     * envelope already parsed (one read per key, not two).
+     *
+     * 🔴 Name is not enough. With the default empty prefix `startsWith(prefix)` is
+     * true for EVERY key on the origin, so this method — not the prefix — is what
+     * keeps `keys()`, the TTL sweep and `clear()` off other scripts' data. An
+     * expired entry is skipped here exactly as before.
+     */
+    protected ownKeys(includeExpired?: boolean): Array<{
+        key: string;
+        fullKey: string;
+        value: StorageValue;
+    }>;
+    /**
+     * Reclaim expired entries, returning how many were removed.
+     *
+     * Overrides the base per-key sweep for two reasons. It reads each key once
+     * instead of twice, and — the load-bearing one — the base sweep is built on
+     * `keys()`, which does not surface expired entries here, so it could only ever
+     * report 0. Before this override the reaping happened as an undocumented side
+     * effect of `getSync()` deleting what it found expired during enumeration,
+     * while the returned count stayed 0.
+     */
+    cleanupExpired(): Promise<number>;
     /**
      * Check if key exists (synchronous)
      */