@xnetjs/data-bridge 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -1,320 +1,12 @@
-import * as _xnetjs_data from '@xnetjs/data';
-import { PropertyBuilder, DefinedSchema, InferCreateProps, NodeState, NodeChangeEvent, ListNodesOptions, NodeStore, SchemaIRI } from '@xnetjs/data';
+import { D as DataBridge, R as RemoteNodeQueryClient, N as NodeQueryRouterThresholds, Q as QueryOptions, a as QuerySubscription, b as QueryDescriptor, B as BridgeTransactionResult, A as AcquiredDoc, c as DataBridgeConfig, S as SyncStatus, d as QueryMetadata, e as QuerySource, f as RemoteNodeQueryMode, g as RemoteNodeQuerySource, h as QueryRoutingMetadata, i as RemoteNodeQueryErrorResponse, j as RemoteNodeQuerySuccessResponse, k as QueryVerificationMetadata } from './types-BRvuTwEn.js';
+export { K as CreateResult, l as QueryCompletenessMetadata, m as QueryExecutionMode, n as QueryMaterializedMetadata, o as QueryMaterializedViewOptions, q as QueryPageCountMode, p as QueryPageInfo, r as QueryPageOptions, s as QuerySearchField, t as QuerySearchFilter, u as QuerySourcePreference, v as QuerySpatialFilter, w as QuerySpatialPoint, x as QuerySpatialPointFields, y as QuerySpatialRadius, z as QuerySpatialRect, C as QuerySpatialRectFields, E as QuerySpatialWindow, H as QueryStalenessMetadata, ac as QueryStreamEvent, F as QueryStreamEventType, G as QueryStreamMetadata, ad as QueryStreamProgress, ae as QueryStreamProgressPhase, af as QueryStreamResetReason, ag as QueryStreamState, ah as QueryStreamStatus, L as REMOTE_NODE_QUERY_PROTOCOL, M as REMOTE_NODE_QUERY_PROTOCOL_VERSION, W as RemoteNodeQueryAuth, X as RemoteNodeQueryClientState, Y as RemoteNodeQueryInvalidation, Z as RemoteNodeQueryInvalidationController, _ as RemoteNodeQueryInvalidationObserver, $ as RemoteNodeQueryInvalidationReason, a0 as RemoteNodeQueryInvalidationSubscription, a1 as RemoteNodeQueryRequest, a2 as RemoteNodeQueryResponse, a3 as RemoteNodeQueryStreamController, a4 as RemoteNodeQueryStreamObserver, a5 as RemoteNodeQueryStreamSubscription, a6 as RemoteQueryCompleteness, a7 as RemoteQueryStaleness, a8 as RemoteQueryVerification, I as SortDirection, J as SystemOrderField, U as UpdateResult, a9 as createQueryStreamState, O as createRemoteNodeQueryRequest, P as isRemoteNodeQueryError, T as isRemoteNodeQuerySource, V as isRemoteNodeQuerySuccess, aa as reduceQueryStreamEvent, ab as reduceQueryStreamEvents } from './types-BRvuTwEn.js';
+import { B as BoundedQueryWorkingSet, W as WorkerQuerySnapshot } from './query-descriptor-D0k2gUQ0.js';
+export { r as BOUNDED_QUERY_OVERFETCH, u as BoundedQueryResultDelta, D as DataWorkerAPI, c as DocUpdateMessage, Q as QueryDelta, t as QueryResultDelta, S as SerializedQueryOptions, b as WorkerAcquiredDoc, a as WorkerConfig, l as applyNodeChangeToBoundedQueryResult, k as applyNodeChangeToQueryResult, i as applyQueryDescriptor, o as createBoundedWorkingSet, p as createBoundedWorkingSetDescriptor, d as createQueryDescriptor, f as decodeQueryCursor, e as encodeQueryCursor, g as filterQueryNodes, m as matchesQueryDescriptor, j as queryDescriptorNeedsBoundedReload, n as queryDescriptorSupportsBoundedDelta, q as queryDescriptorToOptions, s as serializeQueryDescriptor, h as sortQueryNodes } from './query-descriptor-D0k2gUQ0.js';
+import { NodeStore, PropertyBuilder, DefinedSchema, InferCreateProps, NodeState, NodeBatchWriteInput, NodeBatchWriteResult, TransactionOperation, NodeChangeEvent, ListNodesOptions, SchemaIRI, NodeQueryResult } from '@xnetjs/data';
 import { Awareness } from 'y-protocols/awareness';
 import { Doc } from 'yjs';
