strata-storage 2.8.4 → 2.9.0

package/dist/adapters/web/URLAdapter.js

@@ -39,7 +39,7 @@ export class URLAdapter extends BaseAdapter {
             typeof window.location !== 'undefined' &&
             typeof window.history !== 'undefined');
     }
-    async initialize(config) {
+    configure(config) {
         if (config?.mode)
             this.mode = config.mode;
         if (config?.prefix !== undefined)
@@ -48,6 +48,13 @@ export class URLAdapter extends BaseAdapter {
             this.historyMode = config.history;
         if (typeof config?.maxLength === 'number')
             this.maxLength = config.maxLength;
+    }
+    /** The URL is usable whenever `window.location` is. */
+    isAvailableSync() {
+        return typeof window !== 'undefined' && typeof window.location !== 'undefined';
+    }
+    async initialize(config) {
+        this.configure(config);
         if (typeof window === 'undefined')
             return;
         // Seed the snapshot and listen for external navigation (back/forward, manual

package/dist/core/BaseAdapter.d.ts

@@ -14,6 +14,22 @@ export declare abstract class BaseAdapter implements StorageAdapter {
     protected queryEngine: QueryEngine;
     protected ttlCleanupInterval?: ReturnType<typeof setInterval>;
     protected ttlCheckInterval: number;
+    /**
+     * Apply adapter configuration SYNCHRONOUSLY, before any operation runs.
+     *
+     * 🔴 Config that changes the PHYSICAL KEY (`prefix`) cannot wait for the async
+     * `initialize()`. The synchronous API is deliberately usable before
+     * initialization completes — `Strata.selectAdapterSync()` falls back to the
+     * registry — so a `prefix` applied only at `initialize()` is silently absent
+     * for every `setSync`/`getSync` issued in that window, and the value lands at
+     * the bare key. That is the whole of ISSUE-08: `initialize({ prefix })` worked,
+     * and the config path to it did not.
+     *
+     * `initialize()` calls this first, so both paths agree. Default is a no-op;
+     * adapters with configurable fields override it with pure assignment only —
+     * never I/O, never a timer.
+     */
+    configure(_config?: unknown): void;
     /**
      * Initialize TTL cleanup if needed
      */
@@ -33,6 +49,22 @@ export declare abstract class BaseAdapter implements StorageAdapter {
      * `Strata.cleanupExpired()`.
      */
     cleanupExpired(): Promise<number>;
+    /**
+     * Parse a raw stored string into a value THIS adapter owns, or null.
+     *
+     * 🔴 The classification is the point, not the parse. Web adapters share their
+     * storage area with every other script on the origin, so a raw value that is
+     * not our envelope means the key belongs to somebody else — the ordinary case,
+     * not a failure. Reporting it through `logger.error` asserts something untrue
+     * about the consumer's own data, and on any origin running a third-party
+     * script that stores a raw string (Microsoft Clarity's `_cltk` is the usual
+     * one) it produces a permanent error stream that reaches their error tracker.
+     *
+     * `logger.error` is therefore reserved for a key carrying OUR envelope that
+     * still fails — which is a real defect, and currently cannot be distinguished
+     * from somebody else's data at all.
+     */
+    protected parseOwnValue<T = unknown>(raw: string | null, key: string): StorageValue<T> | null;
     /**
      * Check if value is expired
      */

package/dist/core/BaseAdapter.js

@@ -2,7 +2,7 @@
  * Base adapter implementation with common functionality
  */
 import { NotSupportedError } from "../utils/errors.js";
-import { EventEmitter, matchGlob, getObjectSize } from "../utils/index.js";
+import { EventEmitter, matchGlob, getObjectSize, deserialize, isStorageEnvelope } from "../utils/index.js";
 import { logger } from "../utils/logger.js";
 import { QueryEngine } from "../features/query.js";
 /**
@@ -13,6 +13,24 @@ export class BaseAdapter {
     queryEngine = new QueryEngine();
     ttlCleanupInterval;
     ttlCheckInterval = 60000; // Check every minute
+    /**
+     * Apply adapter configuration SYNCHRONOUSLY, before any operation runs.
+     *
+     * 🔴 Config that changes the PHYSICAL KEY (`prefix`) cannot wait for the async
+     * `initialize()`. The synchronous API is deliberately usable before
+     * initialization completes — `Strata.selectAdapterSync()` falls back to the
+     * registry — so a `prefix` applied only at `initialize()` is silently absent
+     * for every `setSync`/`getSync` issued in that window, and the value lands at
+     * the bare key. That is the whole of ISSUE-08: `initialize({ prefix })` worked,
+     * and the config path to it did not.
+     *
+     * `initialize()` calls this first, so both paths agree. Default is a no-op;
+     * adapters with configurable fields override it with pure assignment only —
+     * never I/O, never a timer.
+     */
+    configure(_config) {
+        // No configurable fields by default.
+    }
     /**
      * Initialize TTL cleanup if needed
      */
@@ -60,6 +78,40 @@ export class BaseAdapter {
         }
         return removed;
     }
+    /**
+     * Parse a raw stored string into a value THIS adapter owns, or null.
+     *
+     * 🔴 The classification is the point, not the parse. Web adapters share their
+     * storage area with every other script on the origin, so a raw value that is
+     * not our envelope means the key belongs to somebody else — the ordinary case,
+     * not a failure. Reporting it through `logger.error` asserts something untrue
+     * about the consumer's own data, and on any origin running a third-party
+     * script that stores a raw string (Microsoft Clarity's `_cltk` is the usual
+     * one) it produces a permanent error stream that reaches their error tracker.
+     *
+     * `logger.error` is therefore reserved for a key carrying OUR envelope that
+     * still fails — which is a real defect, and currently cannot be distinguished
+     * from somebody else's data at all.
+     */
+    parseOwnValue(raw, key) {
+        if (raw === null || raw === '')
+            return null;
+        let parsed;
+        try {
+            parsed = deserialize(raw);
+        }
+        catch {
+            logger.debug(`${this.name}: skipping key "${key}" — value is not readable as ${this.name} data ` +
+                `(not written by this adapter).`);
+            return null;
+        }
+        if (!isStorageEnvelope(parsed)) {
+            logger.debug(`${this.name}: skipping key "${key}" — value carries no storage envelope ` +
+                `(not written by this adapter).`);
+            return null;
+        }
+        return parsed;
+    }
     /**
      * Check if value is expired
      */

package/dist/core/Strata.d.ts

@@ -222,6 +222,12 @@ export declare class Strata {
     clearSync(options?: ClearOptions & StorageOptions): void;
     private requireSyncAdapter;
     private selectAdapterSync;
+    /**
+     * Whether an adapter can serve a synchronous operation right now. An adapter
+     * with no `isAvailableSync` is assumed usable — absence of a probe is not
+     * evidence of unavailability.
+     */
+    private static isUsableSync;
     private syncCapableAdapters;
     private computeExpiration;
     /**
@@ -314,6 +320,10 @@ export declare class Strata {
      * ```
      */
     registerAdapter(adapter: StorageAdapter): void;
+    /** The configured options for one adapter, or undefined when it has none. */
+    private adapterConfigFor;
+    /** Push the configured options into an adapter synchronously. */
+    private applyAdapterConfig;
     /**
      * Initialize and attach any registered adapters that are not yet active, then
      * re-pick the default adapter. Call this after `registerAdapter()` on an

package/dist/core/Strata.js

@@ -729,6 +729,8 @@ export class Strata {
     // Synchronous adapter lookup — falls back to the registry so sync operations
     // work even before async initialize() has completed.
     selectAdapterSync(storage) {
+        // An explicitly named storage is honoured as asked — the caller chose it, and
+        // a hard error naming it is more useful than a silent substitution.
         if (storage) {
             const names = Array.isArray(storage) ? storage : [storage];
             for (const name of names) {
@@ -738,19 +740,51 @@ export class Strata {
             }
             throw new StorageError(`No adapter registered for storage type(s): ${names.join(', ')}`);
         }
-        if (this.defaultAdapter)
+        if (this.defaultAdapter && Strata.isUsableSync(this.defaultAdapter)) {
             return this.defaultAdapter;
+        }
+        // 🔴 `defaultStorages` reads as an ordered fallback list, so honour it as
+        // one HERE too. It previously guarded only the async path: with
+        // localStorage unavailable (SSR, private mode, a blocked cookie policy),
+        // `defineStorage({ defaultStorages: ['localStorage','memory'] }).setSync()`
+        // still selected localStorage and threw SerializationError rather than
+        // falling through to memory, which is the whole point of listing memory.
         const preferred = this.config.defaultStorages ?? [];
         for (const name of preferred) {
             const adapter = this.adapters.get(name) ?? this.registry.get(name);
-            if (adapter)
+            if (adapter && Strata.isUsableSync(adapter))
+                return adapter;
+        }
+        for (const adapter of this.registry.getAll().values()) {
+            if (Strata.isUsableSync(adapter))
                 return adapter;
         }
+        // Nothing usable: fall back to the previous behaviour so the caller gets the
+        // adapter's own specific error rather than a vague one from here.
+        if (this.defaultAdapter)
+            return this.defaultAdapter;
         const first = this.registry.getAll().values().next().value;
         if (first)
             return first;
         throw new StorageError('No storage adapter registered for synchronous operation.');
     }
+    /**
+     * Whether an adapter can serve a synchronous operation right now. An adapter
+     * with no `isAvailableSync` is assumed usable — absence of a probe is not
+     * evidence of unavailability.
+     */
+    static isUsableSync(adapter) {
+        if (!adapter.capabilities.synchronous || !adapter.getSync)
+            return false;
+        if (!adapter.isAvailableSync)
+            return true;
+        try {
+            return adapter.isAvailableSync();
+        }
+        catch {
+            return false;
+        }
+    }
     // All sync-capable adapters (initialized set, or the registry before init).
     syncCapableAdapters() {
         const source = this.adapters.size > 0 ? this.adapters.values() : this.registry.getAll().values();
@@ -863,13 +897,43 @@ export class Strata {
         const attach = () => {
             if (cancelled)
                 return;
-            const targets = options?.storage !== undefined
+            const explicit = options?.storage !== undefined;
+            const targets = explicit
                 ? [this.adapters.get(options.storage)]
                 : Array.from(this.adapters.values());
             for (const adapter of targets) {
-                if (adapter?.subscribe) {
+                if (!adapter?.subscribe)
+                    continue;
+                // 🔴 Skip backends that cannot observe rather than letting the first one
+                // abort the fan-out. `BaseAdapter.subscribe` throws NotSupportedError
+                // when `capabilities.observable` is false — true for indexedDB, cookies
+                // and cache, ALL of which the default registration includes — so the
+                // documented options-less "hear every adapter" form threw on every
+                // default instance and took application boot down with it.
+                //
+                // An observer that hears fewer backends is the correct outcome of "hear
+                // every adapter" when some cannot speak. When the caller named ONE
+                // backend explicitly they get told, because silence is not what they
+                // asked for.
+                if (!adapter.capabilities.observable) {
+                    if (explicit) {
+                        logger.warn(`subscribe: storage "${adapter.name}" does not support change events, so this ` +
+                            `subscription will never fire. Target an observable backend ` +
+                            `(memory, localStorage, sessionStorage, url).`);
+                    }
+                    else {
+                        logger.debug(`subscribe: skipping non-observable adapter "${adapter.name}".`);
+                    }
+                    continue;
+                }
+                // A custom adapter may still refuse despite advertising the capability;
+                // one that does must not cost the caller every other subscription.
+                try {
                     unsubscribers.push(adapter.subscribe(effectiveCallback));
                 }
+                catch (error) {
+                    logger.debug(`subscribe: adapter "${adapter.name}" refused to attach:`, error);
+                }
             }
         };
         // Attach now if ready; otherwise once initialization completes — so a
@@ -1231,6 +1295,31 @@ export class Strata {
      */
     registerAdapter(adapter) {
         this.registry.register(adapter);
+        // 🔴 Apply the adapter's config NOW, not at initialize(). The synchronous
+        // API is usable before initialization completes (selectAdapterSync falls
+        // back to the registry), so a `prefix` applied only in the async
+        // initialize() is silently absent for every setSync/getSync issued in that
+        // window and the value lands at the bare key. That was ISSUE-08: the
+        // adapter honoured `initialize({ prefix })` all along, and the config path
+        // to it did not reach the sync path.
+        this.applyAdapterConfig(adapter);
+    }
+    /** The configured options for one adapter, or undefined when it has none. */
+    adapterConfigFor(name) {
+        const raw = this.config.adapters?.[name];
+        return typeof raw === 'object' && raw !== null ? raw : undefined;
+    }
+    /** Push the configured options into an adapter synchronously. */
+    applyAdapterConfig(adapter) {
+        const config = this.adapterConfigFor(adapter.name);
+        if (!config || !adapter.configure)
+            return;
+        try {
+            adapter.configure(config);
+        }
+        catch (error) {
+            logger.warn(`Failed to configure ${adapter.name} adapter:`, error);
+        }
     }
     /**
      * Initialize and attach any registered adapters that are not yet active, then
@@ -1397,8 +1486,7 @@ export class Strata {
             try {
                 if (!(await adapter.isAvailable()))
                     continue;
-                const adapterConfig = typeof rawConfig === 'object' ? rawConfig : undefined;
-                await adapter.initialize(adapterConfig);
+                await adapter.initialize(this.adapterConfigFor(name));
                 this.adapters.set(name, adapter);
             }
             catch (error) {
@@ -1609,7 +1697,9 @@ export class Strata {
         for (const s of storages) {
             const adapter = this.registry.get(s);
             if (adapter && (await adapter.isAvailable())) {
-                await adapter.initialize();
+                // Pass the adapter's configured options — initializing bare here dropped
+                // the prefix for any adapter first reached through this path.
+                await adapter.initialize(this.adapterConfigFor(s));
                 this.adapters.set(s, adapter);
                 return adapter;
             }

package/dist/index.d.ts

@@ -19,7 +19,8 @@ export { MigrationManager } from "./features/migration.js";
 export type { Migration } from "./features/migration.js";
 export { StrataError, StorageError, IntegrityError, QuotaExceededError, EncryptionError, CompressionError, SerializationError, ValidationError, NotSupportedError, AdapterNotAvailableError, } from "./utils/errors.js";
 export type { StorageType, StorageOptions, StorageValue, StorageAdapter, AdapterConfig, QueryOptions, SyncConfig, EncryptionConfig, CompressionConfig, ObserverCallback, StorageEvent, StorageCapabilities, StorageMetadata, TTLConfig, StrataConfig, StorageChange, SubscriptionCallback, UnsubscribeFunction, } from "./types/index.js";
-export { isValidKey, isValidValue, serializeValue, deserializeValue, generateId, createError, retry, debounce, throttle, } from "./utils/index.js";
+export { setLogLevel, getLogLevel, type LogLevel } from "./utils/logger.js";
+export { isValidKey, isValidValue, isStorageEnvelope, serializeValue, deserializeValue, generateId, createError, retry, debounce, throttle, } from "./utils/index.js";
 import { Strata } from "./core/Strata.js";
 import type { StrataConfig } from "./types/index.js";
 /**
@@ -28,7 +29,7 @@ import type { StrataConfig } from "./types/index.js";
  * custom instance can opt into the same default set. Returns the same instance
  * for chaining.
  */
-export declare function registerWebAdapters(strata: Strata): Strata;
+export declare function registerWebAdapters(strata: Strata, config?: StrataConfig): Strata;
 /**
  * Create a ready-to-use Strata instance with the standard web adapters
  * pre-registered — the framework-agnostic, Zustand-style entry point. Create it

package/dist/index.js

@@ -23,8 +23,17 @@ export { computeChecksum, verifyChecksum } from "./features/integrity.js";
 export { MigrationManager } from "./features/migration.js";
 // Error classes (exported as values so consumers can use `instanceof`)
 export { StrataError, StorageError, IntegrityError, QuotaExceededError, EncryptionError, CompressionError, SerializationError, ValidationError, NotSupportedError, AdapterNotAvailableError, } from "./utils/errors.js";
+// Diagnostics.
+//
+// 🔴 The logger's own documentation names `setLogLevel('debug')` as the way to
+// raise verbosity, and it was never exported from this entry point — so the
+// documented control was unreachable. That matters as of 2.9.0: keys this
+// library does not own are now SKIPPED and reported at `debug`, which is below
+// the default `warn`. Raising the level is how a consumer answers "why is my
+// key missing from keys()?", so the control has to be reachable.
+export { setLogLevel, getLogLevel } from "./utils/logger.js";
 // Utils
-export { isValidKey, isValidValue, serializeValue, deserializeValue, generateId, createError, retry, debounce, throttle, } from "./utils/index.js";
+export { isValidKey, isValidValue, isStorageEnvelope, serializeValue, deserializeValue, generateId, createError, retry, debounce, throttle, } from "./utils/index.js";
 // Create and export a default storage instance that works immediately
 import { Strata } from "./core/Strata.js";
 import { LocalStorageAdapter } from "./adapters/web/LocalStorageAdapter.js";
@@ -40,14 +49,29 @@ import { logger } from "./utils/logger.js";
  * custom instance can opt into the same default set. Returns the same instance
  * for chaining.
  */
-export function registerWebAdapters(strata) {
+export function registerWebAdapters(strata, config) {
+    // `adapters: { <name>: false }` opts an adapter out of REGISTRATION, not just
+    // out of initialization. Registering one the instance will never use still
+    // costs a TTL sweep over a storage area it does not own.
+    //
+    // 🔴 `defaultStorages` is NOT this switch. It is the preference order for
+    // picking the DEFAULT adapter; multi-adapter operations (keys/clear/size/
+    // subscribe with no `storage`) deliberately span everything registered. That
+    // distinction was undocumented, and reading `defaultStorages` as a
+    // registration allow-list is what produced ISSUE-09.
+    const enabled = (name) => config?.adapters?.[name] !== false;
     try {
         strata.registerAdapter(new MemoryAdapter()); // always-available fallback
-        strata.registerAdapter(new LocalStorageAdapter());
-        strata.registerAdapter(new SessionStorageAdapter());
-        strata.registerAdapter(new IndexedDBAdapter());
-        strata.registerAdapter(new CookieAdapter());
-        strata.registerAdapter(new CacheAdapter());
+        if (enabled('localStorage'))
+            strata.registerAdapter(new LocalStorageAdapter());
+        if (enabled('sessionStorage'))
+            strata.registerAdapter(new SessionStorageAdapter());
+        if (enabled('indexedDB'))
+            strata.registerAdapter(new IndexedDBAdapter());
+        if (enabled('cookies'))
+            strata.registerAdapter(new CookieAdapter());
+        if (enabled('cache'))
+            strata.registerAdapter(new CacheAdapter());
     }
     catch (error) {
         logger.warn('Strata Storage adapter registration warning:', error);
@@ -71,7 +95,7 @@ export function registerWebAdapters(strata) {
  * ```
  */
 export function defineStorage(config) {
-    return registerWebAdapters(new Strata(config));
+    return registerWebAdapters(new Strata(config), config);
 }
 // Default singleton — created via the same factory so behavior is identical.
 // It initializes lazily on first use, so importing the package has no I/O cost.

package/dist/types/index.d.ts

@@ -518,6 +518,19 @@ export interface StorageAdapter {
      * Get all keys
      */
     keys(pattern?: string | RegExp): Promise<string[]>;
+    /**
+     * Apply configuration synchronously, before any operation runs. Optional —
+     * an adapter with no configurable fields omits it. Implementations do pure
+     * assignment only: config that changes the physical key cannot wait for the
+     * async `initialize()`, because the synchronous API is usable before it.
+     */
+    configure?(config?: unknown): void;
+    /**
+     * Whether this backend can serve a SYNCHRONOUS operation right now, without
+     * awaiting anything. Optional; absence means "assume usable". Lets the sync
+     * path honour `defaultStorages` as the ordered fallback list it reads as.
+     */
+    isAvailableSync?(): boolean;
     /** Synchronous get — sync-capable adapters only. */
     getSync?<T = unknown>(key: string): StorageValue<T> | null;
     /** Synchronous set — sync-capable adapters only. */

package/dist/utils/index.d.ts

@@ -2,6 +2,7 @@
  * Utility functions for Strata Storage
  * Zero dependencies - all utilities implemented from scratch
  */
+import type { StorageValue } from "../types/index.js";
 /**
  * Check if code is running in a browser environment
  */
@@ -134,6 +135,24 @@ export declare function serialize(value: unknown): string;
  * pathological patterns (see SAFE_REGEX_MAX_LENGTH).
  */
 export declare function deserialize(json: string): unknown;
+/**
+ * Whether a deserialized value is a StorageValue envelope this library wrote.
+ *
+ * 🔴 This is the definition of "a key this adapter owns", and it is the ONLY
+ * thing that can answer that question when the key prefix is empty. Web
+ * adapters share their storage area with every other script on the origin, and
+ * an empty prefix makes `startsWith(prefix)` true for every key there — so name
+ * alone cannot distinguish our data from a third-party script's. Shape can.
+ *
+ * A value failing this check is not an error: it is evidence the key belongs to
+ * somebody else, which is the ordinary case in a shared area. Callers skip it
+ * silently rather than reporting a failure about data they do not own.
+ *
+ * Deliberately strict — `created` and `updated` are written by every write path
+ * (`Strata.set`, `setSync`, import, restore) and are finite numbers, so a
+ * foreign object that merely happens to carry a `value` key does not qualify.
+ */
+export declare function isStorageEnvelope(value: unknown): value is StorageValue;
 /**
  * Calculate object size in bytes (rough estimate)
  */

package/dist/utils/index.js

@@ -334,6 +334,35 @@ export function deserialize(json) {
         return val;
     });
 }
+/**
+ * Whether a deserialized value is a StorageValue envelope this library wrote.
+ *
+ * 🔴 This is the definition of "a key this adapter owns", and it is the ONLY
+ * thing that can answer that question when the key prefix is empty. Web
+ * adapters share their storage area with every other script on the origin, and
+ * an empty prefix makes `startsWith(prefix)` true for every key there — so name
+ * alone cannot distinguish our data from a third-party script's. Shape can.
+ *
+ * A value failing this check is not an error: it is evidence the key belongs to
+ * somebody else, which is the ordinary case in a shared area. Callers skip it
+ * silently rather than reporting a failure about data they do not own.
+ *
+ * Deliberately strict — `created` and `updated` are written by every write path
+ * (`Strata.set`, `setSync`, import, restore) and are finite numbers, so a
+ * foreign object that merely happens to carry a `value` key does not qualify.
+ */
+export function isStorageEnvelope(value) {
+    if (!isObject(value))
+        return false;
+    if (!('value' in value))
+        return false;
+    if (!Number.isFinite(value.created) || !Number.isFinite(value.updated))
+        return false;
+    if ('expires' in value && value.expires !== undefined && !Number.isFinite(value.expires)) {
+        return false;
+    }
+    return true;
+}
 /**
  * Calculate object size in bytes (rough estimate)
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strata-storage",
-  "version": "2.8.4",
+  "version": "2.9.0",
   "description": "One storage API across web, iOS and Android — zero runtime dependencies.",
   "type": "module",
   "packageManager": "yarn@4.17.0",

package/scripts/build.js

@@ -153,5 +153,98 @@ fs.writeFileSync(
   JSON.stringify({ type: 'module', sideEffects: false }, null, 2) + '\n'
 );
 
+// ---------------------------------------------------------------------------
+// Build gates
+//
+// This project deliberately ships no test framework — typecheck, lint and build
+// are the gates (README ▸ Limitations). These two checks live inside the build
+// for that reason: they add no dependency and no runner, and they cover exactly
+// the two things the other gates are blind to.
+// ---------------------------------------------------------------------------
+
+const fail = (message) => {
+  console.error(`\n❌ ${message}`);
+  process.exit(1);
+};
+
+// GATE 1 — the storage-ownership predicate.
+//
+// `isStorageEnvelope` decides whether a key in a SHARED storage area belongs to
+// this library. Get it wrong in the permissive direction and we are back to
+// reading, error-logging about, and deleting other applications' data (ISSUE-01,
+// ISSUE-09); wrong in the strict direction and we stop recognising our own.
+// Neither failure is visible to typecheck, lint or a green build.
+console.log('🔍 Gate: storage-ownership predicate...');
+const { isStorageEnvelope } = await import(
+  new URL('../dist/utils/index.js', import.meta.url).href
+);
+
+const envelope = (extra = {}) => ({ value: 'v', created: 1, updated: 2, ...extra });
+const OWNERSHIP_CASES = [
+  // Foreign values seen in the wild — every one of these reached logger.error
+  // before 2.9.0. `ts3hsf` is Microsoft Clarity's `_cltk`; `warn` is a consumer
+  // logger's own level key.
+  ['clarity _cltk raw string', 'ts3hsf', false],
+  ['logger-level raw string', 'warn', false],
+  ['foreign JSON object', { a: 1 }, false],
+  ['foreign JSON array', [1, 2, 3], false],
+  ['foreign object carrying a value key', { value: 'v' }, false],
+  ['null', null, false],
+  ['undefined', undefined, false],
+  ['number', 42, false],
+  ['string', 'plain', false],
+  // Near-misses: shaped like ours but not written by us.
+  ['envelope missing created', { value: 'v', updated: 2 }, false],
+  ['envelope with non-numeric updated', { value: 'v', created: 1, updated: 'x' }, false],
+  ['envelope with NaN created', { value: 'v', created: NaN, updated: 2 }, false],
+  ['envelope with non-numeric expires', envelope({ expires: 'soon' }), false],
+  // Ours, in every shape a write path produces.
+  ['plain envelope', envelope(), true],
+  ['envelope holding null', envelope({ value: null }), true],
+  ['envelope with expires', envelope({ expires: Date.now() }), true],
+  ['envelope with tags + metadata', envelope({ tags: ['a'], metadata: { b: 1 } }), true],
+  ['envelope with created 0', { value: 'v', created: 0, updated: 0 }, true],
+];
+
+const ownershipFailures = OWNERSHIP_CASES.filter(
+  ([, input, expected]) => isStorageEnvelope(input) !== expected
+).map(([name, , expected]) => `  · ${name}: expected ${expected}, got ${!expected}`);
+
+if (ownershipFailures.length > 0) {
+  fail(
+    `Storage-ownership predicate is wrong in ${ownershipFailures.length} case(s):\n` +
+      ownershipFailures.join('\n')
+  );
+}
+console.log(`   ✓ ${OWNERSHIP_CASES.length} ownership cases`);
+
+// GATE 2 — the README's version row cannot drift from package.json.
+//
+// The row is a hand-maintained duplicate of `version`, so it goes stale the
+// moment the version is bumped — it has already shipped stale once (2.8.5), and
+// three in-repo files disagreeing about the current version is ISSUE-06. This
+// asserts on the ARTEFACT that npm actually renders, not on the release process
+// that is supposed to update it.
+console.log('🔍 Gate: README version row matches package.json...');
+const pkgVersion = JSON.parse(
+  fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8')
+).version;
+const readme = fs.readFileSync(path.join(rootDir, 'README.md'), 'utf8');
+const versionRow = readme.match(/^\|\s*\*\*Version\*\*\s*\|\s*`([^`]+)`/m);
+
+if (!versionRow) {
+  fail(
+    'README has no at-a-glance `| **Version** | `x.y.z` |` row, so nothing pins the ' +
+      'published version claim. Restore the row rather than removing this gate.'
+  );
+}
+if (versionRow[1] !== pkgVersion) {
+  fail(
+    `README version row says \`${versionRow[1]}\` but package.json says \`${pkgVersion}\`. ` +
+      'Update the README row — npm renders it verbatim on the package page.'
+  );
+}
+console.log(`   ✓ README version row is ${pkgVersion}`);
+
 console.log('✅ Build completed successfully!');
 console.log(`📂 Output: ${distDir}`);