@korajs/store 1.0.0-beta.11 → 1.0.0-beta.13

package/dist/sqlite-wasm-channel-DVX93Uiq.d.cts

@@ -0,0 +1,141 @@
+/** Fields every request carries besides its type. */
+interface RequestMeta {
+    /** Correlates a worker response with its request on one postMessage channel. */
+    id: number;
+    /**
+     * Stable id for de-duplication. A follower retrying a request (after a
+     * `LeaderUnresponsiveError`, say) sends the same id and the leader worker
+     * answers from its response cache instead of applying it twice.
+     */
+    requestId?: string;
+}
+/**
+ * Request message sent from the main thread (or a follower tab) to the SQLite
+ * WASM worker.
+ */
+type WorkerRequest = (RequestMeta & {
+    type: 'open';
+    ddlStatements: string[];
+    dbName?: string;
+    /**
+     * `memory` opens an in-memory database without touching OPFS (the
+     * IndexedDB adapter persists snapshots itself). Defaults to `opfs`.
+     */
+    storage?: 'opfs' | 'memory';
+    /** Fail with `NOT_FOUND` instead of creating the database file. */
+    mustExist?: boolean;
+}) | (RequestMeta & {
+    type: 'close';
+}) | (RequestMeta & {
+    type: 'destroy';
+}) | (RequestMeta & {
+    type: 'execute';
+    sql: string;
+    params?: unknown[];
+}) | (RequestMeta & {
+    type: 'query';
+    sql: string;
+    params?: unknown[];
+}) | (RequestMeta & {
+    type: 'begin';
+}) | (RequestMeta & {
+    type: 'commit';
+}) | (RequestMeta & {
+    type: 'rollback';
+}) | (RequestMeta & {
+    type: 'migrate';
+    from: number;
+    to: number;
+    statements: string[];
+}) | (RequestMeta & {
+    type: 'export';
+}) | (RequestMeta & {
+    type: 'import';
+    data: Uint8Array;
+}) | (RequestMeta & {
+    /**
+     * Leader worker only: answer follower RPC, pings and heartbeats on this
+     * BroadcastChannel directly, so a hung leader main thread never blocks
+     * other tabs (NEW-STORE-9).
+     */
+    type: 'serve';
+    channelName: string;
+});
+/**
+ * Response message sent from the worker back to the main thread.
+ * Matches the request `id` for correlation.
+ */
+type WorkerResponse = {
+    id: number;
+    type: 'success';
+    data?: unknown;
+} | {
+    id: number;
+    type: 'error';
+    message: string;
+    code: string;
+    context?: Record<string, unknown>;
+};
+/**
+ * Unsolicited status the worker reports while it works on a request, such as
+ * waiting for another holder of the OPFS pool (a blocking state the app shows).
+ */
+type WorkerStatusEvent = {
+    kind: 'storage-blocked';
+    resource: 'pool' | 'legacy-pool';
+    poolName: string;
+} | {
+    kind: 'storage-unblocked';
+    resource: 'pool' | 'legacy-pool';
+    poolName: string;
+    waitedMs: number;
+};
+/** Per-request options accepted by bridges. */
+interface WorkerSendOptions {
+    /** Cancels the wait for the response (the worker may still apply the request). */
+    signal?: AbortSignal;
+    /** Overrides the bridge timeout for this request; `Infinity` disables it. */
+    timeoutMs?: number;
+}
+/**
+ * Abstraction over the communication channel with the SQLite WASM worker.
+ * In browsers, this is backed by a real Web Worker via MessagePort.
+ * In Node.js tests, this is backed by better-sqlite3 via MockWorkerBridge.
+ */
+interface WorkerBridge {
+    /** Send a request to the worker and wait for a response. */
+    send(request: WorkerRequest, clientId?: string, options?: WorkerSendOptions): Promise<WorkerResponse>;
+    /** Terminate the worker. Safe to call multiple times. */
+    terminate(): void;
+}
+
+/** Options for {@link WebWorkerBridge}. */
+interface WebWorkerBridgeOptions {
+    /** Receives status events (blocking state) the worker reports. */
+    onEvent?: (event: WorkerStatusEvent) => void;
+}
+/**
+ * WorkerBridge implementation for browser environments.
+ * Communicates with an actual Web Worker running SQLite WASM.
+ */
+declare class WebWorkerBridge implements WorkerBridge {
+    private worker;
+    private pending;
+    private nextId;
+    private terminated;
+    private timeoutMs;
+    /**
+     * @param workerUrl - URL to the sqlite-wasm-worker script
+     * @param timeoutMs - Timeout for worker responses in milliseconds (default: 30000)
+     * @param options - Status event listener
+     */
+    constructor(workerUrl: string | URL, timeoutMs?: number, options?: WebWorkerBridgeOptions);
+    /** True once {@link terminate} ran. */
+    isTerminated(): boolean;
+    /** Post a request without awaiting a response (fire-and-forget control messages). */
+    post(request: WorkerRequest, clientId?: string): void;
+    send(request: WorkerRequest, clientId?: string, options?: WorkerSendOptions): Promise<WorkerResponse>;
+    terminate(): void;
+}
+
+export { type WorkerBridge as W, WebWorkerBridge as a, type WorkerRequest as b, type WorkerResponse as c, type WorkerSendOptions as d, type WorkerStatusEvent as e };