-
-/**
- * Sort direction for ordering results
- */
-type SortDirection = 'asc' | 'desc';
-/**
- * System fields that can be used for ordering
- */
-type SystemOrderField = 'createdAt' | 'updatedAt';
-/**
- * Options for querying nodes via the DataBridge.
- * Maps to the filter options used by useQuery.
- */
-interface QueryOptions<P extends Record<string, PropertyBuilder> = Record<string, PropertyBuilder>> {
-    /** Filter by single node ID (makes this a single-node query) */
-    nodeId?: string;
-    /** Filter conditions (property: value) */
-    where?: Partial<InferCreateProps<P>>;
-    /** Include soft-deleted nodes */
-    includeDeleted?: boolean;
-    /** Sort by property or system field */
-    orderBy?: {
-        [K in keyof InferCreateProps<P> | SystemOrderField]?: SortDirection;
-    };
-    /** Limit results */
-    limit?: number;
-    /** Offset for pagination */
-    offset?: number;
-}
-/**
- * A subscription to a query result.
- * Compatible with React's useSyncExternalStore pattern.
- *
- * @typeParam P - Property builder type (unused at runtime, for type inference)
- */
-interface QuerySubscription<P extends Record<string, PropertyBuilder> = Record<string, PropertyBuilder>> {
-    /** Get current snapshot (synchronous - reads from cache). Returns null if loading. */
-    getSnapshot(): NodeState[] | null;
-    /** Subscribe to updates (React will call this) */
-    subscribe(callback: () => void): () => void;
-}
-/**
- * Result of a create operation
- */
-interface CreateResult {
-    node: NodeState;
-}
-/**
- * Result of an update operation
- */
-interface UpdateResult {
-    node: NodeState;
-}
-/**
- * Result of acquiring a Y.Doc for editing.
- * The doc is kept in sync with the data thread via the bridge.
- */
-interface AcquiredDoc {
-    /** The Y.Doc instance (on main thread for TipTap binding) */
-    doc: Doc;
-    /** Awareness instance for presence/cursors */
-    awareness: Awareness;
-}
-/**
- * Sync connection status
- */
-type SyncStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
-/**
- * Configuration for initializing a DataBridge
- */
-interface DataBridgeConfig {
-    /** Database name for storage */
-    dbName?: string;
-    /** Author's DID for signing changes */
-    authorDID: string;
-    /** Ed25519 signing key */
-    signingKey: Uint8Array;
-    /** Signaling server URL for sync */
-    signalingUrl?: string;
-}
-/**
- * The DataBridge interface abstracts data access across different platforms.
- *
- * Implementations:
- * - MainThreadBridge: Direct NodeStore access (Phase 0, fallback)
- * - WorkerBridge: Web Worker via Comlink (Phase 1)
- * - IPCBridge: Electron utility process (Phase 2)
- * - NativeBridge: React Native Turbo Module (Phase 5)
- *
- * All implementations provide the same API, allowing React hooks to work
- * identically across all platforms.
- */
-interface DataBridge {
-    /**
-     * Create a subscription to a query result.
-     * Returns an object compatible with useSyncExternalStore.
-     *
-     * The subscription loads data asynchronously and updates the cache.
-     * getSnapshot() returns null while loading, then the result array.
-     */
-    query<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): QuerySubscription<P>;
-    /**
-     * Create a new node.
-     */
-    create<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, data: InferCreateProps<P>, id?: string): Promise<NodeState>;
-    /**
-     * Update an existing node.
-     */
-    update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
-    /**
-     * Soft-delete a node.
-     */
-    delete(nodeId: string): Promise<void>;
-    /**
-     * Restore a soft-deleted node.
-     */
-    restore(nodeId: string): Promise<NodeState>;
-    /**
-     * Acquire a Y.Doc for editing. Returns the doc with current state.
-     * The doc receives updates from the data thread via the bridge.
-     *
-     * Note: Phase 0 (MainThreadBridge) does not implement this method.
-     * It will be implemented in Phase 3 when Y.Doc split architecture is added.
-     */
-    acquireDoc?(nodeId: string): Promise<AcquiredDoc>;
-    /**
-     * Release a Y.Doc when no longer editing.
-     * The data thread continues syncing in the background.
-     *
-     * Note: Phase 0 (MainThreadBridge) does not implement this method.
-     */
-    releaseDoc?(nodeId: string): void;
-    /**
-     * Initialize the bridge with configuration.
-     * For MainThreadBridge, this is a no-op (already initialized with NodeStore).
-     */
-    initialize?(config: DataBridgeConfig): Promise<void>;
-    /**
-     * Clean up resources.
-     */
-    destroy(): void;
-    /**
-     * Current sync status.
-     */
-    readonly status: SyncStatus;
-    /**
-     * Subscribe to status changes.
-     */
-    on(event: 'status', handler: (status: SyncStatus) => void): () => void;
-    /**
-     * Get the underlying NodeStore directly.
-     * Only available in MainThreadBridge for backward compatibility.
-     * Will be removed in later phases.
-     */
-    readonly nodeStore?: _xnetjs_data.NodeStore;
-    /**
-     * Subscribe to store changes directly.
-     * Only available in MainThreadBridge for backward compatibility.
-     */
-    subscribeToChanges?(listener: (event: NodeChangeEvent) => void): () => void;
-    /**
-     * Get a single node by ID directly.
-     * Only available in MainThreadBridge for backward compatibility.
-     */
-    get?(nodeId: string): Promise<NodeState | null>;
-    /**
-     * List nodes with options directly.
-     * Only available in MainThreadBridge for backward compatibility.
-     */
-    list?(options?: ListNodesOptions): Promise<NodeState[]>;
-}
-
-/**
- * Types for worker-main thread communication
- *
- * These types define the contract between the DataWorker running in a
- * Web Worker and the WorkerBridge on the main thread.
- */
-
-/**
- * Result from acquiring a Y.Doc in the worker.
- * The state is sent as a Uint8Array for efficient transfer.
- */
-interface WorkerAcquiredDoc {
-    /** The node ID this doc belongs to */
-    nodeId: string;
-    /** Encoded Y.Doc state (Y.encodeStateAsUpdate) */
-    state: Uint8Array;
-    /** Client ID for this connection */
-    clientId: number;
-}
-/**
- * Document update message from worker to main thread
- */
-interface DocUpdateMessage {
-    type: 'doc-update';
-    nodeId: string;
-    /** Yjs update (Uint8Array) */
-    update: Uint8Array;
-    /** Origin of the update (e.g., 'remote', 'local') */
-    origin: string;
-}
-/**
- * Configuration passed to the worker on initialization
- */
-interface WorkerConfig {
-    /** Database name for IndexedDB */
-    dbName: string;
-    /** Author's DID for signing changes */
-    authorDID: string;
-    /** Ed25519 signing key (serialized as array for transfer) */
-    signingKey: number[];
-}
-/**
- * Serialized query options (sent to worker)
- */
-interface SerializedQueryOptions {
-    nodeId?: string;
-    where?: Record<string, unknown>;
-    includeDeleted?: boolean;
-    orderBy?: Record<string, 'asc' | 'desc'>;
-    limit?: number;
-    offset?: number;
-}
-/**
- * Delta update types for incremental cache updates
- */
-type QueryDelta$1 = {
-    type: 'add';
-    node: NodeState;
-    index: number;
-} | {
-    type: 'remove';
-    nodeId: string;
-} | {
-    type: 'update';
-    nodeId: string;
-    node: NodeState;
-};
-/**
- * The API exposed by the DataWorker via Comlink.
- * This is what WorkerBridge calls on the main thread.
- */
-interface DataWorkerAPI {
-    /**
-     * Initialize the worker with configuration.
-     * Must be called before any other method.
-     */
-    initialize(config: WorkerConfig): Promise<void>;
-    /**
-     * Subscribe to a query. Returns initial results.
-     * Delta updates are sent via the callback.
-     */
-    subscribe(queryId: string, schemaId: string, options: SerializedQueryOptions, onDelta: (delta: QueryDelta$1) => void): Promise<NodeState[]>;
-    /**
-     * Unsubscribe from a query.
-     */
-    unsubscribe(queryId: string): Promise<void>;
-    /**
-     * Create a new node.
-     */
-    create(schemaId: string, data: Record<string, unknown>, id?: string): Promise<NodeState>;
-    /**
-     * Update an existing node.
-     */
-    update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
-    /**
-     * Delete a node (soft delete).
-     */
-    delete(nodeId: string): Promise<void>;
-    /**
-     * Restore a deleted node.
-     */
-    restore(nodeId: string): Promise<NodeState>;
-    /**
-     * Get a single node by ID.
-     */
-    get(nodeId: string): Promise<NodeState | null>;
-    /**
-     * Acquire a Y.Doc for editing.
-     * Returns the current state which should be applied to the main-thread mirror doc.
-     *
-     * @param nodeId - The node ID to acquire
-     * @param onUpdate - Callback for receiving updates from the worker (remote changes)
-     * @returns The initial doc state and client ID
-     */
-    acquireDoc(nodeId: string, onUpdate: (update: Uint8Array, origin: string) => void): Promise<WorkerAcquiredDoc>;
-    /**
-     * Release a Y.Doc when no longer editing.
-     * The doc stays in the pool for background sync.
-     */
-    releaseDoc(nodeId: string): void;
-    /**
-     * Apply a local update from the main-thread mirror doc to the worker's source-of-truth doc.
-     * The worker will broadcast this to the network.
-     *
-     * @param nodeId - The node ID
-     * @param update - The Yjs update (from Y.encodeStateAsUpdate or update event)
-     */
-    applyLocalUpdate(nodeId: string, update: Uint8Array): void;
-    /**
-     * Get current sync status.
-     */
-    getStatus(): SyncStatus;
-    /**
-     * Subscribe to status changes.
-     */
-    onStatusChange(handler: (status: SyncStatus) => void): void;
-    /**
-     * Clean up and close the worker.
-     */
-    destroy(): Promise<void>;
-}
+import { SQLiteAdapter, SQLiteConfig, SQLRow, SQLValue, RunResult, SQLiteNodeBatchApplyInput, SQLiteNodeBatchApplyResult, PreparedStatement } from '@xnetjs/sqlite';
+export { NativeBridge, NativeBridgeConfig, NativeStorageAdapter, createNativeBridge, isExpo, isReactNative } from './native-bridge.js';
 
 /**
  * MainThreadBridge - Direct NodeStore access implementation
@@ -337,6 +29,10 @@ interface SyncManagerLike {
     release(nodeId: string): void;
     getAwareness(nodeId: string): Awareness | null;
 }
+interface MainThreadBridgeOptions {
+    remoteNodeQueryClient?: RemoteNodeQueryClient;
+    remoteNodeQueryRouting?: Partial<NodeQueryRouterThresholds>;
+}
 /**
  * DataBridge implementation that accesses NodeStore directly on the main thread.
  *
@@ -349,26 +45,92 @@ declare class MainThreadBridge implements DataBridge {
     private cache;
     private statusListeners;
     private storeUnsubscribe;
+    private storeBatchUnsubscribe;
     private _syncManager;
-    constructor(store: NodeStore);
+    private remoteNodeQueryClient;
+    private remoteNodeQueryRouting;
+    private remoteLoads;
+    private remoteStreams;
+    private remoteInvalidations;
+    private pendingStoreChanges;
+    private storeChangeFlushQueued;
+    constructor(store: NodeStore, options?: MainThreadBridgeOptions);
     /**
      * Set the SyncManager for Y.Doc acquisition.
      * This is called by XNetProvider after the SyncManager is created.
      */
     setSyncManager(syncManager: SyncManagerLike | null): void;
     query<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): QuerySubscription<P>;
