@syncular/client 0.0.6-219 → 0.0.6-221

package/src/engine/SyncEngine.test.ts

@@ -225,6 +225,70 @@ describe('SyncEngine WS inline apply', () => {
     expect(snapshot.diagnostics).toBeDefined();
   });
 
+  it('emits structured pull/apply trace events when tracing is enabled', async () => {
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const transport: SyncTransport = {
+      async sync() {
+        return {
+          pull: {
+            ok: true,
+            subscriptions: [
+              {
+                id: 'sub-1',
+                status: 'active',
+                table: 'tasks',
+                scopes: {},
+                bootstrap: false,
+                commits: [],
+                snapshots: [],
+                nextCursor: 0,
+              },
+            ],
+          },
+        };
+      },
+    };
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-trace',
+      subscriptions: [{ id: 'sub-1', table: 'tasks', scopes: {} }],
+      stateId: 'default',
+      traceEnabled: true,
+    });
+
+    const stages: string[] = [];
+    engine.on('sync:trace', (payload) => {
+      stages.push(payload.stage);
+    });
+
+    await engine.start();
+
+    expect(stages).toContain('pull:start');
+    expect(stages).toContain('pull:response');
+    expect(stages).toContain('apply:transaction:start');
+    expect(stages).toContain('apply:transaction:complete');
+    expect(stages).toContain('apply:subscription:start');
+    expect(stages).toContain('apply:subscription:complete');
+
+    const snapshot = await engine.getInspectorSnapshot({ eventLimit: 50 });
+    const traceEvents = snapshot.recentEvents.filter(
+      (event) => event.event === 'sync:trace'
+    );
+    expect(traceEvents.length).toBeGreaterThan(0);
+  });
+
   it('coalesces rapid data:change emissions when debounce is configured', async () => {
     const handlers: ClientHandlerCollection<TestDb> = [
       {

package/src/engine/SyncEngine.ts

@@ -14,7 +14,6 @@ import {
   type SyncOperation,
   type SyncPullResponse,
   type SyncPullSubscriptionResponse,
-  type SyncSubscriptionRequest,
   SyncTransportError,
   startSyncSpan,
 } from '@syncular/core';
@@ -53,6 +52,7 @@ import type {
   SyncBootstrapStatus,
   SyncBootstrapStatusOptions,
   SyncBootstrapSubscriptionPhase,
+  SyncClientSubscription,
   SyncConnectionState,
   SyncDiagnostics,
   SyncEngineConfig,
@@ -273,6 +273,11 @@ function defaultSelectorEquality<T>(left: T, right: T): boolean {
   return Object.is(left, right);
 }
 
+function normalizeBootstrapPhase(value: number | undefined): number {
+  if (value === undefined) return 0;
+  return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+
 function areMetadataRecordsEqual(
   left: Record<string, unknown> | undefined,
   right: Record<string, unknown> | undefined
@@ -736,30 +741,100 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
         completedAt: progress?.completedAt,
         lastErrorCode: progress?.lastErrorCode,
         lastErrorMessage: progress?.lastErrorMessage,
+        bootstrapPhase: normalizeBootstrapPhase(configuredSub?.bootstrapPhase),
       };
     });
 
     const expectedSubscriptions = subscriptions.filter((sub) => sub.expected);
-    const readySubscriptionIds = expectedSubscriptions
+    const activePhase =
+      expectedSubscriptions
+        .filter((sub) => !sub.ready)
+        .reduce<number | null>(
+          (lowest, sub) =>
+            lowest === null || sub.bootstrapPhase < lowest
+              ? sub.bootstrapPhase
+              : lowest,
+          null
+        ) ?? null;
+    const selectedMaxPhase =
+      options.maxPhase ??
+      (explicitIdSet.size > 0
+        ? 'all'
+        : expectedSubscriptions.length > 0
+          ? expectedSubscriptions.reduce(
+              (lowest, sub) => Math.min(lowest, sub.bootstrapPhase),
+              Number.POSITIVE_INFINITY
+            )
+          : 0);
+    const blockingSubscriptions = expectedSubscriptions.filter((sub) =>
+      selectedMaxPhase === 'all' ? true : sub.bootstrapPhase <= selectedMaxPhase
+    );
+    const readySubscriptionIds = blockingSubscriptions
       .filter((sub) => sub.ready)
       .map((sub) => sub.id);
-    const pendingSubscriptionIds = expectedSubscriptions
+    const pendingSubscriptionIds = blockingSubscriptions
       .filter((sub) => !sub.ready)
       .map((sub) => sub.id);
     const channelPhase = this.resolveChannelPhase(
       filteredStates.map((sub) => this.mapSubscriptionToProgress(sub))
     );
     const progressPercent =
-      expectedSubscriptions.length === 0
+      blockingSubscriptions.length === 0
         ? pendingSubscriptionIds.length === 0
           ? 100
           : 0
         : Math.round(
-            expectedSubscriptions.reduce(
+            blockingSubscriptions.reduce(
               (sum, sub) => sum + sub.progressPercent,
               0
-            ) / expectedSubscriptions.length
+            ) / blockingSubscriptions.length
           );
+    const phases = Array.from(
+      expectedSubscriptions.reduce(
+        (acc, sub) => {
+          const current = acc.get(sub.bootstrapPhase) ?? {
+            phase: sub.bootstrapPhase,
+            expectedSubscriptionIds: [] as string[],
+            readySubscriptionIds: [] as string[],
+            pendingSubscriptionIds: [] as string[],
+            progressPercent: 0,
+          };
+          current.expectedSubscriptionIds.push(sub.id);
+          if (sub.ready) {
+            current.readySubscriptionIds.push(sub.id);
+          } else {
+            current.pendingSubscriptionIds.push(sub.id);
+          }
+          current.progressPercent += sub.progressPercent;
+          acc.set(sub.bootstrapPhase, current);
+          return acc;
+        },
+        new Map<
+          number,
+          {
+            phase: number;
+            expectedSubscriptionIds: string[];
+            readySubscriptionIds: string[];
+            pendingSubscriptionIds: string[];
+            progressPercent: number;
+          }
+        >()
+      )
+    )
+      .sort(([left], [right]) => left - right)
+      .map(([, phase]) => ({
+        phase: phase.phase,
+        expectedSubscriptionIds: phase.expectedSubscriptionIds,
+        readySubscriptionIds: phase.readySubscriptionIds,
+        pendingSubscriptionIds: phase.pendingSubscriptionIds,
+        isReady: phase.pendingSubscriptionIds.length === 0,
+        progressPercent:
+          phase.expectedSubscriptionIds.length === 0
+            ? 100
+            : Math.round(
+                phase.progressPercent / phase.expectedSubscriptionIds.length
+              ),
+      }));
 
     return {
       stateId,
@@ -767,10 +842,13 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       progressPercent,
       isBootstrapping: pendingSubscriptionIds.length > 0,
       isReady: pendingSubscriptionIds.length === 0,
-      expectedSubscriptionIds: expectedSubscriptions.map((sub) => sub.id),
+      expectedSubscriptionIds: blockingSubscriptions.map((sub) => sub.id),
       readySubscriptionIds,
       pendingSubscriptionIds,
       subscriptions,
+      activePhase,
+      selectedMaxPhase,
+      phases,
     };
   }
 
@@ -826,20 +904,25 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     const deadline = Date.now() + timeoutMs;
 
     while (true) {
-      const states = await this.listSubscriptionStates({ stateId });
-      const relevantStates =
-        options.subscriptionId === undefined
-          ? states
-          : states.filter(
-              (state) => state.subscriptionId === options.subscriptionId
-            );
+      if (options.subscriptionId !== undefined) {
+        const state = await this.getSubscriptionState(options.subscriptionId, {
+          stateId,
+        });
+        const hasPendingBootstrap =
+          state?.status === 'active' && state.bootstrapState !== null;
 
-      const hasPendingBootstrap = relevantStates.some(
-        (state) => state.status === 'active' && state.bootstrapState !== null
-      );
+        if (!hasPendingBootstrap) {
+          return this.getProgress();
+        }
+      } else {
+        const bootstrap = await this.getBootstrapStatus({
+          stateId,
+          maxPhase: options.maxPhase,
+        });
 
-      if (!hasPendingBootstrap) {
-        return this.getProgress();
+        if (bootstrap.isReady) {
+          return this.getProgress();
+        }
       }
 
       if (this.state.error) {
@@ -1668,6 +1751,18 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }
   }
 
+  private shouldTrace(): boolean {
+    return (
+      this.config.traceEnabled === true ||
+      (this.listeners.get('sync:trace')?.size ?? 0) > 0
+    );
+  }
+
+  private emitTrace(payload: SyncEventPayloads['sync:trace']): void {
+    if (!this.shouldTrace()) return;
+    this.emit('sync:trace', payload);
+  }
+
   private updateState(partial: Partial<SyncEngineState>): void {
     const nextState = { ...this.state, ...partial };
     const unchanged =
@@ -1953,14 +2048,14 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
               clientId: this.config.clientId!,
               actorId: this.config.actorId ?? undefined,
               plugins: this.config.plugins,
-              subscriptions: this.config
-                .subscriptions as SyncSubscriptionRequest[],
+              subscriptions: this.config.subscriptions,
               limitCommits: this.config.limitCommits,
               limitSnapshotRows: this.config.limitSnapshotRows,
               maxSnapshotPages: this.config.maxSnapshotPages,
               dedupeRows: this.config.dedupeRows,
               stateId: this.config.stateId,
               sha256: this.config.sha256,
+              onTrace: (event) => this.emitTrace(event),
               trigger,
               allowSkipPullOnLocalWsPush:
                 this.state.transportMode === 'realtime',
@@ -2987,9 +3082,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   /**
    * Update subscriptions dynamically
    */
-  updateSubscriptions(
-    subscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>
-  ): void {
+  updateSubscriptions(subscriptions: SyncClientSubscription[]): void {
     this.config.subscriptions = subscriptions;
     // Trigger a sync to apply new subscriptions
     this.triggerSyncInBackground(undefined, 'subscription update');

package/src/engine/types.ts

@@ -107,6 +107,20 @@ export type SyncBootstrapSubscriptionPhase =
   | SubscriptionProgressPhase
   | 'pending';
 
+export interface SyncClientSubscription
+  extends Omit<SyncSubscriptionRequest, 'cursor'> {
+  /**
+   * Local-only bootstrap phase for staged startup.
+   *
+   * Lower phases bootstrap first. Higher phases are deferred until all lower
+   * phases are ready, but once a higher-phase subscription is already ready it
+   * continues to participate in normal pull requests.
+   *
+   * Defaults to `0`.
+   */
+  bootstrapPhase?: number;
+}
+
 export interface SyncBootstrapSubscriptionStatus {
   stateId: string;
   id: string;
@@ -122,6 +136,16 @@ export interface SyncBootstrapSubscriptionStatus {
   completedAt?: number;
   lastErrorCode?: string;
   lastErrorMessage?: string;
+  bootstrapPhase: number;
+}
+
+export interface SyncBootstrapPhaseStatus {
+  phase: number;
+  expectedSubscriptionIds: string[];
+  readySubscriptionIds: string[];
+  pendingSubscriptionIds: string[];
+  isReady: boolean;
+  progressPercent: number;
 }
 
 export interface SyncBootstrapStatus {
@@ -134,11 +158,51 @@ export interface SyncBootstrapStatus {
   readySubscriptionIds: string[];
   pendingSubscriptionIds: string[];
   subscriptions: SyncBootstrapSubscriptionStatus[];
+  activePhase: number | null;
+  selectedMaxPhase: number | 'all';
+  phases: SyncBootstrapPhaseStatus[];
 }
 
 export interface SyncBootstrapStatusOptions {
   stateId?: string;
   subscriptionIds?: string[];
+  maxPhase?: number | 'all';
+}
+
+export type SyncTraceStage =
+  | 'pull:start'
+  | 'pull:response'
+  | 'pull:error'
+  | 'apply:transaction:start'
+  | 'apply:transaction:complete'
+  | 'apply:transaction:error'
+  | 'apply:subscription:start'
+  | 'apply:subscription:complete'
+  | 'apply:subscription:error'
+  | 'apply:chunk-materialize:start'
+  | 'apply:chunk-materialize:complete'
+  | 'apply:chunk-materialize:error';
+
+export interface SyncTraceEvent {
+  stage: SyncTraceStage;
+  timestamp: number;
+  stateId?: string;
+  subscriptionId?: string;
+  table?: string;
+  bootstrap?: boolean;
+  activeBootstrapPhase?: number | null;
+  transactionMode?: 'single-transaction' | 'per-subscription';
+  subscriptionIds?: string[];
+  subscriptionCount?: number;
+  commitCount?: number;
+  snapshotCount?: number;
+  chunkCount?: number;
+  chunkId?: string;
+  chunkIndex?: number;
+  rowCount?: number;
+  nextCursor?: number | null;
+  durationMs?: number;
+  errorMessage?: string;
 }
 
 /**
@@ -177,6 +241,7 @@ export type SyncEventType =
   | 'state:change'
   | 'sync:start'
   | 'sync:complete'
+  | 'sync:trace'
   | 'sync:live'
   | 'sync:error'
   | 'push:result'
@@ -223,6 +288,7 @@ export interface SyncEventPayloads {
     pullRounds: number;
     pullResponse: SyncPullResponse;
   };
+  'sync:trace': SyncTraceEvent;
   'sync:live': { timestamp: number };
   'sync:error': SyncError;
   'push:result': PushResultInfo;
@@ -287,7 +353,7 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   /** Stable device/app installation id */
   clientId: string | null | undefined;
   /** Subscriptions for partial sync */
-  subscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>;
+  subscriptions: SyncClientSubscription[];
   /** Pull limit (commit count per request) */
   limitCommits?: number;
   /** Bootstrap snapshot rows per page */
@@ -344,6 +410,8 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   plugins?: SyncClientPlugin[];
   /** Custom SHA-256 hash function (for platforms without crypto.subtle, e.g. React Native) */
   sha256?: (bytes: Uint8Array) => Promise<string>;
+  /** Emit structured pull/apply tracing events to the event stream and inspector buffer. */
+  traceEnabled?: boolean;
 }
 
 /**
@@ -469,6 +537,7 @@ export interface SyncAwaitBootstrapOptions {
   timeoutMs?: number;
   stateId?: string;
   subscriptionId?: string;
+  maxPhase?: number | 'all';
 }
 
 export interface SyncDiagnostics {

package/src/pull-engine.test.ts

@@ -1790,3 +1790,121 @@ describe('applyPullResponse chunk streaming', () => {
     expect(clearedScopes).toEqual([{ project_id: 'p1' }]);
   });
 });
+
+describe('buildPullRequest phased bootstrap selection', () => {
+  let db: Kysely<TestDb>;
+
+  beforeEach(async () => {
+    db = createDatabase<TestDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
+    await ensureClientSyncSchema(db);
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+  });
+
+  it('requests only the lowest pending bootstrap phase by default', async () => {
+    const pullState = await buildPullRequest(db, {
+      clientId: 'client-1',
+      stateId: 'default',
+      subscriptions: [
+        { id: 'catalog-meta', table: 'items', bootstrapPhase: 0 },
+        { id: 'catalog-relations', table: 'scoped_items', bootstrapPhase: 1 },
+      ],
+    });
+
+    expect(pullState.request.subscriptions.map((sub) => sub.id)).toEqual([
+      'catalog-meta',
+    ]);
+  });
+
+  it('unlocks later phases once earlier phases are ready', async () => {
+    const now = Date.now();
+
+    await db
+      .insertInto('sync_subscription_state')
+      .values({
+        state_id: 'default',
+        subscription_id: 'catalog-meta',
+        table: 'items',
+        scopes_json: '{}',
+        params_json: '{}',
+        cursor: 12,
+        bootstrap_state_json: null,
+        status: 'active',
+        created_at: now,
+        updated_at: now,
+      })
+      .execute();
+
+    const pullState = await buildPullRequest(db, {
+      clientId: 'client-1',
+      stateId: 'default',
+      subscriptions: [
+        { id: 'catalog-meta', table: 'items', bootstrapPhase: 0 },
+        { id: 'catalog-relations', table: 'scoped_items', bootstrapPhase: 1 },
+      ],
+    });
+
+    expect(pullState.request.subscriptions.map((sub) => sub.id)).toEqual([
+      'catalog-meta',
+      'catalog-relations',
+    ]);
+  });
+
+  it('keeps already-ready later phases live while earlier phases rebootstrap', async () => {
+    const now = Date.now();
+
+    await db
+      .insertInto('sync_subscription_state')
+      .values([
+        {
+          state_id: 'default',
+          subscription_id: 'catalog-meta',
+          table: 'items',
+          scopes_json: '{}',
+          params_json: '{}',
+          cursor: -1,
+          bootstrap_state_json: JSON.stringify({
+            asOfCommitSeq: 0,
+            tables: ['items'],
+            tableIndex: 0,
+            rowCursor: null,
+          }),
+          status: 'active',
+          created_at: now,
+          updated_at: now,
+        },
+        {
+          state_id: 'default',
+          subscription_id: 'catalog-relations',
+          table: 'scoped_items',
+          scopes_json: '{}',
+          params_json: '{}',
+          cursor: 42,
+          bootstrap_state_json: null,
+          status: 'active',
+          created_at: now,
+          updated_at: now,
+        },
+      ])
+      .execute();
+
+    const pullState = await buildPullRequest(db, {
+      clientId: 'client-1',
+      stateId: 'default',
+      subscriptions: [
+        { id: 'catalog-meta', table: 'items', bootstrapPhase: 0 },
+        { id: 'catalog-relations', table: 'scoped_items', bootstrapPhase: 1 },
+      ],
+    });
+
+    expect(pullState.request.subscriptions.map((sub) => sub.id)).toEqual([
+      'catalog-meta',
+      'catalog-relations',
+    ]);
+  });
+});