package/dist/sqlite-wasm-channel-DVX93Uiq.d.ts

@@ -0,0 +1,141 @@
+/** Fields every request carries besides its type. */
+interface RequestMeta {
+    /** Correlates a worker response with its request on one postMessage channel. */
+    id: number;
+    /**
+     * Stable id for de-duplication. A follower retrying a request (after a
+     * `LeaderUnresponsiveError`, say) sends the same id and the leader worker
+     * answers from its response cache instead of applying it twice.
+     */
+    requestId?: string;
+}
+/**
+ * Request message sent from the main thread (or a follower tab) to the SQLite
+ * WASM worker.
+ */
+type WorkerRequest = (RequestMeta & {
+    type: 'open';
+    ddlStatements: string[];
+    dbName?: string;
+    /**
+     * `memory` opens an in-memory database without touching OPFS (the
+     * IndexedDB adapter persists snapshots itself). Defaults to `opfs`.
+     */
+    storage?: 'opfs' | 'memory';
+    /** Fail with `NOT_FOUND` instead of creating the database file. */
+    mustExist?: boolean;
+}) | (RequestMeta & {
+    type: 'close';
+}) | (RequestMeta & {
+    type: 'destroy';
+}) | (RequestMeta & {
+    type: 'execute';
+    sql: string;
+    params?: unknown[];
+}) | (RequestMeta & {
+    type: 'query';
+    sql: string;
+    params?: unknown[];
+}) | (RequestMeta & {
+    type: 'begin';
+}) | (RequestMeta & {
+    type: 'commit';
+}) | (RequestMeta & {
+    type: 'rollback';
+}) | (RequestMeta & {
+    type: 'migrate';
+    from: number;
+    to: number;
+    statements: string[];
+}) | (RequestMeta & {
+    type: 'export';
+}) | (RequestMeta & {
+    type: 'import';
+    data: Uint8Array;
+}) | (RequestMeta & {
+    /**
+     * Leader worker only: answer follower RPC, pings and heartbeats on this
+     * BroadcastChannel directly, so a hung leader main thread never blocks
+     * other tabs (NEW-STORE-9).
+     */
+    type: 'serve';
+    channelName: string;
+});
+/**
+ * Response message sent from the worker back to the main thread.
+ * Matches the request `id` for correlation.
+ */
+type WorkerResponse = {
+    id: number;
+    type: 'success';
+    data?: unknown;
+} | {
+    id: number;
+    type: 'error';
+    message: string;
+    code: string;
+    context?: Record<string, unknown>;
+};
+/**
+ * Unsolicited status the worker reports while it works on a request, such as
+ * waiting for another holder of the OPFS pool (a blocking state the app shows).
+ */
+type WorkerStatusEvent = {
+    kind: 'storage-blocked';
+    resource: 'pool' | 'legacy-pool';
+    poolName: string;
+} | {
+    kind: 'storage-unblocked';
+    resource: 'pool' | 'legacy-pool';
+    poolName: string;
+    waitedMs: number;
+};
+/** Per-request options accepted by bridges. */
+interface WorkerSendOptions {
+    /** Cancels the wait for the response (the worker may still apply the request). */
+    signal?: AbortSignal;
+    /** Overrides the bridge timeout for this request; `Infinity` disables it. */
+    timeoutMs?: number;
+}
+/**
+ * Abstraction over the communication channel with the SQLite WASM worker.
+ * In browsers, this is backed by a real Web Worker via MessagePort.
+ * In Node.js tests, this is backed by better-sqlite3 via MockWorkerBridge.
+ */
+interface WorkerBridge {
+    /** Send a request to the worker and wait for a response. */
+    send(request: WorkerRequest, clientId?: string, options?: WorkerSendOptions): Promise<WorkerResponse>;
+    /** Terminate the worker. Safe to call multiple times. */
+    terminate(): void;
+}
+
+/** Options for {@link WebWorkerBridge}. */
+interface WebWorkerBridgeOptions {
+    /** Receives status events (blocking state) the worker reports. */
+    onEvent?: (event: WorkerStatusEvent) => void;
+}
+/**
+ * WorkerBridge implementation for browser environments.
+ * Communicates with an actual Web Worker running SQLite WASM.
+ */
+declare class WebWorkerBridge implements WorkerBridge {
+    private worker;
+    private pending;
+    private nextId;
+    private terminated;
+    private timeoutMs;
+    /**
+     * @param workerUrl - URL to the sqlite-wasm-worker script
+     * @param timeoutMs - Timeout for worker responses in milliseconds (default: 30000)
+     * @param options - Status event listener
+     */
+    constructor(workerUrl: string | URL, timeoutMs?: number, options?: WebWorkerBridgeOptions);
+    /** True once {@link terminate} ran. */
+    isTerminated(): boolean;
+    /** Post a request without awaiting a response (fire-and-forget control messages). */
+    post(request: WorkerRequest, clientId?: string): void;
+    send(request: WorkerRequest, clientId?: string, options?: WorkerSendOptions): Promise<WorkerResponse>;
+    terminate(): void;
+}
+
+export { type WorkerBridge as W, WebWorkerBridge as a, type WorkerRequest as b, type WorkerResponse as c, type WorkerSendOptions as d, type WorkerStatusEvent as e };