+    private subscribeToQuery;
+    reloadQuery(descriptor: QueryDescriptor): Promise<void>;
+    /**
+     * Load query data according to the descriptor's local/remote execution mode.
+     */
+    private loadInitialQuery;
+    private getQueryRouteRowCount;
+    /**
+     * Load query data from the local store and update cache.
+     */
+    private loadLocalQuery;
+    /**
+     * Load query data from the configured remote query client.
+     */
+    private loadRemoteQuery;
+    private shouldUseRemoteStream;
+    private startRemoteQueryStream;
+    private stopRemoteQueryStream;
+    private normalizeRemoteStreamSubscription;
+    private normalizeRemoteInvalidationSubscription;
+    private normalizeRemoteSubscription;
+    private startRemoteInvalidationSubscription;
+    private stopRemoteInvalidationSubscription;
+    private handleRemoteQueryInvalidation;
+    private getRemoteInvalidationRouteRowCount;
+    private getRemoteInvalidationEntries;
+    private applyRemoteStreamEvent;
+    private normalizeRemoteStreamEvent;
+    private withStreamMetadata;
+    private createStreamErrorMetadata;
+    private executeRemoteQuery;
+    private handleRemoteQueryError;
+    private debugQueryPlan;
     /**
-     * Load query data from the store and update cache.
+     * Handle store changes and invalidate affected caches.
      */
