@syncular/client 0.30.11 → 0.30.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.30.11",
+  "version": "0.30.12",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.30.11"
+    "@syncular/core": "0.30.12"
   },
   "devDependencies": {
-    "@syncular/server": "0.30.11",
+    "@syncular/server": "0.30.12",
     "playwright": "1.63.0",
     "@electric-sql/pglite": "^0.5.4"
   }

package/src/apply.ts

@@ -1,3 +1,4 @@
+import { RETAINED_ROWS } from './failed-overlay';
 import { retainedBaseWrite, restoreFailedBases } from './failed-overlay';
 /**
  * Local application of server data: `COMMIT` frames (§4.5), rows segments
@@ -19,6 +20,8 @@ import {
   type CompiledClientSchema,
   type CompiledClientTable,
   quoteIdent,
+  matchesLocalScopes,
+  type JsonRowValue,
   SYNC_VERSION_COLUMN,
   toSqlValue,
   rowValueToJson,
@@ -93,7 +96,8 @@ export async function applyCommitFrame(
   schema: CompiledClientSchema,
   frame: CommitFrame,
   encryption?: EncryptionConfig,
-  transaction: ApplyTransaction = (fn) => db.transaction(fn),
+  transaction: (fn: () => readonly string[] | undefined) => unknown = (fn) =>
+    db.transaction(fn),
 ): Promise<void> {
   type Resolved =
     | { op: 'delete'; table: CompiledClientTable; rowId: string }
@@ -138,14 +142,31 @@ export async function applyCommitFrame(
     });
   }
   transaction(() => {
-    restoreFailedBases(db, schema);
-    for (const change of resolved) {
+    const rowKeys = frame.tables.some((name) =>
+      schema.tables.get(name)?.indexes.some((index) => index.unique),
+    )
+      ? undefined
+      : frame.changes.map((change) =>
+          JSON.stringify([frame.tables[change.tableIndex], change.rowId]),
+        );
+    restoreFailedBases(db, schema, false, rowKeys);
+    for (const [index, change] of resolved.entries()) {
+      const rowId = frame.changes[index]!.rowId;
+      db.exec(
+        "UPDATE _syncular_outbox_before_images SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE (client_commit_id,op_index) IN(SELECT client_commit_id,json_each.key FROM _syncular_outbox,json_each(operations) WHERE json_extract(value,'$.table')=? AND json_extract(value,'$.rowId')=?)",
+        [frame.commitSeq, change.table.name, rowId],
+      );
+      db.exec(
+        `DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`,
+        [change.table.name, rowId, frame.commitSeq],
+      );
       if (change.op === 'delete') {
         deleteLocalRow(db, change.table, change.rowId);
       } else {
         upsertLocalRow(db, change.table, change.values, change.rowVersion);
       }
     }
+    return rowKeys;
   });
 }
 
@@ -195,39 +216,43 @@ export function validateSegmentColumns(
  * (`sync.scope_revoked`) when the table has no local mapping for a key:
  * precision or nothing, never clear-the-table.
  */