package/dist/sqlite-wasm-channel-MLHLKEED.js

@@ -0,0 +1,12 @@
+import {
+  WebWorkerBridge
+} from "./chunk-MCQKEHOD.js";
+import {
+  Mutex
+} from "./chunk-TVJEC5S2.js";
+import "./chunk-DUKTWVZW.js";
+export {
+  Mutex,
+  WebWorkerBridge
+};
+//# sourceMappingURL=sqlite-wasm-channel-MLHLKEED.js.map

package/dist/store-IMWKZLWB.js

@@ -0,0 +1,16 @@
+import {
+  ReservedNodeIdError,
+  Store
+} from "./chunk-Y5LRH7KI.js";
+import "./chunk-HZTDBLDB.js";
+import "./chunk-A6GFH5IG.js";
+import "./chunk-P4V375FY.js";
+import "./chunk-32EDKWMI.js";
+import "./chunk-SJP2HTYZ.js";
+import "./chunk-J5AGXF3D.js";
+import "./chunk-DUKTWVZW.js";
+export {
+  ReservedNodeIdError,
+  Store
+};
+//# sourceMappingURL=store-IMWKZLWB.js.map

package/dist/store-IMWKZLWB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{types-BslDOTk0.d.ts → types-Dh-xyUjP.d.cts}

@@ -1,4 +1,5 @@
-import { HLCTimestamp, SchemaDefinition, Operation, KoraEventEmitter, SecretKeyProvider } from '@korajs/core';
+import * as _korajs_core from '@korajs/core';
+import { HLCTimestamp, SchemaDefinition, Operation, KoraEventEmitter, SecretKeyProvider, OperationTransform } from '@korajs/core';
 
 /**
  * Transaction interface for executing multiple operations atomically.
@@ -22,6 +23,14 @@ interface StorageOpenState {
     mode: 'opfs' | 'indexeddb' | 'memory' | 'native' | 'unknown';
     /** Present when a primary storage mode degraded during open. */
     fallbackReason?: StorageFallbackReason;
+    /** OPFS pool that owns the database file (one pool per database), when known. */
+    poolName?: string;
+    /**
+     * SQLite journal mode the database actually runs with, when known (NEW-STORE-11).
+     * OPFS (opfs-sahpool): `delete`, the rollback journal; WAL is not available on
+     * that VFS. In-memory fallback: `memory`. Native better-sqlite3: `wal`.
+     */
+    journalMode?: string;
 }
 /**
  * Storage adapter interface. All storage backends must implement this.
@@ -46,39 +55,32 @@ interface StorageAdapter {
      * fallback before app code starts reading or writing user data.
      */
     getStorageOpenState?(): StorageOpenState | null;
