@rool-dev/sdk 0.2.0-dev.29da71e → 0.2.0-dev.64c2b97

package/dist/space.js

@@ -1,4 +1,3 @@
-import { immutableJSONPatch } from 'immutable-json-patch';
 import { EventEmitter } from './event-emitter.js';
 import { SpaceSubscriptionManager } from './subscription.js';
 // 6-character alphanumeric ID (62^6 = 56.8 billion possible values)
@@ -10,9 +9,15 @@ export function generateEntityId() {
     }
     return result;
 }
+// Default timeout for waiting on SSE object events (30 seconds)
+const OBJECT_COLLECT_TIMEOUT = 30000;
 /**
  * First-class Space object.
  *
+ * Objects are fetched on demand from the server; only schema, metadata,
+ * and conversations are cached locally. Object changes arrive via SSE
+ * semantic events and are emitted as SDK events.
+ *
  * Features:
  * - High-level object operations
  * - Built-in undo/redo with checkpoints
@@ -27,7 +32,6 @@ export class RoolSpace extends EventEmitter {
     _linkAccess;
     _userId;
     _conversationId;
-    _data;
     _closed = false;
     graphqlClient;
     mediaClient;
@@ -35,6 +39,18 @@ export class RoolSpace extends EventEmitter {
     onCloseCallback;
     _subscriptionReady;
     logger;
+    // Local cache for bounded data (schema, metadata, conversations, object IDs)
+    _meta;
+    _schema;
+    _conversations;
+    _objectIds;
+    // Object collection: tracks pending local mutations for dedup
+    // Maps objectId → optimistic object data (for create/update) or null (for delete)
+    _pendingMutations = new Map();
+    // Resolvers waiting for object data from SSE events
+    _objectResolvers = new Map();
+    // Buffer for object data that arrived before a collector was registered
+    _objectBuffer = new Map();
     constructor(config) {
         super();
         this._id = config.id;
@@ -44,11 +60,15 @@ export class RoolSpace extends EventEmitter {
         this._userId = config.userId;
         this._emitterLogger = config.logger;
         this._conversationId = config.conversationId ?? generateEntityId();
-        this._data = config.initialData;
         this.graphqlClient = config.graphqlClient;
         this.mediaClient = config.mediaClient;
         this.logger = config.logger;
         this.onCloseCallback = config.onClose;
+        // Initialize local cache from server data
+        this._meta = config.initialData.meta ?? {};
+        this._schema = config.initialData.schema ?? {};
+        this._conversations = config.initialData.conversations ?? {};
+        this._objectIds = config.initialData.objectIds ?? [];
         // Create space-level subscription
         this.subscriptionManager = new SpaceSubscriptionManager({
             graphqlUrl: config.graphqlUrl,
@@ -126,20 +146,20 @@ export class RoolSpace extends EventEmitter {
      * Returns the interactions array.
      */
     getInteractions() {
-        return this._data.conversations?.[this._conversationId]?.interactions ?? [];
+        return this._conversations[this._conversationId]?.interactions ?? [];
     }
     /**
      * Get interactions for a specific conversation ID.
      * Useful for viewing other conversations in the space.
      */
     getInteractionsById(conversationId) {
-        return this._data.conversations?.[conversationId]?.interactions ?? [];
+        return this._conversations[conversationId]?.interactions ?? [];
     }
     /**
      * Get all conversation IDs that have conversations in this space.
      */
     getConversationIds() {
-        return Object.keys(this._data.conversations ?? {});
+        return Object.keys(this._conversations);
     }
     // ===========================================================================
     // Space Lifecycle
@@ -166,6 +186,10 @@ export class RoolSpace extends EventEmitter {
         this._closed = true;
         this.subscriptionManager.destroy();
         this.onCloseCallback(this._id);
+        // Clean up pending object collectors
+        this._objectResolvers.clear();
+        this._objectBuffer.clear();
+        this._pendingMutations.clear();
         this.removeAllListeners();
     }
     // ===========================================================================
