@syncular/client 0.15.5 → 0.15.7

package/dist/client.js

@@ -17,8 +17,8 @@ import { singleOwnerLock, } from './leader-lock.js';
 import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
-import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
-import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
+import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
+import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
 /**
  * True iff `unit` is windowed-in AND its bootstrap completed (§4.8 I3):
@@ -144,7 +144,10 @@ export class SyncClient {
             return;
         const lock = this.#config.leaderLock ?? singleOwnerLock();
         this.#lease = await lock.acquire(this.#config.lockName ?? 'syncular-leader');
-        ensureLocalSchema(this.#db, this.#schema);
+        // Bookkeeping must exist before we inspect the persisted schema marker.
+        // Do not materialize new app indexes/FTS projections yet: on a version
+        // bump they may reference columns that only exist after the reset.
+        ensureLocalBookkeepingSchema(this.#db);
         if (this.#hasBlobs)
             ensureBlobSchema(this.#db);
         this.#db.transaction(() => {
@@ -175,6 +178,11 @@ export class SyncClient {
         // before the first sync round. A fresh install (no marker) is treated as
         // already at the generated version.
         this.#detectAndResetSchema();
+        // A registration remains app intent only while its table exists in the
+        // running schema. Removed-table registrations would poison every pull.
+        this.#db.transaction(() => {
+            pruneUnknownSubscriptions(this.#db, new Set(this.#schema.tables.keys()));
+        });
         this.#started = true;
         // A persisted active subscription needs one catch-up round on every open:
         // realtime only covers changes after the socket connects, and an
@@ -214,12 +222,16 @@ export class SyncClient {
         const markerJson = getMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY);
         if (markerJson === undefined) {
             // Fresh install: the tables just created match the running code.
+            ensureLocalSyncedSchema(this.#db, this.#schema);
             setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
             return;
         }
         const marker = Number(markerJson);
-        if (marker === this.#schema.version)
+        if (marker === this.#schema.version) {
+            // Same-version opens remain self-healing for absent tables/indexes.
+            ensureLocalSyncedSchema(this.#db, this.#schema);
             return;
+        }
         this.#runSchemaReset();
     }
     /**

package/dist/schema.d.ts

@@ -103,9 +103,19 @@ export declare function localColumnType(column: RowColumn): RowColumn['type'];
 /** §7.4.1 persisted local schema-version marker (`_syncular_meta` key). */
 export declare const LOCAL_SCHEMA_VERSION_KEY = "localSchemaVersion";
 /**
- * Create the synced tables plus client bookkeeping tables (outbox,
- * subscription state, meta). Idempotent.
+ * Create only the application-owned synced tables, indexes, and FTS
+ * projections. Callers opening an existing database must compare the
+ * persisted schema version before invoking this: a new index may reference a
+ * column that does not exist until the schema-bump reset recreates the table.
  */
+export declare function ensureLocalSyncedSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
+/**
+ * Create the protected Syncular bookkeeping tables without touching the
+ * application schema. This makes the persisted schema-version marker
+ * readable before any new application index or FTS projection is applied.
+ */
+export declare function ensureLocalBookkeepingSchema(db: ClientDatabase): void;
+/** Create both application and protected bookkeeping tables. */
 export declare function ensureLocalSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
 /**
  * §7.4.3 reset: drop every synced local table (whatever the *previous*

package/dist/schema.js

@@ -241,10 +241,12 @@ function createFtsProjection(db, table, index) {
     }
 }
 /**
- * Create the synced tables plus client bookkeeping tables (outbox,
- * subscription state, meta). Idempotent.
+ * Create only the application-owned synced tables, indexes, and FTS
+ * projections. Callers opening an existing database must compare the
+ * persisted schema version before invoking this: a new index may reference a
+ * column that does not exist until the schema-bump reset recreates the table.
  */