+export function localScopePredicate(
+  table: CompiledClientTable,
+  effective: ScopeMap,
+): { sql: string; params: string[] } | undefined {
+  const entries = Object.entries(effective);
+  if (!entries.length || entries.some(([, values]) => !values.length)) return;
+  const params: string[] = [];
+  const sql = entries
+    .map(([variable, values]) => {
+      const column = table.scopeColumnByVariable.get(variable);
+      if (column === undefined)
+        throw new ClientSyncError(
+          'sync.scope_revoked',
+          'table has no local scope-column mapping',
+        );
+      params.push(...values);
+      return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
+    })
+    .join(' AND ');
+  return { sql, params };
+}
+
 export function deleteScopedRows(
   db: ClientDatabase,
   table: CompiledClientTable,
   effective: ScopeMap,
 ): void {
-  const entries = Object.entries(effective);
-  if (entries.length === 0) return;
-  const clauses: string[] = [];
-  const params: string[] = [];
-  for (const [variable, values] of entries) {
-    const column = table.scopeColumnByVariable.get(variable);
-    if (column === undefined) {
-      throw new ClientSyncError(
-        'sync.scope_revoked',
-        `table ${JSON.stringify(table.name)} has no local scope-column mapping for ${JSON.stringify(variable)} (§3.3 fail-closed)`,
-      );
-    }
-    if (values.length === 0) return;
-    clauses.push(
-      `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`,
-    );
-    params.push(...values);
-  }
+  const scope = localScopePredicate(table, effective);
+  if (!scope) return;
+  const { sql, params } = scope;
   for (const row of db.query(
-    `SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}`,
+    `SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${sql}`,
     params,
   )) {
     retainedBaseWrite(db, table, String(row.id));
   }
-  db.exec(
-    `DELETE FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}`,
-    params,
-  );
+  db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${sql}`, params);
 }
 
 /**
@@ -246,24 +271,9 @@ export function evictScopedRows(
   effective: ScopeMap,
   pinnedRowIds: ReadonlySet<string>,
 ): { remaining: boolean; deferred: boolean } {
-  const entries = Object.entries(effective);
-  if (entries.length === 0) return { remaining: false, deferred: false };
-  const clauses: string[] = [];
-  const params: string[] = [];
-  for (const [variable, values] of entries) {
-    const column = table.scopeColumnByVariable.get(variable);
-    if (column === undefined) {
-      throw new ClientSyncError(
-        'sync.scope_revoked',
-        `table ${JSON.stringify(table.name)} has no local scope-column mapping for ${JSON.stringify(variable)} (§4.8/§3.3 fail-closed)`,
-      );
-    }
-    if (values.length === 0) return { remaining: false, deferred: false };
-    clauses.push(
-      `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`,
-    );
-    params.push(...values);
-  }
+  const scope = localScopePredicate(table, effective);
+  if (!scope) return { remaining: false, deferred: false };
+  const { sql, params } = scope;
   const pk = quoteIdent(table.primaryKey);
   let pinnedClause = '';
   if (pinnedRowIds.size > 0) {
@@ -272,19 +282,40 @@ export function evictScopedRows(
     params.push(...ids);
   }
   const target = quoteIdent(table.name);
+  for (const row of db.query(
+    `SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl=?`,
+    [table.name],
+  )) {
+    if (
+      !pinnedRowIds.has(row.id as string) &&
+      [row.intent, row.base].some(
+        (json) =>
+          json !== null &&
+          matchesLocalScopes(
+            table,
+            effective,
+            JSON.parse(json as string) as Record<string, JsonRowValue>,
+          ),
+      )
+    )
+      db.exec(
+        `DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq IS NOT NULL`,
+        [table.name, row.id as string],
+      );
+  }
   db.exec(
-    `DELETE FROM ${target} WHERE ${pk} IN(SELECT ${pk} FROM ${target} WHERE ${clauses.join(' AND ')}${pinnedClause} LIMIT 1024)`,
+    `DELETE FROM ${target} WHERE ${pk} IN(SELECT ${pk} FROM ${target} WHERE ${sql}${pinnedClause} LIMIT 1024)`,
     params,
   );
   const remaining =
     db.query(
-      `SELECT 1 FROM ${target} WHERE ${clauses.join(' AND ')}${pinnedClause} LIMIT 1`,
+      `SELECT 1 FROM ${target} WHERE ${sql}${pinnedClause} LIMIT 1`,
       params,
     ).length > 0;
   const deferred =
     remaining ||
     db.query(
-      `SELECT 1 FROM ${target} WHERE ${clauses.join(' AND ')} LIMIT 1`,
+      `SELECT 1 FROM ${target} WHERE ${sql} LIMIT 1`,
       params.slice(0, params.length - pinnedRowIds.size),
     ).length > 0;
   return { remaining, deferred };
@@ -329,7 +360,7 @@ export async function applySqliteSegment(
   const withImage = db.withSqliteImage?.bind(db);
   if (withImage === undefined) {
     throw invalidRequest(
-      'received a sqlite segment but the database backend cannot import images (§4.2: do not advertise accept bit 2)',
+      'database cannot import images; disable accept bit 2 (§4.2)',
     );
   }
   if (descriptor.table !== table.name) {
@@ -506,12 +537,12 @@ export async function applyRowsSegment(
     first = false;
     if (!clearThisBlock && rows.length === 0) continue;
     (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
-      restoreFailedBases(db, schema);
+      const protectedRows = restoreFailedBases(db, schema);
       if (clearThisBlock) {
         deleteScopedRows(db, table, options.effective);
       }
       for (const row of rows) {
-        upsertLocalRow(db, table, row.values, row.serverVersion);
+        upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
         applied += 1;
         if (applied % 1024 === 0) options.onProgress?.(applied);
       }

package/src/client.ts

@@ -1,3 +1,4 @@
+import { RETAINED_ROWS } from './failed-overlay';
 import {
   dropFailedRows,
   failedOverlayCommits,
@@ -51,6 +52,7 @@ import {
   applySqliteSegment,
   deleteLocalRow,
   deleteScopedRows,
+  localScopePredicate,
   evictScopedRows,
   yieldToHost,
   upsertLocalRow,
@@ -196,6 +198,7 @@ import {
   type CompiledClientSchema,
   type CompiledClientTable,
   compileClientSchema,
+  matchesLocalScopes,
   dropAndRecreateSyncedTables,
   ensureLocalBookkeepingSchema,
   ensureLocalSyncedSchema,
@@ -837,7 +840,7 @@ export class SyncClient {
   constructor(config: SyncClientConfig) {
     if (config.securityPreflight === true && config.encryption !== undefined) {
       throw invalidRequest(
-        'securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight',
+        'securityPreflight and encryption are mutually exclusive; activateSecurity installs keys',
       );
     }
     this.#retainFailedCommits = config.retainFailedCommits === true;
@@ -923,7 +926,7 @@ export class SyncClient {
       this.#lease = undefined;
       throw new ClientSyncError(
         'client.identity_mismatch',
-        `this client database belongs to ${JSON.stringify(persisted)}; refusing to rebind it to ${JSON.stringify(this.#config.clientId)}`,
+        `database clientId ${JSON.stringify(persisted)} differs from ${JSON.stringify(this.#config.clientId)}`,
       );
     }
     this.#clientId = persisted ?? this.#config.clientId ?? crypto.randomUUID();
@@ -961,6 +964,9 @@ export class SyncClient {
     const startupWork =
       this.#schemaFloor === undefined &&
       (countOutbox(this.#db) > 0 ||
+        this.#db.query(
+          `SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`,
+        ).length > 0 ||
         loadPendingEvictions(this.#db).length > 0 ||
         subscriptions.some((sub) => sub.status === 'active'));
     if (startupWork && this.#securityLifecycle === 'active') {
@@ -1060,6 +1066,7 @@ export class SyncClient {
           this.#schema,
           true,
         );
+        this.#discardAcknowledgedRows();
         dropAndRecreateSyncedTables(this.#db, this.#schema);
         resetSubscriptionsForBump(this.#db);
         setMeta(
@@ -1160,6 +1167,7 @@ export class SyncClient {
     this.#sweepPreviousVersionContainer();
     this.#applyBatch((batch) => {
       this.#db.transaction(() => {
+        this.#discardAcknowledgedRows();
         dropAndRecreateSyncedTables(this.#db, this.#schema);
         resetSubscriptionsForBump(this.#db);
         setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
@@ -1981,7 +1989,9 @@ export class SyncClient {
           result = fn(batch);
           if (
             this.#db
-              .query('SELECT DISTINCT tbl FROM _syncular_failed_rows')
+              .query(
+                `SELECT DISTINCT tbl FROM ${RETAINED_ROWS} WHERE commit_seq IS NULL`,
+              )
               .some((row) => batch.hasTable(String(row.tbl)))
           )
             batch.outcomes();
@@ -2327,7 +2337,7 @@ export class SyncClient {
     return this.#applyBatch(
       (batch) => {
         restoreFailedBases(this.#db, this.#schema);
-        this.#db.exec('DELETE FROM _syncular_failed_rows WHERE commit_id=?', [
+        this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_id=?`, [
           input.clientCommitId,
         ]);
         const resolved = persistCommitOutcomeResolution(
@@ -2475,7 +2485,7 @@ export class SyncClient {
       if (!sameIntent) {
         throw new ClientSyncError(
           'client.subscription_intent_mismatch',
-          'subscribe: the subscription id is already registered for a different table, scopes, or params',
+          'subscription id already names different table, scopes, or params',
         );
       }
       return;
@@ -2533,7 +2543,7 @@ export class SyncClient {
     const table = this.#table(base.table);
     if (!table.scopeColumnByVariable.has(base.variable)) {
       throw invalidRequest(
-        `setWindow: table ${JSON.stringify(base.table)} has no scope variable ${JSON.stringify(base.variable)} (§4.8)`,
+        `${base.table}: unknown scope variable ${base.variable} (§4.8)`,
       );
     }
     // Serialize the whole window edit: it spans an `await deriveSubId` between
@@ -2965,26 +2975,13 @@ export class SyncClient {
       return this.#applyBatch((batch) => {
         const targetsByTable = this.#localPurgeTargetsByTable(purge);
         restoreFailedBases(this.#db, this.#schema);
-        const droppedRetained = dropFailedRows(this.#db, (table, values) =>
+        this.#dropRetainedRows(batch, (table, values) =>
           (targetsByTable.get(table) ?? []).some((target) =>
             target.selectors.every((selector) =>
               selector.values.includes(String(values[selector.column])),
             ),
           ),
         );
-        for (const commit of droppedRetained) {
-          batch.conflicts();
-          batch.rejections();
-          this.#conflicts = this.#conflicts.filter(
-            (record) => record.clientCommitId !== commit.clientCommitId,
-          );
-          this.#rejections = this.#rejections.filter(
-            (record) => record.clientCommitId !== commit.clientCommitId,
-          );
-          for (const operation of commit.operations)
-            batch.table(operation.table);
-          batch.outcomes();
-        }
         // Doomed detection runs to fixpoint, matching the Rust core's rule:
         // a commit is doomed when any of its ops touches a base-matching
         // row. Base values only become visible here as rollbacks restore
@@ -3144,6 +3141,7 @@ export class SyncClient {
         this.#upgrading = true;
         this.#needsPull = true;
         batch.status();
+        this.#discardAcknowledgedRows();
         dropAndRecreateSyncedTables(this.#db, this.#schema);
         resetSubscriptionsForBump(this.#db);
         for (const table of this.#schema.tables.values()) {
@@ -4151,6 +4149,7 @@ export class SyncClient {
                 index += 1;
               }
             }
+            const previousNeedsPull = this.#needsPull;
             const conflictCount = this.#conflicts.length;
             const rejectionCount = this.#rejections.length;
             let outboxCount = countOutbox(this.#db);
@@ -4183,11 +4182,12 @@ export class SyncClient {
               },
               () => this.#statusSnapshot(outboxCount),
               (cause) => {
+                this.#needsPull = previousNeedsPull;
                 this.#conflicts.length = conflictCount;
                 this.#rejections.length = rejectionCount;
                 const error = new ClientSyncError(
                   'client.outcome_persistence_failed',
-                  'local commit outcome could not be persisted',
+                  'outcome persistence failed',
                 );
                 error.cause = cause;
                 throw error;
@@ -4485,6 +4485,18 @@ export class SyncClient {
     if (frame.status === 'applied' || frame.status === 'cached') {
       // §6.3: applied and cached both drain the outbox — cached means
       // "already applied, you may have missed the ack".
+      if (frame.commitSeq === undefined)
+        throw new ClientSyncError(
+          'client.invalid_host_response',
+          'ACK lacks a commit sequence',
+        );
+      retainFailedRows(
+        this.#db,
+        commit,
+        listOutboxBeforeImages(this.#db, commit.clientCommitId),
+        frame.commitSeq,
+      );
+      this.#setSyncNeeded(true);
       recordCommitOutcome(this.#db, {
         clientCommitId: frame.clientCommitId,
         status: frame.status,
@@ -4638,12 +4650,7 @@ export class SyncClient {
         this.#applyBatch((batch) => {
           this.#recordCommitChanges(batch, frame);
           const result = fn();
-          if (
-            this.#retainFailedCommits &&
-            this.#db.query('SELECT 1 FROM _syncular_failed_rows LIMIT 1')
-              .length > 0
-          )
-            this.#replayOutbox();
+          this.#replayOutbox(result);
           return result;
         }),
     );
@@ -4695,22 +4702,12 @@ export class SyncClient {
 
   /** Whether a fresh-bootstrap clear would remove at least one local row. */
   #scopedRowsExist(table: CompiledClientTable, effective: ScopeMap): boolean {
-    const entries = Object.entries(effective);
-    if (entries.length === 0) return false;
-    const clauses: string[] = [];
-    const params: string[] = [];
-    for (const [variable, values] of entries) {
-      const column = table.scopeColumnByVariable.get(variable);
-      if (column === undefined || values.length === 0) return false;
-      clauses.push(
-        `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`,
-      );
-      params.push(...values);
-    }
+    const scope = localScopePredicate(table, effective);
     return (
+      scope !== undefined &&
       this.#db.query(
-        `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')} LIMIT 1`,
-        params,
+        `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${scope.sql} LIMIT 1`,
+        scope.params,
       ).length > 0
     );
   }
@@ -4817,7 +4814,7 @@ export class SyncClient {
         // §5.4: MUST NOT start a fetch at/past expiry.
         throw new ClientSyncError(
           'sync.segment_expired',
-          `signed URL for segment ${frame.segmentId} expired before fetch — re-pull mints fresh descriptors (§5.4)`,
+          `segment download grant expired; pull again (§5.4)`,
           true,
         );
       }
@@ -4875,6 +4872,34 @@ export class SyncClient {
             status: 'active',
           }),
         );
+        if (completed) {
+          const table = this.#table(sub.table);
+          const effective = start.effectiveScopes;
+          const covered = this.#db
+            .query(
+              `SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq<=?`,
+              [sub.table, nextCursor],
+            )
+            .filter((row) =>
+              [row.intent, row.base].some((json) => {
+                if (json === null) return false;
+                const values: Record<string, JsonRowValue> = JSON.parse(
+                  String(json),
+                );
+                return matchesLocalScopes(table, effective, values);
+              }),
+            );
+          if (covered.length) {
+            restoreFailedBases(this.#db, this.#schema);
+            for (const row of covered)
+              this.#db.exec(
+                `DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`,
+                [sub.table, String(row.id), nextCursor],
+              );
+            batch.table(sub.table);
+            this.#replayOutbox();
+          }
+        }
         if (completed && registered !== undefined) {
           // A zero-row bootstrap is a window-domain transition, not a fake
           // row/table change (SPEC §4.8 / §7.5).
@@ -4923,29 +4948,12 @@ export class SyncClient {
       ) {
         try {
           restoreFailedBases(this.#db, this.#schema);
-          const droppedRetained = dropFailedRows(
-            this.#db,
+          this.#dropRetainedRows(
+            batch,
             (name, values) =>
               name === table.name &&
-              Object.entries(lastEffective).every(([variable, allowed]) =>
-                allowed.includes(
-                  String(values[table.scopeColumnByVariable.get(variable)!]),
-                ),
-              ),
+              matchesLocalScopes(table, lastEffective, values),
           );
-          for (const commit of droppedRetained) {
-            batch.conflicts();
-            batch.rejections();
-            this.#conflicts = this.#conflicts.filter(
-              (record) => record.clientCommitId !== commit.clientCommitId,
-            );
-            this.#rejections = this.#rejections.filter(
-              (record) => record.clientCommitId !== commit.clientCommitId,
-            );
-            for (const operation of commit.operations)
-              batch.table(operation.table);
-            batch.outcomes();
-          }
           deleteScopedRows(this.#db, table, lastEffective);
           batch.scopeMap(table, lastEffective);
           const pendingById = new Map(
@@ -5229,18 +5237,52 @@ export class SyncClient {
   }
 
   /** Re-apply every pending outbox commit on top of server state (§7.1). */
-  #replayOutbox(): void {
+  #discardAcknowledgedRows(): void {
+    this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL`);
+  }
+
+  #dropRetainedRows(
+    batch: ChangeAccumulator,
+    matches: (
+      table: string,
+      values: Readonly<Record<string, JsonRowValue>>,
+    ) => boolean,
+  ): void {
+    for (const commit of dropFailedRows(this.#db, matches)) {
+      batch.conflicts();
+      batch.rejections();
+      batch.outcomes();
+      this.#conflicts = this.#conflicts.filter(
+        (record) => record.clientCommitId !== commit.clientCommitId,
+      );
+      this.#rejections = this.#rejections.filter(
+        (record) => record.clientCommitId !== commit.clientCommitId,
+      );
+      for (const op of commit.operations) batch.table(op.table);
+    }
+  }
+
+  #replayOutbox(rowKeys?: readonly string[]): void {
+    const acknowledged = failedOverlayCommits(this.#db, true, rowKeys);
     const pending = [
-      ...failedOverlayCommits(this.#db),
-      ...listOutbox(this.#db),
+      ...failedOverlayCommits(this.#db, false, rowKeys),
+      ...listOutbox(this.#db, rowKeys),
     ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
-    if (pending.length === 0) return;
+    if (pending.length === 0 && acknowledged.length === 0) return;
     this.#applyBatch((batch) => {
       this.#db.transaction(() => {
-        restoreFailedBases(this.#db, this.#schema);
-        restoreFailedBases(this.#db, this.#schema, true);
-        for (const commit of pending)
-          this.#applyOperationsLocally(commit.operations, batch, true);
+        restoreFailedBases(this.#db, this.#schema, false, rowKeys);
+        restoreFailedBases(this.#db, this.#schema, true, rowKeys);
+        for (const commit of [...acknowledged, ...pending])
+          this.#applyOperationsLocally(
+            rowKeys === undefined
+              ? commit.operations
+              : commit.operations.filter((op) =>
+                  rowKeys.includes(JSON.stringify([op.table, op.rowId])),
+                ),
+            batch,
+            true,
+          );
       });
     });
   }
@@ -5255,17 +5297,14 @@ export class SyncClient {
   #table(name: string): CompiledClientTable {
     const table = this.#schema.tables.get(name);
     if (table === undefined) {
-      throw new ClientSyncError(
-        'sync.unknown_table',
-        `unknown local table ${JSON.stringify(name)}`,
-      );
+      throw new ClientSyncError('sync.unknown_table', `unknown table ${name}`);
     }
     return table;
   }
 
   #requireStarted(): void {
     if (!this.#started) {
-      throw invalidRequest('SyncClient.start() has not completed');
+      throw invalidRequest('call SyncClient.start() first');
     }
   }
 
@@ -5274,7 +5313,7 @@ export class SyncClient {
     if (this.#securityLifecycle === 'preflight') {
       throw new ClientSyncError(
         SECURITY_PREFLIGHT_REQUIRED_CODE,
-        'the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data',
+        'security preflight must complete before accessing protected data; call activateSecurity',
       );
     }
   }