-    private loadQuery;
+    private enqueueStoreChange;
+    private flushStoreChanges;
+    private isBulkStoreChangeSet;
+    private handleStoreChangeSet;
+    private handleStoreBatchChange;
+    private reloadEntriesForSchemas;
+    private applyStoreBatchChangeDeltas;
     /**
-     * Handle store changes and invalidate affected caches.
+     * Apply a list of node changes to a single cache entry, falling back to a
+     * storage re-query only when a delta is ambiguous. Optimistic
+     * (pre-persistence) applies skip ambiguous entries instead of reloading —
+     * storage still holds the OLD state, and the durable change event that
+     * follows will reconcile them.
      */
+    private applyChangesToEntry;
+    /**
+     * Find the freshest cached snapshot of a node across all cache entries.
+     */
+    private findCachedNode;
+    /**
+     * Synchronously apply an optimistic node mutation to every affected cache
+     * entry before persistence, so subscribers see the edit immediately.
+     * Returns a revert function that restores authoritative state by
+     * re-querying storage (used when persistence fails).
+     */
+    private applyOptimisticNodeChange;
+    private applyChangeToEntryState;
     private handleStoreChange;
     create<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, data: InferCreateProps<P>, id?: string): Promise<NodeState>;
     update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
     delete(nodeId: string): Promise<void>;
     restore(nodeId: string): Promise<NodeState>;
+    bulkWrite(input: NodeBatchWriteInput): Promise<NodeBatchWriteResult>;
+    transaction(operations: TransactionOperation[]): Promise<BridgeTransactionResult>;
     /**
      * Acquire a Y.Doc for editing.
      * Delegates to SyncManager if available, otherwise throws.
@@ -380,6 +142,7 @@ declare class MainThreadBridge implements DataBridge {
      * Release a Y.Doc when no longer editing.
      */
     releaseDoc(nodeId: string): void;
+    initialize(config: DataBridgeConfig): Promise<void>;
     destroy(): void;
     get status(): SyncStatus;
     on(event: 'status', handler: (status: SyncStatus) => void): () => void;
