strata-storage 2.8.5 → 3.0.0

package/dist/core/Strata.js

@@ -116,6 +116,9 @@ export class Strata {
             this._ttlCleanupTimer = setInterval(() => {
                 void this.cleanupAllAdapters();
             }, interval);
+            // See BaseAdapter.startTTLCleanup — a live interval must not keep a Node
+            // process alive. No-op in browsers.
+            this._ttlCleanupTimer.unref?.();
         }
         // Start periodic auto-backup if configured
         if (this.config.autoBackup?.interval) {
@@ -729,6 +732,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 +743,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 +900,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 +1298,70 @@ 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);
+    }
+    /**
+     * Web adapters that share their storage area with every other script on the
+     * origin, and therefore take the instance-wide `keyPrefix`.
+     *
+     * Cookies are excluded deliberately: they already default to `strata_`, so
+     * moving them would break existing cookies for no gain. IndexedDB and the Cache
+     * API own a named store, memory owns its own Map, and the URL adapter already
+     * prefixes its params — none of them can collide with another script's keys.
+     */
+    static PREFIXED_WEB_ADAPTERS = new Set([
+        'localStorage',
+        'sessionStorage',
+    ]);
+    /**
+     * The configured options for one adapter, or undefined when it has none.
+     *
+     * For the shared-area web adapters this also resolves the 3.0.0 key prefix and
+     * decides whether that adapter may adopt pre-3.0 unprefixed entries. Precedence,
+     * and it lives only here:
+     *
+     *   1. `adapters.<name>.prefix` — the most specific thing the caller wrote
+     *   2. `keyPrefix` — the instance-wide switch (`false` restores 2.x behaviour)
+     *   3. the adapter's own constructor default (`DEFAULT_WEB_KEY_PREFIX`)
+     */
+    adapterConfigFor(name) {
+        const raw = this.config.adapters?.[name];
+        const explicit = typeof raw === 'object' && raw !== null ? { ...raw } : undefined;
+        if (!Strata.PREFIXED_WEB_ADAPTERS.has(name))
+            return explicit;
+        const resolved = explicit ?? {};
+        // Only fill in the prefix when the caller did not name one for this adapter.
+        if (resolved.prefix === undefined && this.config.keyPrefix !== undefined) {
+            resolved.prefix = this.config.keyPrefix === false ? '' : this.config.keyPrefix;
+        }
+        // 🔴 Migration is enabled HERE and nowhere else — only for an adapter whose
+        // prefix this instance resolved. A directly constructed adapter must never
+        // adopt bare keys: `plugin/web.ts` builds a `strata_prefs_` instance beside
+        // the main one, and if that adopted every unprefixed entry it found it would
+        // take them from the instance they belong to.
+        if (resolved.migrateLegacyKeys === undefined) {
+            resolved.migrateLegacyKeys = this.config.migrateLegacyKeys !== false;
+        }
+        return resolved;
+    }
+    /** 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 +1528,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) {
@@ -1590,6 +1720,7 @@ export class Strata {
                 }
             })();
         }, cfg.interval);
+        this._autoBackupTimer.unref?.();
     }
     async selectAdapter(storage) {
         await this.ensureReady();
@@ -1609,7 +1740,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

@@ -8,6 +8,7 @@ export { CookieAdapter } from "./adapters/web/CookieAdapter.js";
 export { CacheAdapter } from "./adapters/web/CacheAdapter.js";
 export { MemoryAdapter } from "./adapters/web/MemoryAdapter.js";
 export { URLAdapter, type URLAdapterConfig } from "./adapters/web/URLAdapter.js";
+export { DEFAULT_WEB_KEY_PREFIX } from "./adapters/web/LocalStorageAdapter.js";
 export { EncryptionManager } from "./features/encryption.js";
 export { CompressionManager } from "./features/compression.js";
 export { TTLManager } from "./features/ttl.js";
@@ -19,7 +20,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 +30,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

@@ -10,6 +10,7 @@ export { CookieAdapter } from "./adapters/web/CookieAdapter.js";
 export { CacheAdapter } from "./adapters/web/CacheAdapter.js";
 export { MemoryAdapter } from "./adapters/web/MemoryAdapter.js";
 export { URLAdapter } from "./adapters/web/URLAdapter.js";
+export { DEFAULT_WEB_KEY_PREFIX } from "./adapters/web/LocalStorageAdapter.js";
 // Core features
 export { EncryptionManager } from "./features/encryption.js";
 export { CompressionManager } from "./features/compression.js";
@@ -23,8 +24,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 +50,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 +96,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

@@ -308,6 +308,38 @@ export interface StrataConfig {
      * Default storage types in order of preference
      */
     defaultStorages?: StorageType[];
+    /**
+     * Key prefix for the web adapters that share a storage area with every other
+     * script on the origin (`localStorage`, `sessionStorage`).
+     *
+     * Defaults to `'strata:'` as of 3.0.0. Set `false` (or `''`) for the pre-3.0
+     * behaviour of writing to the bare key.
+     *
+     * 🔴 **Take the opt-out when anything outside this library reads a physical key
+     * directly** — a pre-paint theme script that runs before any module loads, or a
+     * logger reading its own level. Those readers know the exact key name, and a
+     * prefix changes it underneath them. `migrateLegacyKeys` keeps the *data*
+     * reachable through this library, but it cannot fix a hard-coded reader.
+     *
+     * Composes with `namespace`, which is a separate mechanism and unaffected:
+     * the physical key is `<keyPrefix><namespace>:<key>`. A per-adapter
+     * `adapters.localStorage.prefix` overrides this for that adapter.
+     */
+    keyPrefix?: string | false;
+    /**
+     * Whether the shared-area web adapters may adopt pre-3.0 unprefixed entries.
+     * Default `true`.
+     *
+     * Migration is per key and happens on read: a miss at the prefixed key falls
+     * back to the bare key, and if the value is one of ours it is moved under the
+     * prefix. It never overwrites an existing prefixed value, and it never adopts a
+     * value that is not a `StorageValue` envelope — which is what stops it taking
+     * another application's keys.
+     *
+     * Set `false` when two applications share an origin and one of them is still on
+     * 2.x, so that upgrading one does not move keys the other still reads.
+     */
+    migrateLegacyKeys?: boolean;
     /**
      * Adapter configuration
      */
@@ -518,6 +550,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.5",
+  "version": "3.0.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}`);