@syncular/client 0.3.0 → 0.4.0

package/dist/client.d.ts

@@ -182,8 +182,20 @@ export interface SubscribeInput {
 export interface WindowState {
     /** Windowed-in units for this base, ordered by value. */
     readonly units: readonly string[];
+    /**
+     * Registered units whose bootstrap has not yet completed (§4.8): the
+     * unit's subscription still has `cursor: -1` (never synced) or holds a
+     * resume token (mid-bootstrap). Between `setWindow` and the bootstrap
+     * landing, the local replica for a pending unit may be empty or partial —
+     * it MUST NOT be rendered as complete.
+     */
+    readonly pending: readonly string[];
 }
-/** True iff `unit` is windowed-in for this snapshot (a registry hit, I3). */
+/**
+ * True iff `unit` is windowed-in AND its bootstrap completed (§4.8 I3):
+ * registered and not pending. A unit with zero server rows still becomes
+ * complete once its bootstrap round finishes — emptiness ≠ pendency.
+ */
 export declare function windowComplete(state: WindowState, unit: string): boolean;
 export declare class SyncClient {
     #private;
@@ -305,10 +317,13 @@ export declare class SyncClient {
     setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
     /**
      * The completeness oracle (§4.8 I3): which units of a base are windowed-in
-     * locally, and a per-unit verdict a live query renders "may be partial"
-     * from. A query whose scope footprint includes an un-windowed unit is
+     * locally, which of those are still bootstrap-pending, and thereby the
+     * per-unit verdict a live query renders "may be partial" from. A query
+     * whose scope footprint includes an un-windowed OR still-pending unit is
      * NOT answerable in full — the host widens or shows partial, never
-     * silently-complete.
+     * silently-complete. Registration alone is not completeness: a unit is
+     * pending until its subscription completes a bootstrap round (cursor
+     * advances past -1 with no resume token held).
      */
     windowState(base: WindowBase): WindowState;
     /**

package/dist/client.js

@@ -19,9 +19,13 @@ 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 { deleteSubscription, getMeta, getSubscription, loadSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
-/** True iff `unit` is windowed-in for this snapshot (a registry hit, I3). */
+/**
+ * True iff `unit` is windowed-in AND its bootstrap completed (§4.8 I3):
+ * registered and not pending. A unit with zero server rows still becomes
+ * complete once its bootstrap round finishes — emptiness ≠ pendency.
+ */
 export function windowComplete(state, unit) {
-    return state.units.includes(unit);
+    return state.units.includes(unit) && !state.pending.includes(unit);
 }
 // ---------------------------------------------------------------------------
 // Internals
@@ -645,15 +649,28 @@ export class SyncClient {
     }
     /**
      * The completeness oracle (§4.8 I3): which units of a base are windowed-in
-     * locally, and a per-unit verdict a live query renders "may be partial"
-     * from. A query whose scope footprint includes an un-windowed unit is
+     * locally, which of those are still bootstrap-pending, and thereby the
+     * per-unit verdict a live query renders "may be partial" from. A query
+     * whose scope footprint includes an un-windowed OR still-pending unit is
      * NOT answerable in full — the host widens or shows partial, never
-     * silently-complete.
+     * silently-complete. Registration alone is not completeness: a unit is
+     * pending until its subscription completes a bootstrap round (cursor
+     * advances past -1 with no resume token held).
      */
     windowState(base) {
         this.#requireStarted();
         const baseKey = windowBaseKey(base);
-        return { units: loadWindowUnits(this.#db, baseKey).map((u) => u.unit) };
+        const live = loadWindowUnits(this.#db, baseKey);
+        const pending = [];
+        for (const { unit, subId } of live) {
+            const sub = getSubscription(this.#db, subId);
+            if (sub === undefined ||
+                sub.cursor < 0 ||
+                sub.bootstrapState !== undefined) {
+                pending.push(unit);
+            }
+        }
+        return { units: live.map((u) => u.unit), pending };
     }
     /**
      * §4.8 E1–E4: evict one departing unit, fused with its unsubscription in
@@ -1600,6 +1617,7 @@ export class SyncClient {
             // §3.3: the effective-scope echo is persisted for the purge contract.
             // An absent bootstrapState clears any previous resume token (§4.4:
             // absent = bootstrap complete, or not bootstrapping).
+            const wasPending = sub.cursor < 0 || sub.bootstrapState !== undefined;
             saveSubscription(this.#db, {
                 id: sub.id,
                 table: sub.table,
@@ -1610,6 +1628,12 @@ export class SyncClient {
                 effectiveScopes: start.effectiveScopes,
                 status: 'active',
             });
+            if (wasPending && nextCursor >= 0 && bootstrapState === undefined) {
+                // §4.8: the completeness verdict flipped pending → complete. A
+                // zero-row bootstrap applies nothing, so the flip itself must reach
+                // live oracles through the choke point (shares the pull's batch).
+                this.#applyBatch((batch) => batch.table(sub.table));
+            }
             return true;
         }
         if (start.status === 'reset') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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.2.1"
+    "@syncular/core": "0.3.1"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.2.1",
+    "@syncular/server": "0.3.1",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -309,11 +309,23 @@ export interface SubscribeInput {
 export interface WindowState {
   /** Windowed-in units for this base, ordered by value. */
   readonly units: readonly string[];
+  /**
+   * Registered units whose bootstrap has not yet completed (§4.8): the
+   * unit's subscription still has `cursor: -1` (never synced) or holds a
+   * resume token (mid-bootstrap). Between `setWindow` and the bootstrap
+   * landing, the local replica for a pending unit may be empty or partial —
+   * it MUST NOT be rendered as complete.
+   */
+  readonly pending: readonly string[];
 }
 
-/** True iff `unit` is windowed-in for this snapshot (a registry hit, I3). */
+/**
+ * True iff `unit` is windowed-in AND its bootstrap completed (§4.8 I3):
+ * registered and not pending. A unit with zero server rows still becomes
+ * complete once its bootstrap round finishes — emptiness ≠ pendency.
+ */
 export function windowComplete(state: WindowState, unit: string): boolean {
-  return state.units.includes(unit);
+  return state.units.includes(unit) && !state.pending.includes(unit);
 }
 
 // ---------------------------------------------------------------------------
@@ -1069,15 +1081,30 @@ export class SyncClient {
 
   /**
    * The completeness oracle (§4.8 I3): which units of a base are windowed-in
-   * locally, and a per-unit verdict a live query renders "may be partial"
-   * from. A query whose scope footprint includes an un-windowed unit is
+   * locally, which of those are still bootstrap-pending, and thereby the
+   * per-unit verdict a live query renders "may be partial" from. A query
+   * whose scope footprint includes an un-windowed OR still-pending unit is
    * NOT answerable in full — the host widens or shows partial, never
-   * silently-complete.
+   * silently-complete. Registration alone is not completeness: a unit is
+   * pending until its subscription completes a bootstrap round (cursor
+   * advances past -1 with no resume token held).
    */
   windowState(base: WindowBase): WindowState {
     this.#requireStarted();
     const baseKey = windowBaseKey(base);
-    return { units: loadWindowUnits(this.#db, baseKey).map((u) => u.unit) };
+    const live = loadWindowUnits(this.#db, baseKey);
+    const pending: string[] = [];
+    for (const { unit, subId } of live) {
+      const sub = getSubscription(this.#db, subId);
+      if (
+        sub === undefined ||
+        sub.cursor < 0 ||
+        sub.bootstrapState !== undefined
+      ) {
+        pending.push(unit);
+      }
+    }
+    return { units: live.map((u) => u.unit), pending };
   }
 
   /**
@@ -2236,6 +2263,7 @@ export class SyncClient {
       // §3.3: the effective-scope echo is persisted for the purge contract.
       // An absent bootstrapState clears any previous resume token (§4.4:
       // absent = bootstrap complete, or not bootstrapping).
+      const wasPending = sub.cursor < 0 || sub.bootstrapState !== undefined;
       saveSubscription(this.#db, {
         id: sub.id,
         table: sub.table,
@@ -2246,6 +2274,12 @@ export class SyncClient {
         effectiveScopes: start.effectiveScopes,
         status: 'active',
       });
+      if (wasPending && nextCursor >= 0 && bootstrapState === undefined) {
+        // §4.8: the completeness verdict flipped pending → complete. A
+        // zero-row bootstrap applies nothing, so the flip itself must reach
+        // live oracles through the choke point (shares the pull's batch).
+        this.#applyBatch((batch) => batch.table(sub.table));
+      }
       return true;
     }