@@ -391,7 +154,7 @@ declare class MainThreadBridge implements DataBridge {
 /**
  * Create a MainThreadBridge from a NodeStore.
  */
-declare function createMainThreadBridge(store: NodeStore): MainThreadBridge;
+declare function createMainThreadBridge(store: NodeStore, options?: MainThreadBridgeOptions): MainThreadBridge;
 
 /**
  * WorkerBridge - Main thread bridge to DataWorker
@@ -417,17 +180,24 @@ declare class WorkerBridge implements DataBridge {
     private remote;
     private cache;
     private subscriptions;
-    private queryCounter;
+    private activeRemoteSubscriptions;
     private statusListeners;
+    private changeListeners;
+    private changeFeedStarted;
     private _status;
     private initialized;
     private mirrorDocs;
     constructor(workerUrl: string | URL);
     /**
      * Initialize the bridge and underlying worker.
+     *
+     * When `config.storagePort` is provided (a MessagePort connected to the
+     * SQLite worker), it is transferred to the data worker so storage calls
+     * run worker-to-worker without a main-thread hop.
      */
     initialize(config: DataBridgeConfig): Promise<void>;
     query<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): QuerySubscription<P>;
+    reloadQuery(descriptor: QueryDescriptor): Promise<void>;
     private startWorkerSubscription;
     private applyDelta;
     private serializeOptions;
@@ -435,6 +205,14 @@ declare class WorkerBridge implements DataBridge {
     update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
     delete(nodeId: string): Promise<void>;
     restore(nodeId: string): Promise<NodeState>;
+    bulkWrite(input: NodeBatchWriteInput): Promise<NodeBatchWriteResult>;
+    transaction(operations: TransactionOperation[]): Promise<BridgeTransactionResult>;
+    /**
+     * Subscribe to the worker's store change feed (devtools and other
+     * instrumentation). A single proxied forwarder is registered with the
+     * worker on first use; events fan out to local listeners from there.
+     */
+    subscribeToChanges(listener: (event: NodeChangeEvent) => void): () => void;
     /**
      * Acquire a Y.Doc for editing.
      *
@@ -464,119 +242,52 @@ declare class WorkerBridge implements DataBridge {
 declare function createWorkerBridge(workerUrl: string | URL): WorkerBridge;
 
 /**
- * NativeBridge - DataBridge implementation for React Native/Expo
+ * PortSQLiteAdapter - SQLiteAdapter over a forwarded MessagePort
  *
- * Phase 5 implementation that provides the DataBridge interface for React Native.
+ * Runs inside the data worker and speaks the same Comlink
+ * `SQLiteWorkerHandler` protocol as `WebSQLiteProxy`, but over a
+ * MessagePort transferred from the main thread instead of a Worker it
+ * owns. This is option A of exploration 0164: the data worker hosts
+ * NodeStore + invalidation while storage stays in the existing SQLite
+ * worker — storage calls hop data worker → SQLite worker without
+ * touching the main thread.
  *
- * Architecture:
- * - Uses expo-sqlite for storage (runs on native thread)
- * - Uses NodeStore on JS thread (can be moved to JSI in future)
- * - Provides same API as MainThreadBridge/WorkerBridge
- *
- * Future enhancements:
- * - Turbo Module for heavy operations (crypto, queries)
- * - JSI bindings for direct native access
- * - Native WebSocket for sync
+ * The database lifecycle is owned by the main thread (which opened it
+ * and applied the schema before forwarding the port), so `open()` only
+ * verifies connectivity and `close()` only closes this port.
  */
 
-/**
- * Interface for native storage adapters (expo-sqlite, etc.)
- * This allows the NativeBridge to work with different storage backends.
- */
-interface NativeStorageAdapter {
-    /** Open the database */
-    open(): Promise<void>;
-    /** Close the database */
+declare class PortSQLiteAdapter implements SQLiteAdapter {
+    private port;
+    private proxy;
+    private inTransaction;
+    constructor(port: MessagePort);
+    open(_config?: SQLiteConfig): Promise<void>;
     close(): Promise<void>;
-    /** Get a document by ID */
-    getDocument(id: string): Promise<{
-        content: Uint8Array;
-    } | null>;
-    /** Set a document */
-    setDocument(id: string, content: Uint8Array): Promise<void>;
-    /** Delete a document */
-    deleteDocument(id: string): Promise<void>;
-    /** List all document IDs */
-    listDocuments(): Promise<string[]>;
-}
-interface NativeBridgeConfig {
-    /** The NodeStore instance to use */
-    store: NodeStore;
-    /** Optional native storage adapter for Y.Doc persistence */
-    storageAdapter?: NativeStorageAdapter;
-    /** Signaling server URL for sync (optional, default: no sync) */
-    signalingUrl?: string;
+    isOpen(): boolean;
+    private requireProxy;
+    query<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T[]>;
+    queryOne<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T | null>;
+    run(sql: string, params?: SQLValue[]): Promise<RunResult>;
+    exec(sql: string): Promise<void>;
+    transaction<T>(_fn: () => Promise<T>): Promise<T>;
+    transactionBatch(operations: Array<{
+        sql: string;
+        params?: SQLValue[];
+    }>): Promise<void>;
+    applyNodeBatch(input: SQLiteNodeBatchApplyInput): Promise<SQLiteNodeBatchApplyResult>;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    prepare(_sql: string): Promise<PreparedStatement>;
+    getSchemaVersion(): Promise<number>;
+    setSchemaVersion(version: number): Promise<void>;
+    applySchema(version: number, sql: string): Promise<boolean>;
+    getDatabaseSize(): Promise<number>;
+    vacuum(): Promise<void>;
+    checkpoint(): Promise<number>;
+    getStorageMode(): Promise<'opfs' | 'memory'>;
 }
-/**
- * DataBridge implementation for React Native/Expo.
- *
- * This implementation runs on the JS thread but is designed to work with
- * React Native's architecture. Storage operations use expo-sqlite which
- * runs on a native thread.
- *
- * For now, this is similar to MainThreadBridge but structured for RN.
- * Future versions will add Turbo Module integration for off-thread operations.
- */
-declare class NativeBridge implements DataBridge {
-    private store;
-    private cache;
-    private statusListeners;
-    private storeUnsubscribe;
-    private storageAdapter?;
-    private _status;
-    private destroyed;
-    constructor(config: NativeBridgeConfig);
-    query<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): QuerySubscription<P>;
-    /**
-     * Load query data from the store and update cache.
-     */
-    private loadQuery;
-    /**
-     * Handle store changes and invalidate affected caches.
-     */
-    private handleStoreChange;
-    create<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, data: InferCreateProps<P>, id?: string): Promise<NodeState>;
-    update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
-    delete(nodeId: string): Promise<void>;
-    restore(nodeId: string): Promise<NodeState>;
-    /**
-     * Acquire a Y.Doc for editing.
-     *
-     * Note: Y.Doc management in React Native is limited compared to web.
-     * For now, this throws an error. Future versions will support Y.Doc
-     * via native WebSocket sync or JSI bindings.
-     */
-    acquireDoc(_nodeId: string): Promise<AcquiredDoc>;
-    /**
-     * Release a Y.Doc when no longer editing.
-     */
-    releaseDoc(_nodeId: string): void;
-    /**
-     * Initialize the bridge.
-     * Opens storage adapter if provided.
-     */
-    initialize(_config: DataBridgeConfig): Promise<void>;
-    destroy(): void;
-    get status(): SyncStatus;
-    on(event: 'status', handler: (status: SyncStatus) => void): () => void;
-    private setStatus;
-    get nodeStore(): NodeStore;
-    subscribeToChanges(listener: (event: NodeChangeEvent) => void): () => void;
-    get(nodeId: string): Promise<NodeState | null>;
-    list(options?: ListNodesOptions): Promise<NodeState[]>;
-}
-/**
- * Create a NativeBridge from a NodeStore.
- */
-declare function createNativeBridge(config: NativeBridgeConfig): NativeBridge;
-/**
- * Check if we're running in a React Native environment.
- */
-declare function isReactNative(): boolean;
-/**
- * Check if we're running in Expo.
- */
-declare function isExpo(): boolean;
 
 /**
  * Factory functions for creating DataBridge instances
@@ -627,6 +338,12 @@ declare function isWorkerSupported(): boolean;
  * Check if we're in a Node.js environment (e.g., SSR, tests).
  */
 declare function isNodeEnvironment(): boolean;
