mnfst 0.5.273 → 0.5.275

package/lib/manifest.appwrite.data.js

@@ -2,7 +2,7 @@
 
 (function () {
 
-const MANIFEST_BUILD_VERSION = '0.5.273';
+const MANIFEST_BUILD_VERSION = '0.5.275';
 
 /* Manifest Data Sources - Appwrite Integration */
 
@@ -1642,337 +1642,213 @@ window.ManifestDataQueries = {
 
 /* Manifest Data Sources - Pagination (Appwrite) */
 
-// First page, cursor-based
-// Returns { items, cursor, total, hasMore }
-async function getFirstPage(dataSourceName, limit, baseQueries = []) {
+// Resolve the source's table or bucket
+async function resolvePagedSource(dataSourceName) {
     const manifest = await window.ManifestDataConfig.ensureManifest();
     if (!manifest?.data) {
         throw new Error('[Manifest Data] Manifest not available');
     }
-
     const dataSource = manifest.data[dataSourceName];
     if (!dataSource) {
         throw new Error(`[Manifest Data] Data source "${dataSourceName}" not found`);
     }
-
-    // Check if this is an Appwrite data source
-    const isAppwriteTable = window.ManifestDataConfig.isAppwriteCollection(dataSource);
-    if (!isAppwriteTable) {
+    if (!window.ManifestDataConfig.isAppwriteCollection(dataSource)) {
         throw new Error(`[Manifest Data] Pagination is only supported for Appwrite data sources`);
     }
-
     const appwriteConfig = await window.ManifestDataConfig.getAppwriteConfig(dataSource);
     if (!appwriteConfig) {
         throw new Error(`[Manifest Data] Invalid Appwrite configuration for "${dataSourceName}"`);
     }
-
     const tableId = window.ManifestDataConfig.getAppwriteTableId(dataSource);
     const bucketId = window.ManifestDataConfig.getAppwriteBucketId(dataSource);
+    if (!tableId && !bucketId) {
+        throw new Error(`[Manifest Data] Data source "${dataSourceName}" is not a table or bucket`);
+    }
+    return { appwriteConfig, tableId, bucketId };
+}
 
-    // Build queries with limit
-    const queries = [
-        ...baseQueries,
-        window.Appwrite.Query.limit(limit)
-    ];
-
+// One page request. Asks for limit + 1 rows: the extra row only answers "is there more"
+async function fetchPage(dataSourceName, baseQueries, pageQueries, limit) {
+    const { appwriteConfig, tableId, bucketId } = await resolvePagedSource(dataSourceName);
+    const queries = [...baseQueries, ...pageQueries, window.Appwrite.Query.limit(limit + 1)];
+    const services = await window.ManifestDataAppwrite._getAppwriteDataServices();
     let response;
     if (tableId) {
-        // Table pagination - need to call Appwrite directly to get full response with total
-        const services = await window.ManifestDataAppwrite._getAppwriteDataServices();
-        if (!services?.tablesDB) {
-            throw new Error('[Manifest Data] Appwrite TablesDB service not available');
-        }
-
-        const appwriteResponse = await services.tablesDB.listRows({
-            databaseId: appwriteConfig.databaseId,
-            tableId: tableId,
-            queries: queries
-        });
-
-        const items = appwriteResponse.rows || [];
-        const total = appwriteResponse.total || 0;
-        const cursor = items.length > 0 ? items[items.length - 1].$id : null;
-        const hasMore = items.length === limit && total > limit;
-
-        return {
-            items,
-            cursor,
-            total,
-            hasMore
-        };
-    } else if (bucketId) {
-        // Storage pagination
-        const services = await window.ManifestDataAppwrite._getAppwriteDataServices();
-        if (!services?.storage) {
-            throw new Error('[Manifest Data] Appwrite Storage service not available');
-        }
-
-        const storageResponse = await services.storage.listFiles(bucketId, queries);
-        const items = storageResponse.files || [];
-        const total = storageResponse.total || 0;
-        const cursor = items.length > 0 ? items[items.length - 1].$id : null;
-        const hasMore = items.length === limit && total > limit;
-
-        return {
-            items,
-            cursor,
-            total,
-            hasMore
-        };
+        if (!services?.tablesDB) throw new Error('[Manifest Data] Appwrite TablesDB service not available');
+        response = await services.tablesDB.listRows({ databaseId: appwriteConfig.databaseId, tableId, queries });
     } else {
-        throw new Error(`[Manifest Data] Data source "${dataSourceName}" is not a table or bucket`);
+        if (!services?.storage) throw new Error('[Manifest Data] Appwrite Storage service not available');
+        response = await services.storage.listFiles(bucketId, queries);
     }
+    const rows = (tableId ? response.rows : response.files) || [];
+    return { rows, total: response.total || 0, extra: rows.length > limit };
+}
+
+// First page, cursor-based. Returns { items, cursor, total, hasMore }
+async function getFirstPage(dataSourceName, limit, baseQueries = []) {
+    const { rows, total, extra } = await fetchPage(dataSourceName, baseQueries, [], limit);
+    const items = rows.slice(0, limit);
+    return { items, cursor: items.length ? items[items.length - 1].$id : null, total, hasMore: extra };
 }
 
-// Next page from cursor
-// Returns { items, cursor, total, hasMore }
+// Next page after a cursor. Returns { items, cursor, total, hasMore }
 async function getNextPage(dataSourceName, cursor, limit, baseQueries = []) {
     if (!cursor) {
         throw new Error('[Manifest Data] Cursor is required for next page');
     }
-
-    const manifest = await window.ManifestDataConfig.ensureManifest();
-    if (!manifest?.data) {
-        throw new Error('[Manifest Data] Manifest not available');
-    }
-
-    const dataSource = manifest.data[dataSourceName];
-    if (!dataSource) {
-        throw new Error(`[Manifest Data] Data source "${dataSourceName}" not found`);
-    }
-
-    const appwriteConfig = await window.ManifestDataConfig.getAppwriteConfig(dataSource);
-    if (!appwriteConfig) {
-        throw new Error(`[Manifest Data] Invalid Appwrite configuration for "${dataSourceName}"`);
-    }
-
-    const tableId = window.ManifestDataConfig.getAppwriteTableId(dataSource);
-    const bucketId = window.ManifestDataConfig.getAppwriteBucketId(dataSource);
-
-    // Build queries with cursorAfter and limit
-    const queries = [
-        ...baseQueries,
-        window.Appwrite.Query.cursorAfter(cursor),
-        window.Appwrite.Query.limit(limit)
-    ];
-
-    let response;
-    if (tableId) {
-        const services = await window.ManifestDataAppwrite._getAppwriteDataServices();
-        if (!services?.tablesDB) {
-            throw new Error('[Manifest Data] Appwrite TablesDB service not available');
-        }
-
-        const appwriteResponse = await services.tablesDB.listRows({
-            databaseId: appwriteConfig.databaseId,
-            tableId: tableId,
-            queries: queries
-        });
-
-        const items = appwriteResponse.rows || [];
-        const total = appwriteResponse.total || 0;
-        const newCursor = items.length > 0 ? items[items.length - 1].$id : null;
-        const hasMore = items.length === limit && total > limit;
-
-        return {
-            items,
-            cursor: newCursor,
-            total,
-            hasMore
-        };
-    } else if (bucketId) {
-        const services = await window.ManifestDataAppwrite._getAppwriteDataServices();
-        if (!services?.storage) {
-            throw new Error('[Manifest Data] Appwrite Storage service not available');
-        }
-
-        const storageResponse = await services.storage.listFiles(bucketId, queries);
-        const items = storageResponse.files || [];
-        const total = storageResponse.total || 0;
-        const newCursor = items.length > 0 ? items[items.length - 1].$id : null;
-        const hasMore = items.length === limit && total > (limit * 2); // Rough estimate
-
-        return {
-            items,
-            cursor: newCursor,
-            total,
-            hasMore
-        };
-    } else {
-        throw new Error(`[Manifest Data] Data source "${dataSourceName}" is not a table or bucket`);
-    }
+    const { rows, total, extra } = await fetchPage(dataSourceName, baseQueries, [window.Appwrite.Query.cursorAfter(cursor)], limit);
+    const items = rows.slice(0, limit);
+    return { items, cursor: items.length ? items[items.length - 1].$id : null, total, hasMore: extra };
 }
 
-// Previous page from cursor
-// Returns { items, cursor, total, hasMore }
+// Previous page before a cursor. hasMore: rows exist before this page. Returns { items, cursor, total, hasMore }
 async function getPrevPage(dataSourceName, cursor, limit, baseQueries = []) {
     if (!cursor) {
         throw new Error('[Manifest Data] Cursor is required for previous page');
     }
-
-    const manifest = await window.ManifestDataConfig.ensureManifest();
-    if (!manifest?.data) {
-        throw new Error('[Manifest Data] Manifest not available');
-    }
-
-    const dataSource = manifest.data[dataSourceName];
-    if (!dataSource) {
-        throw new Error(`[Manifest Data] Data source "${dataSourceName}" not found`);
-    }
-
-    const appwriteConfig = await window.ManifestDataConfig.getAppwriteConfig(dataSource);
-    if (!appwriteConfig) {
-        throw new Error(`[Manifest Data] Invalid Appwrite configuration for "${dataSourceName}"`);
-    }
-
-    const tableId = window.ManifestDataConfig.getAppwriteTableId(dataSource);
-    const bucketId = window.ManifestDataConfig.getAppwriteBucketId(dataSource);
-
-    // Build queries with cursorBefore and limit
-    const queries = [
-        ...baseQueries,
-        window.Appwrite.Query.cursorBefore(cursor),
-        window.Appwrite.Query.limit(limit)
-    ];
-
-    let response;
-    if (tableId) {
-        const services = await window.ManifestDataAppwrite._getAppwriteDataServices();
-        if (!services?.tablesDB) {
-            throw new Error('[Manifest Data] Appwrite TablesDB service not available');
-        }
-
-        const appwriteResponse = await services.tablesDB.listRows({
-            databaseId: appwriteConfig.databaseId,
-            tableId: tableId,
-            queries: queries
-        });
-
-        const items = appwriteResponse.rows || [];
-        const total = appwriteResponse.total || 0;
-        const newCursor = items.length > 0 ? items[0].$id : null; // First item's ID for going back further
-        const hasMore = true; // Can't easily determine if there's a previous page
-
-        return {
-            items,
-            cursor: newCursor,
-            total,
-            hasMore
-        };
-    } else if (bucketId) {
-        const services = await window.ManifestDataAppwrite._getAppwriteDataServices();
-        if (!services?.storage) {
-            throw new Error('[Manifest Data] Appwrite Storage service not available');
-        }
-
-        const storageResponse = await services.storage.listFiles(bucketId, queries);
-        const items = storageResponse.files || [];
-        const total = storageResponse.total || 0;
-        const newCursor = items.length > 0 ? items[0].$id : null;
-        const hasMore = true;
-
-        return {
-            items,
-            cursor: newCursor,
-            total,
-            hasMore
-        };
-    } else {
-        throw new Error(`[Manifest Data] Data source "${dataSourceName}" is not a table or bucket`);
-    }
+    const { rows, total, extra } = await fetchPage(dataSourceName, baseQueries, [window.Appwrite.Query.cursorBefore(cursor)], limit);
+    // cursorBefore returns the rows nearest the cursor last; the extra row is the first one
+    const items = extra ? rows.slice(rows.length - limit) : rows;
+    return { items, cursor: items.length ? items[0].$id : null, total, hasMore: extra };
 }
 
-// Specific page (1-based), offset-based
-// Returns { items, page, total, totalPages, hasMore }
+// Specific page (1-based), offset-based. Returns { items, page, total, totalPages, hasMore }
 async function getPage(dataSourceName, pageNumber, limit, baseQueries = []) {
-    if (pageNumber < 1) {
+    if (!pageNumber || pageNumber < 1) {
         throw new Error('[Manifest Data] Page number must be >= 1');
     }
+    const offset = (pageNumber - 1) * limit;
+    const { rows, total, extra } = await fetchPage(dataSourceName, baseQueries, [window.Appwrite.Query.offset(offset)], limit);
+    const items = rows.slice(0, limit);
+    return { items, page: pageNumber, total, totalPages: Math.ceil(total / limit), hasMore: extra };
+}
 
-    const manifest = await window.ManifestDataConfig.ensureManifest();
-    if (!manifest?.data) {
-        throw new Error('[Manifest Data] Manifest not available');
-    }
-
-    const dataSource = manifest.data[dataSourceName];
-    if (!dataSource) {
-        throw new Error(`[Manifest Data] Data source "${dataSourceName}" not found`);
-    }
+window.ManifestDataPagination = {
+    getFirstPage,
+    getNextPage,
+    getPrevPage,
+    getPage
+};
 
-    const appwriteConfig = await window.ManifestDataConfig.getAppwriteConfig(dataSource);
-    if (!appwriteConfig) {
-        throw new Error(`[Manifest Data] Invalid Appwrite configuration for "${dataSourceName}"`);
-    }
 
-    const tableId = window.ManifestDataConfig.getAppwriteTableId(dataSource);
-    const bucketId = window.ManifestDataConfig.getAppwriteBucketId(dataSource);
+/* Manifest Data Sources - Contract checks */
 
-    const offset = (pageNumber - 1) * limit;
+// Rows of Appwrite sources whose table the contract declares throw when app code
+// reads a column that is undeclared and never seen on a row. Dev hosts by default.
+(function () {
+    const proxies = new WeakMap();
+    const targets = new WeakMap();
+    const warned = new Set();
+    // Read by the framework on every row; storage columns are added per source
+    const ALLOWED = new Set(['then', 'catch', 'finally', 'toJSON', 'length', 'contentType', 'fileIds']);
+    let enabled;
+    let tables = null;
+    const tableBySource = new Map();
+    const seenBySource = new Map();
+    let appwriteSources = null;
+
+    function devHost(h) {
+        return h === 'localhost' || h === '127.0.0.1' || h === '[::1]' || h === '::1' || h === '0.0.0.0' ||
+            h.endsWith('.localhost') || h.endsWith('.local') || h.endsWith('.test');
+    }
+
+    function hostMatches(pattern, host) {
+        const re = new RegExp('^' + String(pattern).toLowerCase().replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^.]*') + '$');
+        return re.test(host);
+    }
+
+    function config(manifest) {
+        const c = manifest && manifest.contract;
+        if (typeof c === 'string') return { module: c, checks: 'dev' };
+        if (c && typeof c === 'object' && typeof c.module === 'string') return { module: c.module, checks: c.checks === undefined ? 'dev' : c.checks };
+        return null;
+    }
 
-    // Build queries with offset and limit
-    const queries = [
-        ...baseQueries,
-        window.Appwrite.Query.offset(offset),
-        window.Appwrite.Query.limit(limit)
-    ];
+    function decide(manifest) {
+        const cfg = config(manifest);
+        if (!cfg || cfg.checks === false) return false;
+        const host = String(location.hostname || '').toLowerCase();
+        if (cfg.checks === true) return cfg;
+        if (devHost(host)) return cfg;
+        return Array.isArray(cfg.checks) && cfg.checks.some(p => hostMatches(p, host)) ? cfg : false;
+    }
+
+    function load(manifest, cfg) {
+        import(new URL(cfg.module, location.origin + '/').href).then(mod => {
+            tables = mod && mod.tables && typeof mod.tables === 'object' ? mod.tables : {};
+            const defaultDb = manifest.appwrite && (manifest.appwrite.databaseId || manifest.appwrite.database);
+            for (const [source, src] of Object.entries(manifest.data || {})) {
+                if (!src || typeof src.appwriteTableId !== 'string') continue;
+                const db = src.appwriteDatabaseId || defaultDb;
+                const hit = Object.entries(tables).find(([key, t]) => t && (t.id || key) === src.appwriteTableId && (!t.database || !db || t.database === db));
+                if (!hit || !Array.isArray(hit[1].columns)) continue;
+                const columns = new Set(hit[1].columns);
+                for (const c of Object.values(src.storage || {})) columns.add(typeof c === 'string' ? c : (c && c.column) || 'fileIds');
+                tableBySource.set(source, { key: hit[0], columns });
+            }
+        }).catch(e => {
+            console.warn(`[Manifest] contract ${cfg.module} failed to load; column checks are off`, e);
+            tables = {};
+        });
+    }
 
-    let response;
-    let total;
-    if (tableId) {
-        const services = await window.ManifestDataAppwrite._getAppwriteDataServices();
-        if (!services?.tablesDB) {
-            throw new Error('[Manifest Data] Appwrite TablesDB service not available');
+    function isEnabled() {
+        if (enabled !== undefined) return enabled;
+        const manifest = window.__manifestLoaded;
+        if (!manifest) return false;
+        const cfg = decide(manifest);
+        enabled = !!cfg;
+        if (cfg) {
+            appwriteSources = new Set(Object.entries(manifest.data || {}).filter(([, s]) => s && typeof s.appwriteTableId === 'string').map(([k]) => k));
+            load(manifest, cfg);
         }
+        return enabled;
+    }
 
-        const appwriteResponse = await services.tablesDB.listRows({
-            databaseId: appwriteConfig.databaseId,
-            tableId: tableId,
-            queries: queries
-        });
-
-        const items = appwriteResponse.rows || [];
-        total = appwriteResponse.total || 0;
-        const totalPages = Math.ceil(total / limit);
-        const hasMore = pageNumber < totalPages;
+    const known = (key, table) => key[0] === '$' || key[0] === '_' || ALLOWED.has(key) || table.columns.has(key);
 
-        return {
-            items,
-            page: pageNumber,
-            total,
-            totalPages,
-            hasMore
-        };
-    } else if (bucketId) {
-        const services = await window.ManifestDataAppwrite._getAppwriteDataServices();
-        if (!services?.storage) {
-            throw new Error('[Manifest Data] Appwrite Storage service not available');
+    function drift(source, table, row) {
+        for (const key of Object.keys(row)) {
+            if (known(key, table) || warned.has(source + '\0' + key)) continue;
+            warned.add(source + '\0' + key);
+            console.warn(`[Manifest] data source "${source}" has column "${key}", which the contract does not declare for "${table.key}"`);
         }
+    }
 
-        const storageResponse = await services.storage.listFiles(bucketId, queries);
-        const items = storageResponse.files || [];
-        total = storageResponse.total || 0;
-        const totalPages = Math.ceil(total / limit);
-        const hasMore = pageNumber < totalPages;
-
-        return {
-            items,
-            page: pageNumber,
-            total,
-            totalPages,
-            hasMore
-        };
-    } else {
-        throw new Error(`[Manifest Data] Data source "${dataSourceName}" is not a table or bucket`);
+    function guard(source, row) {
+        if (!row || typeof row !== 'object' || Array.isArray(row) || !isEnabled() || !appwriteSources.has(source)) return row;
+        const existing = proxies.get(row);
+        if (existing) return existing;
+        let seen = seenBySource.get(source);
+        if (!seen) seenBySource.set(source, seen = new Set());
+        for (const key of Object.keys(row)) seen.add(key);
+        let checked = false;
+        const proxy = new Proxy(row, {
+            // App reads arrive through Alpine's reactive proxy; its own old-value reads use this one
+            get(target, key, receiver) {
+                if (typeof key === 'string' && tables && receiver !== proxy) {
+                    const table = tableBySource.get(source);
+                    if (table) {
+                        if (!checked) { checked = true; drift(source, table, target); }
+                        if (!known(key, table) && !(key in target) && !seen.has(key)) {
+                            throw new Error(`[Manifest] "${key}" is not a column of "${table.key}" in the contract (data source "${source}")`);
+                        }
+                    }
+                }
+                return Reflect.get(target, key, receiver);
+            }
+        });
+        proxies.set(row, proxy);
+        proxies.set(proxy, proxy);
+        targets.set(proxy, row);
+        return proxy;
     }
-}
 
-// Export functions
-window.ManifestDataPagination = {
-    getFirstPage,
-    getNextPage,
-    getPrevPage,
-    getPage
-};
+    // Framework reads go through the unchecked row
+    const raw = (obj) => (obj && targets.get(obj)) || obj;
+
+    window.ManifestDataContract = { guard, raw };
+})();
 
 
 })();

package/lib/manifest.data.js

@@ -2,7 +2,7 @@
 
 (function () {
 
-const MANIFEST_BUILD_VERSION = '0.5.273';
+const MANIFEST_BUILD_VERSION = '0.5.275';
 
 /* Manifest Data Sources - Configuration */
 
@@ -397,7 +397,7 @@ function mergeRowFields(target, fields, dataSourceName) {
         if (key === '$files') continue;
         const value = fields[key];
         if (sameScalarOrList(raw[key], value)) continue;
-        target[key] = createReactiveReferences(value, dataSourceName);
+        target[key] = createReactiveReferences(value, dataSourceName, true);
     }
 }
 
@@ -432,9 +432,12 @@ function sourceGeneration(dataSourceName) {
 // next read hydrates/fetches for the new scope; older loads are discarded
 function resetSource(dataSourceName) {
     sourceGen.set(dataSourceName, sourceGeneration(dataSourceName) + 1);
+    latestRead.delete(dataSourceName);
+    window.ManifestDataMain?.forgetLiveSource?.(dataSourceName);
     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);
+    for (const key of [...loadReadTokens.keys()]) if (key.startsWith(prefix)) loadReadTokens.delete(key);
     freshness.delete(dataSourceName);
     pendingLocal.delete(dataSourceName);
     for (let i = pendingLandings.length - 1; i >= 0; i--) {
@@ -468,6 +471,15 @@ function setSourceState(dataSourceName, patch) {
     return next;
 }
 
+// Last-issued read per source: a slower earlier read ($query or load) never lands over a later one
+const latestRead = new Map();
+let readSeq = 0;
+const loadReadTokens = new Map(); // source:locale → token of the load in flight under that key
+function beginRead(dataSourceName) { const token = ++readSeq; latestRead.set(dataSourceName, token); return token; }
+function adoptRead(dataSourceName, token) { if (token !== undefined) latestRead.set(dataSourceName, token); }
+// A reset clears the record: generation stamps already drop the older reads
+function isLatestRead(dataSourceName, token) { return token === undefined || !latestRead.has(dataSourceName) || latestRead.get(dataSourceName) === token; }
+
 // Authoritative in-flight map: one promise per key, cleared on settle
 function runDeduped(key, factory) {
     if (loadingPromises.has(key)) return loadingPromises.get(key);
@@ -492,16 +504,74 @@ function ensureSourceArray(dataSourceName) {
     return store[dataSourceName];
 }
 
+// Sort spec [[attr, 1|-1], ...] → comparator; nulls sort first ascending,
+// strings case-insensitively (Appwrite's collation)
+function compareBy(order) {
+    const norm = v => (typeof v === 'string' ? v.toLowerCase() : v);
+    return (a, b) => {
+        for (const [key, dir] of order) {
+            const x = norm(a?.[key]), y = norm(b?.[key]);
+            if (x === y) continue;
+            if (x === null || x === undefined) return -dir;
+            if (y === null || y === undefined) return dir;
+            return (x < y ? -1 : 1) * dir;
+        }
+        return 0;
+    };
+}
+
+function sortedIndex(arr, row, cmp) {
+    let lo = 0, hi = arr.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (cmp(arr[mid], row) <= 0) lo = mid + 1; else hi = mid;
+    }
+    return lo;
+}
+
+// Ordered append (realtime on a sorted source): new rows insert at their sort
+// position; merged rows whose sort key moved are re-positioned. Structure is
+// rebuilt on a raw copy and assigned once (one reactive write, not per splice)
+function upsertOrdered(store, dataSourceName, rows, order) {
+    const cmp = compareBy(order);
+    const cur = store[dataSourceName];
+    const curRaw = rawOf(store)[dataSourceName];
+    let next = null;
+    for (const row of rows) {
+        const list = next || curRaw;
+        const id = rowKey(row);
+        const i = id !== null ? list.findIndex(r => rowKey(r) === id) : -1;
+        if (i !== -1) {
+            // Only a changed sort value moves a held row; the server's placement otherwise stands
+            const keyChanged = order.some(([key]) => Object.prototype.hasOwnProperty.call(row, key) && !sameScalarOrList(list[i][key], row[key]));
+            mergeRowFields(next ? (Alpine.reactive ? Alpine.reactive(list[i]) : list[i]) : cur[i], row, dataSourceName);
+            const misplaced = keyChanged && ((i > 0 && cmp(list[i - 1], list[i]) > 0) || (i < list.length - 1 && cmp(list[i], list[i + 1]) > 0));
+            if (!misplaced) continue;
+            if (!next) next = curRaw.slice();
+            const [moved] = next.splice(i, 1);
+            next.splice(sortedIndex(next, moved, cmp), 0, moved);
+            continue;
+        }
+        if (!next) next = curRaw.slice();
+        next.splice(sortedIndex(next, row, cmp), 0, rawOf(createReactiveReferences(row, dataSourceName)));
+    }
+    if (next) store[dataSourceName] = next;
+}
+
 // Identity-preserving upsert by $id: existing rows are merged in place, new
 // rows created; append keeps the array, replace swaps it only when membership
 // or order changed
-function upsertRows(store, dataSourceName, rows, mode) {
+function upsertRows(store, dataSourceName, rows, mode, order) {
     const raw = rawOf(store);
     const curRaw = Array.isArray(raw[dataSourceName]) ? raw[dataSourceName] : null;
     if (!curRaw) {
         store[dataSourceName] = rows.map(row => createReactiveReferences(row, dataSourceName));
         return;
     }
+    if (mode === 'append' && Array.isArray(order) && order.length) {
+        upsertOrdered(store, dataSourceName, rows, order);
+        return;
+    }
     const cur = store[dataSourceName];
     const index = new Map();
     curRaw.forEach((row, i) => { const id = rowKey(row); if (id !== null) index.set(id, i); });
@@ -557,7 +627,7 @@ function writeSource(dataSourceName, data, options = {}) {
             rawDataStore.set(dataSourceName, data);
         }
     } else if (Array.isArray(data)) {
-        upsertRows(store, dataSourceName, data, mode);
+        upsertRows(store, dataSourceName, data, mode, options.order);
         const arr = rawOf(store)[dataSourceName];
         rawDataStore.set(dataSourceName, arr);
         attachMethods(arr, dataSourceName);
@@ -729,24 +799,25 @@ function getRawData(dataSourceName) {
 }
 
 // New object/array references (incl. nested arrays like fileIds) so Alpine tracks changes
-function createReactiveReferences(data, dataSourceName = null) {
+function createReactiveReferences(data, dataSourceName = null, nested = false) {
     if (data === null || data === undefined) {
         return data;
     }
 
     if (Array.isArray(data)) {
         // Create new array with new references for each item
-        return data.map(item => createReactiveReferences(item, dataSourceName));
+        return data.map(item => createReactiveReferences(item, dataSourceName, nested));
     }
 
     if (typeof data === 'object') {
         // Object.keys, not for…in + .hasOwnProperty (see deepSeal). Hot path for
         // every Appwrite mutation result and realtime event.
         const newObj = {};
+        let self = newObj;
         for (const key of Object.keys(data)) {
             const value = data[key];
             // Recursively create new references for nested objects/arrays
-            newObj[key] = createReactiveReferences(value, dataSourceName);
+            newObj[key] = createReactiveReferences(value, dataSourceName, true);
         }
 
         // Detect file objects (have mimeType or sizeOriginal)
@@ -785,7 +856,7 @@ function createReactiveReferences(data, dataSourceName = null) {
                             data.$id,
                             bucketName,
                             columnName,
-                            { owner: newObj }
+                            { owner: self }
                         );
 
                         // Assign computed array to entry
@@ -972,7 +1043,11 @@ function createReactiveReferences(data, dataSourceName = null) {
             });
         }
 
-        return newObj;
+        // Contract checks wrap top-level Appwrite rows (dev and opted-in hosts)
+        if (!nested && isDatabaseEntry && dataSourceName && window.ManifestDataContract) {
+            self = window.ManifestDataContract.guard(dataSourceName, newObj);
+        }
+        return self;
     }
 
     // Primitives can be returned as-is
@@ -1523,6 +1598,10 @@ window.ManifestDataStore = {
     // Stale-first + dedupe (§11.1)
     setSourceState,
     runDeduped,
+    beginRead,
+    adoptRead,
+    loadReadTokens,
+    isLatestRead,
     sourceFreshness,
     // Persistence (§12.2)
     sourceGeneration,
@@ -2865,7 +2944,8 @@ window.ManifestDataLoaders = {
 // Load from API endpoint (read-only)
 async function loadFromAPI(dataSource) {
     try {
-        const url = new URL(window.ManifestDataConfig.interpolateEnvVars(dataSource.url));
+        // Relative urls resolve against the page
+        const url = new URL(window.ManifestDataConfig.interpolateEnvVars(dataSource.url), window.location.href);
 
         // Add query parameters
         if (dataSource.params) {
@@ -3176,7 +3256,15 @@ async function executeMutation(mutationConfig) {
             if (type === 'create') {
                 // Ack: swap the temp row for the server row in place (new $id → new $files binding)
                 const { store, arr, index } = findRawIndex(dataSourceName, optimisticData.$id);
-                if (store && arr) {
+                // Realtime echo of this create may have landed first under the real $id
+                const held = (arr && result.$id !== optimisticData.$id) ? arr.findIndex(r => r && r.$id === result.$id) : -1;
+                if (store && arr && held !== -1) {
+                    const ds = window.ManifestDataStore;
+                    ds.mergeRowFields(store[dataSourceName][held], result, dataSourceName);
+                    if (index !== -1) store[dataSourceName].splice(index, 1);
+                    ds.touchSource(dataSourceName);
+                    clearSourceCaches(dataSourceName);
+                } else if (store && arr) {
                     if (index !== -1) {
                         const ds = window.ManifestDataStore;
                         store[dataSourceName].splice(index, 1, ds.createReactiveReferences(result, dataSourceName));
@@ -4602,52 +4690,9 @@ function attachArrayMethods(array, dataSourceName, reloadDataSource) {
             });
         }
 
-        // Attach pagination methods
-        const createPaginationMethod = (methodName) => {
-            return async function (...args) {
-                const manifest = await window.ManifestDataConfig.ensureManifest();
-                if (!manifest?.data) {
-                    throw new Error('[Manifest Data] Manifest not available');
-                }
-                const dataSource = manifest.data[dataSourceName];
-                if (!dataSource || !window.ManifestDataConfig.isAppwriteCollection(dataSource)) {
-                    throw new Error(`[Manifest Data] Pagination is only supported for Appwrite data sources`);
-                }
-                const scope = window.ManifestDataConfig.getScope(dataSource);
-                const scopeColumns = window.ManifestDataConfig.getScopeColumns(dataSource);
-                const queriesConfig = window.ManifestDataConfig.getQueries(dataSource);
-                const baseQueries = queriesConfig
-                    ? await window.ManifestDataQueries.buildAppwriteQueries(queriesConfig.default || queriesConfig, scope, scopeColumns)
-                    : await window.ManifestDataQueries.buildAppwriteQueries([], scope, scopeColumns);
-
-                if (baseQueries === null) {
-                    throw new Error(`[Manifest Data] "${dataSourceName}" pagination: auth not ready yet — retry after auth settles`);
-                }
-
-                if (methodName === '$first') {
-                    const limit = args[0] || 10;
-                    return await window.ManifestDataPagination.getFirstPage(dataSourceName, limit, baseQueries);
-                } else if (methodName === '$next') {
-                    const [cursor, limit = 10] = args;
-                    if (!cursor) {
-                        throw new Error('[Manifest Data] Cursor is required for $next');
-                    }
-                    return await window.ManifestDataPagination.getNextPage(dataSourceName, cursor, limit, baseQueries);
-                } else if (methodName === '$prev') {
-                    const [cursor, limit = 10] = args;
-                    if (!cursor) {
-                        throw new Error('[Manifest Data] Cursor is required for $prev');
-                    }
-                    return await window.ManifestDataPagination.getPrevPage(dataSourceName, cursor, limit, baseQueries);
-                } else if (methodName === '$page') {
-                    const [pageNumber, limit = 10] = args;
-                    if (!pageNumber || pageNumber < 1) {
-                        throw new Error('[Manifest Data] Page number must be >= 1');
-                    }
-                    return await window.ManifestDataPagination.getPage(dataSourceName, pageNumber, limit, baseQueries);
-                }
-            };
-        };
+        // Attach pagination methods (one implementation: magic.pagination)
+        const createPaginationMethod = (methodName) => (...args) =>
+            window.ManifestDataProxiesMagic.createPaginationMethod(methodName, dataSourceName)(...args);
 
         ['$first', '$next', '$prev', '$page'].forEach(methodName => {
             Object.defineProperty(array, methodName, {
@@ -4952,52 +4997,7 @@ function createArrayProxyWithRoute(arrayTarget, dataSourceName = null, reloadDat
 
                 // Handle pagination methods
                 if (key === '$first' || key === '$next' || key === '$prev' || key === '$page') {
-                    return async function (...args) {
-                        const manifest = await window.ManifestDataConfig.ensureManifest();
-                        if (!manifest?.data) {
-                            throw new Error('[Manifest Data] Manifest not available');
-                        }
-
-                        const dataSource = manifest.data[dataSourceName];
-                        if (!dataSource || !window.ManifestDataConfig.isAppwriteCollection(dataSource)) {
-                            throw new Error(`[Manifest Data] Pagination is only supported for Appwrite data sources`);
-                        }
-
-                        // Get base queries (from manifest or scope)
-                        const scope = window.ManifestDataConfig.getScope(dataSource);
-                        const scopeColumns = window.ManifestDataConfig.getScopeColumns(dataSource);
-                        const queriesConfig = window.ManifestDataConfig.getQueries(dataSource);
-                        const baseQueries = queriesConfig
-                            ? await window.ManifestDataQueries.buildAppwriteQueries(queriesConfig.default || queriesConfig, scope, scopeColumns)
-                            : await window.ManifestDataQueries.buildAppwriteQueries([], scope, scopeColumns);
-
-                        if (baseQueries === null) {
-                            throw new Error(`[Manifest Data] "${dataSourceName}" pagination: auth not ready yet — retry after auth settles`);
-                        }
-
-                        if (key === '$first') {
-                            const limit = args[0] || 10;
-                            return await window.ManifestDataPagination.getFirstPage(dataSourceName, limit, baseQueries);
-                        } else if (key === '$next') {
-                            const [cursor, limit = 10] = args;
-                            if (!cursor) {
-                                throw new Error('[Manifest Data] Cursor is required for $next');
-                            }
-                            return await window.ManifestDataPagination.getNextPage(dataSourceName, cursor, limit, baseQueries);
-                        } else if (key === '$prev') {
-                            const [cursor, limit = 10] = args;
-                            if (!cursor) {
-                                throw new Error('[Manifest Data] Cursor is required for $prev');
-                            }
-                            return await window.ManifestDataPagination.getPrevPage(dataSourceName, cursor, limit, baseQueries);
-                        } else if (key === '$page') {
-                            const [pageNumber, limit = 10] = args;
-                            if (!pageNumber || pageNumber < 1) {
-                                throw new Error('[Manifest Data] Page number must be >= 1');
-                            }
-                            return await window.ManifestDataPagination.getPage(dataSourceName, pageNumber, limit, baseQueries);
-                        }
-                    };
+                    return (...args) => window.ManifestDataProxiesMagic.createPaginationMethod(key, dataSourceName)(...args);
                 }
 
                 // $files handler for tables
@@ -7701,6 +7701,8 @@ function createAppwriteMethodsHandler(dataSourceName, reloadDataSource) {
     const handleMethod = async function (method, ...args) {
         const sourceUnloaded = args[3]?.sourceUnloaded === true;
         if (!sourceUnloaded) clearErrorState();
+        // Reads are ordered by call, not by network start: the last-issued one lands
+        const readToken = method === '$query' ? window.ManifestDataStore?.beginRead?.(dataSourceName) : undefined;
 
         try {
             const manifest = await window.ManifestDataConfig?.ensureManifest?.();
@@ -7793,13 +7795,19 @@ function createAppwriteMethodsHandler(dataSourceName, reloadDataSource) {
 
                     // Support batch updates
                     if (Array.isArray(idOrArray)) {
-                        const updates = idOrArray;
+                        // Batch: ids (or rows) sharing `data`, or [{ id, data }] entries
+                        const updates = idOrArray.map(update => (update !== null && typeof update === 'object')
+                            ? { id: update.$id || update.id || update.rowId, data: update.data || data || update }
+                            : { id: update, data });
+                        if (updates.some(u => u.id === undefined || u.id === null || u.id === '' || u.data === undefined)) {
+                            throw new Error(`[Manifest Data] "${dataSourceName}" $update: batch entries need an id and data`);
+                        }
                         if (executeMutation) {
                             // Use optimistic updates for batch
                             const results = await Promise.all(
                                 updates.map(update => {
-                                    const entryId = update.id || update.$id || update.rowId;
-                                    const updateData = update.data || update;
+                                    const entryId = update.id;
+                                    const updateData = update.data;
                                     return executeMutation({
                                         type: 'update',
                                         dataSourceName,
@@ -7829,8 +7837,8 @@ function createAppwriteMethodsHandler(dataSourceName, reloadDataSource) {
                                     window.ManifestDataAppwrite.updateRow(
                                         appwriteConfig.databaseId,
                                         tableId,
-                                        update.id || update.$id || update.rowId,
-                                        update.data || update
+                                        update.id,
+                                        update.data
                                     )
                                 )
                             );
@@ -8077,23 +8085,24 @@ function createAppwriteMethodsHandler(dataSourceName, reloadDataSource) {
                     }
                     // Dedupe key: source + serialized queries (never across different queries)
                     const key = `${dataSourceName}:$query:${JSON.stringify(appwriteQueries.map(q => String(q)))}`;
-                    const { runDeduped, landRows, sourceGeneration } = window.ManifestDataStore || {};
+                    const { runDeduped, landRows, sourceGeneration, isLatestRead } = window.ManifestDataStore || {};
                     const generation = sourceGeneration?.(dataSourceName);
                     const requireAuth = window.ManifestDataMain?.requiresIdentity?.({ ...dataSource, queries: [dataSource.queries, queries] }) ?? true;
-                    const run = async () => {
-                        const result = await window.ManifestDataAppwrite.loadTableRows(
-                            appwriteConfig.databaseId,
-                            tableId,
-                            appwriteQueries,
-                            { requireAuth }
-                        );
-                        // Network landing: query result replaces the source (coalesced, identity-preserving)
-                        if (result !== undefined && landRows) {
-                            await landRows(dataSourceName, result, { mode: 'replace', fresh: true, generation });
-                        }
-                        return result;
-                    };
-                    return runDeduped ? await runDeduped(key, run) : await run();
+                    const run = () => window.ManifestDataAppwrite.loadTableRows(
+                        appwriteConfig.databaseId,
+                        tableId,
+                        appwriteQueries,
+                        { requireAuth }
+                    );
+                    const result = runDeduped ? await runDeduped(key, run) : await run();
+                    // Network landing: query result replaces the source (coalesced, identity-preserving);
+                    // only the last-issued read of this source lands
+                    const latest = !isLatestRead || isLatestRead(dataSourceName, readToken);
+                    if (result !== undefined && landRows && latest && sourceGeneration?.(dataSourceName) === generation) {
+                        window.ManifestDataMain?.setActiveQuery?.(dataSourceName, queries || [], Array.isArray(result) ? result.length : 0);
+                        await landRows(dataSourceName, result, { mode: 'replace', fresh: true, generation });
+                    }
+                    return result;
                 }
             }
 
@@ -9198,6 +9207,8 @@ window.ManifestDataProxiesMagic.createUploadMethod = createUploadMethod;
 /* Manifest Data Sources - Magic Method Pagination Handlers */
 // $first, $next, $prev, $page
 
+const PAGE_WINDOW_METHODS = new Set(['limit', 'offset', 'cursorAfter', 'cursorBefore']);
+
 function createPaginationMethod(methodName, dataSourceName) {
     return async function (...args) {
         const manifest = await window.ManifestDataConfig.ensureManifest();
@@ -9213,10 +9224,13 @@ function createPaginationMethod(methodName, dataSourceName) {
         // Base queries from manifest or scope
         const scope = window.ManifestDataConfig.getScope(dataSource);
         const scopeColumns = window.ManifestDataConfig.getScopeColumns(dataSource);
+        // Pages follow the active $query, else the default queries; paging supplies its own window
         const queriesConfig = window.ManifestDataConfig.getQueries(dataSource);
-        const baseQueries = queriesConfig
-            ? await window.ManifestDataQueries.buildAppwriteQueries(queriesConfig.default || queriesConfig, scope, scopeColumns)
-            : await window.ManifestDataQueries.buildAppwriteQueries([], scope, scopeColumns);
+        const defaults = queriesConfig ? (queriesConfig.default || queriesConfig) : [];
+        const active = window.ManifestDataMain?.getActiveQuery?.(dataSourceName);
+        const filters = (Array.isArray(active) ? active : (Array.isArray(defaults) ? defaults : []))
+            .filter(q => !(Array.isArray(q) && PAGE_WINDOW_METHODS.has(q[0])));
+        const baseQueries = await window.ManifestDataQueries.buildAppwriteQueries(filters, scope, scopeColumns);
 
         if (baseQueries === null) {
             throw new Error(`[Manifest Data] "${dataSourceName}" pagination: auth not ready yet — retry after auth settles`);
@@ -11905,6 +11919,56 @@ function configureRealtimeMeta(dataSourceName, config, initialCount, limitQuery)
     window.ManifestDataStore.setSourceState(dataSourceName, { realtimeOverflow: 0 });
 }
 
+// Active $query per source (manifest-format): realtime matches, orders and
+// server-filters by it until the next default load replaces the rows
+const activeQueries = new Map();
+const realtimeBinds = new Map(); // Map<name, { config, mode, rebind }>
+
+function realtimeQueriesFor(dataSourceName, defaults) {
+    return activeQueries.has(dataSourceName) ? activeQueries.get(dataSourceName) : defaults;
+}
+
+// [['orderDesc', 'n'], ...] → [['n', -1], ...]; orderRandom has no stable position
+function sortSpec(queries) {
+    if (!Array.isArray(queries)) return null;
+    if (queries.some(q => Array.isArray(q) && q[0] === 'orderRandom')) return null;
+    const order = queries
+        .filter(q => Array.isArray(q) && (q[0] === 'orderAsc' || q[0] === 'orderDesc') && typeof q[1] === 'string')
+        .map(q => [q[1], q[0] === 'orderAsc' ? 1 : -1]);
+    return order.length ? order : null;
+}
+
+function rebindLive(dataSourceName) {
+    const bind = realtimeBinds.get(dataSourceName);
+    if (bind?.mode !== 'all') return;
+    Promise.resolve().then(bind.rebind).catch(error => console.error(`[Manifest Data] Realtime rebind failed for "${dataSourceName}":`, error));
+}
+
+// $query landing: realtime follows the new filter set (caps reset to its result)
+function setActiveQuery(dataSourceName, queries, rowCount) {
+    const list = Array.isArray(queries) ? queries : [];
+    activeQueries.set(dataSourceName, list);
+    const bind = realtimeBinds.get(dataSourceName);
+    if (!bind) return;
+    const limitQ = list.find(q => Array.isArray(q) && q[0] === 'limit');
+    configureRealtimeMeta(dataSourceName, bind.config, rowCount || 0, limitQ ? limitQ[1] : null);
+    rebindLive(dataSourceName);
+}
+
+// Default rows landed: back to the manifest queries (caps sized to those rows)
+function clearActiveQuery(dataSourceName, rowCount) {
+    if (!activeQueries.delete(dataSourceName)) return;
+    const bind = realtimeBinds.get(dataSourceName);
+    if (bind) configureRealtimeMeta(dataSourceName, bind.config, rowCount || 0, bind.defaultLimit);
+    rebindLive(dataSourceName);
+}
+
+// Source reset (identity/scope) or torn down: nothing of the old binding carries over
+function forgetLiveSource(dataSourceName) {
+    activeQueries.delete(dataSourceName);
+    realtimeBinds.delete(dataSourceName);
+}
+
 // Events not applied since the last load — $x.<source>.$realtimeOverflow
 function bumpRealtimeOverflow(dataSourceName) {
     const state = Alpine.store('data')?.[`_${dataSourceName}_state`];
@@ -11913,12 +11977,12 @@ function bumpRealtimeOverflow(dataSourceName) {
 
 // Append under the cap. 'window' evicts the oldest realtime-appended row first
 // (never an initially-loaded row); otherwise the event counts in $realtimeOverflow.
-function realtimeAppend(dataSourceName, row, currentRows, generation) {
+function realtimeAppend(dataSourceName, row, currentRows, generation, order) {
     const { landRows, landRemove } = window.ManifestDataStore;
     const meta = realtimeMeta.get(dataSourceName);
     if (!meta || meta.maxRows === 0) {
         if (meta) meta.appended.push(row.$id);
-        landRows(dataSourceName, [row], { mode: 'append', generation });
+        landRows(dataSourceName, [row], { mode: 'append', generation, order });
         return;
     }
     const len = currentRows.length + meta.pending;
@@ -11943,7 +12007,7 @@ function realtimeAppend(dataSourceName, row, currentRows, generation) {
     }
     meta.pending++;
     meta.appended.push(row.$id);
-    landRows(dataSourceName, [row], { mode: 'append', generation })
+    landRows(dataSourceName, [row], { mode: 'append', generation, order })
         .then(() => { meta.pending = Math.max(0, meta.pending - 1); });
 }
 
@@ -11992,6 +12056,7 @@ async function handleTableRealtimeEvent(dataSourceName, databaseId, tableId, sco
 
     // Network landings: coalesced per frame (landRows upserts by $id), never the sync mutation path
     const { landRows, landRemove } = window.ManifestDataStore;
+    const order = sortSpec(queriesConfig);
 
     if (eventType === 'create') {
         const row = payload?.$id ? payload : (payload?.row || payload);
@@ -12001,9 +12066,9 @@ async function handleTableRealtimeEvent(dataSourceName, databaseId, tableId, sco
             if (rowMatchesScope && eventMatchesQueries(row, queriesConfig)) {
                 if (currentRows.find(r => r.$id === row.$id)) {
                     // Echo of a row already held (optimistic create): merge, never counts as growth
-                    landRows(dataSourceName, [row], { mode: 'append', generation });
+                    landRows(dataSourceName, [row], { mode: 'append', generation, order });
                 } else {
-                    realtimeAppend(dataSourceName, row, currentRows, generation);
+                    realtimeAppend(dataSourceName, row, currentRows, generation, order);
                 }
             }
         } else {
@@ -12024,7 +12089,7 @@ async function handleTableRealtimeEvent(dataSourceName, databaseId, tableId, sco
             }
             if (!existingRow) {
                 // Row not in list, but matches now - add it (capped like a create)
-                realtimeAppend(dataSourceName, row, currentRows, generation);
+                realtimeAppend(dataSourceName, row, currentRows, generation, order);
                 return;
             }
 
@@ -12084,7 +12149,7 @@ async function handleTableRealtimeEvent(dataSourceName, databaseId, tableId, sco
                 const fileIdsChanged = isProjectWithFiles &&
                     JSON.stringify(existingFileIds) !== JSON.stringify(incomingFileIds);
 
-                landRows(dataSourceName, [row], { mode: 'append', generation });
+                landRows(dataSourceName, [row], { mode: 'append', generation, order });
 
                 // Emit custom event for project file updates so UI can refresh
                 if (fileIdsChanged && dataSourceName === 'projects') {
@@ -12264,11 +12329,17 @@ async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
         return cachedData;
     }
 
-    // In flight for this source+locale: share it (every entry path lands here)
+    // In flight for this source+locale: share it (every entry path lands here);
+    // joining makes it the latest read again
     if (loadingPromises.has(cacheKey)) {
+        window.ManifestDataStore.adoptRead?.(dataSourceName, window.ManifestDataStore.loadReadTokens?.get(cacheKey));
         return loadingPromises.get(cacheKey);
     }
 
+    // Reads are ordered by call: a $query issued after this load wins over it
+    const readToken = window.ManifestDataStore.beginRead?.(dataSourceName);
+    window.ManifestDataStore.loadReadTokens?.set(cacheKey, readToken);
+
     // Loading state: rows already landed stay live; first-ever load clears
     const keepRows = hasLiveRows(dataSourceName);
     if (!isInitializing) {
@@ -12403,22 +12474,29 @@ async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
                     if (dataSource.realtime !== false && window.ManifestDataRealtime && window.ManifestDataRealtime.subscribeToTable) {
                         const rtQueries = Array.isArray(queriesConfig?.default || queriesConfig) ? (queriesConfig.default || queriesConfig) : [];
                         const limitQ = rtQueries.find(q => Array.isArray(q) && q[0] === 'limit');
-                        configureRealtimeMeta(dataSourceName, dataSource.realtime, Array.isArray(data) ? data.length : 0, limitQ ? limitQ[1] : null);
+                        if (!activeQueries.has(dataSourceName) || !realtimeMeta.has(dataSourceName)) {
+                            configureRealtimeMeta(dataSourceName, dataSource.realtime, Array.isArray(data) ? data.length : 0, limitQ ? limitQ[1] : null);
+                        }
                         // Events server-filtered where the SDK supports realtime queries; the client
                         // matcher below still runs. serverFilter: 'scope' (default) | 'all' (alias true) | false
                         const rtMode = serverFilterMode(dataSource.realtime);
-                        const rtFilterSpec = rtMode ? { queriesConfig: rtQueries, scope, scopeColumns, mode: rtMode } : null;
-                        const unsubscribe = await window.ManifestDataRealtime.subscribeToTable(
+                        const rtFilterSpec = rtMode ? {
+                            get queriesConfig() { return realtimeQueriesFor(dataSourceName, rtQueries); },
+                            scope, scopeColumns, mode: rtMode
+                        } : null;
+                        const subscribe = () => window.ManifestDataRealtime.subscribeToTable(
                             dataSourceName,
                             appwriteConfig.databaseId,
                             tableId,
                             scope,
                             async (eventType, payload) => {
-                                await handleTableRealtimeEvent(dataSourceName, appwriteConfig.databaseId, tableId, scope, scopeColumns, eventType, payload, generation, rtQueries);
+                                await handleTableRealtimeEvent(dataSourceName, appwriteConfig.databaseId, tableId, scope, scopeColumns, eventType, payload, generation, realtimeQueriesFor(dataSourceName, rtQueries));
                             },
                             () => !superseded(),
                             rtFilterSpec
                         );
+                        realtimeBinds.set(dataSourceName, { config: dataSource.realtime, mode: rtMode, rebind: subscribe, defaultLimit: limitQ ? limitQ[1] : null });
+                        const unsubscribe = await subscribe();
                         if (superseded()) { dropSubscription(dataSourceName, unsubscribe); landed = true; return null; }
                     }
                 } else if (bucketId) {
@@ -12594,6 +12672,13 @@ async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
 
             if (superseded()) { landed = true; return null; }
 
+            // A $query issued since this load began: its rows stand, this result never lands
+            if (window.ManifestDataStore.isLatestRead && !window.ManifestDataStore.isLatestRead(dataSourceName, readToken)) {
+                landed = true;
+                if (!isInitializing) setSourceState(dataSourceName, { loading: false });
+                return enhancedData;
+            }
+
             // Cache is always safe — the key carries this load's locale.
             dataSourceCache.set(cacheKey, enhancedData);
 
@@ -12610,6 +12695,7 @@ async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
             // Network landing (coalesced per frame, merges by $id); resolves once visible
             if (!isInitializing && !staleLocale) {
                 landed = true;
+                clearActiveQuery(dataSourceName, Array.isArray(enhancedData) ? enhancedData.length : 0);
                 await landRows(dataSourceName, enhancedData, { mode: 'replace', loading: false, error: null, ready: true, fresh: true, generation });
             }
 
@@ -12780,12 +12866,38 @@ async function initializeDataSourcesPlugin() {
     }
 
     // Export loadDataSource for use by team change listener
+    // Catch-up: events missed while offline or asleep never arrive, so live sources
+    // refetch (their active $query, else the default load) on reconnect or wake
+    const CATCH_UP_HIDDEN_MS = 60000;
+    let hiddenSince = document.hidden ? Date.now() : null;
+    let catchUpTimer = null;
+    const catchUpLiveSources = () => {
+        clearTimeout(catchUpTimer);
+        catchUpTimer = setTimeout(() => {
+            for (const name of realtimeBinds.keys()) {
+                const active = activeQueries.get(name);
+                const handler = active && window.ManifestDataProxiesAppwrite?.createAppwriteMethodsHandler?.(name, reloadDataSource);
+                Promise.resolve(handler ? handler('$query', active) : reloadDataSource(name)).catch(() => { /* $error carries it */ });
+            }
+        }, 250);
+    };
+    window.addEventListener('online', catchUpLiveSources);
+    document.addEventListener('visibilitychange', () => {
+        if (document.hidden) { hiddenSince = Date.now(); return; }
+        const away = hiddenSince !== null ? Date.now() - hiddenSince : 0;
+        hiddenSince = null;
+        if (away >= CATCH_UP_HIDDEN_MS) catchUpLiveSources();
+    });
+
     window.ManifestDataMain = {
         loadDataSource,
         reloadDataSource,
         _loadDataSource: reloadDataSource, // Internal: every user is a reload-after-mutation
         filterFilesByScope, // Export for use by getFilesForEntry
-        requiresIdentity
+        requiresIdentity,
+        setActiveQuery,
+        forgetLiveSource,
+        getActiveQuery: (dataSourceName) => activeQueries.get(dataSourceName) || null
     };
 
     // Listen for manifest:dev-reload (fired by mnfst-run when a data file changes).

package/lib/manifest.integrity.json

@@ -1,6 +1,6 @@
 {
   "manifest.appwrite.auth.js": "sha384-gWLSeVPqCLMiUZB8MU7GqMg3x2yULFUsp8nTTZrPp/9Dlkix42rBn9yIimvwrHqZ",
-  "manifest.appwrite.data.js": "sha384-42+RFwO3akEoogPnpUFNOeXgDGztU1Kmk/WAag6yJrdjOFIXRZcEGqy9DToHqssG",
+  "manifest.appwrite.data.js": "sha384-DL3DcEUoVXDqLwODzd/CBtnTyBPqeFl6RVx01oBv1lCwgMkNEGQeeKdA9l132m2m",
   "manifest.appwrite.presences.js": "sha384-LINPhIPTCK+rA8zd+HPUzMSEgH6Sl2vQMEyItT97bnEE2FYGYKqjXX+CWdt6nl9z",
   "manifest.bindings.js": "sha384-lPtMf8Ykaic9gNVZKq8Scia1881ZeMAyxer3WCIkUNwwrgzGBWto1OXADUwjvORF",
   "manifest.charts.js": "sha384-AFbP7mQnigy7DU1s+YE30yKTeQAKfgNazhbfSNbfd9ZpLgeulZKaPi/fAq3gJHDO",
@@ -11,7 +11,7 @@
   "manifest.combobox.js": "sha384-/lJo6vaxKjgnBSRs/dzkhK1dzGk3GBw8FISoNJZB70mwAVwu1k5veZyBXjOb4keS",
   "manifest.components.js": "sha384-1el5WMdgmzu/2ocaYN21OjLi/lfjllvA8aju1J3knYuOizw+XFfJU1+rvGqYW7qk",
   "manifest.computed.js": "sha384-GYML/e81gQfN+iDbqhPUgny8bINCyL+SrbTofoGk4hlCnLLjv51mCv42JMqq+ku5",
-  "manifest.data.js": "sha384-OtzsgGwSGzMkj9of9mCLKC9ZbLjIdDV8Q4nUcWTHJADTbWh69nI2HfEQScK0CUN1",
+  "manifest.data.js": "sha384-pOXyFP7tUdQG4c52usKJkWYgGxMN5g2a6dWAKYGAJEHrJL4gZDYRNgOsSq/+jnTm",
   "manifest.datepicker.js": "sha384-EzlMwvIxlla/0BuyhAEqxN0M8TGcWIWgEIg840V0akKQQK1uY648wPWMkobvtq/o",
   "manifest.defer.js": "sha384-PRp7+dCZHnnl55rX2xrHutLrQnszHo7o5o9Tq28M/yjLZPuXDzcwQNxCdvbtCYSz",
   "manifest.device.js": "sha384-YeQaS56L8IILqrQNBSeAOLwIh5DuAOrE60cYLK1+46qJtUrXlAvqGe2j5mbV4Vq7",
@@ -29,7 +29,7 @@
   "manifest.status.js": "sha384-ofu7nBnVIGZ1U1o2R9d2H3V8aEMPUCVbl5FO3gIToXqi0oa36fTviEdh5UU7Kitw",
   "manifest.submissions.js": "sha384-v9eS47ytAfTGIKAyVnbd0QWegucVS7yduvigqfsxxoqXmbaEoy0M2y+BiI4xeZBd",
   "manifest.svg.js": "sha384-qr/8H9+2cIhSXNbRWRtIdrDlTOxKlNJqwEefHvCYoiBNW/kKhPTFa109Orv/EBnb",
-  "manifest.sw.js": "sha384-aAbMkl5+e8xG9U16+K2l6XUphDZP/binE6AnswmuNEjKl6A4DsOSzWaqHXSiOgpL",
+  "manifest.sw.js": "sha384-hyn8eZtfGN2VxD1+L4AxEyI7CQlPPguEkG5AgjB19A2Ca/W4HhOnTiF3QfoAMnLq",
   "manifest.tabs.js": "sha384-otU09H7jnawVKQdLAYpMCd3jx00tgyPVr42D2hLIBzN5dG4se505YesavdnMqEi1",
   "manifest.tailwind.js": "sha384-yuP3LEvWU+QVjxjkZ0YhErtC9RrGmhOmHjjFjhS9obqZbp5/KTIEnSR0CXDvHE0B",
   "manifest.toasts.js": "sha384-UpOz9fAdGeGUhL0NamBg5iPepEfIy73p9HYdcxfOQC5b7CVsl7Our0skdZzaLNcC",

package/lib/manifest.schema.json

@@ -137,6 +137,28 @@
                 "type": "string"
             }
         },
+        "contract": {
+            "description": "Shared contract module, a path from the project root (e.g. /shared/contract.js), whose `tables` export declares Appwrite tables and columns. mnfst-test checks data sources against it; on dev hosts (or hosts listed in `checks`) app code reading a column of an Appwrite row that is undeclared and absent from every row of the source throws.",
+            "oneOf": [
+                { "type": "string" },
+                {
+                    "type": "object",
+                    "properties": {
+                        "module": { "type": "string" },
+                        "checks": {
+                            "description": "Where column checks run: 'dev' (default, local hosts), true (everywhere), false (nowhere), or host patterns such as '*-staging.example.com' (dev hosts included).",
+                            "oneOf": [
+                                { "type": "boolean" },
+                                { "type": "string", "enum": ["dev"] },
+                                { "type": "array", "items": { "type": "string" } }
+                            ]
+                        }
+                    },
+                    "required": ["module"],
+                    "additionalProperties": false
+                }
+            ]
+        },
         "data": {
             "type": "object",
             "description": "Named data sources made available via $x.<sourceName>. Each value is either a string path/URL or a config object.",

package/lib/manifest.sw.js

@@ -16,7 +16,7 @@
 
 // Build stamps the published version here; unstamped (dev) falls back to the
 // registration URL's `v`, then 'dev'.
-const BUILD_VERSION = '0.5.273';
+const BUILD_VERSION = '0.5.275';
 const CACHE_PREFIX = 'mnfst-sw:';
 const META_CACHE = CACHE_PREFIX + 'meta';
 // Sized to hold a full precache.json warm-up (PRECACHE_MAX_ENTRIES server-side)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mnfst",
-    "version": "0.5.273",
+    "version": "0.5.275",
     "private": false,
     "workspaces": [
         "templates/starter",
@@ -53,6 +53,7 @@
         "test:e2e:test-kit": "node tests/e2e/test-kit-journeys.e2e.mjs",
         "test:e2e:submissions": "node tests/e2e/submissions.e2e.mjs",
         "test:e2e:modules": "node tests/e2e/modules.e2e.mjs",
+        "test:e2e:contract": "node tests/e2e/contract.e2e.mjs && node tests/e2e/contract-checks.e2e.mjs",
         "lint": "echo 'No linting configured'",
         "release:docs": "node scripts/release-bump.mjs packages/docs && cd packages/docs && npm publish --auth-type=web",
         "release:check": "node scripts/release-check.mjs"