+    /**
+     * Optional durability barrier (RT-35): resolve once every write committed before the
+     * call is durable, reject when it cannot be made durable. Adapters whose commits are
+     * durable when they resolve (SQLite on a file or OPFS) omit it; an adapter that
+     * persists asynchronously (the IndexedDB snapshot fallback) must implement it.
+     */
+    ensureDurable?(): Promise<void>;
 }
 /**
- * Buffered SQL + operation produced during a transaction (before commit).
- */
-interface TransactionBufferedEntry {
-    operation: Operation;
-    commands: Array<{
-        sql: string;
-        params: unknown[];
-    }>;
-    collection: string;
-}
-/**
- * Batch passed to {@link LocalMutationHandler.commitTransaction} on commit.
+ * Routes local mutations through a unified apply pipeline (korajs ApplyPipeline).
+ *
+ * Every local write — including each entry of an `app.transaction` commit — is
+ * built and persisted by the store's single local write path; the handler adds
+ * pipeline behaviour around it.
  */
-interface TransactionCommitBatch {
-    entries: TransactionBufferedEntry[];
-    transactionId: string;
-    mutationName?: string;
-}
-interface TransactionCommitResult {
-    operations: Operation[];
-    affectedCollections: Set<string>;
-}
 interface LocalMutationHandler {
     insert(collection: string, data: Record<string, unknown>): Promise<CollectionRecord>;
     update(collection: string, id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
     delete(collection: string, id: string): Promise<void>;
     /**
-     * Commit a buffered transaction through the unified apply pipeline.
-     * When omitted, the store uses the built-in SQL commit path.
+     * Called inside the write transaction for every local delete (single-record,
+     * transactional and cascaded), after the delete operation is built and before
+     * referential side effects run. Reads must go through `tx`. Throwing aborts
+     * the whole write.
      */
-    commitTransaction?(batch: TransactionCommitBatch): Promise<TransactionCommitResult>;
+    beforeLocalDelete?(operation: Operation, tx: Transaction): Promise<void>;
 }
 type StoreIsolation = 'shared' | 'per-tab';
 interface StoreConfig {
@@ -104,6 +106,30 @@ interface StoreConfig {
      * Required only when the schema declares encrypted secret fields.
      */
     secretKeyProvider?: SecretKeyProvider;
+    /**
+     * How rows are materialized. `'fold'` (default, W7): every write merges into the
+     * record's per-field CRDT fold state, which re-materializes the row. `'legacy'`:
+     * the beta.12 per-field LWW write paths (used by `experimental.legacyMerge` for
+     * one beta, to compare). Switching modes on an existing database re-materializes
+     * it on open.
+     */
+    materialization?: 'fold' | 'legacy';
+    /**
+     * Schema transforms applied at fold time (RT-84): an operation authored under an
+     * older schema version is stored exactly as written and folded as
+     * `operationSchemaView(op, schema.version, transforms)` reads it. Pass the same list
+     * as the sync engine's `operationTransforms` (`createApp` does). Transforms must be
+     * pure and deterministic; they are part of the fold plan fingerprint, so changing
+     * them re-folds once.
+     */
+    operationTransforms?: readonly OperationTransform[];
+    /**
+     * Largest serialized operation a local write may produce, in bytes (RT-86). Set it to
+     * the sync server's `maxOperationBytes`. A write over it is refused with
+     * `OperationTooLargeError` and nothing is written. Default 256 KiB, the server's
+     * default.
+     */
+    maxOperationBytes?: number;
 }
 /**
  * Operators for where clause conditions.
@@ -150,6 +176,38 @@ interface QueryDescriptor {
  * Callback for reactive subscriptions. Receives the current result set.
  */
 type SubscriptionCallback<T> = (results: T[]) => void;
+/**
+ * Where a subscription failure happened.
+ * - `initial`: the first run of the query, before any result was delivered.
+ * - `refresh`: a re-run after a write to a collection the query reads.
+ * - `callback`: the query succeeded but the subscriber's own callback threw.
+ */
+type QueryErrorPhase = 'initial' | 'refresh' | 'callback';
+/**
+ * A failure delivered to a subscriber's `onError` (STORE-12). The previous result
+ * set stays current; the subscription stays registered and is re-run on the next
+ * write, and a later success is delivered even if it equals the last results.
+ */
+interface QuerySubscriptionError {
+    /** The error thrown by the query or the callback. */
+    error: Error;
+    phase: QueryErrorPhase;
+    /** The collection the query reads. */
+    collection: string;
+    /** Subscription id, the same `queryId` carried by the `query:error` event. */
+    queryId: string;
+}
+/**
+ * Options for `QueryBuilder.subscribe()`.
+ */
+interface SubscribeOptions {
+    /**
+     * Called when the query fails (or the callback throws) instead of the failure
+     * becoming an unhandled rejection. Every failure is also emitted as a
+     * `query:error` event; without `onError` it is additionally logged.
+     */
+    onError?: (failure: QuerySubscriptionError) => void;
+}
 /**
  * Serialized row in the operations log table.
  */
@@ -198,12 +256,27 @@ interface Subscription<T = CollectionRecord> {
     callback: SubscriptionCallback<T>;
     executeFn: () => Promise<T[]>;
     lastResults: T[];
+    /** Result-set comparator (structural, per field kind). */
+    resultsEqual?: (prev: readonly T[], next: readonly T[]) => boolean;
+    onError?: (failure: QuerySubscriptionError) => void;
+    /** Monotonic run counter: a slower, older run never overwrites a newer result. */
+    runsStarted?: number;
+    lastAppliedRun?: number;
+    /** True after a failure until the next successful delivery. */
+    errored?: boolean;
+    /** True once a result set has been delivered to the callback. */
+    delivered?: boolean;
 }
 
 /**
  * Options for applying a remote operation to materialized storage.
  */
 interface ApplyRemoteOptions {
+    /**
+     * W7: receives the merge traces of the operation (conflicting field decisions),
+     * after commit. The store also emits them as `merge:*` events.
+     */
+    onMergeTraces?: (traces: _korajs_core.MergeTrace[]) => void;
     /** When true, a winning remote update clears soft-delete on the row. */
     reactivateIfDeleted?: boolean;
     /**
@@ -280,4 +353,4 @@ interface VersionVectorRow {
     sequence_number: number;
 }
 
-export type { ApplyRemoteOptions as A, CollectionRecord as C, LocalMutationHandler as L, MigrationPlan as M, OperationRow as O, QueryDescriptor as Q, RawCollectionRow as R, StorageAdapter as S, Transaction as T, VersionVectorRow as V, WhereClause as W, StorageOpenState as a, MetaRow as b, Subscription as c, SubscriptionCallback as d, OrderByDirection as e, StoreConfig as f, MaterializedRowSnapshot as g, RowVersionState as h, OrderByClause as i, StorageFallbackReason as j, StoreIsolation as k, TransactionBufferedEntry as l, TransactionCommitBatch as m, TransactionCommitResult as n, WhereOperators as o };
+export type { ApplyRemoteOptions as A, CollectionRecord as C, LocalMutationHandler as L, MigrationPlan as M, OperationRow as O, QueryDescriptor as Q, RawCollectionRow as R, StorageAdapter as S, Transaction as T, VersionVectorRow as V, WhereClause as W, StorageOpenState as a, MetaRow as b, Subscription as c, QuerySubscriptionError as d, SubscriptionCallback as e, SubscribeOptions as f, OrderByDirection as g, StoreConfig as h, MaterializedRowSnapshot as i, RowVersionState as j, OrderByClause as k, QueryErrorPhase as l, StorageFallbackReason as m, StoreIsolation as n, WhereOperators as o };

package/dist/{types-BslDOTk0.d.cts → types-Dh-xyUjP.d.ts}

@@ -1,4 +1,5 @@
-import { HLCTimestamp, SchemaDefinition, Operation, KoraEventEmitter, SecretKeyProvider } from '@korajs/core';
+import * as _korajs_core from '@korajs/core';
+import { HLCTimestamp, SchemaDefinition, Operation, KoraEventEmitter, SecretKeyProvider, OperationTransform } from '@korajs/core';
 
 /**
  * Transaction interface for executing multiple operations atomically.
@@ -22,6 +23,14 @@ interface StorageOpenState {
     mode: 'opfs' | 'indexeddb' | 'memory' | 'native' | 'unknown';
     /** Present when a primary storage mode degraded during open. */
     fallbackReason?: StorageFallbackReason;
+    /** OPFS pool that owns the database file (one pool per database), when known. */
+    poolName?: string;
+    /**
+     * SQLite journal mode the database actually runs with, when known (NEW-STORE-11).
+     * OPFS (opfs-sahpool): `delete`, the rollback journal; WAL is not available on
+     * that VFS. In-memory fallback: `memory`. Native better-sqlite3: `wal`.
+     */
+    journalMode?: string;
 }
 /**
  * Storage adapter interface. All storage backends must implement this.
@@ -46,39 +55,32 @@ interface StorageAdapter {
      * fallback before app code starts reading or writing user data.
      */
     getStorageOpenState?(): StorageOpenState | null;
+    /**
+     * Optional durability barrier (RT-35): resolve once every write committed before the
+     * call is durable, reject when it cannot be made durable. Adapters whose commits are
+     * durable when they resolve (SQLite on a file or OPFS) omit it; an adapter that
+     * persists asynchronously (the IndexedDB snapshot fallback) must implement it.
+     */
+    ensureDurable?(): Promise<void>;
 }
 /**
- * Buffered SQL + operation produced during a transaction (before commit).
- */
-interface TransactionBufferedEntry {
-    operation: Operation;
-    commands: Array<{
-        sql: string;
-        params: unknown[];
-    }>;
-    collection: string;
-}
-/**
- * Batch passed to {@link LocalMutationHandler.commitTransaction} on commit.
+ * Routes local mutations through a unified apply pipeline (korajs ApplyPipeline).
+ *
+ * Every local write — including each entry of an `app.transaction` commit — is
+ * built and persisted by the store's single local write path; the handler adds
+ * pipeline behaviour around it.
  */
-interface TransactionCommitBatch {
-    entries: TransactionBufferedEntry[];
-    transactionId: string;
-    mutationName?: string;
-}
-interface TransactionCommitResult {
-    operations: Operation[];
-    affectedCollections: Set<string>;
-}
 interface LocalMutationHandler {
     insert(collection: string, data: Record<string, unknown>): Promise<CollectionRecord>;
     update(collection: string, id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
     delete(collection: string, id: string): Promise<void>;
     /**
-     * Commit a buffered transaction through the unified apply pipeline.
-     * When omitted, the store uses the built-in SQL commit path.
+     * Called inside the write transaction for every local delete (single-record,
+     * transactional and cascaded), after the delete operation is built and before
+     * referential side effects run. Reads must go through `tx`. Throwing aborts
+     * the whole write.
      */
-    commitTransaction?(batch: TransactionCommitBatch): Promise<TransactionCommitResult>;
+    beforeLocalDelete?(operation: Operation, tx: Transaction): Promise<void>;
 }
 type StoreIsolation = 'shared' | 'per-tab';
 interface StoreConfig {
@@ -104,6 +106,30 @@ interface StoreConfig {
      * Required only when the schema declares encrypted secret fields.
      */
     secretKeyProvider?: SecretKeyProvider;
+    /**
+     * How rows are materialized. `'fold'` (default, W7): every write merges into the
+     * record's per-field CRDT fold state, which re-materializes the row. `'legacy'`:
+     * the beta.12 per-field LWW write paths (used by `experimental.legacyMerge` for
+     * one beta, to compare). Switching modes on an existing database re-materializes
+     * it on open.
+     */
+    materialization?: 'fold' | 'legacy';
+    /**
+     * Schema transforms applied at fold time (RT-84): an operation authored under an
+     * older schema version is stored exactly as written and folded as
+     * `operationSchemaView(op, schema.version, transforms)` reads it. Pass the same list
+     * as the sync engine's `operationTransforms` (`createApp` does). Transforms must be
+     * pure and deterministic; they are part of the fold plan fingerprint, so changing
+     * them re-folds once.
+     */
+    operationTransforms?: readonly OperationTransform[];
+    /**
+     * Largest serialized operation a local write may produce, in bytes (RT-86). Set it to
+     * the sync server's `maxOperationBytes`. A write over it is refused with
+     * `OperationTooLargeError` and nothing is written. Default 256 KiB, the server's
+     * default.
+     */
+    maxOperationBytes?: number;
 }
 /**
  * Operators for where clause conditions.
@@ -150,6 +176,38 @@ interface QueryDescriptor {
  * Callback for reactive subscriptions. Receives the current result set.
  */
 type SubscriptionCallback<T> = (results: T[]) => void;
+/**
+ * Where a subscription failure happened.
+ * - `initial`: the first run of the query, before any result was delivered.
+ * - `refresh`: a re-run after a write to a collection the query reads.
+ * - `callback`: the query succeeded but the subscriber's own callback threw.
+ */
+type QueryErrorPhase = 'initial' | 'refresh' | 'callback';
+/**
+ * A failure delivered to a subscriber's `onError` (STORE-12). The previous result
+ * set stays current; the subscription stays registered and is re-run on the next
+ * write, and a later success is delivered even if it equals the last results.
+ */
+interface QuerySubscriptionError {
+    /** The error thrown by the query or the callback. */
+    error: Error;
+    phase: QueryErrorPhase;
+    /** The collection the query reads. */
+    collection: string;
+    /** Subscription id, the same `queryId` carried by the `query:error` event. */
+    queryId: string;
+}
+/**
+ * Options for `QueryBuilder.subscribe()`.
+ */
+interface SubscribeOptions {
+    /**
+     * Called when the query fails (or the callback throws) instead of the failure
+     * becoming an unhandled rejection. Every failure is also emitted as a
+     * `query:error` event; without `onError` it is additionally logged.
+     */
+    onError?: (failure: QuerySubscriptionError) => void;
+}
 /**
  * Serialized row in the operations log table.
  */
@@ -198,12 +256,27 @@ interface Subscription<T = CollectionRecord> {
     callback: SubscriptionCallback<T>;
     executeFn: () => Promise<T[]>;
     lastResults: T[];
+    /** Result-set comparator (structural, per field kind). */
+    resultsEqual?: (prev: readonly T[], next: readonly T[]) => boolean;
+    onError?: (failure: QuerySubscriptionError) => void;
+    /** Monotonic run counter: a slower, older run never overwrites a newer result. */
+    runsStarted?: number;
+    lastAppliedRun?: number;
+    /** True after a failure until the next successful delivery. */
+    errored?: boolean;
+    /** True once a result set has been delivered to the callback. */
+    delivered?: boolean;
 }
 
 /**
  * Options for applying a remote operation to materialized storage.
  */
 interface ApplyRemoteOptions {
+    /**
+     * W7: receives the merge traces of the operation (conflicting field decisions),
+     * after commit. The store also emits them as `merge:*` events.
+     */
+    onMergeTraces?: (traces: _korajs_core.MergeTrace[]) => void;
     /** When true, a winning remote update clears soft-delete on the row. */
     reactivateIfDeleted?: boolean;
     /**
@@ -280,4 +353,4 @@ interface VersionVectorRow {
     sequence_number: number;
 }
 
-export type { ApplyRemoteOptions as A, CollectionRecord as C, LocalMutationHandler as L, MigrationPlan as M, OperationRow as O, QueryDescriptor as Q, RawCollectionRow as R, StorageAdapter as S, Transaction as T, VersionVectorRow as V, WhereClause as W, StorageOpenState as a, MetaRow as b, Subscription as c, SubscriptionCallback as d, OrderByDirection as e, StoreConfig as f, MaterializedRowSnapshot as g, RowVersionState as h, OrderByClause as i, StorageFallbackReason as j, StoreIsolation as k, TransactionBufferedEntry as l, TransactionCommitBatch as m, TransactionCommitResult as n, WhereOperators as o };
+export type { ApplyRemoteOptions as A, CollectionRecord as C, LocalMutationHandler as L, MigrationPlan as M, OperationRow as O, QueryDescriptor as Q, RawCollectionRow as R, StorageAdapter as S, Transaction as T, VersionVectorRow as V, WhereClause as W, StorageOpenState as a, MetaRow as b, Subscription as c, QuerySubscriptionError as d, SubscriptionCallback as e, SubscribeOptions as f, OrderByDirection as g, StoreConfig as h, MaterializedRowSnapshot as i, RowVersionState as j, OrderByClause as k, QueryErrorPhase as l, StorageFallbackReason as m, StoreIsolation as n, WhereOperators as o };