+/**
+ * URL of the package's built data worker, resolved relative to this
+ * module (mirrors how @xnetjs/sqlite locates its web worker). Pass to
+ * `WorkerBridge`/`createDataBridge` or `runtime.worker.url`.
+ */
+declare function getDefaultDataWorkerUrl(): URL;
 /**
  * Create a DataBridge with automatic platform detection.
  *
@@ -652,7 +369,7 @@ declare function createDataBridge(options: CreateBridgeOptions): Promise<DataBri
  * Create a MainThreadBridge directly.
  * Use this when you don't need off-main-thread support.
  */
-declare function createMainThreadBridgeSync(nodeStore: NodeStore): MainThreadBridge;
+declare function createMainThreadBridgeSync(nodeStore: NodeStore, options?: ConstructorParameters<typeof MainThreadBridge>[1]): MainThreadBridge;
 /**
  * Create a WorkerBridge directly.
  * The bridge must be initialized before use.
@@ -707,7 +424,7 @@ declare class QueryCache {
      * Compute a stable query ID from schema and options.
      * Same query params should produce the same ID for deduplication.
      */
-    computeQueryId<P extends Record<string, PropertyBuilder>>(schemaId: string, options?: QueryOptions<P>): string;
+    computeQueryId<P extends Record<string, PropertyBuilder>>(schemaId: string | QueryDescriptor, options?: QueryOptions<P>): string;
     /**
      * Get cached data for a query (synchronous for useSyncExternalStore).
      * Updates lastAccessed for LRU tracking.
@@ -721,11 +438,11 @@ declare class QueryCache {
      * Set cached data for a query and notify subscribers.
      * Triggers LRU eviction if cache exceeds maxSize.
      */
-    set(queryId: string, data: NodeState[], schemaId: SchemaIRI, options: QueryOptions): void;
+    set(queryId: string, data: NodeState[] | null, schemaIdOrDescriptor?: SchemaIRI | QueryDescriptor, options?: QueryOptions, metadata?: QueryMetadata | null, workingSet?: BoundedQueryWorkingSet | null): void;
     /**
      * Initialize a cache entry (called when starting a subscription).
      */
