mnfst 0.5.198 → 0.5.199-next.0

package/lib/manifest.data.js

@@ -2,6 +2,8 @@
 
 (function () {
 
+const MANIFEST_BUILD_VERSION = '0.5.199-next.0';
+
 /* Manifest Data Sources - Configuration */
 
 // Load manifest if not already loaded (loader may set __manifestLoaded / registry.manifest).
@@ -282,6 +284,9 @@ let allDirty = true;
 // Per-source freshness: `$fresh` resolves on the first network-fresh landing of this page-load
 const freshness = new Map(); // source -> { promise, resolve, done }
 
+// Per-source generation: bumped by resetSource so an in-flight load of the old scope never lands
+const sourceGen = new Map();
+
 // Deep seal so Alpine won't proxy (double-proxying causes recursion)
 function deepSeal(obj) {
     if (obj === null || typeof obj !== 'object') {
@@ -397,6 +402,38 @@ function markFresh(dataSourceName) {
     if (!f.done) { f.done = true; f.resolve(); }
 }
 
+function sourceGeneration(dataSourceName) {
+    return sourceGen.get(dataSourceName) || 0;
+}
+
+// Drop a source from memory (rows, caches, in-flight keys, freshness): the
+// next read hydrates/fetches for the new scope; older loads are discarded
+function resetSource(dataSourceName) {
+    sourceGen.set(dataSourceName, sourceGeneration(dataSourceName) + 1);
+    const prefix = `${dataSourceName}:`;
+    for (const key of [...dataSourceCache.keys()]) if (key.startsWith(prefix)) dataSourceCache.delete(key);
+    for (const key of [...loadingPromises.keys()]) if (key.startsWith(prefix)) loadingPromises.delete(key);
+    freshness.delete(dataSourceName);
+    pendingLocal.delete(dataSourceName);
+    for (let i = pendingLandings.length - 1; i >= 0; i--) {
+        if (pendingLandings[i].source !== dataSourceName) continue;
+        pendingLandings.splice(i, 1);
+        landingResolvers.splice(i, 1)[0]?.();
+    }
+    const store = typeof Alpine !== 'undefined' ? Alpine.store('data') : null;
+    if (!store) return;
+    ensureStoreShape(store);
+    store[dataSourceName] = null;
+    rawDataStore.delete(dataSourceName);
+    store[`_${dataSourceName}_state`] = { loading: false, error: null, ready: false, stale: true, errorTime: null };
+    const proxies = window.ManifestDataProxies;
+    proxies?.clearAccessCache?.(dataSourceName);
+    proxies?.clearArrayProxyCacheForDataSource?.(dataSourceName);
+    proxies?.clearRouteProxyCacheForDataSource?.(dataSourceName);
+    proxies?.clearNestedProxyCacheForDataSource?.(dataSourceName);
+    touchSources(store, [dataSourceName]);
+}
+
 // State-only write (loading/error) — rows stay live, no version bump
 function setSourceState(dataSourceName, patch) {
     const store = typeof Alpine !== 'undefined' ? Alpine.store('data') : null;
@@ -590,17 +627,19 @@ function flushLandings() {
 
     const store = typeof Alpine !== 'undefined' ? Alpine.store('data') : null;
     const touched = new Set();
+    const landed = new Set(); // network-origin landings (persistence snapshots these)
     let settled = false;
     if (store) {
         for (const op of ops) {
             try {
                 if (op.remove) {
-                    if (removeRows(store, op.source, op.remove)) touched.add(op.source);
+                    if (removeRows(store, op.source, op.remove)) { touched.add(op.source); landed.add(op.source); }
                     continue;
                 }
                 const state = writeSource(op.source, op.rows, op.options);
                 if (!state) continue;
                 touched.add(op.source);
+                if (!op.options.persistHydration && op.rows !== null && op.rows !== undefined) landed.add(op.source);
                 // Only load completions (explicit loading state) feed render-ready; realtime upserts never do
                 if (op.options.loading !== undefined && !state.loading) settled = true;
             } catch (error) {
@@ -621,6 +660,7 @@ function flushLandings() {
         if (touched.size) touchSources(store, touched);
     }
     resolvers.forEach(resolve => resolve());
+    if (landed.size) window.ManifestDataPersist?.onLanded?.(landed);
     if (settled) checkAndDispatchRenderReady();
 }
 
@@ -1435,6 +1475,9 @@ window.ManifestDataStore = {
     setSourceState,
     runDeduped,
     sourceFreshness,
+    // Persistence (§12.2)
+    sourceGeneration,
+    resetSource,
     touchSource,
     bumpAllVersions,
     mergeRowFields,
@@ -1464,6 +1507,642 @@ window.ManifestDataStore = {
 
 
 
+/* Manifest Data Sources - Persistence (IndexedDB) */
+// Per-source snapshots hydrated before the network with fresh:false, keyed by
+// `${scope}|${source}` (PERF-PRIMITIVES-DESIGN.md §12.2). Off unless a source
+// opts in via manifest.json `persist`.
+
+(function () {
+    const STORE_NAME = 'sources';
+    const DB_VERSION = 1;
+    const WRITE_DEBOUNCE_MS = 500;
+    const BOOT_HYDRATE_MAX_WAIT_MS = 100;
+    const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+    const DEFAULT_MAX_ROWS = 1000;
+    const SECRET_PATTERNS = ['*secret*', '*token*', '*password*', 'credentials*'];
+    const NEVER_PERSIST_KEYS = new Set(['$files', '$filesLoading', '$filesError']);
+    const AUTH_EVENTS = ['manifest:auth:login', 'manifest:auth:logout', 'manifest:auth:anonymous',
+        'manifest:auth:session-cleared', 'manifest:auth:initialized', 'manifest:auth:teams-loaded'];
+    const WIPE_EVENTS = new Set(['manifest:auth:logout', 'manifest:auth:session-cleared']);
+
+    const state = {
+        configured: false,
+        enabled: false,        // at least one source opted in and IndexedDB exists
+        external: false,       // another primitive (chat windows) turned the store on
+        disabled: false,       // runtime failure → off for the rest of the session
+        disabledReason: null,
+        dbName: null,
+        dbPromise: null,
+        sources: new Map(),    // source -> config (+ rows/savedAt bookkeeping)
+        filters: new Map(),    // source -> row filter
+        scopeExpr: null,
+        scopeFn: null,
+        scope: '',
+        generation: 0,
+        pending: new Map(),    // source -> time its debounced write is due
+        writeTimer: null,
+        hydrated: new Set(),   // sources hydrated (or attempted) this generation
+        fetchKicked: new Set(),
+        watching: false,
+        deployment: null,
+        frameworkVersion: null,
+        warned: new Set()
+    };
+
+    const dataStore = () => window.ManifestDataStore;
+    const alpineData = () => (typeof Alpine !== 'undefined' && Alpine.store ? Alpine.store('data') : null);
+    const keyOf = (scope, source) => `${scope}|${source}`;
+    const liveLocale = () => (typeof document !== 'undefined' && document.documentElement?.lang)
+        || (typeof Alpine !== 'undefined' && Alpine.store?.('locale')?.current) || 'en';
+
+    function warnOnce(key, message, error) {
+        if (state.warned.has(key)) return;
+        state.warned.add(key);
+        console.warn(`[Manifest Data] ${message}`, error || '');
+    }
+
+    function disable(error) {
+        if (state.disabled) return;
+        state.disabled = true;
+        state.disabledReason = error?.name || error?.message || String(error);
+        cancelWrites();
+        warnOnce('disabled', `persistence disabled for this session (${state.disabledReason})`);
+    }
+
+    // ---- config ----
+
+    function parseTtl(value) {
+        if (typeof value === 'number') return value > 0 ? value : DEFAULT_TTL_MS;
+        if (typeof value !== 'string') return DEFAULT_TTL_MS;
+        const m = value.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)?$/i);
+        if (!m) return DEFAULT_TTL_MS;
+        const unit = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000, w: 604800000 }[(m[2] || 'ms').toLowerCase()];
+        const ms = parseFloat(m[1]) * unit;
+        return ms > 0 ? ms : DEFAULT_TTL_MS;
+    }
+
+    function globToRegExp(pattern) {
+        const escaped = String(pattern).split('*').map(part => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*');
+        return new RegExp(`^${escaped}$`, 'i');
+    }
+
+    function normalizeConfig(raw) {
+        if (raw !== true && (!raw || typeof raw !== 'object')) return null;
+        const opts = raw === true ? {} : raw;
+        const strip = Array.isArray(opts.strip) ? opts.strip : (typeof opts.strip === 'string' ? [opts.strip] : []);
+        const maxRows = Number.isFinite(opts.maxRows) && opts.maxRows > 0 ? Math.floor(opts.maxRows) : DEFAULT_MAX_ROWS;
+        return {
+            tier: opts.tier === 'lazy' ? 'lazy' : 'boot',
+            maxRows,
+            recent: typeof opts.recent === 'string' && opts.recent ? opts.recent : null,
+            ttl: parseTtl(opts.ttl),
+            stripPatterns: [...SECRET_PATTERNS, ...strip].map(globToRegExp),
+            rows: null,
+            savedAt: null
+        };
+    }
+
+    function frameworkVersion() {
+        if (typeof MANIFEST_BUILD_VERSION === 'string') return MANIFEST_BUILD_VERSION;
+        const src = typeof document !== 'undefined' ? document.currentScript?.src : null;
+        const m = src && src.match(/mnfst@(\d+\.\d+\.\d+[^/]*)/);
+        return m ? m[1] : '0.0.0';
+    }
+    const buildVersion = frameworkVersion();
+
+    function majorMinor(version) {
+        const m = String(version || '').match(/^(\d+)\.(\d+)/);
+        return m ? `${m[1]}.${m[2]}` : null;
+    }
+
+    // Reads `persist` per source and top-level `persistence`; true when anything opted in
+    function configure(manifest) {
+        state.configured = true;
+        state.sources.clear();
+        for (const [name, source] of Object.entries(manifest?.data || {})) {
+            if (!source || typeof source !== 'object') continue;
+            const cfg = normalizeConfig(source.persist);
+            if (cfg) state.sources.set(name, cfg);
+        }
+        state.scopeExpr = typeof manifest?.persistence?.scope === 'string' && manifest.persistence.scope.trim()
+            ? manifest.persistence.scope.trim() : null;
+        state.scopeFn = null;
+        state.deployment = manifest?.deployment || null;
+        state.frameworkVersion = buildVersion;
+        const projectId = manifest?.projectId || manifest?.project?.id || null;
+        const origin = (typeof location !== 'undefined' && location.origin) || 'null';
+        state.dbName = `manifest:${origin}${projectId ? `:${projectId}` : ''}`;
+        state.enabled = (state.sources.size > 0 || state.external) && typeof indexedDB !== 'undefined' && !!indexedDB;
+        if (!state.enabled) return false;
+        state.scope = evaluateScope();
+        watchScope();
+        return state.sources.size > 0;
+    }
+
+    // Late enable (runtime registration, other primitives on the same store)
+    function ensureEnabled() {
+        state.external = true;
+        if (state.enabled || state.disabled) return state.enabled;
+        if (typeof indexedDB === 'undefined' || !indexedDB) return false;
+        state.enabled = true;
+        if (!state.dbName) state.dbName = `manifest:${(typeof location !== 'undefined' && location.origin) || 'null'}`;
+        if (!state.frameworkVersion) state.frameworkVersion = buildVersion;
+        state.scope = evaluateScope();
+        watchScope();
+        return true;
+    }
+
+    // Runtime registration (harness/tests): same shape as manifest.json
+    function register(source, config) {
+        const cfg = normalizeConfig(config === undefined ? true : config);
+        if (!cfg) { state.sources.delete(source); return false; }
+        state.sources.set(source, cfg);
+        state.hydrated.delete(source);
+        state.fetchKicked.delete(source);
+        ensureEnabled();
+        return true;
+    }
+
+    function setScope(expression) {
+        state.scopeExpr = typeof expression === 'string' && expression.trim() ? expression.trim() : null;
+        state.scopeFn = null;
+        watchScope();
+        refreshScope();
+    }
+
+    // ---- scope ----
+
+    // Expression scope: `$name` → Alpine.store(name) (so `$auth` tracks reactively),
+    // else window[$name] (`$x`); bare names → globals
+    function magicScope() {
+        return new Proxy(Object.create(null), {
+            has: () => true,
+            get(_, name) {
+                if (typeof name !== 'string') return undefined;
+                if (name[0] === '$') {
+                    if (name === '$store') return (n) => (typeof Alpine !== 'undefined' ? Alpine.store(n) : undefined);
+                    if (typeof Alpine !== 'undefined' && Alpine.store) {
+                        const s = Alpine.store(name.slice(1));
+                        if (s !== undefined) return s;
+                    }
+                    return typeof window !== 'undefined' ? window[name] : undefined;
+                }
+                return globalThis[name];
+            }
+        });
+    }
+
+    function evaluateScope() {
+        if (!state.scopeExpr) return '';
+        try {
+            if (!state.scopeFn) state.scopeFn = new Function('__scope', `with (__scope) { return (${state.scopeExpr}); }`);
+            const value = state.scopeFn(magicScope());
+            return value === null || value === undefined || value === false ? '' : String(value);
+        } catch (error) {
+            warnOnce('scope', `persistence scope "${state.scopeExpr}" failed to evaluate; using ""`, error);
+            return '';
+        }
+    }
+
+    function refreshScope() {
+        if (!state.enabled) return;
+        const next = evaluateScope();
+        if (next !== state.scope) changeScope(next);
+    }
+
+    function watchScope() {
+        if (state.watching || typeof window === 'undefined') return;
+        state.watching = true;
+        for (const type of AUTH_EVENTS) {
+            window.addEventListener(type, () => {
+                if (!state.enabled) return;
+                if (WIPE_EVENTS.has(type)) deleteScope(state.scope);
+                refreshScope();
+            });
+        }
+        // Reactive re-evaluation (team switches that fire no event); the switch itself runs outside the effect
+        if (typeof Alpine !== 'undefined' && Alpine.effect) {
+            Alpine.effect(() => {
+                if (!state.scopeExpr) return;
+                const next = evaluateScope();
+                if (next !== state.scope) queueMicrotask(refreshScope);
+            });
+        }
+    }
+
+    // Scope switch: previous entries wiped, memory rows of persisted sources
+    // cleared (older loads discarded), new scope hydrates
+    function changeScope(next) {
+        const prev = state.scope;
+        state.scope = next;
+        state.generation++;
+        cancelWrites();
+        state.hydrated.clear();
+        state.fetchKicked.clear();
+        const ds = dataStore();
+        for (const [source, cfg] of state.sources) {
+            cfg.rows = null;
+            cfg.savedAt = null;
+            ds?.resetSource?.(source);
+        }
+        if (prev !== next) deleteScope(prev);
+        hydrateBoot();
+        if (typeof window !== 'undefined') {
+            try { window.dispatchEvent(new CustomEvent('manifest:persist:scope', { detail: { scope: next, previous: prev } })); } catch { /* no-op */ }
+        }
+    }
+
+    // ---- IndexedDB ----
+
+    function openDb() {
+        if (state.dbPromise) return state.dbPromise;
+        state.dbPromise = new Promise((resolve, reject) => {
+            let request;
+            try { request = indexedDB.open(state.dbName, DB_VERSION); } catch (error) { reject(error); return; }
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains(STORE_NAME)) db.createObjectStore(STORE_NAME, { keyPath: 'key' });
+            };
+            request.onsuccess = () => {
+                const db = request.result;
+                db.onversionchange = () => { try { db.close(); } catch { /* no-op */ } state.dbPromise = null; };
+                resolve(db);
+            };
+            request.onerror = () => reject(request.error || new Error('IndexedDB open failed'));
+            request.onblocked = () => reject(new Error('IndexedDB open blocked'));
+        }).catch(error => { disable(error); return null; });
+        return state.dbPromise;
+    }
+
+    const promisify = (request) => new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error || new Error('IndexedDB request failed'));
+    });
+
+    // One transaction per call; any failure (quota included) disables persistence silently
+    async function withStore(mode, fn) {
+        if (!state.enabled || state.disabled) return undefined;
+        const db = await openDb();
+        if (!db || state.disabled) return undefined;
+        try {
+            const tx = db.transaction(STORE_NAME, mode);
+            const done = new Promise((resolve, reject) => {
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => reject(tx.error || new Error('IndexedDB transaction failed'));
+                tx.onabort = () => reject(tx.error || new Error('IndexedDB transaction aborted'));
+            });
+            const result = await fn(tx.objectStore(STORE_NAME), tx);
+            await done;
+            return result;
+        } catch (error) {
+            disable(error);
+            return undefined;
+        }
+    }
+
+    function readRecords(keys) {
+        return withStore('readonly', (store) => Promise.all(keys.map(key => promisify(store.get(key)))));
+    }
+
+    function putRecord(record) {
+        return withStore('readwrite', (store) => { store.put(record); });
+    }
+
+    function deleteKeys(keys) {
+        if (!keys.length) return Promise.resolve();
+        return withStore('readwrite', (store) => { for (const key of keys) store.delete(key); });
+    }
+
+    async function deleteScope(scope) {
+        const prefix = `${scope}|`;
+        cancelWrites();
+        return withStore('readwrite', async (store) => {
+            const keys = await promisify(store.getAllKeys());
+            for (const key of keys) if (typeof key === 'string' && key.startsWith(prefix)) store.delete(key);
+        });
+    }
+
+    // ---- snapshot (write path) ----
+
+    function stripRow(row, patterns) {
+        const out = {};
+        for (const key of Object.keys(row)) {
+            if (NEVER_PERSIST_KEYS.has(key)) continue;
+            const value = row[key];
+            if (typeof value === 'function') continue;
+            if (patterns.some(re => re.test(key))) continue;
+            out[key] = value;
+        }
+        return out;
+    }
+
+    function compareRecent(a, b) {
+        if (a === b) return 0;
+        if (a === undefined || a === null) return -1;
+        if (b === undefined || b === null) return 1;
+        if (typeof a === 'number' && typeof b === 'number') return a - b;
+        const sa = String(a), sb = String(b);
+        return sa < sb ? -1 : sa > sb ? 1 : 0;
+    }
+
+    // Keep the `maxRows` most recent by `recent` (or `$updatedAt`), in their original order;
+    // no recency field → the last N inserted
+    function capRows(rows, cfg) {
+        if (rows.length <= cfg.maxRows) return rows;
+        const field = cfg.recent || (rows.some(r => r && r.$updatedAt !== undefined) ? '$updatedAt' : null);
+        if (!field) return rows.slice(rows.length - cfg.maxRows);
+        const order = rows.map((row, i) => i).sort((i, j) => compareRecent(rows[j]?.[field], rows[i]?.[field]) || i - j);
+        const keep = new Set(order.slice(0, cfg.maxRows));
+        return rows.filter((_, i) => keep.has(i));
+    }
+
+    function snapshotOf(source, raw, cfg) {
+        const filter = state.filters.get(source);
+        if (Array.isArray(raw)) {
+            let rows = raw;
+            if (filter) {
+                rows = [];
+                for (const row of raw) {
+                    if (row === null || typeof row !== 'object') { rows.push(row); continue; }
+                    const kept = filter(row);
+                    if (kept === null || kept === undefined) continue;
+                    rows.push(typeof kept === 'object' ? kept : row);
+                }
+            }
+            rows = capRows(rows, cfg);
+            return rows.map(row => (row && typeof row === 'object') ? stripRow(row, cfg.stripPatterns) : row);
+        }
+        if (raw && typeof raw === 'object') {
+            const kept = filter ? filter(raw) : raw;
+            if (kept === null || kept === undefined) return null;
+            return stripRow(typeof kept === 'object' ? kept : raw, cfg.stripPatterns);
+        }
+        return null;
+    }
+
+    function snapshotRecord(source) {
+        const cfg = state.sources.get(source);
+        const ds = dataStore();
+        if (!cfg || !ds) return null;
+        const raw = ds.getRawData(source);
+        if (raw === null || raw === undefined) return null;
+        try {
+            const snapshot = snapshotOf(source, raw, cfg);
+            if (snapshot === null) return null;
+            return {
+                key: keyOf(state.scope, source),
+                scope: state.scope,
+                source,
+                rows: JSON.parse(JSON.stringify(snapshot)),
+                savedAt: Date.now(),
+                frameworkVersion: state.frameworkVersion,
+                deployment: state.deployment,
+                locale: liveLocale()
+            };
+        } catch (error) {
+            warnOnce(`snapshot:${source}`, `persistence skipped "${source}" (rows are not serialisable)`, error);
+            return null;
+        }
+    }
+
+    // Every source whose debounce has elapsed is written in ONE transaction
+    function flush(sources) {
+        for (const source of sources) state.pending.delete(source);
+        if (!state.enabled || state.disabled) return Promise.resolve();
+        const records = sources.map(snapshotRecord).filter(Boolean);
+        if (!records.length) return Promise.resolve();
+        const generation = state.generation;
+        return withStore('readwrite', (store) => { for (const record of records) store.put(record); }).then(() => {
+            if (generation !== state.generation || state.disabled) return;
+            for (const record of records) {
+                const cfg = state.sources.get(record.source);
+                if (!cfg) continue;
+                cfg.rows = Array.isArray(record.rows) ? record.rows.length : 1;
+                cfg.savedAt = record.savedAt;
+            }
+        });
+    }
+
+    function flushDue() {
+        state.writeTimer = null;
+        const now = Date.now();
+        const due = [];
+        for (const [source, at] of state.pending) if (at - now <= 5) due.push(source);
+        const run = due.length ? flush(due) : Promise.resolve();
+        scheduleWrites();
+        return run.catch(() => { /* disabled */ });
+    }
+
+    function scheduleWrites() {
+        if (state.writeTimer !== null || !state.pending.size) return;
+        let next = Infinity;
+        for (const at of state.pending.values()) if (at < next) next = at;
+        state.writeTimer = setTimeout(flushDue, Math.max(0, next - Date.now()));
+    }
+
+    function cancelWrites(source) {
+        if (source !== undefined) { state.pending.delete(source); return; }
+        state.pending.clear();
+        if (state.writeTimer !== null) { clearTimeout(state.writeTimer); state.writeTimer = null; }
+    }
+
+    // Landing hook (store flush): each landing restarts that source's 500ms debounce
+    function onLanded(sources) {
+        if (!state.enabled || state.disabled) return;
+        const at = Date.now() + WRITE_DEBOUNCE_MS;
+        for (const source of sources) if (state.sources.has(source)) state.pending.set(source, at);
+        if (state.writeTimer !== null) { clearTimeout(state.writeTimer); state.writeTimer = null; }
+        scheduleWrites();
+    }
+
+    // ---- hydration (read path) ----
+
+    function validRecord(record, cfg) {
+        if (!record || typeof record !== 'object' || record.scope !== state.scope) return { ok: false };
+        if (record.rows === null || record.rows === undefined) return { ok: false, drop: true };
+        if (typeof record.savedAt !== 'number' || Date.now() - record.savedAt > cfg.ttl) return { ok: false, drop: true };
+        if (majorMinor(record.frameworkVersion) !== majorMinor(state.frameworkVersion)) return { ok: false, drop: true };
+        if (record.locale && record.locale !== liveLocale()) return { ok: false };
+        return { ok: true };
+    }
+
+    // One transaction for every requested key; a hydration arriving after the
+    // fresh landing (or after a scope change) is discarded
+    async function hydrate(sources) {
+        const ds = dataStore();
+        const pending = sources.filter(source => state.sources.has(source) && !state.hydrated.has(source));
+        if (!ds || !pending.length || !state.enabled || state.disabled) return;
+        for (const source of pending) state.hydrated.add(source);
+        const generation = state.generation;
+        const scope = state.scope;
+        const records = await readRecords(pending.map(source => keyOf(scope, source)));
+        if (!records || generation !== state.generation) return;
+        const drop = [];
+        const landings = [];
+        pending.forEach((source, i) => {
+            const cfg = state.sources.get(source);
+            const record = records[i];
+            if (!cfg || !record) return;
+            const check = validRecord(record, cfg);
+            if (!check.ok) { if (check.drop) drop.push(record.key); return; }
+            if (ds.sourceFreshness(source).done) return; // fresh landing already applied
+            cfg.rows = Array.isArray(record.rows) ? record.rows.length : 1;
+            cfg.savedAt = record.savedAt;
+            landings.push(ds.landRows(source, record.rows, { mode: 'replace', ready: true, fresh: false, persistHydration: true, allowDuringInit: true }));
+        });
+        if (drop.length) deleteKeys(drop).catch(() => { /* disabled */ });
+        await Promise.all(landings);
+    }
+
+    function bootSources() {
+        const out = [];
+        for (const [source, cfg] of state.sources) if (cfg.tier === 'boot') out.push(source);
+        return out;
+    }
+
+    // Boot tier: all keys in one read; the caller caps the wait (cold boot never blocks)
+    function hydrateBoot(options = {}) {
+        if (!state.enabled || state.disabled) return Promise.resolve();
+        const run = hydrate(bootSources()).catch(() => { /* disabled */ });
+        const maxWaitMs = options.maxWaitMs;
+        if (!Number.isFinite(maxWaitMs)) return run;
+        return Promise.race([run, new Promise(resolve => setTimeout(resolve, maxWaitMs))]);
+    }
+
+    // First `$x.<source>` read without rows → lazy-tier hydration
+    function onRead(source) {
+        if (!state.enabled || state.disabled) return;
+        const cfg = state.sources.get(source);
+        if (!cfg || state.hydrated.has(source)) return;
+        hydrate([source]).catch(() => { /* disabled */ });
+    }
+
+    // Hydrated (stale) rows still need this page-load's network landing: once per source per scope
+    function needsFetch(source) {
+        if (!state.enabled || state.disabled) return false;
+        const cfg = state.sources.get(source);
+        if (!cfg || state.fetchKicked.has(source)) return false;
+        const ds = dataStore();
+        if (!ds || ds.sourceFreshness(source).done) return false;
+        const st = ds.rawOf(alpineData() || {})[`_${source}_state`];
+        if (st && (st.loading || st.error)) return false;
+        const prefix = `${source}:`;
+        for (const key of ds.loadingPromises.keys()) if (key.startsWith(prefix)) return false;
+        state.fetchKicked.add(source);
+        return true;
+    }
+
+    // A kicked load that could not land (init window) may be re-kicked by the next read
+    function onFetchSettled(source, result) {
+        if (result === null || result === undefined) return;
+        const ds = dataStore();
+        if (ds && !ds.sourceFreshness(source).done) state.fetchKicked.delete(source);
+    }
+
+    // ---- public surface ----
+
+    // $x.$wipe(): current scope; $wipe(source); $wipe({ all: true }): every scope
+    async function wipe(arg) {
+        if (!state.enabled || state.disabled) return false;
+        if (arg && typeof arg === 'object' && arg.all) {
+            cancelWrites();
+            for (const cfg of state.sources.values()) { cfg.rows = null; cfg.savedAt = null; }
+            await withStore('readwrite', (store) => { store.clear(); });
+            return !state.disabled;
+        }
+        if (typeof arg === 'string' && arg) {
+            cancelWrites(arg);
+            const cfg = state.sources.get(arg);
+            if (cfg) { cfg.rows = null; cfg.savedAt = null; }
+            await deleteKeys([keyOf(state.scope, arg)]);
+            return !state.disabled;
+        }
+        for (const cfg of state.sources.values()) { cfg.rows = null; cfg.savedAt = null; }
+        await deleteScope(state.scope);
+        return !state.disabled;
+    }
+
+    function persistFilter(source, fn) {
+        if (typeof fn === 'function') state.filters.set(source, fn);
+        else state.filters.delete(source);
+    }
+
+    function persistence() {
+        const getState = window.ManifestDataProxiesMagic?.getStateProperty;
+        const sources = [];
+        for (const [source, cfg] of state.sources) {
+            sources.push({
+                source,
+                tier: cfg.tier,
+                rows: cfg.rows,
+                savedAt: cfg.savedAt,
+                stale: getState ? getState('$stale', source) !== false : true
+            });
+        }
+        const out = { enabled: state.enabled && !state.disabled, scope: state.scope, sources };
+        if (state.disabled) out.disabledReason = state.disabledReason;
+        return out;
+    }
+
+    // Tests/harness: write everything pending now
+    async function flushPending() {
+        const sources = [...state.pending.keys()];
+        if (state.writeTimer !== null) { clearTimeout(state.writeTimer); state.writeTimer = null; }
+        if (sources.length) await flush(sources).catch(() => { /* disabled */ });
+    }
+
+    // Shared record store for other primitives (chat windows, §12.2 "primitive 3"):
+    // same database/object store, scope prefix, stamping and validity rules.
+    // Keys are `${scope}|…`, so scope wipes and logout cover these records too.
+    function stampRecord(record) {
+        return {
+            scope: state.scope, savedAt: Date.now(), frameworkVersion: state.frameworkVersion,
+            deployment: state.deployment, locale: liveLocale(), ...record
+        };
+    }
+    const records = {
+        enable: ensureEnabled,
+        enabled: () => state.enabled && !state.disabled,
+        scope: () => state.scope,
+        key: (...parts) => [state.scope, ...parts].join('|'),
+        get: (keys) => readRecords(keys), // one transaction; array aligned with keys (undefined = miss)
+        put: (list) => withStore('readwrite', (store) => { for (const record of list) store.put(stampRecord(record)); }),
+        delete: (keys) => deleteKeys(keys),
+        keys: (prefix) => withStore('readonly', async (store) =>
+            (await promisify(store.getAllKeys())).filter(key => typeof key === 'string' && key.startsWith(prefix))),
+        clear: () => withStore('readwrite', (store) => { store.clear(); }),
+        valid: (record, ttlMs) => validRecord(record, { ttl: Number.isFinite(ttlMs) ? ttlMs : DEFAULT_TTL_MS }).ok,
+        stamp: stampRecord,
+        ttl: parseTtl
+    };
+
+    window.ManifestDataPersist = {
+        BOOT_HYDRATE_MAX_WAIT_MS,
+        WRITE_DEBOUNCE_MS,
+        configure,
+        register,
+        setScope,
+        refreshScope,
+        hydrateBoot,
+        hydrate,
+        onRead,
+        needsFetch,
+        onFetchSettled,
+        onLanded,
+        flushPending,
+        wipe,
+        persistFilter,
+        persistence,
+        records,
+        state
+    };
+
+    window.ManifestData = window.ManifestData || {};
+    window.ManifestData.persistFilter = persistFilter;
+    window.ManifestData.persistence = persistence;
+})();
+
+
 /* Manifest Data Sources - File Loaders */
 
 // Key names that would walk into Object's prototype chain if used as nested-
@@ -2048,9 +2727,10 @@ async function loadFromAPI(dataSource) {
 
         return data;
     } catch (error) {
-        console.error(`[Manifest Data] Failed to load API dataSource:`, error);
-        // Return empty array/object to prevent breaking the UI
-        return Array.isArray(dataSource.defaultValue) ? dataSource.defaultValue : (dataSource.defaultValue || []);
+        // Callers decide: a first load may land `defaultValue`, a reload keeps its live rows
+        const err = error instanceof Error ? error : new Error(String(error));
+        err.defaultValue = dataSource.defaultValue !== undefined ? dataSource.defaultValue : [];
+        throw err;
     }
 }
 
@@ -3221,6 +3901,84 @@ function clearArrayProxyCacheForDataSource(dataSourceName) {
 // Track which arrays have methods attached to avoid re-attaching
 const arraysWithMethodsAttached = new WeakSet();
 
+// Operator memo: $search/$query/$route results cached per array, keyed by
+// the source version + op + args; a landing or local write bumps _v[source]
+// and invalidates. Uncached when the source has no version or args cannot
+// be stringified deterministically.
+const OP_CACHE_MAX = 8;
+const opCaches = new WeakMap(); // raw array -> { v, map (LRU) }
+
+function stableStringify(value, depth = 0) {
+    if (value === null) return 'null';
+    const t = typeof value;
+    if (t === 'string') return JSON.stringify(value);
+    if (t === 'number' || t === 'boolean' || t === 'undefined') return String(value);
+    if (t === 'bigint') return `${value}n`;
+    if (t !== 'object' || depth > 8) return undefined;
+    const tag = Object.prototype.toString.call(value);
+    if (tag === '[object Date]') return `D${value.getTime()}`;
+    if (Array.isArray(value)) {
+        const parts = [];
+        for (const item of value) {
+            const s = stableStringify(item, depth + 1);
+            if (s === undefined) return undefined;
+            parts.push(s);
+        }
+        return `[${parts.join(',')}]`;
+    }
+    // Plain objects only (any realm): class instances, Map/Set etc. fall through
+    const proto = Object.getPrototypeOf(value);
+    if (tag !== '[object Object]' || (proto !== null && Object.getPrototypeOf(proto) !== null)) return undefined;
+    const parts = [];
+    for (const key of Object.keys(value).sort()) {
+        const s = stableStringify(value[key], depth + 1);
+        if (s === undefined) return undefined;
+        parts.push(`${JSON.stringify(key)}:${s}`);
+    }
+    return `{${parts.join(',')}}`;
+}
+
+// Reactive read of _v[source]: subscribes the caller exactly like the raw $x read
+function sourceVersion(dataSourceName) {
+    if (!dataSourceName || typeof Alpine === 'undefined') return undefined;
+    const v = Alpine.store('data')?._v;
+    return v ? v[dataSourceName] : undefined;
+}
+
+// Run without tracking deps on the caller's effect (throwaway inner effect)
+function untracked(fn) {
+    if (typeof Alpine === 'undefined' || !Alpine.effect) return fn();
+    let out;
+    const e = Alpine.effect(() => { out = fn(); });
+    Alpine.release(e);
+    return out;
+}
+
+function memoOp(array, dataSourceName, op, args, compute) {
+    const version = sourceVersion(dataSourceName);
+    if (version === undefined) return compute();
+    const argsKey = stableStringify(args);
+    if (argsKey === undefined) return compute();
+    const raw = Alpine.raw ? Alpine.raw(array) : array;
+    let entry = opCaches.get(raw);
+    if (!entry || entry.v !== version) {
+        entry = { v: version, map: new Map() };
+        opCaches.set(raw, entry);
+    }
+    const key = `${version}|${op}|${argsKey}`;
+    const map = entry.map;
+    if (map.has(key)) {
+        const hit = map.get(key);
+        map.delete(key);
+        map.set(key, hit);
+        return hit;
+    }
+    const result = untracked(compute);
+    map.set(key, result);
+    if (map.size > OP_CACHE_MAX) map.delete(map.keys().next().value);
+    return result;
+}
+
 // Attach methods directly to the array (no proxy wrapper) so Alpine tracks it directly
 function attachArrayMethods(array, dataSourceName, reloadDataSource) {
     // Skip if already has methods attached
@@ -3309,58 +4067,62 @@ function attachArrayMethods(array, dataSourceName, reloadDataSource) {
                 return array;
             }
 
-            const term = searchTerm.toLowerCase().trim();
-
-            // Weighted mode: $search(term, { title: 3, body: 1 }) — ranks by the
-            // best-matching field's weight per whitespace-separated term (prefix
-            // match gets a small boost); every term must match somewhere.
-            const first = attributes[0];
-            if (attributes.length === 1 && first && typeof first === 'object' && !Array.isArray(first)) {
-                const fields = Object.keys(first);
-                const terms = term.split(/\s+/).filter(Boolean);
-                const scored = [];
-                for (const item of array) {
-                    if (!item || typeof item !== 'object') continue;
-                    let total = 0, ok = true;
-                    for (const t of terms) {
-                        let best = 0;
-                        for (const f of fields) {
-                            const v = item[f];
-                            if (v == null) continue;
-                            const s = String(v).toLowerCase();
-                            if (!s.includes(t)) continue;
-                            let w = Number(first[f]) || 0;
-                            if (s.startsWith(t)) w *= 1.2;
-                            if (w > best) best = w;
-                        }
-                        if (!best) { ok = false; break; }
-                        total += best;
-                    }
-                    if (ok) scored.push([total, item]);
-                }
-                scored.sort((a, b) => b[0] - a[0]);
-                const ranked = scored.map(e => e[1]);
-                attachArrayMethods(ranked, dataSourceName, reloadDataSource);
-                return ranked;
-            }
-
-            const attrs = attributes.length > 0 ? attributes : Object.keys(array[0] || {});
+            return memoOp(array, dataSourceName, 'search', [searchTerm, ...attributes], () => runSearch(searchTerm, attributes));
+        }
+    });
 
-            const filtered = array.filter(item => {
-                if (!item || typeof item !== 'object') return false;
-                return attrs.some(attr => {
-                    const value = item[attr];
-                    if (value == null) return false;
-                    return String(value).toLowerCase().includes(term);
-                });
+    function runSearch(searchTerm, attributes) {
+        const term = searchTerm.toLowerCase().trim();
+
+        // Weighted mode: $search(term, { title: 3, body: 1 }) — ranks by the
+        // best-matching field's weight per whitespace-separated term (prefix
+        // match gets a small boost); every term must match somewhere.
+        const first = attributes[0];
+        if (attributes.length === 1 && first && typeof first === 'object' && !Array.isArray(first)) {
+            const fields = Object.keys(first);
+            const terms = term.split(/\s+/).filter(Boolean);
+            const scored = [];
+            for (const item of array) {
+                if (!item || typeof item !== 'object') continue;
+                let total = 0, ok = true;
+                for (const t of terms) {
+                    let best = 0;
+                    for (const f of fields) {
+                        const v = item[f];
+                        if (v == null) continue;
+                        const s = String(v).toLowerCase();
+                        if (!s.includes(t)) continue;
+                        let w = Number(first[f]) || 0;
+                        if (s.startsWith(t)) w *= 1.2;
+                        if (w > best) best = w;
+                    }
+                    if (!best) { ok = false; break; }
+                    total += best;
+                }
+                if (ok) scored.push([total, item]);
+            }
+            scored.sort((a, b) => b[0] - a[0]);
+            const ranked = scored.map(e => e[1]);
+            attachArrayMethods(ranked, dataSourceName, reloadDataSource);
+            return ranked;
+        }
+
+        const attrs = attributes.length > 0 ? attributes : Object.keys(array[0] || {});
+
+        const filtered = array.filter(item => {
+            if (!item || typeof item !== 'object') return false;
+            return attrs.some(attr => {
+                const value = item[attr];
+                if (value == null) return false;
+                return String(value).toLowerCase().includes(term);
             });
+        });
 
-            // Re-attach so chaining works (.$search().$query())
-            attachArrayMethods(filtered, dataSourceName, reloadDataSource);
+        // Re-attach so chaining works (.$search().$query())
+        attachArrayMethods(filtered, dataSourceName, reloadDataSource);
 
-            return filtered;
-        }
-    });
+        return filtered;
+    }
 
     // Attach $route method
     Object.defineProperty(array, '$route', {
@@ -3368,66 +4130,70 @@ function attachArrayMethods(array, dataSourceName, reloadDataSource) {
         configurable: true,
         writable: false,
         value: function (pathKey) {
-            const createRouteProxy = window.ManifestDataProxies?.createRouteProxy;
-            if (!createRouteProxy) {
-                return new Proxy({}, {
-                    get() { return undefined; }
-                });
-            }
-            if (array && typeof array === 'object') {
-                // Prefer raw data — the real array, not the Alpine proxy
-                const getRawData = window.ManifestDataStore?.getRawData;
-                let dataToUse = array;
+            return memoOp(array, dataSourceName, 'route', [pathKey], () => runRoute(pathKey));
+        }
+    });
 
-                if (dataSourceName && getRawData) {
-                    const rawData = getRawData(dataSourceName);
-                    if (rawData && (Array.isArray(rawData) || (rawData.length !== undefined && rawData.length >= 0))) {
-                        dataToUse = rawData;
-                    }
+    function runRoute(pathKey) {
+        const createRouteProxy = window.ManifestDataProxies?.createRouteProxy;
+        if (!createRouteProxy) {
+            return new Proxy({}, {
+                get() { return undefined; }
+            });
+        }
+        if (array && typeof array === 'object') {
+            // Prefer raw data — the real array, not the Alpine proxy
+            const getRawData = window.ManifestDataStore?.getRawData;
+            let dataToUse = array;
+
+            if (dataSourceName && getRawData) {
+                const rawData = getRawData(dataSourceName);
+                if (rawData && (Array.isArray(rawData) || (rawData.length !== undefined && rawData.length >= 0))) {
+                    dataToUse = rawData;
                 }
+            }
 
-                // If we still don't have raw data, try to convert the proxy to a real array
-                if (!Array.isArray(dataToUse) && dataToUse && typeof dataToUse === 'object' && 'length' in dataToUse) {
+            // If we still don't have raw data, try to convert the proxy to a real array
+            if (!Array.isArray(dataToUse) && dataToUse && typeof dataToUse === 'object' && 'length' in dataToUse) {
+                try {
+                    // Try Array.from first (works for most iterables including Alpine proxies)
+                    dataToUse = Array.from(dataToUse);
+                } catch (e) {
+                    // Fallback: manual conversion
                     try {
-                        // Try Array.from first (works for most iterables including Alpine proxies)
-                        dataToUse = Array.from(dataToUse);
-                    } catch (e) {
-                        // Fallback: manual conversion
-                        try {
-                            const arr = [];
-                            for (let i = 0; i < dataToUse.length; i++) {
-                                arr[i] = dataToUse[i];
-                            }
-                            dataToUse = arr;
-                        } catch (e2) {
-                            // Last resort: try getting from store
-                            const store = Alpine.store('data');
-                            if (store && store[dataSourceName] && Array.isArray(store[dataSourceName])) {
-                                dataToUse = Array.from(store[dataSourceName]);
-                            }
+                        const arr = [];
+                        for (let i = 0; i < dataToUse.length; i++) {
+                            arr[i] = dataToUse[i];
+                        }
+                        dataToUse = arr;
+                    } catch (e2) {
+                        // Last resort: try getting from store
+                        const store = Alpine.store('data');
+                        if (store && store[dataSourceName] && Array.isArray(store[dataSourceName])) {
+                            dataToUse = Array.from(store[dataSourceName]);
                         }
                     }
                 }
+            }
 
-                // Ensure we have a real array before passing to createRouteProxy
-                if (!Array.isArray(dataToUse) && dataToUse && typeof dataToUse === 'object' && 'length' in dataToUse) {
-                    // Final attempt: convert to array
-                    dataToUse = Array.from(dataToUse);
-                }
-
-                // Use the array directly - it should be the actual array, not a proxy
-                // since attachArrayMethods is called on the array from the store
-                return createRouteProxy(
-                    dataToUse,
-                    pathKey,
-                    dataSourceName || undefined  // Always pass dataSourceName for proper raw data lookup
-                );
+            // Ensure we have a real array before passing to createRouteProxy
+            if (!Array.isArray(dataToUse) && dataToUse && typeof dataToUse === 'object' && 'length' in dataToUse) {
+                // Final attempt: convert to array
+                dataToUse = Array.from(dataToUse);
             }
-            return new Proxy({}, {
-                get() { return undefined; }
-            });
+
+            // Use the array directly - it should be the actual array, not a proxy
+            // since attachArrayMethods is called on the array from the store
+            return createRouteProxy(
+                dataToUse,
+                pathKey,
+                dataSourceName || undefined  // Always pass dataSourceName for proper raw data lookup
+            );
         }
-    });
+        return new Proxy({}, {
+            get() { return undefined; }
+        });
+    }
 
     // Attach $files method (for tables)
     if (dataSourceName) {
@@ -3483,106 +4249,111 @@ function attachArrayMethods(array, dataSourceName, reloadDataSource) {
                 if (!Array.isArray(queries) || queries.length === 0) {
                     return array;
                 }
+                // orderRandom reshuffles per call — never memoized
+                if (queries.some(q => Array.isArray(q) && q[0] === 'orderRandom')) return runQuery(queries);
+                return memoOp(array, dataSourceName, 'query', [queries], () => runQuery(queries));
+            }
+        });
+    }
 
-                let result = [...array];
-
-                // Process each query in order
-                for (const query of queries) {
-                    if (!Array.isArray(query) || query.length === 0) continue;
-
-                    const [method, ...args] = query;
-
-                    // Filtering methods
-                    if (method === 'equal' && args.length >= 2) {
-                        const [attr, value] = args;
-                        result = result.filter(item => item && item[attr] === value);
-                    } else if (method === 'notEqual' && args.length >= 2) {
-                        const [attr, value] = args;
-                        result = result.filter(item => item && item[attr] !== value);
-                    } else if (method === 'greaterThan' && args.length >= 2) {
-                        const [attr, value] = args;
-                        result = result.filter(item => item && item[attr] != null && item[attr] > value);
-                    } else if (method === 'greaterThanOrEqual' && args.length >= 2) {
-                        const [attr, value] = args;
-                        result = result.filter(item => item && item[attr] != null && item[attr] >= value);
-                    } else if (method === 'lessThan' && args.length >= 2) {
-                        const [attr, value] = args;
-                        result = result.filter(item => item && item[attr] != null && item[attr] < value);
-                    } else if (method === 'lessThanOrEqual' && args.length >= 2) {
-                        const [attr, value] = args;
-                        result = result.filter(item => item && item[attr] != null && item[attr] <= value);
-                    } else if (method === 'contains' && args.length >= 2) {
-                        const [attr, value] = args;
-                        const searchValue = String(value).toLowerCase();
-                        result = result.filter(item => item && item[attr] != null && String(item[attr]).toLowerCase().includes(searchValue));
-                    } else if (method === 'startsWith' && args.length >= 2) {
-                        const [attr, value] = args;
-                        const searchValue = String(value).toLowerCase();
-                        result = result.filter(item => item && item[attr] != null && String(item[attr]).toLowerCase().startsWith(searchValue));
-                    } else if (method === 'endsWith' && args.length >= 2) {
-                        const [attr, value] = args;
-                        const searchValue = String(value).toLowerCase();
-                        result = result.filter(item => item && item[attr] != null && String(item[attr]).toLowerCase().endsWith(searchValue));
-                    } else if (method === 'isNull' && args.length >= 1) {
-                        const [attr] = args;
-                        result = result.filter(item => item && (item[attr] == null || item[attr] === ''));
-                    } else if (method === 'isNotNull' && args.length >= 1) {
-                        const [attr] = args;
-                        result = result.filter(item => item && item[attr] != null && item[attr] !== '');
-                    } else if (method === 'between' && args.length >= 3) {
-                        const [attr, min, max] = args;
-                        result = result.filter(item => item && item[attr] != null && item[attr] >= min && item[attr] <= max);
-                    }
-                    // Sorting methods
-                    else if (method === 'orderAsc' && args.length >= 1) {
-                        const [attr] = args;
-                        result.sort((a, b) => {
-                            const aVal = a && a[attr];
-                            const bVal = b && b[attr];
-                            if (aVal == null && bVal == null) return 0;
-                            if (aVal == null) return 1;
-                            if (bVal == null) return -1;
-                            if (typeof aVal === 'string' && typeof bVal === 'string') {
-                                return aVal.localeCompare(bVal);
-                            }
-                            return aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
-                        });
-                    } else if (method === 'orderDesc' && args.length >= 1) {
-                        const [attr] = args;
-                        result.sort((a, b) => {
-                            const aVal = a && a[attr];
-                            const bVal = b && b[attr];
-                            if (aVal == null && bVal == null) return 0;
-                            if (aVal == null) return 1;
-                            if (bVal == null) return -1;
-                            if (typeof aVal === 'string' && typeof bVal === 'string') {
-                                return bVal.localeCompare(aVal);
-                            }
-                            return aVal > bVal ? -1 : aVal < bVal ? 1 : 0;
-                        });
-                    } else if (method === 'orderRandom') {
-                        // Fisher-Yates shuffle
-                        for (let i = result.length - 1; i > 0; i--) {
-                            const j = Math.floor(Math.random() * (i + 1));
-                            [result[i], result[j]] = [result[j], result[i]];
-                        }
-                    }
-                    // Pagination methods
-                    else if (method === 'limit' && args.length >= 1) {
-                        const [limit] = args;
-                        result = result.slice(0, parseInt(limit, 10));
-                    } else if (method === 'offset' && args.length >= 1) {
-                        const [offset] = args;
-                        result = result.slice(parseInt(offset, 10));
-                    }
+    function runQuery(queries) {
+        let result = [...array];
+
+        // Process each query in order
+        for (const query of queries) {
+            if (!Array.isArray(query) || query.length === 0) continue;
+
+            const [method, ...args] = query;
+
+            // Filtering methods
+            if (method === 'equal' && args.length >= 2) {
+                const [attr, value] = args;
+                result = result.filter(item => item && item[attr] === value);
+            } else if (method === 'notEqual' && args.length >= 2) {
+                const [attr, value] = args;
+                result = result.filter(item => item && item[attr] !== value);
+            } else if (method === 'greaterThan' && args.length >= 2) {
+                const [attr, value] = args;
+                result = result.filter(item => item && item[attr] != null && item[attr] > value);
+            } else if (method === 'greaterThanOrEqual' && args.length >= 2) {
+                const [attr, value] = args;
+                result = result.filter(item => item && item[attr] != null && item[attr] >= value);
+            } else if (method === 'lessThan' && args.length >= 2) {
+                const [attr, value] = args;
+                result = result.filter(item => item && item[attr] != null && item[attr] < value);
+            } else if (method === 'lessThanOrEqual' && args.length >= 2) {
+                const [attr, value] = args;
+                result = result.filter(item => item && item[attr] != null && item[attr] <= value);
+            } else if (method === 'contains' && args.length >= 2) {
+                const [attr, value] = args;
+                const searchValue = String(value).toLowerCase();
+                result = result.filter(item => item && item[attr] != null && String(item[attr]).toLowerCase().includes(searchValue));
+            } else if (method === 'startsWith' && args.length >= 2) {
+                const [attr, value] = args;
+                const searchValue = String(value).toLowerCase();
+                result = result.filter(item => item && item[attr] != null && String(item[attr]).toLowerCase().startsWith(searchValue));
+            } else if (method === 'endsWith' && args.length >= 2) {
+                const [attr, value] = args;
+                const searchValue = String(value).toLowerCase();
+                result = result.filter(item => item && item[attr] != null && String(item[attr]).toLowerCase().endsWith(searchValue));
+            } else if (method === 'isNull' && args.length >= 1) {
+                const [attr] = args;
+                result = result.filter(item => item && (item[attr] == null || item[attr] === ''));
+            } else if (method === 'isNotNull' && args.length >= 1) {
+                const [attr] = args;
+                result = result.filter(item => item && item[attr] != null && item[attr] !== '');
+            } else if (method === 'between' && args.length >= 3) {
+                const [attr, min, max] = args;
+                result = result.filter(item => item && item[attr] != null && item[attr] >= min && item[attr] <= max);
+            }
+            // Sorting methods
+            else if (method === 'orderAsc' && args.length >= 1) {
+                const [attr] = args;
+                result.sort((a, b) => {
+                    const aVal = a && a[attr];
+                    const bVal = b && b[attr];
+                    if (aVal == null && bVal == null) return 0;
+                    if (aVal == null) return 1;
+                    if (bVal == null) return -1;
+                    if (typeof aVal === 'string' && typeof bVal === 'string') {
+                        return aVal.localeCompare(bVal);
+                    }
+                    return aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+                });
+            } else if (method === 'orderDesc' && args.length >= 1) {
+                const [attr] = args;
+                result.sort((a, b) => {
+                    const aVal = a && a[attr];
+                    const bVal = b && b[attr];
+                    if (aVal == null && bVal == null) return 0;
+                    if (aVal == null) return 1;
+                    if (bVal == null) return -1;
+                    if (typeof aVal === 'string' && typeof bVal === 'string') {
+                        return bVal.localeCompare(aVal);
+                    }
+                    return aVal > bVal ? -1 : aVal < bVal ? 1 : 0;
+                });
+            } else if (method === 'orderRandom') {
+                // Fisher-Yates shuffle
+                for (let i = result.length - 1; i > 0; i--) {
+                    const j = Math.floor(Math.random() * (i + 1));
+                    [result[i], result[j]] = [result[j], result[i]];
                 }
+            }
+            // Pagination methods
+            else if (method === 'limit' && args.length >= 1) {
+                const [limit] = args;
+                result = result.slice(0, parseInt(limit, 10));
+            } else if (method === 'offset' && args.length >= 1) {
+                const [offset] = args;
+                result = result.slice(parseInt(offset, 10));
+            }
+        }
 
-                // Re-attach so chaining works (.$query().$search())
-                attachArrayMethods(result, dataSourceName, reloadDataSource);
+        // Re-attach so chaining works (.$query().$search())
+        attachArrayMethods(result, dataSourceName, reloadDataSource);
 
-                return result;
-            }
-        });
+        return result;
     }
 
     // Attach Appwrite methods ($create, $update, $delete, etc.)
