mnfst 0.5.247 → 0.5.249

package/lib/manifest.appwrite.data.js

@@ -2,7 +2,7 @@
 
 (function () {
 
-const MANIFEST_BUILD_VERSION = '0.5.247';
+const MANIFEST_BUILD_VERSION = '0.5.249';
 
 /* Manifest Data Sources - Appwrite Integration */
 
@@ -91,6 +91,20 @@ async function initializeAppwriteClient() {
     return appwriteClientPromise;
 }
 
+// Shared Realtime: ONE instance (one socket) per tab, keyed to the client it
+// wraps. Auth identity events drop it (below) so the next use rebuilds against
+// the current session; manifest.data.realtime.js re-binds live channels.
+let realtimeCache = null;
+let realtimeClient = null;
+function getSharedRealtime(client) {
+    if (!client || !window.Appwrite?.Realtime) return null;
+    if (!realtimeCache || realtimeClient !== client) {
+        realtimeCache = new window.Appwrite.Realtime(client);
+        realtimeClient = client;
+    }
+    return realtimeCache;
+}
+
 // Get Appwrite data services (TablesDB, Storage, Realtime)
 // Works with or without auth plugin
 async function getAppwriteDataServices() {
@@ -102,7 +116,7 @@ async function getAppwriteDataServices() {
     return {
         tablesDB: window.Appwrite.TablesDB ? new window.Appwrite.TablesDB(client) : null,
         storage: window.Appwrite.Storage ? new window.Appwrite.Storage(client) : null,
-        realtime: window.Appwrite.Realtime ? new window.Appwrite.Realtime(client) : null
+        realtime: getSharedRealtime(client)
     };
 }
 
@@ -110,7 +124,10 @@ async function getAppwriteDataServices() {
 let authCheck = null;
 let authVerified = false;
 ['manifest:auth:login', 'manifest:auth:logout', 'manifest:auth:anonymous', 'manifest:auth:session-cleared', 'manifest:auth:initialized']
-    .forEach(type => window.addEventListener(type, () => { authCheck = null; authVerified = false; }));
+    .forEach(type => window.addEventListener(type, () => {
+        authCheck = null; authVerified = false;
+        realtimeCache = null; realtimeClient = null; // socket re-authenticates as the new identity
+    }));
 
 async function verifyAuthenticated() {
     if (!window.ManifestAppwriteAuthConfig || authVerified) return;
@@ -665,159 +682,278 @@ window.ManifestDataAppwrite = {
 };
 
 
-/* Manifest Data Sources - Real-time Subscriptions */
+/* Manifest Data Sources - Real-time Subscriptions
+   One shared Realtime client per tab; subscriptions ref-counted by
+   (channel + canonical server-filter set) across sources.
+
+   Appwrite Realtime queries (server-side event filtering), verified against
+   the Web SDK and server source 2026-10:
+   - Realtime#subscribe(channels, callback, queries?) — queries are per
+     subscription (Query strings, ANDed; OR across subscriptions), supported
+     ops: equal/notEqual/lessThan(Equal)/greaterThan(Equal)/isNull/isNotNull/
+     and/or. SDK >=25.0.0 sends {type:'subscribe', data:[{subscriptionId,
+     channels, queries}]} socket messages and dispatches by the matched
+     subscription ids the server echoes; 22.4-24 carried per-slot queries in
+     the socket URL. subscribe() resolves to {unsubscribe, update, close}.
+   - Feature detection: a query-capable instance has pendingSubscribes (>=25)
+     or slotToSubscriptionId (22.4-24). Without either marker: channel-only
+     subscribe, exactly the 0.5.248 path.
+   - The server evaluates queries against the event payload only, so an
+     update that makes a held row STOP matching is not delivered. Therefore
+     serverFilter defaults to 'scope': only scope-column filters (permission-
+     mirrored, effectively immutable) ride the subscription; user queries stay
+     client-side so stop-matching rows still drop live. 'all' pushes every
+     expressible filter server-side (such rows then correct on the next load);
+     false sends none. The client matcher stays on in every mode. */
+
+// Map<subKey, { channel, queries, refs, unsubscribe, handlers: Map<sourceName, handler> }>
+const entries = new Map();
+// Map<sourceName, { subKey, channel, token, handler, getFilters }> — token guards a stale unsubscribe closure
+const sources = new Map();
+// Map<sourceName, fn(eventType, row)> — pre-filters, run per event per source
+const filters = new Map();
+// Back-compat/debug surface: Map<sourceName, unsubscribeFunction>
+const subscriptions = new Map();
+// Map<sourceName, n> — explicit teardowns; aborts a subscribe in flight
+const tombstones = new Map();
+// Instance the current subscriptions live on
+let activeRealtime = null;
+
+function classify(event) {
+    if (typeof event !== 'string') return null;
+    if (event.includes('create')) return 'create';
+    if (event.includes('update')) return 'update';
+    if (event.includes('delete')) return 'delete';
+    return null;
+}
 
-// Track active subscriptions
-const subscriptions = new Map(); // Map<dataSourceName, unsubscribeFunction>
+// Query-capable Realtime service (see header): detect per instance, never assume
+function supportsQueries(realtime) {
+    return !!(realtime && (realtime.pendingSubscribes || realtime.slotToSubscriptionId));
+}
 
-// Subscribe to storage bucket file changes
-// isCurrent: false once the requesting load is superseded (logout) — skip, never touch a newer entry
-async function subscribeToStorageBucket(dataSourceName, bucketId, scope, onEvent, isCurrent) {
-    // Unsubscribe from existing subscription if any
-    if (subscriptions.has(dataSourceName)) {
-        const unsubscribe = subscriptions.get(dataSourceName);
-        if (unsubscribe && typeof unsubscribe === 'function') {
-            unsubscribe();
+// (channel, resolved filter set) → stable subscription key; resolved.key is
+// already canonical (sorted) so equivalent filter sets share one subscription
+function subKeyFor(channel, resolved) {
+    if (!resolved || !resolved.key) return channel;
+    return `${channel}\u001f${resolved.key}`;
+}
+
+// Fan one SDK message out: each registered source handler gets each event once,
+// after that source's pre-filter (setFilter) — before any merge/dedup work
+function dispatch(subKey, response) {
+    const entry = entries.get(subKey);
+    if (!entry || !response || !response.events) return;
+    const events = Array.isArray(response.events) ? response.events : [response.events];
+    let payload = response.payload;
+    if (!payload || (!payload.$id && !payload.row)) payload = response;
+    for (const event of events) {
+        const type = classify(event);
+        if (!type) continue;
+        for (const [name, handler] of entry.handlers) {
+            const filter = filters.get(name);
+            if (filter && filter(type, payload) === false) continue;
+            handler(type, payload);
         }
-        subscriptions.delete(dataSourceName);
     }
+}
 
-    const services = await window.ManifestDataAppwrite.getAppwriteDataServices();
-    if (isCurrent && !isCurrent()) return null;
-    if (!services?.realtime) {
-        console.warn('[Manifest Data] Realtime service not available for', dataSourceName);
-        return null;
-    }
+// subscribe() returns an unsubscribe function (legacy client) or a
+// Promise<RealtimeSubscription> (Realtime service): normalize teardown
+function dropSub(sub) {
+    if (typeof sub === 'function') sub();
+    else if (sub && typeof sub.unsubscribe === 'function') sub.unsubscribe(); // per-subscription; never risks the shared socket
+    else if (sub && typeof sub.close === 'function') sub.close();
+}
 
-    // Channel format: buckets.[BUCKET_ID].files
-    const channel = `buckets.${bucketId}.files`;
+function makeUnsubscriber(result) {
+    if (!result || typeof result.then !== 'function') {
+        return () => { try { dropSub(result); } catch (e) { /* socket already gone */ } };
+    }
+    const settled = result.catch(() => null);
+    return () => { settled.then(dropSub).catch(() => { /* socket already gone */ }); };
+}
 
+function sdkSubscribe(realtime, subKey, channel, queries) {
+    const cb = response => dispatch(subKey, response);
+    const result = (queries && queries.length)
+        ? realtime.subscribe(channel, cb, queries)
+        : realtime.subscribe(channel, cb);
+    return makeUnsubscriber(result);
+}
 
+// Get or create the shared entry for (channel, filters); registered in the map
+// before the SDK call so an event arriving mid-subscribe already dispatches
+function ensureEntry(realtime, subKey, channel, queries) {
+    let entry = entries.get(subKey);
+    if (entry) return entry;
+    entry = { channel, queries: queries || [], refs: 0, unsubscribe: null, handlers: new Map() };
+    entries.set(subKey, entry);
     try {
-        const unsubscribe = services.realtime.subscribe(channel, (response) => {
-            if (!response || !response.events) {
-                return;
-            }
-
-            // Handle both array and single event formats
-            const events = Array.isArray(response.events) ? response.events : [response.events];
-
-            events.forEach(event => {
-                if (typeof event !== 'string') return;
-
-                // Payload might be in response.payload or response directly
-                const payload = response.payload || response;
-
-                // Handle different event types
-                if (event.includes('create') || event.includes('storage.files.create')) {
-                    // New file created
-                    onEvent('create', payload);
-                } else if (event.includes('update') || event.includes('storage.files.update')) {
-                    // File updated
-                    onEvent('update', payload);
-                } else if (event.includes('delete') || event.includes('storage.files.delete')) {
-                    // File deleted
-                    onEvent('delete', payload);
-                }
-            });
-        });
-
-        subscriptions.set(dataSourceName, unsubscribe);
-
-        return unsubscribe;
+        entry.unsubscribe = sdkSubscribe(realtime, subKey, channel, queries);
     } catch (error) {
-        console.error('[Manifest Data] Failed to subscribe to storage bucket:', error);
-        return null;
+        entries.delete(subKey);
+        throw error;
     }
+    return entry;
 }
 
-// Unsubscribe from a data source
-function unsubscribeFromDataSource(dataSourceName) {
-    if (subscriptions.has(dataSourceName)) {
-        const unsubscribe = subscriptions.get(dataSourceName);
-        if (unsubscribe && typeof unsubscribe === 'function') {
-            unsubscribe();
+function removeFromEntry(name, subKey) {
+    const entry = entries.get(subKey);
+    if (!entry) return;
+    entry.handlers.delete(name);
+    entry.refs = entry.handlers.size;
+    if (entry.refs === 0) {
+        entries.delete(subKey);
+        if (typeof entry.unsubscribe === 'function') {
+            try { entry.unsubscribe(); } catch (e) { /* socket already gone */ }
         }
-        subscriptions.delete(dataSourceName);
     }
 }
 
-// Unsubscribe from all data sources
-function unsubscribeAll() {
-    subscriptions.forEach((unsubscribe, dataSourceName) => {
-        if (unsubscribe && typeof unsubscribe === 'function') {
-            unsubscribe();
-        }
-    });
-    subscriptions.clear();
+// Drop a source's registration; tear the subscription down when the last source leaves
+function detach(name, token) {
+    const cur = sources.get(name);
+    if (!cur || (token && cur.token !== token)) return;
+    sources.delete(name);
+    removeFromEntry(name, cur.subKey);
 }
 
-// Subscribe to database table row changes
-async function subscribeToTable(dataSourceName, databaseId, tableId, scope, onEvent, isCurrent) {
-    // Unsubscribe from existing subscription if any
-    if (subscriptions.has(dataSourceName)) {
-        const unsubscribe = subscriptions.get(dataSourceName);
-        if (unsubscribe && typeof unsubscribe === 'function') {
-            unsubscribe();
+// Instance changed (client rebuilt on identity change): re-resolve each source's
+// filters ($auth. values are stale) and regroup subscriptions on the new instance.
+// Chained so overlapping rebuilds run in order; a superseded rebuild stops.
+let syncChain = Promise.resolve();
+function syncInstance(realtime) {
+    if (activeRealtime === realtime) return syncChain;
+    activeRealtime = realtime;
+    syncChain = syncChain
+        .then(() => rebindAll(realtime))
+        .catch(error => console.error('[Manifest Data] Realtime rebind failed:', error));
+    return syncChain;
+}
+
+async function rebindAll(realtime) {
+    for (const [, entry] of entries) {
+        if (typeof entry.unsubscribe === 'function') {
+            try { entry.unsubscribe(); } catch (e) { /* old instance */ }
+        }
+    }
+    entries.clear();
+    const canQuery = supportsQueries(realtime);
+    for (const [name, src] of sources) {
+        if (activeRealtime !== realtime) return; // superseded by a newer instance
+        const resolved = (canQuery && src.getFilters) ? await src.getFilters() : null;
+        const subKey = subKeyFor(src.channel, resolved);
+        try {
+            const entry = ensureEntry(realtime, subKey, src.channel, resolved?.queries);
+            entry.handlers.set(name, src.handler);
+            entry.refs = entry.handlers.size;
+            src.subKey = subKey;
+        } catch (error) {
+            console.error('[Manifest Data] Failed to re-subscribe channel:', src.channel, error);
         }
-        subscriptions.delete(dataSourceName);
     }
+}
 
+// One SDK subscribe per distinct (channel, filter set); sources sharing both share it.
+// isCurrent: false once the requesting load is superseded (logout) — skip, never touch a newer entry.
+// getFilters: async () => ({ queries, key }) | null, re-run per (re)subscribe so
+// $auth. values resolve at subscribe time; null → channel-only (0.5.248 path).
+// A replaced registration detaches only after the new subscription is live (no
+// event gap); overlap double-delivery is absorbed by the per-source event dedupe.
+async function subscribeChannel(dataSourceName, channel, onEvent, isCurrent, getFilters) {
+    const epoch = tombstones.get(dataSourceName) || 0;
     const services = await window.ManifestDataAppwrite.getAppwriteDataServices();
     if (isCurrent && !isCurrent()) return null;
     if (!services?.realtime) {
         console.warn('[Manifest Data] Realtime service not available for', dataSourceName);
+        detach(dataSourceName);
+        subscriptions.delete(dataSourceName);
         return null;
     }
+    const realtime = services.realtime;
+    await syncInstance(realtime);
+    if (isCurrent && !isCurrent()) return null;
 
-    // Channel format: databases.[DATABASE_ID].tables.[TABLE_ID].rows
-    const channel = `databases.${databaseId}.tables.${tableId}.rows`;
-
+    const resolved = (supportsQueries(realtime) && getFilters) ? await getFilters() : null;
+    if (isCurrent && !isCurrent()) return null;
+    // Torn down while resolving: land nothing
+    if ((tombstones.get(dataSourceName) || 0) !== epoch) return null;
+    // Instance replaced while resolving (identity rebuild): re-run against the live one
+    if (activeRealtime !== realtime) return subscribeChannel(dataSourceName, channel, onEvent, isCurrent, getFilters);
+    const subKey = subKeyFor(channel, resolved);
+
+    const prev = sources.get(dataSourceName);
+    let entry;
     try {
-        const unsubscribe = services.realtime.subscribe(channel, (response) => {
-            if (!response || !response.events) {
-                return;
-            }
-
-            // Handle both array and single event formats
-            const events = Array.isArray(response.events) ? response.events : [response.events];
+        entry = ensureEntry(realtime, subKey, channel, resolved?.queries);
+    } catch (error) {
+        console.error('[Manifest Data] Failed to subscribe:', channel, error);
+        detach(dataSourceName);
+        subscriptions.delete(dataSourceName);
+        return null;
+    }
+    const token = Symbol(dataSourceName);
+    entry.handlers.set(dataSourceName, onEvent);
+    entry.refs = entry.handlers.size;
+    sources.set(dataSourceName, { subKey, channel, token, handler: onEvent, getFilters });
+    if (prev && prev.subKey !== subKey) removeFromEntry(dataSourceName, prev.subKey);
 
-            events.forEach(event => {
-                if (typeof event !== 'string') {
-                    return;
-                }
+    const unsubscribe = () => detach(dataSourceName, token);
+    subscriptions.set(dataSourceName, unsubscribe);
+    return unsubscribe;
+}
 
-                // Payload might be in response.payload or response directly
-                // Appwrite realtime structure: { events: [...], payload: {...} }
-                let payload = response.payload;
+// Resolver re-runs per (re)subscribe so $auth. values are current at that moment
+function filterResolver(filterSpec) {
+    if (!filterSpec) return null;
+    const build = window.ManifestDataQueries?.buildRealtimeQueries;
+    if (typeof build !== 'function') return null;
+    return () => build(filterSpec.queriesConfig, filterSpec.scope, filterSpec.scopeColumns, filterSpec.mode);
+}
 
-                // If payload doesn't have $id, try response directly
-                if (!payload || (!payload.$id && !payload.row)) {
-                    payload = response;
-                }
+// Subscribe to storage bucket file changes
+function subscribeToStorageBucket(dataSourceName, bucketId, scope, onEvent, isCurrent, filterSpec) {
+    return subscribeChannel(dataSourceName, `buckets.${bucketId}.files`, onEvent, isCurrent, filterResolver(filterSpec));
+}
 
-                // Handle different event types
-                if (event.includes('create') || event.includes('rows.create') || event.includes('documents.create')) {
-                    // New row created
-                    onEvent('create', payload);
-                } else if (event.includes('update') || event.includes('rows.update') || event.includes('documents.update')) {
-                    // Row updated
-                    onEvent('update', payload);
-                } else if (event.includes('delete') || event.includes('rows.delete') || event.includes('documents.delete')) {
-                    // Row deleted
-                    onEvent('delete', payload);
-                } else {
-                }
-            });
-        });
+// Subscribe to database table row changes
+function subscribeToTable(dataSourceName, databaseId, tableId, scope, onEvent, isCurrent, filterSpec) {
+    return subscribeChannel(dataSourceName, `databases.${databaseId}.tables.${tableId}.rows`, onEvent, isCurrent, filterResolver(filterSpec));
+}
 
-        subscriptions.set(dataSourceName, unsubscribe);
+// Unsubscribe from a data source
+function unsubscribeFromDataSource(dataSourceName) {
+    tombstones.set(dataSourceName, (tombstones.get(dataSourceName) || 0) + 1);
+    detach(dataSourceName);
+    subscriptions.delete(dataSourceName);
+}
 
-        return unsubscribe;
-    } catch (error) {
-        console.error('[Manifest Data] Failed to subscribe to table:', error);
-        return null;
+// Unsubscribe from all data sources
+function unsubscribeAll() {
+    for (const name of [...sources.keys()]) {
+        tombstones.set(name, (tombstones.get(name) || 0) + 1);
+        detach(name);
     }
+    subscriptions.clear();
+}
+
+// Programmatic pre-filter: fn(eventType, row) runs per event per source BEFORE
+// any merge/dedup work; returning false drops the event. null clears it.
+function setFilter(sourceName, fn) {
+    if (fn == null) filters.delete(sourceName);
+    else if (typeof fn === 'function') filters.set(sourceName, fn);
+}
+
+// Identity events rebuild the shared Realtime (manifest.data.appwrite.js drops
+// its memo on the same events); re-bind live subscriptions to the new instance
+if (typeof window !== 'undefined') {
+    ['manifest:auth:login', 'manifest:auth:logout', 'manifest:auth:anonymous', 'manifest:auth:session-cleared', 'manifest:auth:initialized']
+        .forEach(type => window.addEventListener(type, async () => {
+            if (!sources.size) return;
+            const services = await window.ManifestDataAppwrite?.getAppwriteDataServices?.();
+            if (services?.realtime) syncInstance(services.realtime);
+        }));
 }
 
 // Export functions
@@ -826,7 +962,9 @@ window.ManifestDataRealtime = {
     subscribeToTable,
     unsubscribeFromDataSource,
     unsubscribeAll,
-    subscriptions // Expose for debugging
+    setFilter,
+    subscriptions, // Expose for debugging
+    _channels: entries // Expose for debugging (keyed by channel + filter set)
 };
 
 
@@ -1186,6 +1324,86 @@ async function buildQueries(queriesConfig, scope, scopeColumns) {
     return [...scopeQueries, ...userQueries];
 }
 
+// Query methods buildAppwriteQueries serializes (anything else is dropped at
+// load and must therefore never drop rows in the realtime matcher below)
+const QUERY_MAP = {
+    'equal': 'equal',
+    'notEqual': 'notEqual',
+    'lessThan': 'lessThan',
+    'lessThanEqual': 'lessThanEqual',
+    'greaterThan': 'greaterThan',
+    'greaterThanEqual': 'greaterThanEqual',
+    'contains': 'contains',
+    'search': 'search',
+    'or': 'or', // Support for multi-team queries (Query.or([Query.equal(...), ...]))
+    'orderAsc': 'orderAsc',
+    'orderDesc': 'orderDesc',
+    'limit': 'limit',
+    'offset': 'offset',
+    'cursorAfter': 'cursorAfter',
+    'cursorBefore': 'cursorBefore'
+};
+
+// Client-side row matcher for realtime events: evaluates a source's configured
+// filter queries against one row. Only operators the load actually serializes
+// (QUERY_MAP) are evaluable. Liveness over precision: anything unevaluable —
+// search, an operator the load drops, or a $auth. arg that can't resolve
+// synchronously — counts as a MATCH so live events are never silently dropped.
+const NON_FILTER_METHODS = new Set(['limit', 'offset', 'orderAsc', 'orderDesc', 'select', 'cursorAfter', 'cursorBefore']);
+
+function rowMatchesQueries(row, queriesConfig) {
+    if (!row || !Array.isArray(queriesConfig) || queriesConfig.length === 0) return true;
+    return queriesConfig.every(query => matchQuery(row, query));
+}
+
+function matchQuery(row, query) {
+    if (!Array.isArray(query) || query.length === 0) return true;
+    let interpolated;
+    try {
+        interpolated = interpolateQuery(query);
+    } catch (e) {
+        if (e === NOT_READY) return true; // unresolved $auth. arg
+        throw e;
+    }
+    const [method, ...args] = interpolated;
+    if (NON_FILTER_METHODS.has(method)) return true;
+    if (!(method in QUERY_MAP)) return true; // load drops it: unevaluable
+    if (method === 'and') return Array.isArray(args[0]) ? args[0].every(sub => matchQuery(row, sub)) : true;
+    if (method === 'or') return Array.isArray(args[0]) ? args[0].some(sub => matchQuery(row, sub)) : true;
+
+    const attr = args[0];
+    const val = row ? row[attr] : undefined;
+    const values = Array.isArray(args[1]) ? args[1] : [args[1]];
+    // Strings compare case-insensitively (Appwrite's ci collation); other types strictly
+    const eq = (a, b) => (typeof a === 'string' && typeof b === 'string')
+        ? a.toLowerCase() === b.toLowerCase()
+        : a === b;
+    const anyEqual = () => Array.isArray(val)
+        ? values.some(v => val.some(el => eq(el, v)))
+        : values.some(v => eq(val, v));
+    const cmp = (bound, op) => val !== null && val !== undefined && bound !== null && bound !== undefined && op(val, bound);
+    const lower = s => String(s).toLowerCase();
+
+    switch (method) {
+        case 'equal': return anyEqual();
+        case 'notEqual': return !anyEqual();
+        case 'lessThan': return cmp(args[1], (a, b) => a < b);
+        case 'lessThanEqual': return cmp(args[1], (a, b) => a <= b);
+        case 'greaterThan': return cmp(args[1], (a, b) => a > b);
+        case 'greaterThanEqual': return cmp(args[1], (a, b) => a >= b);
+        case 'between': return cmp(args[1], (a, b) => a >= b) && cmp(args[2], (a, b) => a <= b);
+        case 'isNull': return val === null || val === undefined;
+        case 'isNotNull': return val !== null && val !== undefined;
+        case 'startsWith': return typeof val === 'string' && values.some(v => lower(val).startsWith(lower(v)));
+        case 'endsWith': return typeof val === 'string' && values.some(v => lower(val).endsWith(lower(v)));
+        case 'contains':
+            if (Array.isArray(val)) return values.some(v => val.some(el => eq(el, v)));
+            if (typeof val === 'string') return values.some(v => lower(val).includes(lower(v)));
+            return false;
+        default: return true; // search: unevaluable
+    }
+}
+
 // Convert query array to Appwrite Query object
 function toAppwriteQuery(queryArray) {
     if (!Array.isArray(queryArray) || queryArray.length === 0) {
@@ -1194,24 +1412,9 @@ function toAppwriteQuery(queryArray) {
 
     const [method, ...args] = queryArray;
 
-    // Map common query methods to Appwrite Query methods
-    const queryMap = {
-        'equal': 'equal',
-        'notEqual': 'notEqual',
-        'lessThan': 'lessThan',
-        'lessThanEqual': 'lessThanEqual',
-        'greaterThan': 'greaterThan',
-        'greaterThanEqual': 'greaterThanEqual',
-        'contains': 'contains',
-        'search': 'search',
-        'or': 'or', // Support for multi-team queries (Query.or([Query.equal(...), ...]))
-        'orderAsc': 'orderAsc',
-        'orderDesc': 'orderDesc',
-        'limit': 'limit',
-        'offset': 'offset',
-        'cursorAfter': 'cursorAfter',
-        'cursorBefore': 'cursorBefore'
-    };
+    // Map common query methods to Appwrite Query methods (QUERY_MAP above —
+    // also the realtime matcher's evaluable set)
+    const queryMap = QUERY_MAP;
 
     if (!window.Appwrite || !window.Appwrite.Query) {
         console.error('[Manifest Data] Appwrite Query not available');
@@ -1252,6 +1455,42 @@ function toAppwriteQuery(queryArray) {
     }
 }
 
+// Realtime-expressible operators: the intersection of what the load serializes
+// (QUERY_MAP), what the matcher evaluates, and what Appwrite realtime filters
+// server-side. isNull/isNotNull are realtime-supported but the load drops them,
+// so filtering on them server-side would drop events the matcher keeps — excluded.
+const REALTIME_FILTER_OPS = new Set(['equal', 'notEqual', 'lessThan', 'lessThanEqual', 'greaterThan', 'greaterThanEqual']);
+
+function isRealtimeExpressible(query) {
+    if (!Array.isArray(query) || query.length === 0) return false;
+    const [method, ...args] = query;
+    if (method === 'or') return Array.isArray(args[0]) && args[0].length > 0 && args[0].every(isRealtimeExpressible);
+    return REALTIME_FILTER_OPS.has(method);
+}
+
+// Server-side realtime filter set, reduced to the expressible subset. Omitting
+// a query only WIDENS delivery — the client matcher still filters — so
+// unexpressible queries are dropped whole, never approximated.
+// mode 'scope' (default): only scope-column queries ride the subscription —
+// permission-mirrored, so a row leaving the filter still delivers its last
+// event and drops live. 'all': user queries too (a held row that stops
+// matching then corrects on the next load, not instantly).
+// Returns { queries, key } (key = canonical sorted serialization, for
+// subscription sharing) or null (not ready / nothing expressible → channel-only
+// subscribe, the 0.5.248 path).
+async function buildRealtimeQueries(queriesConfig, scope, scopeColumns, mode = 'scope') {
+    const userConfig = (mode === 'all' && Array.isArray(queriesConfig)) ? queriesConfig : [];
+    const resolved = await buildQueries(userConfig, scope, scopeColumns);
+    if (resolved === null) return null;
+    const queries = resolved
+        .filter(isRealtimeExpressible)
+        .map(query => toAppwriteQuery(query))
+        .filter(query => query !== null);
+    if (queries.length === 0) return null;
+    const key = queries.map(q => typeof q === 'string' ? q : JSON.stringify(q)).sort().join('\u001e');
+    return { queries, key };
+}
+
 // Build Appwrite queries from configuration
 // scopeColumns: { team, user } column names (default teamId/userId) — see manifest.data.config.js getScopeColumns
 // Returns null ("not ready") straight through — see buildQueries.
@@ -1271,6 +1510,8 @@ window.ManifestDataQueries = {
     getAuthValue,
     buildQueries,
     buildAppwriteQueries,
+    buildRealtimeQueries,
+    rowMatchesQueries,
     toAppwriteQuery,
     ALLOWED_VARIABLES,
     DEFAULT_SCOPE_COLUMNS