@@ -173,7 +197,6 @@ export class RoolSpace extends EventEmitter {
     // ===========================================================================
     /**
      * Create a checkpoint (seal current batch of changes).
-     * Patches accumulate automatically - this seals them with a label.
      * @returns The checkpoint ID
      */
     async checkpoint(label = 'Change') {
@@ -202,7 +225,7 @@ export class RoolSpace extends EventEmitter {
      */
     async undo() {
         const result = await this.graphqlClient.undo(this._id, this._conversationId);
-        // Server broadcasts space_patched if successful, which updates local state
+        // Server broadcasts space_changed, which triggers reset event
         return result.success;
     }
     /**
@@ -211,7 +234,7 @@ export class RoolSpace extends EventEmitter {
      */
     async redo() {
         const result = await this.graphqlClient.redo(this._id, this._conversationId);
-        // Server broadcasts space_patched if successful, which updates local state
+        // Server broadcasts space_changed, which triggers reset event
         return result.success;
     }
     /**
@@ -225,24 +248,19 @@ export class RoolSpace extends EventEmitter {
     // ===========================================================================
     /**
      * Get an object's data by ID.
-     * Returns just the data portion (RoolObject), not the full entry with meta/links.
+     * Fetches from the server on each call.
      */
     async getObject(objectId) {
-        return this._data.objects[objectId]?.data;
+        return this.graphqlClient.getObject(this._id, objectId);
     }
     /**
      * Get an object's stat (audit information).
      * Returns modification timestamp and author, or undefined if object not found.
      */
-    async stat(objectId) {
-        const entry = this._data.objects[objectId];
-        if (!entry)
-            return undefined;
-        return {
-            modifiedAt: entry.modifiedAt,
-            modifiedBy: entry.modifiedBy,
-            modifiedByName: entry.modifiedByName,
-        };
+    async stat(_objectId) {
+        // TODO: Requires a dedicated server endpoint for object audit info
+        this.logger.warn('[RoolSpace] stat() not yet supported in stateless mode');
+        return undefined;
     }
     /**
      * Find objects using structured filters and/or natural language.
@@ -258,44 +276,22 @@ export class RoolSpace extends EventEmitter {
      * @param options.order - Sort order by modifiedAt: `'asc'` or `'desc'` (default: `'desc'`). Only applies to structured filtering (no `prompt`).
      * @param options.ephemeral - If true, the query won't be recorded in conversation history.
      * @returns The matching objects and a descriptive message.
-     *
-     * @example
-     * // Exact match (no AI, no credits)
-     * const { objects } = await space.findObjects({ where: { type: 'article' } });
-     *
-     * @example
-     * // Natural language (AI query)
-     * const { objects, message } = await space.findObjects({
-     *   prompt: 'articles about space exploration'
-     * });
-     *
-     * @example
-     * // Combined — where narrows the data, prompt queries within it
-     * const { objects } = await space.findObjects({
-     *   where: { type: 'article' },
-     *   prompt: 'that discuss climate solutions positively',
-     *   limit: 10
-     * });
      */
     async findObjects(options) {
         return this.graphqlClient.findObjects(this._id, options, this._conversationId);
     }
     /**
-     * Get all object IDs.
+     * Get all object IDs (sync, from local cache).
+     * The list is loaded on open and kept current via SSE events.
      * @param options.limit - Maximum number of IDs to return
      * @param options.order - Sort order by modifiedAt ('asc' or 'desc', default: 'desc')
      */
     getObjectIds(options) {
-        const order = options?.order ?? 'desc';
-        let entries = Object.entries(this._data.objects);
-        // Sort by modifiedAt
-        entries.sort((a, b) => {
-            const aTime = a[1].modifiedAt ?? 0;
-            const bTime = b[1].modifiedAt ?? 0;
-            return order === 'desc' ? bTime - aTime : aTime - bTime;
-        });
-        let ids = entries.map(([id]) => id);
-        if (options?.limit) {
+        let ids = this._objectIds;
+        if (options?.order === 'asc') {
+            ids = [...ids].reverse();
+        }
+        if (options?.limit !== undefined) {
             ids = ids.slice(0, options.limit);
         }
         return ids;
@@ -314,30 +310,25 @@ export class RoolSpace extends EventEmitter {
         if (!/^[a-zA-Z0-9_-]+$/.test(objectId)) {
             throw new Error(`Invalid object ID "${objectId}". IDs must contain only alphanumeric characters, hyphens, and underscores.`);
         }
-        // Fail if object already exists
-        if (this._data.objects[objectId]) {
-            throw new Error(`Object "${objectId}" already exists`);
-        }
         const dataWithId = { ...data, id: objectId };
-        // Build the entry for local state (optimistic - server will overwrite audit fields)
-        const entry = {
-            data: dataWithId,
-            modifiedAt: Date.now(),
-            modifiedBy: this._userId,
-            modifiedByName: null,
-        };
-        // Update local state immediately (optimistic)
-        this._data.objects[objectId] = entry;
-        this.emit('objectCreated', { objectId, object: entry.data, source: 'local_user' });
-        // Await server call (may trigger AI processing that updates local state via patches)
+        // Emit optimistic event and track for dedup
+        this._pendingMutations.set(objectId, dataWithId);
+        this.emit('objectCreated', { objectId, object: dataWithId, source: 'local_user' });
         try {
-            const message = await this.graphqlClient.createObject(this.id, dataWithId, this._conversationId, ephemeral);
-            // Return current state (may have been updated by AI patches)
-            return { object: this._data.objects[objectId].data, message };
+            // Await mutation — server processes AI placeholders before responding.
+            // SSE events arrive during the await and are buffered via _deliverObject.
+            const { message } = await this.graphqlClient.createObject(this.id, dataWithId, this._conversationId, ephemeral);
+            // Collect resolved object from buffer (or wait if not yet arrived)
+            const object = await this._collectObject(objectId);
+            return { object, message };
         }
         catch (error) {
             this.logger.error('[RoolSpace] Failed to create object:', error);
-            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            this._pendingMutations.delete(objectId);
+            this._cancelCollector(objectId);
+            // Emit reset so UI can recover from the optimistic event
+            this.emit('syncError', error instanceof Error ? error : new Error(String(error)));
+            this.emit('reset', { source: 'system' });
             throw error;
         }
     }
@@ -350,10 +341,6 @@ export class RoolSpace extends EventEmitter {
      * @returns The updated object (with AI-filled content) and message
      */
     async updateObject(objectId, options) {
-        const entry = this._data.objects[objectId];
-        if (!entry) {
-            throw new Error(`Object ${objectId} not found for update`);
-        }
         const { data, ephemeral } = options;
         // id is immutable after creation (but null/undefined means delete attempt, which we also reject)
         if (data?.id !== undefined && data.id !== null) {
@@ -371,30 +358,24 @@ export class RoolSpace extends EventEmitter {
                 serverData[key] = value === undefined ? null : value;
             }
         }
-        // Build local updates (apply deletions and updates)
-        if (data) {
-            for (const [key, value] of Object.entries(data)) {
-                if (value === null || value === undefined) {
-                    delete entry.data[key];
-                }
-                else {
-                    entry.data[key] = value;
-                }
-            }
-        }
-        // Emit semantic event with updated object
+        // Emit optimistic event if we have data changes
         if (data) {
-            this.emit('objectUpdated', { objectId, object: entry.data, source: 'local_user' });
+            // Build optimistic object (best effort — we may not have the current state)
+            const optimistic = { id: objectId, ...data };
+            this._pendingMutations.set(objectId, optimistic);
+            this.emit('objectUpdated', { objectId, object: optimistic, source: 'local_user' });
         }
-        // Await server call (may trigger AI processing that updates local state via patches)
         try {
-            const message = await this.graphqlClient.updateObject(this.id, objectId, this._conversationId, serverData, options.prompt, ephemeral);
-            // Return current state (may have been updated by AI patches)
-            return { object: this._data.objects[objectId].data, message };
+            const { message } = await this.graphqlClient.updateObject(this.id, objectId, this._conversationId, serverData, options.prompt, ephemeral);
+            const object = await this._collectObject(objectId);
+            return { object, message };
         }
         catch (error) {
             this.logger.error('[RoolSpace] Failed to update object:', error);
-            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            this._pendingMutations.delete(objectId);
+            this._cancelCollector(objectId);
+            this.emit('syncError', error instanceof Error ? error : new Error(String(error)));
+            this.emit('reset', { source: 'system' });
             throw error;
         }
     }
@@ -405,25 +386,95 @@ export class RoolSpace extends EventEmitter {
     async deleteObjects(objectIds) {
         if (objectIds.length === 0)
             return;
-        const deletedObjectIds = [];
-        // Remove objects (local state)
+        // Track for dedup and emit optimistic events
         for (const objectId of objectIds) {
-            if (this._data.objects[objectId]) {
-                delete this._data.objects[objectId];
-                deletedObjectIds.push(objectId);
-            }
-        }
-        // Emit semantic events
-        for (const objectId of deletedObjectIds) {
+            this._pendingMutations.set(objectId, null);
             this.emit('objectDeleted', { objectId, source: 'local_user' });
         }
-        // Await server call
         try {
             await this.graphqlClient.deleteObjects(this.id, objectIds, this._conversationId);
         }
         catch (error) {
             this.logger.error('[RoolSpace] Failed to delete objects:', error);
-            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            for (const objectId of objectIds) {
+                this._pendingMutations.delete(objectId);
+            }
+            this.emit('syncError', error instanceof Error ? error : new Error(String(error)));
+            this.emit('reset', { source: 'system' });
+            throw error;
+        }
+    }
+    // ===========================================================================
+    // Collection Schema Operations
+    // ===========================================================================
+    /**
+     * Get the current schema for this space.
+     * Returns a map of collection names to their definitions.
+     */
+    getSchema() {
+        return this._schema;
+    }
+    /**
+     * Create a new collection schema.
+     * @param name - Collection name (must start with a letter, alphanumeric/hyphens/underscores only)
+     * @param fields - Field definitions for the collection
+     * @returns The created CollectionDef
+     */
+    async createCollection(name, fields) {
+        if (this._schema[name]) {
+            throw new Error(`Collection "${name}" already exists`);
+        }
+        // Optimistic local update
+        const optimisticDef = { fields: fields.map(f => ({ name: f.name, type: f.type })) };
+        this._schema[name] = optimisticDef;
+        try {
+            return await this.graphqlClient.createCollection(this._id, name, fields, this._conversationId);
+        }
+        catch (error) {
+            this.logger.error('[RoolSpace] Failed to create collection:', error);
+            delete this._schema[name];
+            throw error;
+        }
+    }
+    /**
+     * Alter an existing collection schema, replacing its field definitions.
+     * @param name - Name of the collection to alter
+     * @param fields - New field definitions (replaces all existing fields)
+     * @returns The updated CollectionDef
+     */
+    async alterCollection(name, fields) {
+        if (!this._schema[name]) {
+            throw new Error(`Collection "${name}" not found`);
+        }
+        const previous = this._schema[name];
+        // Optimistic local update
+        this._schema[name] = { fields: fields.map(f => ({ name: f.name, type: f.type })) };
+        try {
+            return await this.graphqlClient.alterCollection(this._id, name, fields, this._conversationId);
+        }
+        catch (error) {
+            this.logger.error('[RoolSpace] Failed to alter collection:', error);
+            this._schema[name] = previous;
+            throw error;
+        }
+    }
+    /**
+     * Drop a collection schema.
+     * @param name - Name of the collection to drop
+     */
+    async dropCollection(name) {
+        if (!this._schema[name]) {
+            throw new Error(`Collection "${name}" not found`);
+        }
+        const previous = this._schema[name];
+        // Optimistic local update
+        delete this._schema[name];
+        try {
+            await this.graphqlClient.dropCollection(this._id, name, this._conversationId);
+        }
+        catch (error) {
+            this.logger.error('[RoolSpace] Failed to drop collection:', error);
+            this._schema[name] = previous;
             throw error;
         }
     }
@@ -437,9 +488,8 @@ export class RoolSpace extends EventEmitter {
     async deleteConversation(conversationId) {
         const targetConversationId = conversationId ?? this._conversationId;
         // Optimistic local update
-        if (this._data.conversations?.[targetConversationId]) {
-            delete this._data.conversations[targetConversationId];
-        }
+        const previous = this._conversations[targetConversationId];
+        delete this._conversations[targetConversationId];
         // Emit events
         this.emit('conversationUpdated', {
             conversationId: targetConversationId,
@@ -456,7 +506,8 @@ export class RoolSpace extends EventEmitter {
         }
         catch (error) {
             this.logger.error('[RoolSpace] Failed to delete conversation:', error);
-            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            if (previous)
+                this._conversations[targetConversationId] = previous;
             throw error;
         }
     }
@@ -466,12 +517,10 @@ export class RoolSpace extends EventEmitter {
      */
     async renameConversation(conversationId, name) {
         // Optimistic local update - auto-create if needed
-        if (!this._data.conversations) {
-            this._data.conversations = {};
-        }
-        const isNew = !this._data.conversations[conversationId];
+        const isNew = !this._conversations[conversationId];
+        const previous = this._conversations[conversationId];
         if (isNew) {
-            this._data.conversations[conversationId] = {
+            this._conversations[conversationId] = {
                 name,
                 createdAt: Date.now(),
                 createdBy: this._userId,
@@ -479,7 +528,7 @@ export class RoolSpace extends EventEmitter {
             };
         }
         else {
-            this._data.conversations[conversationId].name = name;
+            this._conversations[conversationId] = { ...this._conversations[conversationId], name };
         }
         // Emit events
         this.emit('conversationUpdated', {
@@ -498,22 +547,35 @@ export class RoolSpace extends EventEmitter {
         }
         catch (error) {
             this.logger.error('[RoolSpace] Failed to rename conversation:', error);
-            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            if (isNew) {
+                delete this._conversations[conversationId];
+            }
+            else if (previous) {
+                this._conversations[conversationId] = previous;
+            }
             throw error;
         }
     }
     /**
      * List all conversations in this space with summary info.
+     * Returns from local cache (kept in sync via SSE).
      */
-    async listConversations() {
-        return this.graphqlClient.listConversations(this.id);
+    listConversations() {
+        return Object.entries(this._conversations).map(([id, conv]) => ({
+            id,
+            name: conv.name ?? null,
+            createdAt: conv.createdAt,
+            createdBy: conv.createdBy,
+            createdByName: conv.createdByName ?? null,
+            interactionCount: conv.interactions.length,
+        }));
     }
     /**
      * Get the system instruction for the current conversation.
      * Returns undefined if no system instruction is set.
      */
     getSystemInstruction() {
-        return this._data.conversations?.[this._conversationId]?.systemInstruction;
+        return this._conversations[this._conversationId]?.systemInstruction;
     }
     /**
      * Set the system instruction for the current conversation.
@@ -521,21 +583,20 @@ export class RoolSpace extends EventEmitter {
      */
     async setSystemInstruction(instruction) {
         // Optimistic local update
-        if (!this._data.conversations) {
-            this._data.conversations = {};
-        }
-        if (!this._data.conversations[this._conversationId]) {
-            this._data.conversations[this._conversationId] = {
+        if (!this._conversations[this._conversationId]) {
+            this._conversations[this._conversationId] = {
                 createdAt: Date.now(),
                 createdBy: this._userId,
                 interactions: [],
             };
         }
+        const previous = this._conversations[this._conversationId];
         if (instruction === null) {
-            delete this._data.conversations[this._conversationId].systemInstruction;
+            const { systemInstruction: _, ...rest } = this._conversations[this._conversationId];
+            this._conversations[this._conversationId] = rest;
         }
         else {
-            this._data.conversations[this._conversationId].systemInstruction = instruction;
+            this._conversations[this._conversationId] = { ...this._conversations[this._conversationId], systemInstruction: instruction };
         }
         // Emit event
         this.emit('conversationUpdated', {
@@ -548,7 +609,7 @@ export class RoolSpace extends EventEmitter {
         }
         catch (error) {
             this.logger.error('[RoolSpace] Failed to set system instruction:', error);
-            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            this._conversations[this._conversationId] = previous;
             throw error;
         }
     }
@@ -560,29 +621,25 @@ export class RoolSpace extends EventEmitter {
      * Metadata is stored in meta and hidden from AI operations.
      */
     setMetadata(key, value) {
-        if (!this._data.meta) {
-            this._data.meta = {};
-        }
-        this._data.meta[key] = value;
-        this.emit('metadataUpdated', { metadata: this._data.meta, source: 'local_user' });
-        // Fire-and-forget server call - errors trigger resync
-        this.graphqlClient.setSpaceMeta(this.id, this._data.meta, this._conversationId)
+        this._meta[key] = value;
+        this.emit('metadataUpdated', { metadata: this._meta, source: 'local_user' });
+        // Fire-and-forget server call
+        this.graphqlClient.setSpaceMeta(this.id, this._meta, this._conversationId)
             .catch((error) => {
             this.logger.error('[RoolSpace] Failed to set meta:', error);
-            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
         });
     }
     /**
      * Get a space-level metadata value.
      */
     getMetadata(key) {
-        return this._data.meta?.[key];
+        return this._meta[key];
     }
     /**
      * Get all space-level metadata.
      */
     getAllMetadata() {
-        return this._data.meta ?? {};
+        return this._meta;
     }
     // ===========================================================================
     // AI Operations
@@ -599,10 +656,28 @@ export class RoolSpace extends EventEmitter {
             attachmentUrls = await Promise.all(attachments.map(file => this.mediaClient.upload(this._id, file)));
         }
         const result = await this.graphqlClient.prompt(this._id, prompt, this._conversationId, { ...rest, attachmentUrls });
-        // Hydrate modified object IDs to actual objects (filter out deleted ones)
-        const objects = result.modifiedObjectIds
-            .map(id => this._data.objects[id]?.data)
-            .filter((obj) => obj !== undefined);
+        // Collect modified objects — they arrive via SSE events during/after the mutation.
+        // Try collecting from buffer first, then fetch any missing from server.
+        const objects = [];
+        const missing = [];
+        for (const id of result.modifiedObjectIds) {
+            const buffered = this._objectBuffer.get(id);
+            if (buffered) {
+                this._objectBuffer.delete(id);
+                objects.push(buffered);
+            }
+            else {
+                missing.push(id);
+            }
+        }
+        // Fetch any objects not yet received via SSE
+        if (missing.length > 0) {
+            const fetched = await Promise.all(missing.map(id => this.graphqlClient.getObject(this._id, id)));
+            for (const obj of fetched) {
+                if (obj)
+                    objects.push(obj);
+            }
+        }
         return {
             message: result.message,
             objects,
@@ -676,13 +751,6 @@ export class RoolSpace extends EventEmitter {
     // ===========================================================================
     // Low-level Operations
     // ===========================================================================
-    /**
-     * Get the full space data.
-     * Use sparingly - prefer specific operations.
-     */
-    getData() {
-        return this._data;
-    }
     // ===========================================================================
     // Import/Export
     // ===========================================================================
@@ -696,6 +764,64 @@ export class RoolSpace extends EventEmitter {
         return this.mediaClient.exportArchive(this._id);
     }
     // ===========================================================================
+    // Object Collection (internal)
+    // ===========================================================================
+    /**
+     * Register a collector that resolves when the object arrives via SSE.
+     * If the object is already in the buffer (arrived before collector), resolves immediately.
+     * @internal
+     */
+    _collectObject(objectId) {
+        return new Promise((resolve, reject) => {
+            // Check buffer first — SSE event may have arrived before the HTTP response
+            const buffered = this._objectBuffer.get(objectId);
+            if (buffered) {
+                this._objectBuffer.delete(objectId);
+                resolve(buffered);
+                return;
+            }
+            const timer = setTimeout(() => {
+                this._objectResolvers.delete(objectId);
+                // Fallback: try to fetch from server
+                this.graphqlClient.getObject(this._id, objectId).then(obj => {
+                    if (obj) {
+                        resolve(obj);
+                    }
+                    else {
+                        reject(new Error(`Timeout waiting for object ${objectId} from SSE`));
+                    }
+                }).catch(reject);
+            }, OBJECT_COLLECT_TIMEOUT);
+            this._objectResolvers.set(objectId, (obj) => {
+                clearTimeout(timer);
+                resolve(obj);
+            });
+        });
+    }
+    /**
+     * Cancel a pending object collector (e.g., on mutation error).
+     * @internal
+     */
+    _cancelCollector(objectId) {
+        this._objectResolvers.delete(objectId);
+        this._objectBuffer.delete(objectId);
+    }
+    /**
+     * Deliver an object to a pending collector, or buffer it for later collection.
+     * @internal
+     */
+    _deliverObject(objectId, object) {
+        const resolver = this._objectResolvers.get(objectId);
+        if (resolver) {
+            resolver(object);
+            this._objectResolvers.delete(objectId);
+        }
+        else {
+            // Buffer for prompt() or late collectors
+            this._objectBuffer.set(objectId, object);
+        }
+    }
+    // ===========================================================================
     // Event Handlers (internal - handles space subscription events)
     // ===========================================================================
     /**
@@ -706,187 +832,142 @@ export class RoolSpace extends EventEmitter {
         // Ignore events after close - the space is being torn down
         if (this._closed)
             return;
+        const changeSource = event.source === 'agent' ? 'remote_agent' : 'remote_user';
         switch (event.type) {
-            case 'space_patched':
-                if (event.patch) {
-                    this.handleRemotePatch(event.patch, event.source);
+            case 'object_created':
+                if (event.objectId && event.object) {
+                    this._handleObjectCreated(event.objectId, event.object, changeSource);
+                }
+                break;
+            case 'object_updated':
+                if (event.objectId && event.object) {
+                    this._handleObjectUpdated(event.objectId, event.object, changeSource);
+                }
+                break;
+            case 'object_deleted':
+                if (event.objectId) {
+                    this._handleObjectDeleted(event.objectId, changeSource);
+                }
+                break;
+            case 'schema_updated':
+                if (event.schema) {
+                    this._schema = event.schema;
+                }
+                break;
+            case 'metadata_updated':
+                if (event.metadata) {
+                    this._meta = event.metadata;
+                    this.emit('metadataUpdated', { metadata: this._meta, source: changeSource });
+                }
+                break;
+            case 'conversation_updated':
+                if (event.conversationId && event.conversation) {
+                    this._conversations[event.conversationId] = event.conversation;
+                    this.emit('conversationUpdated', { conversationId: event.conversationId, source: changeSource });
+                    // Emit conversationsChanged if this is a new conversation
+                    this.emit('conversationsChanged', {
+                        action: 'created',
+                        conversationId: event.conversationId,
+                        name: event.conversation.name,
+                        source: changeSource,
+                    });
+                }
+                break;
+            case 'conversation_deleted':
+                if (event.conversationId) {
+                    delete this._conversations[event.conversationId];
+                    this.emit('conversationUpdated', { conversationId: event.conversationId, source: changeSource });
+                    this.emit('conversationsChanged', {
+                        action: 'deleted',
+                        conversationId: event.conversationId,
+                        source: changeSource,
+                    });
                 }
                 break;
             case 'space_changed':
-                // Full reload needed
+                // Full reload needed (undo/redo, bulk operations)
                 void this.graphqlClient.getSpace(this._id).then(({ data }) => {
-                    this._data = data;
-                    this.emit('reset', { source: 'remote_user' });
+                    if (this._closed)
+                        return;
+                    this._meta = data.meta ?? {};
+                    this._schema = data.schema ?? {};
+                    this._conversations = data.conversations ?? {};
+                    this._objectIds = data.objectIds ?? [];
+                    this.emit('reset', { source: changeSource });
                 });
                 break;
         }
     }
     /**
-     * Check if a patch would actually change the current data.
-     * Used to deduplicate events when patches don't change anything (e.g., optimistic updates).
+     * Handle an object_created SSE event.
+     * Deduplicates against optimistic local creates.
      * @internal
      */
-    didPatchChangeAnything(patch) {
-        for (const op of patch) {
-            const pathParts = op.path.split('/').filter(p => p);
-            let current = this._data;
-            for (const part of pathParts) {
-                current = current?.[part];
+    _handleObjectCreated(objectId, object, source) {
+        // Deliver to any pending collector (for mutation return values)
+        this._deliverObject(objectId, object);
+        // Maintain local ID list — prepend (most recently modified first)
+        this._objectIds = [objectId, ...this._objectIds.filter(id => id !== objectId)];
+        const pending = this._pendingMutations.get(objectId);
+        if (pending !== undefined) {
+            // This is our own mutation echoed back
+            this._pendingMutations.delete(objectId);
+            if (pending !== null) {
+                // It was a create — already emitted objectCreated optimistically.
+                // Emit objectUpdated only if AI resolved placeholders (data changed).
+                if (JSON.stringify(pending) !== JSON.stringify(object)) {
+                    this.emit('objectUpdated', { objectId, object, source });
+                }
             }
-            if (op.op === 'remove' && current !== undefined)
-                return true;
-            if ((op.op === 'add' || op.op === 'replace') &&
-                JSON.stringify(current) !== JSON.stringify(op.value))
-                return true;
         }
-        return false;
+        else {
+            // Remote event — emit normally
+            this.emit('objectCreated', { objectId, object, source });
+        }
     }
     /**
-     * Handle a patch event from another client.
-     * Checks for version gaps to detect missed patches.
+     * Handle an object_updated SSE event.
+     * Deduplicates against optimistic local updates.
      * @internal
      */
-    handleRemotePatch(patch, source) {
-        // Extract the new version from the patch
-        const versionOp = patch.find(op => op.path === '/version' && (op.op === 'add' || op.op === 'replace'));
-        if (versionOp) {
-            const incomingVersion = versionOp.value;
-            const currentVersion = this._data.version ?? 0;
-            const expectedVersion = currentVersion + 1;
-            // Check for version gap (missed patches)
-            if (incomingVersion > expectedVersion) {
-                this.logger.warn(`[RoolSpace] Version gap detected: expected ${expectedVersion}, got ${incomingVersion}. Resyncing.`);
-                this.resyncFromServer(new Error(`Version gap: expected ${expectedVersion}, got ${incomingVersion}`))
-                    .catch(() => { });
-                return;
-            }
-            // Skip stale patches (version <= current, already applied)
-            if (incomingVersion <= currentVersion) {
-                return;
+    _handleObjectUpdated(objectId, object, source) {
+        // Deliver to any pending collector
+        this._deliverObject(objectId, object);
+        // Maintain local ID list — move to front (most recently modified)
+        this._objectIds = [objectId, ...this._objectIds.filter(id => id !== objectId)];
+        const pending = this._pendingMutations.get(objectId);
+        if (pending !== undefined) {
+            // This is our own mutation echoed back
+            this._pendingMutations.delete(objectId);
+            if (pending !== null) {
+                // Already emitted objectUpdated optimistically.
+                // Emit again only if data changed (AI resolved placeholders).
+                if (JSON.stringify(pending) !== JSON.stringify(object)) {
+                    this.emit('objectUpdated', { objectId, object, source });
+                }
             }
         }
-        // Check if patch would change anything BEFORE applying
-        const willChange = this.didPatchChangeAnything(patch);
-        try {
-            this._data = immutableJSONPatch(this._data, patch);
-        }
-        catch (error) {
-            this.logger.error('[RoolSpace] Failed to apply remote patch:', error);
-            // Force resync on patch error
-            this.resyncFromServer(error instanceof Error ? error : new Error(String(error))).catch(() => { });
-            return;
-        }
-        // Only emit events if something actually changed
-        if (willChange) {
-            const changeSource = source === 'agent' ? 'remote_agent' : 'remote_user';
-            this.emitSemanticEventsFromPatch(patch, changeSource);
+        else {
+            // Remote event
+            this.emit('objectUpdated', { objectId, object, source });
         }
     }
     /**
-     * Parse JSON patch operations and emit semantic events.
+     * Handle an object_deleted SSE event.
+     * Deduplicates against optimistic local deletes.
      * @internal
      */
-    emitSemanticEventsFromPatch(patch, source) {
-        // Track which objects have been updated (to avoid duplicate events)
-        const updatedObjects = new Set();
-        for (const op of patch) {
-            const { path } = op;
-            // Object operations: /objects/{objectId}/...
-            if (path.startsWith('/objects/')) {
-                const parts = path.split('/');
-                const objectId = parts[2];
-                if (parts.length === 3) {
-                    // /objects/{objectId} - full object add or remove
-                    if (op.op === 'add') {
-                        const entry = this._data.objects[objectId];
-                        if (entry) {
-                            this.emit('objectCreated', { objectId, object: entry.data, source });
-                        }
-                    }
-                    else if (op.op === 'remove') {
-                        this.emit('objectDeleted', { objectId, source });
-                    }
-                }
-                else if (parts[3] === 'data') {
-                    // /objects/{objectId}/data/... - data field update
-                    if (!updatedObjects.has(objectId)) {
-                        const entry = this._data.objects[objectId];
-                        if (entry) {
-                            this.emit('objectUpdated', { objectId, object: entry.data, source });
-                            updatedObjects.add(objectId);
-                        }
-                    }
-                }
-            }
-            else if (path === '/meta' || path.startsWith('/meta/')) {
-                this.emit('metadataUpdated', { metadata: this._data.meta, source });
-            }
-            // Conversation operations: /conversations/{conversationId} or /conversations/{conversationId}/...
-            else if (path.startsWith('/conversations/')) {
-                const parts = path.split('/');
-                const conversationId = parts[2];
-                if (conversationId) {
-                    this.emit('conversationUpdated', { conversationId, source });
-                    // Emit conversationsChanged for list-level changes
-                    if (parts.length === 3) {
-                        // /conversations/{conversationId} - full conversation add or remove
-                        if (op.op === 'add') {
-                            const conv = this._data.conversations?.[conversationId];
-                            this.emit('conversationsChanged', {
-                                action: 'created',
-                                conversationId,
-                                name: conv?.name,
-                                source,
-                            });
-                        }
-                        else if (op.op === 'remove') {
-                            this.emit('conversationsChanged', {
-                                action: 'deleted',
-                                conversationId,
-                                source,
-                            });
-                        }
-                    }
-                    else if (parts[3] === 'name') {
-                        // /conversations/{conversationId}/name - rename
-                        const conv = this._data.conversations?.[conversationId];
-                        this.emit('conversationsChanged', {
-                            action: 'renamed',
-                            conversationId,
-                            name: conv?.name,
-                            source,
-                        });
-                    }
-                }
-            }
+    _handleObjectDeleted(objectId, source) {
+        // Remove from local ID list
+        this._objectIds = this._objectIds.filter(id => id !== objectId);
+        const pending = this._pendingMutations.get(objectId);
+        if (pending !== undefined) {
+            // This is our own delete echoed back — already emitted
+            this._pendingMutations.delete(objectId);
         }
-    }
-    // ===========================================================================
-    // Private Methods
-    // ===========================================================================
-    async resyncFromServer(originalError) {
-        this.logger.warn('[RoolSpace] Resyncing from server after sync failure');
-        try {
-            const { data } = await this.graphqlClient.getSpace(this._id);
-            // Check again after await - space might have been closed during fetch
-            if (this._closed)
-                return;
-            this._data = data;
-            // Clear history is now async but we don't need to wait for it during resync
-            // (it's a server-side cleanup that can happen in background)
-            this.clearHistory().catch((err) => {
-                this.logger.warn('[RoolSpace] Failed to clear history during resync:', err);
-            });
-            this.emit('syncError', originalError ?? new Error('Sync failed'));
-            this.emit('reset', { source: 'system' });
-        }
-        catch (error) {
-            // If space was closed during fetch, don't log error - expected during teardown
-            if (this._closed)
-                return;
-            this.logger.error('[RoolSpace] Failed to resync from server:', error);
-            // Still emit syncError with the original error
-            this.emit('syncError', originalError ?? new Error('Sync failed'));
+        else {
+            // Remote event
+            this.emit('objectDeleted', { objectId, source });
         }
     }
 }