@@ -8393,6 +9164,11 @@ function registerXMagicMethod(loadDataSource) {
                         };
                     }
 
+                    // $x.$wipe() / $wipe(source) / $wipe({ all: true }) — persisted snapshots (§12.2)
+                    if (prop === '$wipe') {
+                        return (arg) => window.ManifestDataPersist?.wipe?.(arg) ?? Promise.resolve(false);
+                    }
+
                     // $x.all — lazy cross-source array, versioned by _v.all
                     if (prop === 'all') {
                         return window.ManifestDataStore?.getAll?.() ?? [];
@@ -8413,6 +9189,16 @@ function registerXMagicMethod(loadDataSource) {
                     }
                     const nestedCache = window.ManifestDataProxiesCore.nestedDataSourceProxyCache;
                     const hasData = rawValueEarly !== undefined && rawValueEarly !== null;
+
+                    // Persisted source (§12.2): hydrated rows are stale until the network
+                    // lands, so the first read still fetches (hydration races it)
+                    const persist = window.ManifestDataPersist;
+                    if (hasData && persist?.needsFetch?.(prop)) {
+                        const locale = (typeof document !== 'undefined' && document.documentElement?.lang)
+                            || (typeof Alpine !== 'undefined' && Alpine.store('locale')?.current) || 'en';
+                        Promise.resolve(loadDataSource(prop, locale))
+                            .then(result => persist.onFetchSettled?.(prop, result), () => persist.onFetchSettled?.(prop, null));
+                    }
                     {
                         if (nestedCache.has(prop) && hasData) {
                             const cachedProxy = nestedCache.get(prop);
@@ -8444,6 +9230,7 @@ function registerXMagicMethod(loadDataSource) {
                     // this source lands), return loading proxy. Reading only the
                     // version avoids re-entry/overflow.
                     if (!hasData) {
+                        persist?.onRead?.(prop); // lazy-tier hydration on first read
                         if (!pendingLoads.has(prop)) {
                             const locale = typeof document !== 'undefined' && document.documentElement
                                 ? document.documentElement.lang
@@ -10888,7 +11675,7 @@ function liveLocale() {
 async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
     locale = locale || 'en';
     const cacheKey = `${dataSourceName}:${locale}`;
-    const { dataSourceCache, loadingPromises, isInitializing, updateStore, landRows, setSourceState, runDeduped } = window.ManifestDataStore;
+    const { dataSourceCache, loadingPromises, isInitializing, updateStore, landRows, setSourceState, runDeduped, sourceGeneration } = window.ManifestDataStore;
 
     // Memory cache (this page-load's fetches). Serving cached data is fine, but
     // writing an old locale to the live store would clobber a concurrent locale
@@ -10917,6 +11704,10 @@ async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
         else updateStore(dataSourceName, null, { loading: true, error: null, ready: false });
     }
 
+    // Scope reset (persistence) during this load → its result is discarded
+    const generation = sourceGeneration ? sourceGeneration(dataSourceName) : 0;
+    const superseded = () => sourceGeneration && sourceGeneration(dataSourceName) !== generation;
+
     return runDeduped(cacheKey, async () => {
         let landed = false;
         try {
@@ -11167,6 +11958,8 @@ async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
                 enhancedData = [];
             }
 
+            if (superseded()) { landed = true; return null; }
+
             // Cache is always safe — the key carries this load's locale.
             dataSourceCache.set(cacheKey, enhancedData);
 
@@ -11189,12 +11982,16 @@ async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
             // Return unsealed version for our proxy system
             return enhancedData;
         } catch (error) {
+            if (superseded()) { landed = true; return null; }
             // Error state (timestamped to prevent rapid retries); live rows stay
             if (!isInitializing) {
                 landed = true;
                 const errorMessage = error?.message || error?.toString() || `Failed to load dataSource "${dataSourceName}"`;
                 if (hasLiveRows(dataSourceName)) {
                     setSourceState(dataSourceName, { loading: false, error: errorMessage, errorTime: Date.now() });
+                } else if (error?.defaultValue !== undefined) {
+                    // API-URL first load failed: its defaultValue stands in (not fresh), never over live rows
+                    await landRows(dataSourceName, error.defaultValue, { mode: 'replace', loading: false, error: errorMessage, ready: true, fresh: false });
                 } else {
                     updateStore(dataSourceName, null, {
                         loading: false,
@@ -11217,7 +12014,7 @@ async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
             return null;
         } finally {
             // Early exits (no source, stale locale) must not strand a live source in $loading
-            if (!landed && keepRows && !isInitializing) setSourceState(dataSourceName, { loading: false });
+            if (!landed && keepRows && !isInitializing && !superseded()) setSourceState(dataSourceName, { loading: false });
         }
     });
 }
@@ -11394,6 +12191,13 @@ async function initializeDataSourcesPlugin() {
             const locale = (typeof document !== 'undefined' && document.documentElement?.lang) || (typeof Alpine !== 'undefined' && Alpine.store('locale')?.current) || 'en';
             const isAppwriteCollection = window.ManifestDataConfig.isAppwriteCollection;
 
+            // Persisted $x (§12.2): boot-tier snapshots land before any network load
+            // of those sources; capped so an IndexedDB miss never delays a cold boot
+            const persist = window.ManifestDataPersist;
+            if (persist && manifest && persist.configure(manifest)) {
+                await persist.hydrateBoot({ maxWaitMs: persist.BOOT_HYDRATE_MAX_WAIT_MS });
+            }
+
             if (manifest?.data) {
                 const preloadNames = [];
                 for (const [name, source] of Object.entries(manifest.data)) {