@syncular/client 0.15.5 → 0.15.6

package/dist/client.js

@@ -17,7 +17,7 @@ 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 { 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, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
 /**
@@ -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(() => {
@@ -214,12 +217,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.5",
+  "version": "0.15.6",
   "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.6"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.5",
+    "@syncular/server": "0.15.6",
     "@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,
@@ -544,7 +545,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);
@@ -622,11 +626,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_';