@syncular/client 0.20.0 → 0.21.0

package/src/outcomes.ts

@@ -22,6 +22,12 @@ export interface ConflictRecord {
   readonly serverVersion: number;
   /** The current server row, decoded — resolve without a round-trip. */
   readonly serverRow: Readonly<Record<string, RowValue>>;
+  /**
+   * §6.3: the present columns whose `column_version` exceeded the losing
+   * operation's `baseVersion`. A custom merge recomputes exactly these;
+   * keep-server and keep-local ignore them (§6.5).
+   */
+  readonly conflictColumns: readonly string[];
   /** The losing local operation (absent only for malformed op indexes). */
   readonly operation?: OutboxOperation;
 }
@@ -94,8 +100,13 @@ export interface ResolveCommitOutcomeInput {
   readonly replacementClientCommitId?: string;
 }
 
-interface StoredConflictRecord extends Omit<ConflictRecord, 'serverRow'> {
+interface StoredConflictRecord extends Omit<
+  ConflictRecord,
+  'serverRow' | 'conflictColumns'
+> {
   readonly serverRow: Readonly<Record<string, JsonRowValue>>;
+  /** Absent in journal entries written before wire version 3. */
+  readonly conflictColumns?: readonly string[];
 }
 
 type StoredCommitOperationOutcome =
@@ -130,6 +141,8 @@ function decodeResults(raw: string): CommitOperationOutcome[] {
       status: 'conflict',
       conflict: {
         ...result.conflict,
+        // Pre-column-version journal entries carry no conflictColumns.
+        conflictColumns: result.conflict.conflictColumns ?? [],
         serverRow: Object.fromEntries(
           Object.entries(result.conflict.serverRow).map(([key, value]) => [
             key,

package/src/reactive-store.ts

@@ -359,7 +359,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
   #running = false;
   #requested = false;
   #desiredRevision = 0n;
-  #claimReady: Promise<void> = Promise.resolve();
+  #claimError: Error | undefined;
+  #claimPending = false;
   #offStatus: (() => void) | undefined;
 
   constructor(
@@ -397,10 +398,25 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
             ),
           );
         }
-        this.#claimReady = Promise.all(claims).then(() => undefined);
-        // A render can lose its last subscriber before the read loop starts.
-        // The loop still observes the original rejection while it owns the claim.
-        void this.#claimReady.catch(() => undefined);
+        const generation = this.#generation;
+        this.#claimPending = claims.length > 0;
+        if (claims.length > 0)
+          void Promise.all(claims).then(
+            () => {
+              if (generation !== this.#generation || this.#listeners.size === 0)
+                return;
+              this.#claimPending = false;
+              if (!this.#running && this.#state.phase !== 'ready')
+                this.#requestRead();
+            },
+            (error: unknown) => {
+              if (generation !== this.#generation || this.#listeners.size === 0)
+                return;
+              this.#claimPending = false;
+              this.#claimError = errorOf(error);
+              this.#requestRead();
+            },
+          );
       }
       this.#requestRead();
     }
@@ -426,7 +442,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     this.#running = false;
     this.#requested = false;
     this.#desiredRevision = 0n;
-    this.#claimReady = Promise.resolve();
+    this.#claimError = undefined;
+    this.#claimPending = false;
     this.#state = {
       rows: [],
       phase: 'loading',
@@ -520,9 +537,11 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
       do {
         this.#requested = false;
         if (this.store.availabilitySnapshot().state === 'blocked') break;
-        await this.#claimReady;
+
         if (generation !== this.#generation || this.#listeners.size === 0)
           return;
+        if (this.#claimError !== undefined) throw this.#claimError;
+        const claimWasPending = this.#claimPending;
         const snapshot = await this.store.client.querySnapshot<
           Record<string, SqlValue>
         >({
@@ -536,6 +555,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
         });
         if (generation !== this.#generation || this.#listeners.size === 0)
           return;
+        if (this.#claimError !== undefined) throw this.#claimError;
         const availability = this.store.availabilitySnapshot();
         if (availability.state === 'blocked') {
           this.#publish({
@@ -550,6 +570,12 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
           this.#requested = true;
           continue;
         }
+        if (
+          !snapshot.coverage.complete &&
+          claimWasPending &&
+          !this.#claimPending
+        )
+          this.#requested = true;
         const mappedRows =
           this.spec.mapRow === undefined
             ? (snapshot.rows as readonly Row[])
@@ -625,6 +651,8 @@ interface WindowClaimGroup {
   readonly base: WindowBase;
   readonly claims: Map<symbol, ReadonlySet<string>>;
   appliedKey: string;
+  appliedUnits: ReadonlySet<string>;
+  inFlightUnits?: ReadonlySet<string> | undefined;
   scheduled: boolean;
   running: boolean;
   requested: boolean;
@@ -889,6 +917,7 @@ export class ReactiveClientStore {
         base,
         claims: new Map(),
         appliedKey: '',
+        appliedUnits: new Set(),
         scheduled: false,
         running: false,
         requested: false,
@@ -897,6 +926,17 @@ export class ReactiveClientStore {
       this.#windowClaims.set(key, group);
     }
     group.claims.set(owner, new Set(units));
+    const alreadyHeld =
+      units.length > 0 &&
+      units.every(
+        (unit) =>
+          group.appliedUnits.has(unit) &&
+          (group.inFlightUnits === undefined || group.inFlightUnits.has(unit)),
+      );
+    if (alreadyHeld) {
+      this.#scheduleWindow(group);
+      return Promise.resolve();
+    }
     const result = new Promise<void>((resolve, reject) => {
       group?.waiters.push({ resolve, reject });
     });
@@ -932,13 +972,23 @@ export class ReactiveClientStore {
         ].sort();
         const key = canonicalValue(units);
         if (key !== group.appliedKey) {
-          await this.client.setWindow(group.base, units);
+          group.inFlightUnits = new Set(units);
+          try {
+            await this.client.setWindow(group.base, units);
+          } finally {
+            group.inFlightUnits = undefined;
+          }
           if (this.#windowClaims.get(baseKey) !== group) return;
           group.appliedKey = key;
+          group.appliedUnits = new Set(units);
         }
       }
       for (const waiter of group.waiters.splice(0)) waiter.resolve();
     } catch (error) {
+      // A failed window edit may already have committed its first eviction chunk.
+      // Reconcile through the core before acknowledging any later claim.
+      group.appliedKey = '';
+      group.appliedUnits = new Set();
       for (const waiter of group.waiters.splice(0)) waiter.reject(error);
     } finally {
       group.running = false;

package/src/remote.ts

@@ -9,7 +9,8 @@ import {
   encodeMessage,
   encodeRemoteOperationRequest,
   encodeRemoteOperationRealtimeMessage,
-  encodeRow,
+  encodeSparseRow,
+  PROTOCOL_WIRE_VERSION,
   type PushOperation,
   type PushOperationResult,
   type PushResultDetailsFrame,
@@ -204,7 +205,8 @@ export class SyncRemoteClient {
     }
   >();
   readonly #encryption: EncryptionConfig | undefined;
-  readonly #logEpoch: string | undefined;
+  /** Pinned by config, or acquired on the first prepared commit (§2.1). */
+  #logEpoch: string | undefined;
 
   constructor(config: SyncRemoteClientConfig) {
     if (config.clientId.length === 0) {
@@ -242,6 +244,53 @@ export class SyncRemoteClient {
         'a remote commit must carry at least one mutation (§6.1)',
       );
     }
+    let logEpoch = this.#logEpoch;
+    if (logEpoch === undefined) {
+      // §2.1: a push round binds to the partition log epoch; an acquisition
+      // round carries no push commits.
+      if (this.#transport === undefined) {
+        throw new ClientSyncError(
+          'client.remote_sync_unconfigured',
+          'SyncRemoteClient has no sync transport for ordinary commits',
+        );
+      }
+      const acquisition = decodeMessage(
+        await this.#transport(
+          encodeMessage({
+            wireVersion: PROTOCOL_WIRE_VERSION,
+            msgKind: 'request',
+            frames: [
+              {
+                type: 'REQ_HEADER',
+                clientId: this.#clientId,
+                schemaVersion: schema.version,
+              },
+              // A pull that asks for nothing: the round exists for its epoch.
+              {
+                type: 'PULL_HEADER',
+                limitCommits: 0,
+                limitSnapshotRows: 0,
+                maxSnapshotPages: 0,
+                accept: 0b0011,
+              },
+            ],
+          }),
+        ),
+      );
+      const acquisitionHeader = acquisition.frames[0];
+      if (
+        acquisition.msgKind !== 'response' ||
+        acquisitionHeader?.type !== 'RESP_HEADER' ||
+        acquisitionHeader.logEpoch === undefined
+      ) {
+        throw new ClientSyncError(
+          'client.invalid_host_response',
+          'remote epoch acquisition returned an invalid response',
+        );
+      }
+      logEpoch = acquisitionHeader.logEpoch;
+      this.#logEpoch = logEpoch;
+    }
     const operations: PushOperation[] = [];
     for (const mutation of input.mutations) {
       const table = schema.tables.get(mutation.table);
@@ -277,22 +326,20 @@ export class SyncRemoteClient {
         ...(mutation.baseVersion !== undefined
           ? { baseVersion: mutation.baseVersion }
           : {}),
-        payload: encodeRow(table.columns, values),
+        payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
       });
     }
     return {
       requestId: input.requestId,
       bytes: encodeMessage({
-        wireVersion: this.#logEpoch === undefined ? 1 : 2,
+        wireVersion: PROTOCOL_WIRE_VERSION,
         msgKind: 'request',
         frames: [
           {
             type: 'REQ_HEADER',
             clientId: this.#clientId,
             schemaVersion: schema.version,
-            ...(this.#logEpoch !== undefined
-              ? { logEpoch: this.#logEpoch }
-              : {}),
+            logEpoch,
           },
           {
             type: 'PUSH_COMMIT',

package/src/schema.ts

@@ -318,6 +318,9 @@ function createSyncedTable(
   db: ClientDatabase,
   table: CompiledClientTable,
 ): void {
+  // §6.11: a declared reference is deliberately NOT emitted here. Windowing
+  // evicts a parent independently of its children, so local SQLite never
+  // enforces a reference; the server enforces it.
   const columns = table.columns.map((column) => {
     const notNull = column.nullable ? '' : ' NOT NULL';
     const pk = column.name === table.primaryKey ? ' PRIMARY KEY' : '';
@@ -374,6 +377,14 @@ function createFtsProjection(
     `CREATE VIRTUAL TABLE IF NOT EXISTS ${quoteIdent(index.name)} USING fts5(${quoteIdent(FTS_SOURCE_ID_COLUMN)} UNINDEXED, ${indexedColumns.join(', ')}, tokenize='${tokenizer}')`,
   );
 
+  const mapping = quoteIdent(`_syncular_fts_${index.name}`);
+  const mapped =
+    db.query("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", [
+      `_syncular_fts_${index.name}`,
+    ]).length > 0;
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS ${mapping} (id INTEGER PRIMARY KEY, source_id TEXT NOT NULL UNIQUE)`,
+  );
   const sourceId = `CAST(${quoteIdent(table.primaryKey)} AS TEXT)`;
   const newSourceId = `CAST(new.${quoteIdent(table.primaryKey)} AS TEXT)`;
   const oldSourceId = `CAST(old.${quoteIdent(table.primaryKey)} AS TEXT)`;
@@ -386,9 +397,10 @@ function createFtsProjection(
     ...index.columns.map((column) => `new.${quoteIdent(column)}`),
   ].join(', ');
   const deleteFor = (value: string) =>
-    `DELETE FROM ${quoteIdent(index.name)} WHERE ${quoteIdent(FTS_SOURCE_ID_COLUMN)} = ${value}`;
+    `DELETE FROM ${quoteIdent(index.name)} WHERE rowid = (SELECT id FROM ${mapping} WHERE source_id = ${value}); DELETE FROM ${mapping} WHERE source_id = ${value}`;
   const deleteDisplaced = (select: string) =>
-    `DELETE FROM ${quoteIdent(index.name)} WHERE ${quoteIdent(FTS_SOURCE_ID_COLUMN)} IN (${select})`;
+    `DELETE FROM ${quoteIdent(index.name)} WHERE rowid IN (SELECT id FROM ${mapping} WHERE source_id IN (${select})); DELETE FROM ${mapping} WHERE source_id IN (${select})`;
+  const insertNew = `INSERT INTO ${mapping}(source_id) VALUES (${newSourceId}); INSERT INTO ${quoteIdent(index.name)} (rowid, ${projectionColumns}) VALUES ((SELECT id FROM ${mapping} WHERE source_id = ${newSourceId}), ${newValues})`;
 
   // A clean insert cannot already have a projection row because the source
   // primary key is unique. Keep clean inserts linear by moving replacement
@@ -441,13 +453,13 @@ function createFtsProjection(
     `CREATE TRIGGER ${quoteIdent(`${index.name}_bi`)} BEFORE INSERT ON ${quoteIdent(table.name)} WHEN ${insertGuardCondition} BEGIN ${insertGuardBody}; END`,
   );
   db.exec(
-    `CREATE TRIGGER ${quoteIdent(`${index.name}_ai`)} AFTER INSERT ON ${quoteIdent(table.name)} BEGIN INSERT INTO ${quoteIdent(index.name)} (${projectionColumns}) VALUES (${newValues}); END`,
+    `CREATE TRIGGER ${quoteIdent(`${index.name}_ai`)} AFTER INSERT ON ${quoteIdent(table.name)} BEGIN ${insertNew}; END`,
   );
   db.exec(
     `CREATE TRIGGER ${quoteIdent(`${index.name}_ad`)} AFTER DELETE ON ${quoteIdent(table.name)} BEGIN ${deleteFor(oldSourceId)}; END`,
   );
   db.exec(
-    `CREATE TRIGGER ${quoteIdent(`${index.name}_au`)} AFTER UPDATE ON ${quoteIdent(table.name)} BEGIN ${deleteFor(oldSourceId)}; ${deleteFor(newSourceId)}; INSERT INTO ${quoteIdent(index.name)} (${projectionColumns}) VALUES (${newValues}); END`,
+    `CREATE TRIGGER ${quoteIdent(`${index.name}_au`)} AFTER UPDATE ON ${quoteIdent(table.name)} BEGIN ${deleteFor(oldSourceId)}; ${deleteFor(newSourceId)}; ${insertNew}; END`,
   );
   // BEFORE UPDATE guard for `UPDATE OR REPLACE`: clear the projection of any
   // different-PK row about to be displaced through a secondary unique index by
@@ -468,6 +480,12 @@ function createFtsProjection(
       `INSERT INTO ${quoteIdent(index.name)} (${projectionColumns}) SELECT ${sourceId}, ${indexedColumns.join(', ')} FROM ${quoteIdent(table.name)}`,
     );
   }
+  if (!mapped || !existed) {
+    db.exec(`DELETE FROM ${mapping}`);
+    db.exec(
+      `INSERT INTO ${mapping}(id, source_id) SELECT rowid, ${quoteIdent(FTS_SOURCE_ID_COLUMN)} FROM ${quoteIdent(index.name)}`,
+    );
+  }
 }
 
 /**
@@ -602,6 +620,9 @@ export function dropAndRecreateSyncedTables(
        AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%'`,
   );
   for (const row of virtualTables) {
+    db.exec(
+      `DROP TABLE IF EXISTS ${quoteIdent(`_syncular_fts_${String(row.name)}`)}`,
+    );
     db.exec(`DROP TABLE IF EXISTS ${quoteIdent(String(row.name))}`);
   }
   const existing = db.query(
@@ -698,7 +719,10 @@ export function normalizeRecordKeys(
  * may surface integers as bigint. Anything else passes through untouched —
  * the codec still fails loud on genuine type garbage at encode time.
  */
-function coerceSqlRepresentation(column: RowColumn, value: unknown): unknown {
+export function coerceSqlRepresentation(
+  column: RowColumn,
+  value: unknown,
+): unknown {
   switch (localColumnType(column)) {
     case 'boolean':
       return value === 0 ? false : value === 1 ? true : value;

package/src/wasm-database.ts

@@ -151,9 +151,13 @@ class WasmClientDatabase implements ClientDatabase {
    * §5.3 image import at near-file-copy speed: attach an empty in-memory
    * schema, then `sqlite3_deserialize` the image bytes into it (the
    * documented sqlite-wasm import path — no OPFS round-trip, no SQL-level
-   * row shuttling before the single INSERT…SELECT the caller runs).
+   * row shuttling before the chunked INSERT…SELECT statements the caller runs).
    */
-  withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T {
+  async withSqliteImage<T>(
+    bytes: Uint8Array,
+    alias: string,
+    fn: () => T | Promise<T>,
+  ): Promise<T> {
     assertImageAlias(alias);
     const pointer = this.#db.pointer;
     if (pointer === undefined) {
@@ -182,7 +186,7 @@ class WasmClientDatabase implements ClientDatabase {
           `sqlite3_deserialize failed with code ${rc} (§5.3)`,
         );
       }
-      return fn();
+      return await fn();
     } finally {
       this.exec(`DETACH ${alias}`);
     }