-    initEntry(queryId: string, schemaId: SchemaIRI, options: QueryOptions): void;
+    initEntry(queryId: string, schemaIdOrDescriptor: SchemaIRI | QueryDescriptor, options?: QueryOptions): void;
     /**
      * Subscribe to cache updates for a query.
      * Uses strong references - callback will not be garbage collected until unsubscribed.
@@ -768,14 +485,48 @@ declare class QueryCache {
      * Get all query IDs that match a schema.
      */
     getQueriesForSchema(schemaId: SchemaIRI): string[];
+    /**
+     * Get all cached entries for a schema.
+     */
+    getEntriesForSchema(schemaId: SchemaIRI): Array<{
+        queryId: string;
+        descriptor: QueryDescriptor;
+        data: NodeState[] | null;
+        workingSet: BoundedQueryWorkingSet | null;
+    }>;
+    /**
+     * Get all cached entries.
+     */
+    getEntries(): Array<{
+        queryId: string;
+        descriptor: QueryDescriptor;
+        data: NodeState[] | null;
+        workingSet: BoundedQueryWorkingSet | null;
+    }>;
+    /**
+     * Get the bounded-query working set for a cached query, if any.
+     */
+    getWorkingSet(queryId: string): BoundedQueryWorkingSet | null;
     /**
      * Get the schema IRI for a cached query.
      */
     getSchemaId(queryId: string): SchemaIRI | undefined;
+    /**
+     * Get the descriptor for a cached query.
+     */
+    getDescriptor(queryId: string): QueryDescriptor | undefined;
     /**
      * Get the options for a cached query.
      */
     getOptions(queryId: string): QueryOptions | undefined;
+    /**
+     * Get the latest metadata for a cached query.
+     */
+    getMetadata(queryId: string): QueryMetadata | null;
+    /**
+     * Set metadata without replacing query data.
+     */
+    setMetadata(queryId: string, metadata: QueryMetadata | null): void;
     /**
      * Clear the entire cache and stop cleanup interval.
      */
@@ -819,6 +570,71 @@ declare class QueryCache {
     paginateNodes(nodes: NodeState[], options?: QueryOptions): NodeState[];
 }
 
+/**
+ * Shared query metadata helpers for bridge implementations.
+ */
+
+declare function createQueryMetadata(input: {
+    descriptor: QueryDescriptor;
+    result: NodeQueryResult;
+    source: QuerySource;
+}): QueryMetadata;
+declare function createQueryErrorMetadata(input: {
+    descriptor: QueryDescriptor;
+    source: QuerySource;
+    error: Error;
+}): QueryMetadata;
+declare function createQuerySnapshotMetadata(input: {
+    descriptor: QueryDescriptor;
+    nodes: NodeState[];
+    source: QuerySource;
+}): QueryMetadata;
+
+/**
+ * Helpers for progressive remote Node query execution.
+ */
+
+declare const DEFAULT_NODE_QUERY_ROUTER_THRESHOLDS: NodeQueryRouterThresholds;
+type RemoteNodeQueryRouteDecision = {
+    shouldRunRemote: false;
+    source: 'local';
+    reason: string;
+    localRowCount?: number;
+    thresholds: NodeQueryRouterThresholds;
+} | {
+    shouldRunRemote: true;
+    mode: RemoteNodeQueryMode;
+    source: RemoteNodeQuerySource;
+    reason: string;
+    localRowCount?: number;
+    thresholds: NodeQueryRouterThresholds;
+};
+declare function getRemoteQueryMode(descriptor: QueryDescriptor): RemoteNodeQueryMode | null;
+declare function getRemoteQuerySource(descriptor: QueryDescriptor): RemoteNodeQuerySource;
+declare function shouldRunRemoteQuery(descriptor: QueryDescriptor): boolean;
+declare function shouldUseRemoteOnlyQuery(descriptor: QueryDescriptor): boolean;
+declare function normalizeNodeQueryRouterThresholds(thresholds?: Partial<NodeQueryRouterThresholds>): NodeQueryRouterThresholds;
+declare function routeRemoteNodeQuery(input: {
+    descriptor: QueryDescriptor;
+    localRowCount?: number;
+    hasRemoteClient: boolean;
+    thresholds?: Partial<NodeQueryRouterThresholds>;
+}): RemoteNodeQueryRouteDecision;
+declare function createQueryRoutingMetadata(route: RemoteNodeQueryRouteDecision): QueryRoutingMetadata;
+declare function mergeRemoteNodeSnapshots(localNodes: readonly NodeState[], remoteNodes: readonly NodeState[]): NodeState[];
+declare function isRemoteVerificationFailed(verification: QueryVerificationMetadata | undefined): boolean;
+declare function filterRemoteNodesByVerification(nodes: readonly NodeState[], verification: QueryVerificationMetadata | undefined): NodeState[];
+declare function createRemoteSuccessMetadata(input: {
+    response: RemoteNodeQuerySuccessResponse;
+    source: QuerySource;
+    loadedCount: number;
+}): QueryMetadata;
+declare function createRemoteFallbackMetadata(input: {
+    localMetadata: QueryMetadata;
+    error: RemoteNodeQueryErrorResponse | Error;
+}): QueryMetadata;
+declare function withRemoteErrorVerificationMetadata(metadata: QueryMetadata, error: RemoteNodeQueryErrorResponse | Error): QueryMetadata;
+
 /**
  * Debounce utilities for DataBridge
  *
@@ -929,22 +745,6 @@ interface DeltaBatcher {
  */
 declare function createDeltaBatcher(options: DeltaBatcherOptions): DeltaBatcher;
 
