@rool-dev/sdk 0.10.2-dev.47747e3 → 0.10.2-dev.550002

package/README.md

@@ -2,8 +2,6 @@
 
 The TypeScript SDK for Rool, a persistent and collaborative environment for organizing objects.
 
-> **Building a new Rool extension?** Start with [`@rool-dev/extension`](/extension/) — it handles hosting, dev server, and gives you a reactive Svelte channel out of the box. This SDK is for advanced use cases: integrating Rool into an existing application, building Node.js scripts, or working outside the extension sandbox.
-
 The SDK manages authentication, real-time synchronization, and per-space file storage. Core primitives:
 
 - **Spaces** — Containers for objects, schema, metadata, channels, and files
@@ -65,10 +63,9 @@ const { message, objects } = await channel.prompt(
 console.log(message);  // AI explains what it did
 console.log(`Modified ${objects.length} objects`);
 
-// Query with natural language
-const { objects: innerPlanets } = await channel.findObjects({
-  prompt: 'planets closer to the sun than Earth'
-});
+// Read an object by location
+const loadedEarth = await channel.getObject(earth.location);
+console.log(loadedEarth?.body.name);
 
 // Clean up
 channel.close();
@@ -229,7 +226,7 @@ References are just data — no special API is needed to create or remove them.
 #### Location helpers
 
 ```typescript
-import { loc, parseLocation, normalizeLocation, generateBasename } from '@rool-dev/sdk';
+import { loc, parseLocation, normalizeLocation } from '@rool-dev/sdk';
 
 loc('article', 'welcome');                  // '/space/article/welcome.json'
 parseLocation('/space/article/welcome.json'); // { collection: 'article', basename: 'welcome' }
@@ -237,9 +234,6 @@ parseLocation('/space/article/welcome.json'); // { collection: 'article', basena
 // normalizeLocation accepts canonical or short form and returns canonical
 normalizeLocation('article/welcome');         // '/space/article/welcome.json'
 normalizeLocation('/space/article/welcome.json'); // unchanged
-
-// 6-char random basename — same generator the SDK uses by default
-generateBasename();                           // e.g., 'X7kQ9p'
 ```
 
 SDK methods that accept a location (`getObject`, `updateObject`, `deleteObjects`, `moveObject`, etc.) accept either form and normalize internally. SDK return values always use the canonical full form.
@@ -320,24 +314,24 @@ await channel.createObject('article', {
 
 ### Real-time Sync
 
-Events fire for both local and remote changes. The `source` field indicates origin:
-
-- `local_user` — This client made the change
-- `remote_user` — Another user/client made the change
-- `remote_agent` — AI agent made the change
-- `system` — Resync after error
+Object and file reactivity is WebDAV-based. Listen for space-level file change notifications, then reconcile with `webdav.syncCollection()` using your sync token. This covers both object files under `/space` and user files under `/rool-drive`.
 
 ```typescript
-// All UI updates happen in one place, regardless of change source
-channel.on('objectUpdated', ({ location, object, source }) => {
-  renderObject(location, object);
-  if (source === 'remote_agent') {
-    doLayout(); // AI might have added content
-  }
-});
+let token: string | null = null;
 
-// Caller just makes the change - event handler does the UI work
-channel.updateObject(location, { prompt: 'expand this' });
+async function syncFiles() {
+  const result = await space.webdav.syncCollection('/', {
+    token,
+    level: 'infinite',
+    props: ['displayname', 'getetag', 'getlastmodified', 'resourcetype'],
+  });
+  token = result.token;
+  updateFileTree(result.responses);
+}
+
+space.on('filesChanged', syncFiles);
+space.on('filesReset', () => { token = null; syncFiles(); });
+await syncFiles();
 ```
 
 ### Locations & Basenames
@@ -358,7 +352,7 @@ await channel.createObject('article',
 
 ```typescript
 // Fire-and-forget: create and reference without waiting
-const basename = RoolClient.generateBasename();
+const basename = 'idea-seed';
 const location = loc('note', basename);
 
 channel.createObject('note', { text: '{{expand this idea}}' }, { basename });
@@ -574,7 +568,7 @@ await space.addUser(user.id, 'editor');
 | `owner` | Full control, can delete space and manage all users |
 | `admin` | All editor capabilities, plus can manage users (except other admins/owners) |
 | `editor` | Can create, modify, move, and delete objects |
-| `viewer` | Read-only access (can query with `prompt` and `findObjects`) |
+| `viewer` | Read-only access (can query with `prompt` and read objects/files) |
 
 ### Space Collaboration Methods
 
@@ -621,18 +615,9 @@ When a user accesses a space via URL, they're granted the corresponding role (`v
 
 ### Real-time Collaboration
 
-When multiple users have a space open, changes sync in real-time. The `source` field in events tells you who made the change:
-
-```typescript
-channel.on('objectUpdated', ({ location, object, source }) => {
-  if (source === 'remote_user') {
-    // Another user made this change
-    showCollaboratorActivity(object);
-  }
-});
-```
+When multiple users have a space open, object and file changes are announced by `space.on('filesChanged')` and reconciled through WebDAV `syncCollection()`. Channel/conversation state still emits channel events; filesystem state does not use channel object events.
 
-See [Real-time Sync](#real-time-sync) for more on event sources.
+See [Real-time Sync](#real-time-sync) for a WebDAV sync-token example.
 
 ## RoolClient API
 
@@ -663,8 +648,6 @@ const client = new RoolClient({
 | `duplicateSpace(sourceSpaceId, name): Promise<RoolSpace>` | Duplicate an existing space. Returns a handle to the new space. |
 | `deleteSpace(id): Promise<void>` | Permanently delete a space (cannot be undone) |
 | `importArchive(name, archive): Promise<RoolSpace>` | Import from a zip archive, creating a new space |
-| `webdav(spaceId): RoolWebDAV` | Open a WebDAV client for a space's file storage |
-| `getSpaceStorageUsage(spaceId): Promise<SpaceFileStorageUsage>` | Get WebDAV quota usage for a space |
 
 ### Channel Management
 
@@ -673,7 +656,6 @@ Manage channels on the `RoolSpace` handle:
 | Method | Description |
 |--------|-------------|
 | `space.channels: ChannelInfo[]` | Live channel list (auto-updates via SSE) |
-| `space.getChannels(): ChannelInfo[]` | List channels (deprecated — use `space.channels` instead) |
 | `space.renameChannel(channelId, name): Promise<void>` | Rename a channel |
 | `space.deleteChannel(channelId): Promise<void>` | Delete a channel and its interaction history |
 | `channel.rename(name): Promise<void>` | Rename the current open channel |
@@ -717,39 +699,11 @@ client.on('userStorageChanged', ({ key, value, source }) => {
 });
 ```
 
-### Extensions
-
-Manage and publish extensions. See [`@rool-dev/extension`](/extension/) for building extensions.
-
-There are two distinct domains: your **personal library** (extensions you've created or installed) and the **published extensions** (extensions discoverable by all users). Each has its own return type.
-
-#### Your Library (`ExtensionInfo`)
-
-Manage extensions you own. Each `ExtensionInfo` includes `published` (whether it's listed in the marketplace) and `marketplaceExtensionId` (non-null if you installed it from someone else's listing, null if you authored it).
-
-| Method | Description |
-|--------|-------------|
-| `uploadExtension(extensionId, options): Promise<ExtensionInfo>` | Upload or update an extension (`options.bundle`: zip with `index.html` and `manifest.json`) |
-| `listExtensions(): Promise<ExtensionInfo[]>` | List your extensions |
-| `getExtensionInfo(extensionId): Promise<ExtensionInfo \| null>` | Get info for a specific extension |
-| `deleteExtension(extensionId): Promise<void>` | Delete an extension permanently (removes files and DB row) |
-
-#### Marketplace (`PublishedExtensionInfo`)
-
-Discover and install extensions published by other users.
-
-| Method | Description |
-|--------|-------------|
-| `findExtensions(options?): Promise<PublishedExtensionInfo[]>` | Search the marketplace. Options: `query` (semantic search string), `limit` (default 20, max 100). Omit `query` to browse all. |
-| `publishToPublic(extensionId): Promise<void>` | Publish one of your extensions to the marketplace |
-| `unpublishFromPublic(extensionId): Promise<void>` | Remove from the marketplace (keeps the extension in your library) |
-
 ### Utilities
 
 | Method | Description |
 |--------|-------------|
-| `RoolClient.generateBasename(): string` | Generate a 6-char alphanumeric basename for new object identities. |
-| `RoolClient.generateId(): string` | Same as `generateBasename()`; retained for callers minting non-object IDs (interactions, conversations, channels). |
+| `RoolClient.generateId(): string` | Generate a unique 6-character alphanumeric ID. |
 | `destroy(): void` | Clean up resources |
 
 ### Client Events
@@ -811,10 +765,8 @@ A space handle with a live SSE subscription. Extends `EventEmitter`. Manages use
 | `addUser(userId, role): Promise<void>` | Add user to space |
 | `removeUser(userId): Promise<void>` | Remove user from space |
 | `setLinkAccess(linkAccess): Promise<void>` | Set URL sharing level |
-| `getChannels(): ChannelInfo[]` | List channels (deprecated — use `channels` property instead) |
 | `renameChannel(channelId, name): Promise<void>` | Rename a channel |
 | `deleteChannel(channelId): Promise<void>` | Delete a channel |
-| `installExtension(extensionId, channelId): Promise<string>` | Install an extension into a channel of this space. If you own it, wires it directly. If it's a marketplace extension, copies and builds a new extension in your library. Returns the channel ID. |
 | `exportArchive(): Promise<Blob>` | Export space as zip archive |
 | `getStorageUsage(): Promise<SpaceFileStorageUsage>` | Get WebDAV quota usage for this space |
 | `fetchMachineResource(resource): Promise<Response>` | Fetch a resolved file `MachineResource` through this space |
@@ -824,7 +776,7 @@ A space handle with a live SSE subscription. Extends `EventEmitter`. Manages use
 
 ```typescript
 space.on('channelCreated', (channel: ChannelInfo) => void)   // New channel added
-space.on('channelUpdated', (channel: ChannelInfo) => void)   // Channel metadata changed (name, extension, manifest)
+space.on('channelUpdated', (channel: ChannelInfo) => void)   // Channel metadata changed
 space.on('channelDeleted', (channelId: string) => void)      // Channel removed
 space.on('filesChanged', ({ source, timestamp }) => void)     // WebDAV file storage changed; call webdav.syncCollection()
 space.on('connectionStateChanged', (state: 'connected' | 'disconnected' | 'reconnecting') => void)
@@ -845,9 +797,6 @@ A channel is a named context within a space. All object operations, AI prompts,
 | `userId: string` | Current user's ID |
 | `channelId: string` | Channel ID (read-only, fixed at open time) |
 | `isReadOnly: boolean` | True if viewer role |
-| `extensionUrl: string \| null` | URL of the installed extension, or null if this is a plain channel |
-| `extensionId: string \| null` | ID of the installed extension, or null if this is a plain channel |
-| `manifest: ExtensionManifest \| null` | Extension manifest snapshot (name, icon, collections, etc.), or null |
 
 ### Lifecycle
 
@@ -867,8 +816,6 @@ All methods that accept a location accept either the canonical form or the short
 |--------|-------------|
 | `getObject(location): Promise<RoolObject \| undefined>` | Get an object, or undefined if not found. |
 | `stat(location): RoolObjectStat \| undefined` | Get audit info for an object: when it was last modified, by whom, and where (channel/conversation/interaction). Sync read from local cache. |
-| `findObjects(options): Promise<{ objects, message }>` | Find objects using structured filters and/or natural language. Results sorted by modifiedAt (desc by default). |
-| `getObjectLocations(options?): string[]` | Get all object locations. Sorted by modifiedAt (desc by default). Options: `{ limit?, order? }`. |
 | `createObject(collection, body, options?): Promise<{ object, message }>` | Create a new object in `collection`. The SDK mints a random basename unless you pass `options.basename`. |
 | `updateObject(location, options): Promise<{ object, message }>` | Update an existing object's body. |
 | `moveObject(from, to, options?): Promise<{ object, message }>` | Rename or relocate an object. See [Moving and Renaming](#moving-and-renaming). |
@@ -961,59 +908,6 @@ await channel.moveObject(from, to, {
 | `ephemeral` | If true, the operation won't be recorded in interaction history. |
 | `parentInteractionId` | Conversation tree parent. Omit to auto-continue; pass `null` for a new root. |
 
-#### findObjects
-
-Find objects using structured filters and/or natural language.
-
-- **`where` only** — exact-match filtering, no AI, no credits.
-- **`collection` only** — filter by collection name, no AI, no credits.
-- **`prompt` only** — AI-powered semantic query over all objects.
-- **`where` + `prompt`** — `where` (and `locations`) narrow the data set first, then the AI queries within the constrained set.
-
-| Option | Description |
-|--------|-------------|
-| `where` | Exact-match body-field filter (e.g. `{ status: 'published' }`). Values must match literally — no operators or `{{placeholders}}`. When combined with `prompt`, constrains which objects the AI can see. |
-| `collection` | Filter by collection name. |
-| `prompt` | Natural language query. Triggers AI evaluation (uses credits). |
-| `limit` | Maximum number of results. |
-| `locations` | Scope to specific object locations. Constrains the candidate set in both structured and AI queries. |
-| `order` | Sort order by modifiedAt: `'asc'` or `'desc'` (default: `'desc'`). |
-| `ephemeral` | If true, the query won't be recorded in interaction history. Useful for responsive search. |
-
-**Examples:**
-
-```typescript
-// Filter by collection (no AI, no credits)
-const { objects } = await channel.findObjects({
-  collection: 'article'
-});
-
-// Exact field matching (no AI, no credits)
-const { objects } = await channel.findObjects({
-  where: { status: 'published' }
-});
-
-// Combine collection and field filters
-const { objects } = await channel.findObjects({
-  collection: 'article',
-  where: { status: 'published' }
-});
-
-// Pure natural language query (AI interprets)
-const { objects, message } = await channel.findObjects({
-  prompt: 'articles about space exploration published this year'
-});
-
-// Combined: collection + where narrow the data, prompt queries within it
-const { objects } = await channel.findObjects({
-  collection: 'article',
-  prompt: 'that discuss climate solutions positively',
-  limit: 10
-});
-```
-
-When `where` or `locations` are provided with a `prompt`, the AI only sees the filtered subset — not the full space. The returned `message` explains the query result.
-
 ### Undo/Redo
 
 | Method | Description |
@@ -1041,12 +935,13 @@ Store arbitrary data alongside the space without it being part of an object's bo
 
 Every space has authenticated file storage. WebDAV is the SDK surface for that storage: paths are relative to the space root and collection operations use WebDAV collection semantics. Human/AI file links use `rool-machine:/rool-drive/...`; resolve those links with `resolveMachineResource()` and fetch file resources with `space.fetchMachineResource(resource)`.
 
-Use `client.webdav(spaceId)` when you only have an ID, or `space.webdav` when you already have an open space.
+Open a space, then use `space.webdav`.
 
 ```typescript
 import { resolveMachineResource } from '@rool-dev/sdk';
 
-const webdav = client.webdav('space-id');
+const space = await client.openSpace('space-id');
+const webdav = space.webdav;
 
 await webdav.mkcol('docs');
 await webdav.put('docs/readme.md', '# Hello', {
@@ -1091,8 +986,6 @@ Paths are space-relative (`docs/readme.md`, not `/docs/readme.md`). WebDAV metho
 
 | Method | Description |
 |--------|-------------|
-| `client.webdav(spaceId)` | Create a WebDAV client for a space |
-| `client.getSpaceStorageUsage(spaceId)` | Get WebDAV quota usage for a space |
 | `space.webdav` | WebDAV client for an open space |
 | `space.getStorageUsage()` | Get WebDAV quota usage for an open space |
 | `webdav.getStorageUsage()` | Get WebDAV quota usage through the WebDAV client |
@@ -1225,37 +1118,23 @@ The archive bundles `data.json` (objects, metadata, and channels) together with
 
 ### Channel Events
 
-Semantic events describe what changed. Events fire for both local changes and remote changes.
+Channel events are for channel/conversation state. Object and file reactivity goes through `space.on('filesChanged' | 'filesReset')` plus WebDAV `syncCollection()`.
 
 ```typescript
-// source indicates origin:
-// - 'local_user': This client made the change
-// - 'remote_user': Another user/client made the change
-// - 'remote_agent': AI agent made the change
-// - 'system': Resync after error
-
-// Object events — payload includes the full RoolObject
-channel.on('objectCreated', ({ location, object, source }) => void)
-channel.on('objectUpdated', ({ location, object, source }) => void)
-channel.on('objectDeleted', ({ location, source }) => void)
-channel.on('objectMoved',   ({ from, to, object, source }) => void)
-
-// Space metadata
-channel.on('metadataUpdated', ({ metadata, source }) => void)
-
-// Collection schema changed
-channel.on('schemaUpdated', ({ schema, source }) => void)
-
-// Channel metadata updated (name, extensionUrl)
+// Channel metadata updated
 channel.on('channelUpdated', ({ channelId, source }) => void)
 
 // Conversation interaction history updated
 channel.on('conversationUpdated', ({ conversationId, channelId, source }) => void)
 
+// Space metadata / schema compatibility events
+channel.on('metadataUpdated', ({ metadata, source }) => void)
+channel.on('schemaUpdated', ({ schema, source }) => void)
+
 // Full state replacement (undo/redo, resync after error)
 channel.on('reset', ({ source }) => void)
 
-// Sync error occurred, channel resynced from server
+// Sync error occurred
 channel.on('syncError', (error: Error) => void)
 ```
 
@@ -1386,13 +1265,10 @@ interface Channel {
   createdAt: number;            // Timestamp when channel was created
   createdBy: string;            // User ID who created the channel
   createdByName?: string;       // Display name at time of creation
-  extensionUrl?: string;        // URL of installed extension (set by installExtension)
-  extensionId?: string;         // ID of installed extension (user_extensions.extension_id)
-  manifest?: ExtensionManifest; // Extension manifest snapshot (set when extension is wired)
   conversations: Record<string, Conversation>;  // Keyed by conversation ID
 }
 
-// Channel summary info (returned by client.getChannels)
+// Channel summary info (used by space.channels)
 interface ChannelInfo {
   id: string;
   name: string | null;
@@ -1400,9 +1276,6 @@ interface ChannelInfo {
   createdBy: string;
   createdByName: string | null;
   interactionCount: number;
-  extensionUrl: string | null;  // URL of installed extension, or null
-  extensionId: string | null;   // ID of installed extension, or null
-  manifest: ExtensionManifest | null;  // Extension manifest snapshot, or null
 }
 ```
 

package/dist/channel.d.ts

@@ -1,9 +1,9 @@
 import { EventEmitter } from './event-emitter.js';
 import type { GraphQLClient } from './graphql.js';
 import type { RestClient } from './rest.js';
-import type { RoolWebDAV } from './webdav.js';
+import { type RoolWebDAV } from './webdav.js';
 import type { Logger } from './logger.js';
-import type { RoolObject, RoolObjectStat, ChannelEvents, RoolUserRole, PromptOptions, FindObjectsOptions, CreateObjectOptions, UpdateObjectOptions, MoveObjectOptions, ChannelEvent, Interaction, Channel, ConversationInfo, LinkAccess, SpaceSchema, CollectionDef, FieldDef, ExtensionManifest } from './types.js';
+import type { RoolObject, GetObjectsResult, RoolObjectStat, ChannelEvents, RoolUserRole, PromptOptions, UpdateObjectOptions, MoveObjectOptions, ChannelEvent, Interaction, Channel, ConversationInfo, LinkAccess, SpaceSchema, CollectionDef, FieldDef, CollectionOptions } from './types.js';
 export declare function generateEntityId(): string;
 export interface ChannelConfig {
     id: string;
@@ -12,9 +12,7 @@ export interface ChannelConfig {
     linkAccess: LinkAccess;
     /** Current user's ID (for identifying own interactions) */
     userId: string;
-    /** Object locations in the space (sorted by modifiedAt desc) */
-    objectLocations: string[];
-    /** Object stats keyed by location */
+    /** Object stats keyed by path */
     objectStats: Record<string, RoolObjectStat>;
     /** Collection schema */
     schema: SpaceSchema;
@@ -37,10 +35,10 @@ export interface ChannelConfig {
  * at open time and cannot be changed. To use a different channel,
  * open a second one.
  *
- * Objects are addressed by location (`/space/<collection>/<basename>.json`).
- * Only schema, metadata, the live object location list, and the channel's own
- * history are cached locally. Object bodies are fetched on demand. Changes
- * arrive via SSE semantic events and are emitted as SDK events.
+ * Objects are addressed by machine path (`/space/.../*.json`).
+ * Only schema, metadata, object stats, and the channel's own history are cached
+ * locally. Object bodies are fetched on demand. Object/file reactivity is
+ * exposed at the space level via WebDAV sync notifications.
  */
 export declare class RoolChannel extends EventEmitter<ChannelEvents> {
     private _id;
@@ -59,12 +57,8 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
     private _meta;
     private _schema;
     private _channel;
-    private _objectLocations;
     private _objectStats;
     private _activeLeaves;
-    private _pendingMutations;
-    private _objectResolvers;
-    private _objectBuffer;
     constructor(config: ChannelConfig);
     /**
      * Handle an event from the shared space subscription.
@@ -80,7 +74,6 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
     _applyResyncData(data: {
         meta: Record<string, unknown>;
         schema: SpaceSchema;
-        objectLocations: string[];
         objectStats: Record<string, RoolObjectStat>;
         channel: Channel | undefined;
     }): void;
@@ -105,18 +98,6 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
      */
     get conversationId(): string;
     get isReadOnly(): boolean;
-    /**
-     * Get the extension URL if this channel was created via installExtension, or null.
-     */
-    get extensionUrl(): string | null;
-    /**
-     * Get the extension ID if this channel has an installed extension, or null.
-     */
-    get extensionId(): string | null;
-    /**
-     * Get the extension manifest if this channel has an installed extension, or null.
-     */
-    get manifest(): ExtensionManifest | null;
     /**
      * Get the active branch of the current conversation as a flat array (root → leaf).
      * Walks from the active leaf up through parentId pointers.
@@ -178,83 +159,35 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
     redo(): Promise<boolean>;
     /** Clear the space's checkpoint history. */
     clearHistory(): Promise<void>;
-    /**
-     * Get an object by location. Fetches from the server on each call.
-     *
-     * Accepts either the canonical form (`/space/<collection>/<basename>.json`)
-     * or the short form (`<collection>/<basename>`).
-     */
-    getObject(location: string): Promise<RoolObject | undefined>;
-    /**
-     * Get an object's stat (audit information).
-     * Returns the cached stat or undefined if not known.
-     */
-    stat(location: string): RoolObjectStat | undefined;
-    /**
-     * Find objects using structured filters and/or natural language.
-     */
-    findObjects(options: FindObjectsOptions): Promise<{
-        objects: RoolObject[];
-        message: string;
-    }>;
-    /** @internal */
-    _findObjectsImpl(options: FindObjectsOptions, conversationId: string): Promise<{
-        objects: RoolObject[];
-        message: string;
-    }>;
-    /**
-     * Get all object locations (sync, from local cache).
-     * The list is loaded on open and kept current via SSE events.
-     */
-    getObjectLocations(options?: {
-        limit?: number;
-        order?: 'asc' | 'desc';
-    }): string[];
-    /**
-     * Create a new object in the given collection.
-     *
-     * @param collection - The collection (must exist in the schema)
-     * @param body - Object body fields. Use `{{placeholder}}` for AI-generated content.
-     *               Fields prefixed with `_` are hidden from AI.
-     * @param options.basename - Specific basename to use. If omitted, the SDK generates a random one.
-     * @param options.ephemeral - If true, the operation won't be recorded in interaction history.
-     * @returns The created object and a status message.
-     */
-    createObject(collection: string, body: Record<string, unknown>, options?: CreateObjectOptions): Promise<{
+    private davHeaders;
+    private readObject;
+    /** Get an object JSON file by machine path. Fetches from the server on each call. */
+    getObject(path: string): Promise<RoolObject | undefined>;
+    /** Get object JSON files by machine path in bulk. Duplicate paths are fetched once. */
+    getObjects(paths: string[]): Promise<GetObjectsResult>;
+    /** Get an object's cached audit information. */
+    stat(path: string): RoolObjectStat | undefined;
+    /** Create or replace an object JSON file at an exact machine path. */
+    putObject(path: string, body: Record<string, unknown>): Promise<{
         object: RoolObject;
         message: string;
     }>;
     /** @internal */
-    _createObjectImpl(collection: string, body: Record<string, unknown>, options: CreateObjectOptions | undefined, conversationId: string): Promise<{
+    _putObjectImpl(path: string, body: Record<string, unknown>, conversationId: string): Promise<{
         object: RoolObject;
         message: string;
     }>;
-    /**
-     * Update an existing object.
-     *
-     * @param location - The object's location (canonical or short form)
-     * @param options.data - Fields to add or update. Pass `null` to delete a field. Use `{{placeholder}}` for AI-generated content.
-     * @param options.prompt - AI prompt to drive the update.
-     * @param options.ephemeral - If true, the operation won't be recorded in interaction history.
-     */
-    updateObject(location: string, options: UpdateObjectOptions): Promise<{
+    /** Patch an existing object. Null or undefined deletes a field. */
+    patchObject(path: string, options: UpdateObjectOptions): Promise<{
         object: RoolObject;
         message: string;
     }>;
     /** @internal */
-    _updateObjectImpl(location: string, options: UpdateObjectOptions, conversationId: string): Promise<{
+    _patchObjectImpl(path: string, options: UpdateObjectOptions, conversationId: string): Promise<{
         object: RoolObject;
         message: string;
     }>;
-    /**
-     * Move (rename or relocate) an object to a new location.
-     * Use this to rename, change collection, or atomically rewrite the body.
-     *
-     * @param from - Current location
-     * @param to - New location
-     * @param options.body - Replace the body atomically as part of the move.
-     * @param options.ephemeral - If true, the operation won't be recorded in interaction history.
-     */
+    /** Move an object JSON file to a new machine path, optionally replacing its body. */
     moveObject(from: string, to: string, options?: MoveObjectOptions): Promise<{
         object: RoolObject;
         message: string;
@@ -264,23 +197,22 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
         object: RoolObject;
         message: string;
     }>;
-    /**
-     * Delete objects by location.
-     * Other objects that reference deleted objects will retain stale ref values.
-     */
-    deleteObjects(locations: string[]): Promise<void>;
+    /** Delete object JSON files by machine path. */
+    deleteObjects(paths: string[]): Promise<void>;
+    /** @deprecated Use deleteObjects instead. */
+    deletePaths(paths: string[]): Promise<void>;
     /** @internal */
-    _deleteObjectsImpl(locations: string[], conversationId: string): Promise<void>;
+    _deleteObjectsImpl(paths: string[], conversationId: string): Promise<void>;
     /** Get the current schema for this space. */
     getSchema(): SpaceSchema;
     /** Create a new collection schema. */
-    createCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    createCollection(name: string, fields: FieldDef[] | CollectionDef, options?: CollectionOptions): Promise<CollectionDef>;
     /** @internal */
-    _createCollectionImpl(name: string, fields: FieldDef[], conversationId: string): Promise<CollectionDef>;
+    _createCollectionImpl(name: string, fields: FieldDef[] | CollectionDef, options: CollectionOptions | undefined, conversationId: string): Promise<CollectionDef>;
     /** Alter an existing collection schema, replacing its field definitions. */
-    alterCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    alterCollection(name: string, fields: FieldDef[] | CollectionDef, options?: CollectionOptions): Promise<CollectionDef>;
     /** @internal */
-    _alterCollectionImpl(name: string, fields: FieldDef[], conversationId: string): Promise<CollectionDef>;
+    _alterCollectionImpl(name: string, fields: FieldDef[] | CollectionDef, options: CollectionOptions | undefined, conversationId: string): Promise<CollectionDef>;
     /** Drop a collection schema. */
     dropCollection(name: string): Promise<void>;
     /** @internal */
@@ -334,28 +266,11 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
     }): Promise<Response>;
     private uploadAttachment;
     private ensureCollection;
-    /**
-     * Register a collector that resolves when the object arrives via SSE.
-     * @internal
-     */
-    private _collectObject;
-    /** @internal */
-    private _cancelCollector;
-    /** @internal */
-    private _deliverObject;
     /**
      * Handle a channel event from the subscription.
      * @internal
      */
     private handleChannelEvent;
-    /** @internal */
-    private _handleObjectCreated;
-    /** @internal */
-    private _handleObjectUpdated;
-    /** @internal */
-    private _handleObjectDeleted;
-    /** @internal */
-    private _handleObjectMoved;
 }
 /**
  * A lightweight handle for a specific conversation within a channel.
@@ -382,18 +297,13 @@ export declare class ConversationHandle {
     setSystemInstruction(instruction: string | null): Promise<void>;
     /** Rename this conversation. */
     rename(name: string): Promise<void>;
-    /** Find objects using structured filters and/or natural language. */
-    findObjects(options: FindObjectsOptions): Promise<{
-        objects: RoolObject[];
-        message: string;
-    }>;
-    /** Create a new object. */
-    createObject(collection: string, body: Record<string, unknown>, options?: CreateObjectOptions): Promise<{
+    /** Create or replace an object JSON file. */
+    putObject(path: string, body: Record<string, unknown>): Promise<{
         object: RoolObject;
         message: string;
     }>;
-    /** Update an existing object. */
-    updateObject(location: string, options: UpdateObjectOptions): Promise<{
+    /** Patch an existing object JSON file. */
+    patchObject(path: string, options: UpdateObjectOptions): Promise<{
         object: RoolObject;
         message: string;
     }>;
@@ -402,17 +312,19 @@ export declare class ConversationHandle {
         object: RoolObject;
         message: string;
     }>;
-    /** Delete objects by location. */
-    deleteObjects(locations: string[]): Promise<void>;
+    /** Delete object JSON files by path. */
+    deleteObjects(paths: string[]): Promise<void>;
+    /** @deprecated Use deleteObjects instead. */
+    deletePaths(paths: string[]): Promise<void>;
     /** Send a prompt to the AI agent, scoped to this conversation's history. */
     prompt(text: string, options?: PromptOptions): Promise<{
         message: string;
         objects: RoolObject[];
     }>;
     /** Create a new collection schema. */
-    createCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    createCollection(name: string, fields: FieldDef[] | CollectionDef, options?: CollectionOptions): Promise<CollectionDef>;
     /** Alter an existing collection schema. */
-    alterCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    alterCollection(name: string, fields: FieldDef[] | CollectionDef, options?: CollectionOptions): Promise<CollectionDef>;
     /** Drop a collection schema. */
     dropCollection(name: string): Promise<void>;
     setMetadata(key: string, value: unknown): void;