-export function ensureLocalSchema(db, schema) {
+export function ensureLocalSyncedSchema(db, schema) {
     db.transaction(() => {
         for (const table of schema.tables.values()) {
             createSyncedTable(db, table);
@@ -254,6 +256,15 @@ export function ensureLocalSchema(db, schema) {
                 createFtsProjection(db, table, index);
             }
         }
+    });
+}
+/**
+ * Create the protected Syncular bookkeeping tables without touching the
+ * application schema. This makes the persisted schema-version marker
+ * readable before any new application index or FTS projection is applied.
+ */
+export function ensureLocalBookkeepingSchema(db) {
+    db.transaction(() => {
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
       key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
         db.exec(`INSERT OR IGNORE INTO _syncular_meta(key, value) VALUES ('localRevision', '0')`);
@@ -316,6 +327,11 @@ export function ensureLocalSchema(db, schema) {
       effective_scopes TEXT NOT NULL)`);
     });
 }
+/** Create both application and protected bookkeeping tables. */
+export function ensureLocalSchema(db, schema) {
+    ensureLocalBookkeepingSchema(db);
+    ensureLocalSyncedSchema(db, schema);
+}
 /** Bookkeeping tables the schema-bump reset (§7.4.3) MUST NOT drop. */
 const RESERVED_TABLE_PREFIX = '_syncular_';
 /**

package/dist/state.d.ts

@@ -38,6 +38,13 @@ export declare function deleteSubscription(db: ClientDatabase, id: string): void
  * subscriptions the app still wants. Caller owns the transaction.
  */
 export declare function resetSubscriptionsForBump(db: ClientDatabase): void;
+/**
+ * Remove registrations whose table no longer exists in the running schema.
+ * Keeping one would make every subsequent pull fail with
+ * `sync.unknown_table`. Window bookkeeping belongs to the registration and
+ * is removed with it.
+ */
+export declare function pruneUnknownSubscriptions(db: ClientDatabase, tableNames: ReadonlySet<string>): void;
 export declare function getMeta(db: ClientDatabase, key: string): string | undefined;
 export declare function setMeta(db: ClientDatabase, key: string, value: string): void;
 /** Read the durable client-local observer revision (SPEC §7.5). */

package/dist/state.js

@@ -65,6 +65,25 @@ export function resetSubscriptionsForBump(db) {
        SET cursor = -1, bootstrap_state = NULL, effective_scopes = NULL,
            status = 'active', reason_code = NULL`);
 }
+/**
+ * Remove registrations whose table no longer exists in the running schema.
+ * Keeping one would make every subsequent pull fail with
+ * `sync.unknown_table`. Window bookkeeping belongs to the registration and
+ * is removed with it.
+ */
+export function pruneUnknownSubscriptions(db, tableNames) {
+    const staleIds = db
+        .query('SELECT id, tbl FROM _syncular_subscriptions')
+        .filter((row) => !tableNames.has(String(row.tbl)))
+        .map((row) => String(row.id));
+    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]);
+    }
+}
 export function getMeta(db, key) {
     const row = db.query('SELECT value FROM _syncular_meta WHERE key = ?', [
         key,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.5",
+  "version": "0.15.7",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.5"
+    "@syncular/core": "0.15.7"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.5",
+    "@syncular/server": "0.15.7",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -114,7 +114,8 @@ import {
   type CompiledClientTable,
   compileClientSchema,
   dropAndRecreateSyncedTables,
-  ensureLocalSchema,
+  ensureLocalBookkeepingSchema,
+  ensureLocalSyncedSchema,
   fromSqlValue,
   jsonToRowValue,
   LOCAL_SCHEMA_VERSION_KEY,
@@ -133,6 +134,7 @@ import {
   getMeta,
   getSubscription,
   loadSubscriptions,
+  pruneUnknownSubscriptions,
   resetSubscriptionsForBump,
   type SubscriptionRecord,
   saveSubscription,
@@ -544,7 +546,10 @@ export class SyncClient {
     this.#lease = await lock.acquire(
       this.#config.lockName ?? 'syncular-leader',
     );
-    ensureLocalSchema(this.#db, this.#schema);
+    // Bookkeeping must exist before we inspect the persisted schema marker.
+    // Do not materialize new app indexes/FTS projections yet: on a version
+    // bump they may reference columns that only exist after the reset.
+    ensureLocalBookkeepingSchema(this.#db);
     if (this.#hasBlobs) ensureBlobSchema(this.#db);
     this.#db.transaction(() => {
       pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
@@ -581,6 +586,11 @@ export class SyncClient {
     // before the first sync round. A fresh install (no marker) is treated as
     // already at the generated version.
     this.#detectAndResetSchema();
+    // A registration remains app intent only while its table exists in the
+    // running schema. Removed-table registrations would poison every pull.
+    this.#db.transaction(() => {
+      pruneUnknownSubscriptions(this.#db, new Set(this.#schema.tables.keys()));
+    });
     this.#started = true;
     // A persisted active subscription needs one catch-up round on every open:
     // realtime only covers changes after the socket connects, and an
@@ -622,11 +632,16 @@ export class SyncClient {
     const markerJson = getMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY);
     if (markerJson === undefined) {
       // Fresh install: the tables just created match the running code.
+      ensureLocalSyncedSchema(this.#db, this.#schema);
       setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
       return;
     }
     const marker = Number(markerJson);
-    if (marker === this.#schema.version) return;
+    if (marker === this.#schema.version) {
+      // Same-version opens remain self-healing for absent tables/indexes.
+      ensureLocalSyncedSchema(this.#db, this.#schema);
+      return;
+    }
     this.#runSchemaReset();
   }
 

package/src/schema.ts

@@ -395,10 +395,12 @@ function createFtsProjection(
 }
 
 /**
- * Create the synced tables plus client bookkeeping tables (outbox,
- * subscription state, meta). Idempotent.
+ * Create only the application-owned synced tables, indexes, and FTS
+ * projections. Callers opening an existing database must compare the
+ * persisted schema version before invoking this: a new index may reference a
+ * column that does not exist until the schema-bump reset recreates the table.
  */
-export function ensureLocalSchema(
+export function ensureLocalSyncedSchema(
   db: ClientDatabase,
   schema: CompiledClientSchema,
 ): void {
@@ -411,6 +413,16 @@ export function ensureLocalSchema(
         createFtsProjection(db, table, index);
       }
     }
+  });
+}
+
+/**
+ * Create the protected Syncular bookkeeping tables without touching the
+ * application schema. This makes the persisted schema-version marker
+ * readable before any new application index or FTS projection is applied.
+ */
+export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
+  db.transaction(() => {
     db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
       key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
     db.exec(
@@ -477,6 +489,15 @@ export function ensureLocalSchema(
   });
 }
 
+/** Create both application and protected bookkeeping tables. */
+export function ensureLocalSchema(
+  db: ClientDatabase,
+  schema: CompiledClientSchema,
+): void {
+  ensureLocalBookkeepingSchema(db);
+  ensureLocalSyncedSchema(db, schema);
+}
+
 /** Bookkeeping tables the schema-bump reset (§7.4.3) MUST NOT drop. */
 const RESERVED_TABLE_PREFIX = '_syncular_';
 

package/src/state.ts

@@ -115,6 +115,29 @@ export function resetSubscriptionsForBump(db: ClientDatabase): void {
   );
 }
 
+/**
+ * Remove registrations whose table no longer exists in the running schema.
+ * Keeping one would make every subsequent pull fail with
+ * `sync.unknown_table`. Window bookkeeping belongs to the registration and
+ * is removed with it.
+ */
+export function pruneUnknownSubscriptions(
+  db: ClientDatabase,
+  tableNames: ReadonlySet<string>,
+): void {
+  const staleIds = db
+    .query('SELECT id, tbl FROM _syncular_subscriptions')
+    .filter((row) => !tableNames.has(String(row.tbl)))
+    .map((row) => String(row.id));
+  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]);
+  }
+}
+
 export function getMeta(db: ClientDatabase, key: string): string | undefined {
   const row = db.query('SELECT value FROM _syncular_meta WHERE key = ?', [
     key,