-/**
- * Binary Serialization for NodeState
- *
- * Provides efficient binary encoding for NodeState objects when transferring
- * between main thread and worker via postMessage. This is more efficient than
- * JSON for large datasets with typed arrays.
- *
- * Format:
- * - Uses TextEncoder/TextDecoder for strings
- * - Preserves Uint8Array as-is (transferable)
- * - Compacts property timestamps
- *
- * Note: This is an optimization for large transfers. For small payloads,
- * structured clone (default postMessage behavior) may be faster.
- */
-
 /**
  * Binary encoder for NodeState arrays.
  *
@@ -1007,5 +807,15 @@ declare function decodeNodeStates(data: Uint8Array): NodeState[];
  * For small payloads, structured clone may be faster.
  */
 declare function shouldUseBinaryEncoding(states: NodeState[]): boolean;
+/**
+ * Encode a query snapshot for the worker → main-thread wire: binary above
+ * the size threshold (so the caller can transfer the buffer), structured
+ * clone below it.
+ */
+declare function encodeWorkerQuerySnapshot(nodes: NodeState[]): WorkerQuerySnapshot;
+/**
+ * Decode a wire snapshot back to NodeState[] on the main thread.
+ */
+declare function decodeWorkerQuerySnapshot(snapshot: WorkerQuerySnapshot): NodeState[];
 
-export { type AcquiredDoc, type CreateBridgeOptions, type CreateResult, type DataBridge, type DataBridgeConfig, type DataWorkerAPI, type DebounceOptions, type DebouncedFunction, type DeltaBatcher, type DeltaBatcherOptions, type QueryDelta as DeltaQueryDelta, type DocUpdateMessage, MainThreadBridge, NativeBridge, type NativeBridgeConfig, type NativeStorageAdapter, NodeStateDecoder, NodeStateEncoder, QueryCache, type QueryDelta$1 as QueryDelta, type QueryOptions, type QuerySubscription, type SerializedQueryOptions, type SortDirection, type SyncManagerLike, type SyncStatus, type SystemOrderField, type UpdateBatcher, type UpdateBatcherOptions, type UpdateResult, type WorkerAcquiredDoc, WorkerBridge, type WorkerConfig, createDataBridge, createDeltaBatcher, createMainThreadBridge, createMainThreadBridgeSync, createNativeBridge, createUpdateBatcher, createWorkerBridge, createWorkerBridgeSync, debounce, decodeNodeStates, encodeNodeStates, isExpo, isNodeEnvironment, isReactNative, isWorkerSupported, shouldUseBinaryEncoding };
+export { AcquiredDoc, BoundedQueryWorkingSet, BridgeTransactionResult, type CreateBridgeOptions, DEFAULT_NODE_QUERY_ROUTER_THRESHOLDS, DataBridge, DataBridgeConfig, type DebounceOptions, type DebouncedFunction, type DeltaBatcher, type DeltaBatcherOptions, type QueryDelta as DeltaQueryDelta, MainThreadBridge, type MainThreadBridgeOptions, NodeQueryRouterThresholds, NodeStateDecoder, NodeStateEncoder, PortSQLiteAdapter, QueryCache, QueryDescriptor, QueryMetadata, QueryOptions, QueryRoutingMetadata, QuerySource, QuerySubscription, QueryVerificationMetadata, RemoteNodeQueryClient, RemoteNodeQueryErrorResponse, RemoteNodeQueryMode, type RemoteNodeQueryRouteDecision, RemoteNodeQuerySource, RemoteNodeQuerySuccessResponse, type SyncManagerLike, SyncStatus, type UpdateBatcher, type UpdateBatcherOptions, WorkerBridge, WorkerQuerySnapshot, createDataBridge, createDeltaBatcher, createMainThreadBridge, createMainThreadBridgeSync, createQueryErrorMetadata, createQueryMetadata, createQueryRoutingMetadata, createQuerySnapshotMetadata, createRemoteFallbackMetadata, createRemoteSuccessMetadata, createUpdateBatcher, createWorkerBridge, createWorkerBridgeSync, debounce, decodeNodeStates, decodeWorkerQuerySnapshot, encodeNodeStates, encodeWorkerQuerySnapshot, filterRemoteNodesByVerification, getDefaultDataWorkerUrl, getRemoteQueryMode, getRemoteQuerySource, isNodeEnvironment, isRemoteVerificationFailed, isWorkerSupported, mergeRemoteNodeSnapshots, normalizeNodeQueryRouterThresholds, routeRemoteNodeQuery, shouldRunRemoteQuery, shouldUseBinaryEncoding, shouldUseRemoteOnlyQuery, withRemoteErrorVerificationMetadata };