@syncular/client 0.30.13 → 0.30.14

package/src/previous-version.ts

@@ -42,7 +42,7 @@ import {
   quoteIdent,
   rowValueToJson,
 } from './schema';
-import { getMeta, setMeta } from './state';
+import { getMeta, setMeta, META_TABLE } from './state';
 
 /** `_syncular_meta` key holding the persisted {@link LocalSchemaDescriptor}. */
 const LOCAL_SCHEMA_DESCRIPTOR_KEY = 'localSchemaDescriptor';
@@ -724,7 +724,7 @@ export function writePreviousVersionRefusal(
 
 /** Delete the durable refusal. Part of the orphan sweep and of a successful capture. */
 export function clearPreviousVersionRefusal(db: ClientDatabase): void {
-  db.exec('DELETE FROM _syncular_meta WHERE key=?', [
+  db.exec(`DELETE FROM ${META_TABLE} WHERE key=?`, [
     PREVIOUS_VERSION_CONTEXT_KEY,
   ]);
 }
@@ -892,7 +892,7 @@ export function writePreviousVersionAudit(
 
 /** Delete the advisory audit. Part of a discard, never of a normal bump. */
 export function clearPreviousVersionAudit(db: ClientDatabase): void {
-  db.exec('DELETE FROM _syncular_meta WHERE key=?', [
+  db.exec(`DELETE FROM ${META_TABLE} WHERE key=?`, [
     PREVIOUS_VERSION_AUDIT_KEY,
   ]);
 }

package/src/schema.ts

@@ -1,3 +1,9 @@
+import { BLOB_COMMIT_REFS } from './blob';
+import { PENDING_EVICTIONS } from './window';
+import { WINDOWS_TABLE } from './window';
+import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox';
+import { OUTCOMES_TABLE } from './outcomes';
+import { SUBSCRIPTIONS_TABLE, META_TABLE } from './state';
 import { ensureFailedOverlaySchema } from './failed-overlay';
 /**
  * Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
@@ -265,6 +271,10 @@ export function stripSyncColumns(rows: SqlRow[]): SqlRow[] {
   });
 }
 
+export function hasUniqueIndex(table: CompiledClientTable): boolean {
+  return table.indexes.some((index) => index.unique);
+}
+
 export function matchesLocalScopes(
   table: CompiledClientTable,
   scopes: Readonly<Record<string, readonly string[]>>,
@@ -531,64 +541,60 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
     ensureFailedOverlaySchema(db);
     const createTable = (name: string, columns: string) =>
       db.exec(`CREATE TABLE IF NOT EXISTS ${name}(${columns})`);
-    createTable('_syncular_meta', 'key TEXT PRIMARY KEY,value TEXT NOT NULL');
+    createTable(META_TABLE, 'key TEXT PRIMARY KEY,value TEXT NOT NULL');
     createTable(
-      '_syncular_blob_commit_refs',
+      BLOB_COMMIT_REFS,
       'commit_id TEXT NOT NULL,blob_id TEXT NOT NULL,PRIMARY KEY(commit_id,blob_id)',
     );
     db.exec(
-      'CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body ON _syncular_blob_commit_refs(blob_id)',
+      `CREATE INDEX IF NOT EXISTS ${BLOB_COMMIT_REFS}_body ON ${BLOB_COMMIT_REFS}(blob_id)`,
     );
     db.exec(
-      "INSERT OR IGNORE INTO _syncular_meta(key,value)VALUES('localRevision','0')",
+      `INSERT OR IGNORE INTO ${META_TABLE}(key,value)VALUES('localRevision','0')`,
     );
     createTable(
-      '_syncular_outbox',
+      OUTBOX_TABLE,
       'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL',
     );
     createTable(
-      '_syncular_outbox_before_images',
+      OUTBOX_IMAGES,
       'client_commit_id TEXT NOT NULL,op_index INTEGER NOT NULL,existed INTEGER NOT NULL CHECK(existed IN (0,1)),sync_version INTEGER,values_json TEXT,PRIMARY KEY(client_commit_id,op_index)',
     );
     if (
       !db
-        .query('PRAGMA table_info(_syncular_outbox_before_images)')
+        .query(`PRAGMA table_info(${OUTBOX_IMAGES})`)
         .some((row) => row.name === 'delivery_seq')
     )
-      db.exec(
-        'ALTER TABLE _syncular_outbox_before_images ADD COLUMN delivery_seq INTEGER',
-      );
+      db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN delivery_seq INTEGER`);
     createTable(
-      '_syncular_commit_outcomes',
+      OUTCOMES_TABLE,
       "seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,status TEXT NOT NULL CHECK(status IN ('applied','cached','conflict','rejected')),recorded_at_ms INTEGER NOT NULL,results TEXT NOT NULL,operations TEXT,resolution TEXT NOT NULL DEFAULT 'active' CHECK(resolution IN ('active','resolved_keep_server','superseded','dismissed')),resolved_at_ms INTEGER,replacement_client_commit_id TEXT",
     );
     // Outcomes created before durable aggregate recovery retain no commit
     // envelope. New failed outcomes store it in the protected client DB.
     try {
-      db.exec(
-        'ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations TEXT',
-      );
+      db.exec(`ALTER TABLE ${OUTCOMES_TABLE} ADD COLUMN operations TEXT`);
     } catch {
       // column already exists — the CREATE above included it
     }
     db.exec(
-      'CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq ON _syncular_commit_outcomes(resolution,seq)',
+      `CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`,
     );
     createTable(
-      '_syncular_subscriptions',
+      SUBSCRIPTIONS_TABLE,
       "id TEXT PRIMARY KEY,tbl TEXT NOT NULL,requested_scopes TEXT NOT NULL,params TEXT,cursor INTEGER NOT NULL DEFAULT -1,bootstrap_state TEXT,effective_scopes TEXT,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT",
     );
     // §4.8 window registry: which units (scope values) of a window base are
     // live locally — the completeness oracle (I3) and the shrink driver
     // (a unit's omission from the next pull unregisters it, §4.1).
     createTable(
-      '_syncular_windows',
+      WINDOWS_TABLE,
       'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)',
     );
     // §4.8 E1: units that left the window but still had outbox-pinned rows.
     // Retried when the outbox drains; cancelled if the unit re-enters.
     createTable(
-      '_syncular_window_pending_evict',
+      PENDING_EVICTIONS,
       'sub_id TEXT PRIMARY KEY,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL',
     );
   });

package/src/state.ts

@@ -1,3 +1,7 @@
+export const META_TABLE = '_syncular_meta';
+import { PENDING_EVICTIONS } from './window';
+import { WINDOWS_TABLE } from './window';
+export const SUBSCRIPTIONS_TABLE = '_syncular_subscriptions';
 /**
  * Durable client sync state: per-subscription cursor, bootstrap resume
  * token (round-tripped opaquely, §4.7), and the last-echoed effective
@@ -58,7 +62,7 @@ function rowToRecord(row: Record<string, unknown>): SubscriptionRecord {
 
 export function loadSubscriptions(db: ClientDatabase): SubscriptionRecord[] {
   return db
-    .query('SELECT * FROM _syncular_subscriptions ORDER BY rowid ASC')
+    .query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} ORDER BY rowid ASC`)
     .map(rowToRecord);
 }
 
@@ -66,7 +70,7 @@ export function getSubscription(
   db: ClientDatabase,
   id: string,
 ): SubscriptionRecord | undefined {
-  const row = db.query('SELECT * FROM _syncular_subscriptions WHERE id=?', [
+  const row = db.query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [
     id,
   ])[0];
   return row === undefined ? undefined : rowToRecord(row);
@@ -77,7 +81,7 @@ export function saveSubscription(
   record: SubscriptionRecord,
 ): void {
   db.exec(
-    'INSERT OR REPLACE INTO _syncular_subscriptions(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)',
+    `INSERT OR REPLACE INTO ${SUBSCRIPTIONS_TABLE}(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)`,
     [
       record.id,
       record.table,
@@ -95,7 +99,7 @@ export function saveSubscription(
 }
 
 export function deleteSubscription(db: ClientDatabase, id: string): void {
-  db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
+  db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
 }
 
 /**
@@ -107,7 +111,7 @@ export function deleteSubscription(db: ClientDatabase, id: string): void {
  */
 export function resetSubscriptionsForBump(db: ClientDatabase): void {
   db.exec(
-    "UPDATE _syncular_subscriptions SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL",
+    `UPDATE ${SUBSCRIPTIONS_TABLE} SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL`,
   );
 }
 
@@ -184,7 +188,7 @@ export function pruneUnknownSubscriptions(
   // Shrinking a pinned window already removed its registration. Its deferred
   // eviction still carries the old scope declaration and needs the same fence.
   for (const row of db.query(
-    'SELECT sub_id,tbl,effective_scopes FROM _syncular_window_pending_evict',
+    `SELECT sub_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`,
   )) {
     if (
       !compatible({
@@ -197,25 +201,21 @@ export function pruneUnknownSubscriptions(
   if (staleIds.size === 0) return retained;
   db.transaction(() => {
     for (const id of staleIds) {
-      db.exec('DELETE FROM _syncular_windows WHERE sub_id=?', [id]);
-      db.exec('DELETE FROM _syncular_window_pending_evict WHERE sub_id=?', [
-        id,
-      ]);
-      db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
+      db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
+      db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id=?`, [id]);
+      db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
     }
   });
   return retained;
 }
 
 export function getMeta(db: ClientDatabase, key: string): string | undefined {
-  const row = db.query('SELECT value FROM _syncular_meta WHERE key=?', [
-    key,
-  ])[0];
+  const row = db.query(`SELECT value FROM ${META_TABLE} WHERE key=?`, [key])[0];
   return row === undefined ? undefined : (row.value as string);
 }
 
 export function setMeta(db: ClientDatabase, key: string, value: string): void {
-  db.exec('INSERT OR REPLACE INTO _syncular_meta(key,value)VALUES(?,?)', [
+  db.exec(`INSERT OR REPLACE INTO ${META_TABLE}(key,value)VALUES(?,?)`, [
     key,
     value,
   ]);

package/src/window.ts

@@ -1,3 +1,5 @@
+export const PENDING_EVICTIONS = '_syncular_window_pending_evict';
+export const WINDOWS_TABLE = '_syncular_windows';
 /**
  * Windowed subscriptions (SPEC.md §4.8).
  *
@@ -151,7 +153,7 @@ export function loadWindowUnits(
 ): WindowUnit[] {
   return db
     .query(
-      'SELECT unit, sub_id FROM _syncular_windows WHERE base = ? ORDER BY unit ASC',
+      `SELECT unit,sub_id FROM ${WINDOWS_TABLE} WHERE base=? ORDER BY unit`,
       [baseKey],
     )
     .map((row) => ({ unit: row.unit as string, subId: row.sub_id as string }));
@@ -163,7 +165,7 @@ export function getWindowUnitBySubId(
   subId: string,
 ): RegisteredWindowUnit | undefined {
   const row = db.query(
-    `SELECT base, unit, sub_id FROM _syncular_windows
+    `SELECT base, unit, sub_id FROM ${WINDOWS_TABLE}
       WHERE sub_id = ? LIMIT 1`,
     [subId],
   )[0];
@@ -183,7 +185,7 @@ export function insertWindowUnit(
   subId: string,
 ): void {
   db.exec(
-    'INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?, ?, ?)',
+    `INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`,
     [baseKey, unit, subId],
   );
 }
@@ -193,7 +195,7 @@ export function deleteWindowUnit(
   baseKey: string,
   unit: string,
 ): void {
-  db.exec('DELETE FROM _syncular_windows WHERE base = ? AND unit = ?', [
+  db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE base=? AND unit=?`, [
     baseKey,
     unit,
   ]);
@@ -206,10 +208,10 @@ export function isUnitLive(
   unit: string,
 ): boolean {
   return (
-    db.query(
-      'SELECT 1 FROM _syncular_windows WHERE base = ? AND unit = ? LIMIT 1',
-      [baseKey, unit],
-    ).length > 0
+    db.query(`SELECT 1 FROM ${WINDOWS_TABLE} WHERE base=? AND unit=? LIMIT 1`, [
+      baseKey,
+      unit,
+    ]).length > 0
   );
 }
 
@@ -230,23 +232,19 @@ export function savePendingEviction(
   effective: ScopeMap,
 ): void {
   db.exec(
-    `INSERT OR REPLACE INTO _syncular_window_pending_evict(sub_id, tbl, effective_scopes)
+    `INSERT OR REPLACE INTO ${PENDING_EVICTIONS}(sub_id, tbl, effective_scopes)
        VALUES (?, ?, ?)`,
     [subId, table, JSON.stringify(effective)],
   );
 }
 
 export function deletePendingEviction(db: ClientDatabase, subId: string): void {
-  db.exec('DELETE FROM _syncular_window_pending_evict WHERE sub_id = ?', [
-    subId,
-  ]);
+  db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id = ?`, [subId]);
 }
 
 export function loadPendingEvictions(db: ClientDatabase): PendingEviction[] {
   return db
-    .query(
-      'SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict',
-    )
+    .query(`SELECT sub_id, tbl, effective_scopes FROM ${PENDING_EVICTIONS}`)
     .map((row) => ({
       subId: row.sub_id as string,
       table: row.tbl as string,