@syncular/client 0.30.13 → 0.30.15

package/src/client.ts

@@ -1,9 +1,15 @@
+import { BLOB_COMMIT_REFS } from './blob';
+import type { AuthorityReadPolicy, AuthoritySnapshot } from './authority';
+import { hasUniqueIndex } from './schema';
+import { OUTCOMES_TABLE } from './outcomes';
+import { OUTBOX_TABLE } from './outbox';
 import { RETAINED_ROWS } from './failed-overlay';
 import {
   dropFailedRows,
   failedOverlayCommits,
   retainFailedRows,
   restoreFailedBases,
+  type OverlayScope,
   uniqueConflicts,
 } from './failed-overlay';
 import {
@@ -419,6 +425,7 @@ export interface SyncClientConfig {
    * hosts must not materialize key bytes before their preflight has passed.
    */
   readonly securityPreflight?: boolean;
+  readonly authorityReads?: AuthorityReadPolicy;
   /**
    * RFC 0005 previous-version context. A feature flag, default off: when
    * absent or `enabled: false`, a schema bump behaves exactly as 0.22.0 did
@@ -741,6 +748,7 @@ export type ClientSnapshotReader = {
 
 export class SyncClient {
   readonly #config: SyncClientConfig;
+  readonly #authorityReads: AuthorityReadPolicy | undefined;
   readonly #db: ClientDatabase;
   readonly #schema: CompiledClientSchema;
   /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
@@ -855,6 +863,8 @@ export class SyncClient {
     this.#retainFailedCommits = config.retainFailedCommits === true;
     this.#db = config.database;
     this.#schema = compileClientSchema(config.schema);
+    this.#authorityReads = config.authorityReads;
+    this.#authorityReads?.validate(this.#schema);
     const realtimePolicy = config.realtimePolicy ?? 'optional';
     if (
       realtimePolicy !== 'required' &&
@@ -1168,6 +1178,13 @@ export class SyncClient {
 
   /** §2.1 reset after the server reports a different log continuity. */
   #runLogEpochReset(logEpoch: string): string[] {
+    if (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined) {
+      this.#applyBatch(() => setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch));
+      this.#setSyncNeeded(true);
+      this.#emitSyncNeeded('startup');
+      this.#emitSyncIntent({ kind: 'interactive' });
+      return [];
+    }
     const subscriptions = loadSubscriptions(this.#db);
     const pending = listOutbox(this.#db);
     this.#setUpgrading(true);
@@ -1220,6 +1237,7 @@ export class SyncClient {
   }
 
   async close(): Promise<void> {
+    this.#started = false;
     this.#emitSyncIntent({ kind: 'none' });
     this.#devtoolsUnregister?.();
     this.#devtoolsUnregister = undefined;
@@ -1227,7 +1245,6 @@ export class SyncClient {
     this.#abortPendingRound('client closed mid-round');
     await this.#lease?.release();
     this.#lease = undefined;
-    this.#started = false;
     this.#progress.clear();
     this.#syncNeededListeners.clear();
     this.#syncIntentListeners.clear();
@@ -1386,6 +1403,17 @@ export class SyncClient {
     return getLocalRevision(this.#db);
   }
 
+  /** Read the creation-time plain authority policy, including preflight. */
+  authoritySnapshot(): AuthoritySnapshot {
+    this.#requireStarted();
+    if (!this.#authorityReads || arguments.length)
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authority read denied',
+      );
+    return this.#authorityReads.snapshot(this.#db, this.#schema);
+  }
+
   /**
    * Read rows, window answerability, and revision from one SQLite snapshot.
    * Reactive integrations use this instead of composing `query()` and
@@ -1406,28 +1434,11 @@ export class SyncClient {
         const missing: WindowUnitRef[] = [];
         for (const requested of spec.coverage ?? []) {
           const baseKey = windowBaseKey(requested.base);
-          const live = new Map(
-            loadWindowUnits(this.#db, baseKey).map((entry) => [
-              entry.unit,
-              entry.subId,
-            ]),
-          );
+          const state = this.windowState(requested.base);
           for (const unit of new Set(requested.units)) {
-            const subId = live.get(unit);
             const ref = { baseKey, unit };
-            if (subId === undefined) {
-              missing.push(ref);
-              continue;
-            }
-            const sub = getSubscription(this.#db, subId);
-            if (
-              sub === undefined ||
-              sub.status !== 'active' ||
-              sub.cursor < 0 ||
-              sub.bootstrapState !== undefined
-            ) {
-              pending.push(ref);
-            }
+            if (!state.units.includes(unit)) missing.push(ref);
+            else if (state.pending.includes(unit)) pending.push(ref);
           }
         }
         return {
@@ -1805,7 +1816,7 @@ export class SyncClient {
         item.table.length === 0
       ) {
         throw invalidRequest(
-          'diagnosticsSnapshot expected subscriptions require non-empty id and table strings',
+          'diagnosticsSnapshot needs subscription id and table',
         );
       }
       const registeredSubscription = subscriptions.get(item.id);
@@ -1917,11 +1928,11 @@ export class SyncClient {
       );
       const outboxBytes = Number(
         this.#db.query(
-          'SELECT COALESCE(SUM(LENGTH(operations)),0)AS bytes FROM _syncular_outbox',
+          `SELECT COALESCE(SUM(LENGTH(operations)),0)AS bytes FROM ${OUTBOX_TABLE}`,
         )[0]?.bytes ?? 0,
       );
       const outcome = this.#db.query(
-        'SELECT COUNT(*)AS entries,COALESCE(SUM(LENGTH(results)+ COALESCE(LENGTH(operations),0)),0)AS bytes FROM _syncular_commit_outcomes',
+        `SELECT COUNT(*)AS entries,COALESCE(SUM(LENGTH(results)+ COALESCE(LENGTH(operations),0)),0)AS bytes FROM ${OUTCOMES_TABLE}`,
       )[0];
       const blobBytes = this.#hasBlobs
         ? Number(
@@ -2894,7 +2905,7 @@ export class SyncClient {
               continue;
             }
             this.#db.exec(
-              'INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id,blob_id)SELECT ?,? WHERE EXISTS(SELECT 1 FROM _syncular_blobs WHERE blob_id=?)',
+              `INSERT OR IGNORE INTO ${BLOB_COMMIT_REFS}(commit_id,blob_id)SELECT ?,? WHERE EXISTS(SELECT 1 FROM _syncular_blobs WHERE blob_id=?)`,
               [clientCommitId, blobId, blobId],
             );
           }
@@ -3158,9 +3169,7 @@ export class SyncClient {
       };
     }
     if (this.#schemaFloor !== undefined) {
-      throw invalidRequest(
-        'local rebootstrap cannot bypass an active schema-floor stop; update the application first',
-      );
+      throw invalidRequest('local rebootstrap needs a schema-floor update');
     }
 
     const pending = listOutbox(this.#db);
@@ -3295,7 +3304,7 @@ export class SyncClient {
     // Pin before the first encryption await: mutations can append while a
     // round is encoding, and belong to the next request.
     const bounds = this.#db.query(
-      'SELECT COUNT(*)AS count,MAX(seq)AS last_seq FROM _syncular_outbox',
+      `SELECT COUNT(*)AS count,MAX(seq)AS last_seq FROM ${OUTBOX_TABLE}`,
     )[0]!;
     const pendingCount = bounds.count as number;
     const throughSeq = (bounds.last_seq as number | null) ?? 0;
@@ -4398,13 +4407,7 @@ export class SyncClient {
         if (errorFrame !== undefined) break;
       }
     } finally {
-      try {
-        // §7.1: local reads see outbox state applied optimistically — replay
-        // the still-pending commits on top of the freshly applied server state.
-        this.#replayOutbox();
-      } finally {
-        this.#endDiagnosticsDeferral();
-      }
+      this.#endDiagnosticsDeferral();
     }
 
     if (errorFrame !== undefined) throw errorFrame;
@@ -4558,6 +4561,15 @@ export class SyncClient {
           listOutboxBeforeImages(this.#db, commit.clientCommitId),
         );
       this.#rollbackFailedCommit(commit, batch);
+      this.#replayOutbox(
+        commit.operations.map((operation) =>
+          JSON.stringify(
+            hasUniqueIndex(this.#table(operation.table))
+              ? [operation.table]
+              : [operation.table, operation.rowId],
+          ),
+        ),
+      );
     });
     batch.status();
     summary.rejected.push(frame.clientCommitId);
@@ -4567,7 +4579,7 @@ export class SyncClient {
   #outboxCommitExists(clientCommitId: string): boolean {
     return (
       this.#db.query(
-        'SELECT 1 FROM _syncular_outbox WHERE client_commit_id=? LIMIT 1',
+        `SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`,
         [clientCommitId],
       ).length > 0
     );
@@ -4621,7 +4633,7 @@ export class SyncClient {
         this.#applyBatch((batch) => {
           this.#recordCommitChanges(batch, frame);
           const result = fn();
-          this.#replayOutbox(result);
+          this.#replayOutbox(result, false);
           return result;
         }),
     );
@@ -4704,7 +4716,7 @@ export class SyncClient {
           )
             batch.table(table.name);
           const result = fn();
-          this.#replayOutbox();
+          this.#replayOutbox(result, false);
           return result;
         }),
     };
@@ -4888,14 +4900,17 @@ export class SyncClient {
               }),
             );
           if (covered.length) {
-            restoreFailedBases(this.#db, this.#schema);
+            const scope = covered.map((row) =>
+              JSON.stringify([sub.table, String(row.id)]),
+            );
+            restoreFailedBases(this.#db, this.#schema, scope);
             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();
+            this.#replayOutbox(scope, false);
           }
         }
         if (completed && registered !== undefined) {
@@ -4945,13 +4960,15 @@ export class SyncClient {
         Object.keys(lastEffective).length > 0
       ) {
         try {
-          restoreFailedBases(this.#db, this.#schema);
-          this.#dropRetainedRows(
-            batch,
-            (name, values) =>
-              name === table.name &&
-              matchesLocalScopes(table, lastEffective, values),
-          );
+          const scope = [
+            JSON.stringify([table.name]),
+            ...this.#dropRetainedRows(
+              batch,
+              (name, values) =>
+                name === table.name &&
+                matchesLocalScopes(table, lastEffective, values),
+            ),
+          ];
           deleteScopedRows(this.#db, table, lastEffective);
           batch.scopeMap(table, lastEffective);
           const pendingById = new Map(
@@ -4997,6 +5014,7 @@ export class SyncClient {
             batch.rejections();
             batch.outcomes();
           }
+          this.#replayOutbox(scope);
           this.#deleteUnreferencedBlobs();
         } catch (error) {
           if (
@@ -5217,7 +5235,7 @@ export class SyncClient {
           : (local[SYNC_VERSION_COLUMN] as number);
       if (
         replay &&
-        table.indexes.some((index) => index.unique) &&
+        hasUniqueIndex(table) &&
         uniqueConflicts(
           this.#db,
           table,
@@ -5245,8 +5263,9 @@ export class SyncClient {
       table: string,
       values: Readonly<Record<string, JsonRowValue>>,
     ) => boolean,
-  ): void {
-    for (const commit of dropFailedRows(this.#db, matches)) {
+  ): string[] {
+    const scope: string[] = [];
+    for (const commit of dropFailedRows(this.#db, this.#schema, matches)) {
       batch.conflicts();
       batch.rejections();
       batch.outcomes();
@@ -5256,32 +5275,39 @@ export class SyncClient {
       this.#rejections = this.#rejections.filter(
         (record) => record.clientCommitId !== commit.clientCommitId,
       );
-      for (const op of commit.operations) batch.table(op.table);
+      for (const op of commit.operations) {
+        batch.table(op.table);
+        scope.push(JSON.stringify([op.table, op.rowId]));
+      }
     }
+    return scope;
   }
 
-  #replayOutbox(rowKeys?: readonly string[]): void {
-    const acknowledged = failedOverlayCommits(this.#db, true, rowKeys);
-    const pending = [
-      ...failedOverlayCommits(this.#db, false, rowKeys),
-      ...listOutbox(this.#db, rowKeys),
-    ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
-    if (pending.length === 0 && acknowledged.length === 0) return;
+  #replayOutbox(scope?: OverlayScope, restoreBases = true): void {
+    if (scope?.length === 0) return;
     this.#applyBatch((batch) => {
-      this.#db.transaction(() => {
-        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,
-          );
-      });
+      if (restoreBases) restoreFailedBases(this.#db, this.#schema, scope);
+      const acknowledged = failedOverlayCommits(
+        this.#db,
+        true,
+        scope,
+        this.#schema,
+      );
+      const pending = [
+        ...failedOverlayCommits(this.#db, false, scope, this.#schema),
+        ...listOutbox(this.#db, scope),
+      ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
+      for (const commit of [...acknowledged, ...pending])
+        this.#applyOperationsLocally(
+          commit.operations.filter(
+            (op) =>
+              scope === undefined ||
+              scope.includes(JSON.stringify([op.table, op.rowId])) ||
+              scope.includes(JSON.stringify([op.table])),
+          ),
+          batch,
+          true,
+        );
     });
   }
 
@@ -5302,7 +5328,7 @@ export class SyncClient {
 
   #requireStarted(): void {
     if (!this.#started) {
-      throw invalidRequest('call SyncClient.start() first');
+      throw invalidRequest('call start() first');
     }
   }
 
@@ -5311,7 +5337,7 @@ export class SyncClient {
     if (this.#securityLifecycle === 'preflight') {
       throw new ClientSyncError(
         SECURITY_PREFLIGHT_REQUIRED_CODE,
-        'security preflight must complete before accessing protected data; call activateSecurity',
+        'protected reads require activateSecurity',
       );
     }
   }

package/src/failed-overlay.ts

@@ -1,3 +1,6 @@
+import { hasUniqueIndex } from './schema';
+import { OUTCOMES_TABLE } from './outcomes';
+import { OUTBOX_TABLE } from './outbox';
 export const RETAINED_ROWS = '_syncular_failed_rows';
 import { ClientSyncError } from './errors';
 import type { ClientDatabase } from './database';
@@ -48,7 +51,7 @@ export function retainedBaseWrite(
     table.name,
     rowId,
   ]);
-  if (!table.indexes.some((index) => index.unique)) return;
+  if (!hasUniqueIndex(table)) return;
   for (const retained of db.query(
     `SELECT commit_id,idx,intent,unique_conflicts FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq IS NULL`,
     [table.name],
@@ -164,90 +167,51 @@ export function uniqueConflicts(
     );
 }
 
-function retainedRows(db: ClientDatabase, rowKeys?: readonly string[]) {
+/** Exact row keys are JSON [table,id]; table scopes include unique-key peers. */
+export type OverlayScope = readonly string[];
+
+export function overlayScopePredicate(table: string, id: string): string {
+  return `?1 IS NULL OR json_array(${table},${id}) IN(SELECT value FROM json_each(?1)) OR json_array(${table}) IN(SELECT value FROM json_each(?1))`;
+}
+
+function retainedRows(
+  db: ClientDatabase,
+  scope?: OverlayScope,
+  acknowledged?: boolean,
+) {
   return db.query(
-    `SELECT * FROM ${RETAINED_ROWS} WHERE ?1 IS NULL OR json_array(tbl,id) IN(SELECT value FROM json_each(?1)) ORDER BY commit_seq,at,commit_id,idx`,
-    [rowKeys ? JSON.stringify(rowKeys) : null],
+    `SELECT * FROM ${RETAINED_ROWS} WHERE (${overlayScopePredicate('tbl', 'id')})${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
+    [scope ? JSON.stringify(scope) : null],
   );
 }
 
+function retainedTable(
+  schema: CompiledClientSchema,
+  name: string,
+): CompiledClientTable {
+  const table = schema.tables.get(name);
+  if (!table)
+    throw new ClientSyncError(
+      'sync.unknown_table',
+      'retained table is unknown',
+    );
+  return table;
+}
+
 export function restoreFailedBases(
   db: ClientDatabase,
   schema: CompiledClientSchema,
-  absentIntent = false,
-  rowKeys?: readonly string[],
+  scope?: OverlayScope,
 ): boolean {
   const seen = new Set<string>();
-  for (const row of retainedRows(db, rowKeys)) {
+  for (const row of retainedRows(db, scope)) {
     const key = JSON.stringify([row.tbl, row.id]);
-    if (!absentIntent && seen.has(key)) continue;
+    if (seen.has(key)) continue;
     seen.add(key);
-    const table = schema.tables.get(row.tbl as string);
-    if (!table)
-      throw new ClientSyncError(
-        'sync.unknown_table',
-        'retained table is unknown',
-      );
-    const json = absentIntent ? row.intent : row.base;
-    if (absentIntent && row.intent !== null) {
-      const values: Record<string, JsonRowValue> = JSON.parse(
-        row.intent as string,
-      );
-      const conflicts = uniqueConflicts(
-        db,
-        table,
-        mapRowValues(values, jsonToRowValue),
-      );
-      // Hydrate a pre-0.30.11 failure after its winner was already imported.
-      // Pending and retained overlays cannot supply authoritative row evidence.
-      if (row.commit_seq === null && row.unique_conflicts === null) {
-        const authorized = conflicts.filter(
-          (conflict) =>
-            conflict.serverVersion >= 0 &&
-            !db.query(
-              `SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM _syncular_outbox,json_each(operations)WHERE json_extract(json_each.value,'$.table')=? AND json_extract(json_each.value,'$.rowId')=? LIMIT 1`,
-              [table.name, conflict.rowId, table.name, conflict.rowId],
-            ).length,
-        );
-        if (authorized.length)
-          db.exec(
-            `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`,
-            [
-              JSON.stringify(
-                authorized.map((conflict) => ({
-                  ...conflict,
-                  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
-                })),
-              ),
-              row.commit_id as string,
-              row.idx as number,
-            ],
-          );
-      }
-      if (conflicts.length) continue;
-    }
-    if (
-      absentIntent &&
-      (json === null ||
-        db.query(
-          `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
-          [row.id as string],
-        ).length)
-    )
-      continue;
-    if (json === null) deleteLocalRow(db, table, row.id as string, false);
+    const table = retainedTable(schema, row.tbl as string);
+    if (row.base === null) deleteLocalRow(db, table, row.id as string, false);
     else {
-      const values: Record<string, JsonRowValue> = JSON.parse(String(json));
-      if (absentIntent) {
-        const operation: OutboxOperation = JSON.parse(row.op as string);
-        if (
-          row.commit_seq === null &&
-          !table.columns.every((column) =>
-            Object.hasOwn(operation.values ?? {}, column.name),
-          )
-        )
-          continue;
-      }
+      const values: Record<string, JsonRowValue> = JSON.parse(String(row.base));
       upsertLocalRow(
         db,
         table,
@@ -265,7 +229,8 @@ export function restoreFailedBases(
 export function failedOverlayCommits(
   db: ClientDatabase,
   acknowledged = false,
-  rowKeys?: readonly string[],
+  scope?: OverlayScope,
+  schema?: CompiledClientSchema,
 ): OutboxCommit[] {
   const commits = new Map<
     string,
@@ -276,10 +241,55 @@ export function failedOverlayCommits(
       operations: OutboxOperation[];
     }
   >();
-  for (const row of retainedRows(db, rowKeys)) {
-    if ((row.commit_seq !== null) !== acknowledged) continue;
+  for (const row of retainedRows(db, scope, acknowledged)) {
     const id = row.commit_id as string;
-    const operation: OutboxOperation = JSON.parse(row.op as string);
+    let operation: OutboxOperation = JSON.parse(row.op as string);
+    if (schema && operation.op === 'upsert') {
+      const table = retainedTable(schema, operation.table);
+      if (acknowledged) {
+        if (
+          !db.query(
+            `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
+            [operation.rowId],
+          ).length
+        )
+          operation = {
+            ...operation,
+            values: JSON.parse(row.intent as string),
+          };
+      } else if (row.unique_conflicts === null && row.intent !== null) {
+        // Hydrate legacy failure evidence from authoritative unique-key peers.
+        const values: Record<string, JsonRowValue> = JSON.parse(
+          row.intent as string,
+        );
+        const authorized = uniqueConflicts(
+          db,
+          table,
+          mapRowValues(values, jsonToRowValue),
+        ).filter(
+          (conflict) =>
+            conflict.serverVersion >= 0 &&
+            !db.query(
+              `SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_TABLE},json_each(operations)WHERE json_extract(json_each.value,'$.table')=? AND json_extract(json_each.value,'$.rowId')=? LIMIT 1`,
+              [table.name, conflict.rowId, table.name, conflict.rowId],
+            ).length,
+        );
+        if (authorized.length)
+          db.exec(
+            `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`,
+            [
+              JSON.stringify(
+                authorized.map((conflict) => ({
+                  ...conflict,
+                  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
+                })),
+              ),
+              row.commit_id as string,
+              row.idx as number,
+            ],
+          );
+      }
+    }
     const prior = commits.get(id);
     if (prior) prior.operations.push(operation);
     else
@@ -295,6 +305,7 @@ export function failedOverlayCommits(
 
 export function dropFailedRows(
   db: ClientDatabase,
+  schema: CompiledClientSchema,
   matches: (
     table: string,
     values: Readonly<Record<string, JsonRowValue>>,
@@ -312,10 +323,17 @@ export function dropFailedRows(
     ...failedOverlayCommits(db),
     ...failedOverlayCommits(db, true),
   ].filter((commit) => ids.has(commit.clientCommitId));
+  restoreFailedBases(
+    db,
+    schema,
+    dropped.flatMap((commit) =>
+      commit.operations.map((op) => JSON.stringify([op.table, op.rowId])),
+    ),
+  );
   for (const id of ids) {
     db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_id=?`, [id]);
     db.exec(
-      "UPDATE _syncular_commit_outcomes SET operations=NULL,results='[]' WHERE client_commit_id=?",
+      `UPDATE ${OUTCOMES_TABLE} SET operations=NULL,results='[]' WHERE client_commit_id=?`,
       [id],
     );
   }

package/src/index.ts

@@ -8,6 +8,12 @@
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.
  */
+export {
+  defineAuthorityReads,
+  type AuthorityReadPolicy,
+  type AuthorityReadDeclaration,
+  type AuthoritySnapshot,
+} from './authority';
 export * from './apply';
 export * from './availability';
 export * from './blob';