@syncular/client 0.52.0 → 0.53.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -393,6 +393,11 @@ and generated table names, never scopes. It lets a support screen distinguish
393
393
  an absent registration from a legitimate zero-row completed bootstrap. The
394
394
  snapshot also distinguishes reset, revocation, failure, schema floor, lease
395
395
  stop, pending outbox, offline transport, and storage pressure/unreadability.
396
+ Failed progress and `lastRound` diagnostics expose an optional bounded
397
+ `causeKind` and HTTP status. Worker leaders and followers receive the same
398
+ evidence. A new progress attempt clears its failure fields; a successful round
399
+ replaces the failed last round. `host.connectivity` describes the latest
400
+ endpoint observation and does not prove the device's network state.
396
401
  `queryFailures` retains at most 256 failed owned snapshot reads until each query
397
402
  reads successfully. An entry contains only its stable PHI-free owner id,
398
403
  generated table names, a stable code, an optional numeric SQLite result code,
package/dist/client.d.ts CHANGED
@@ -12,6 +12,7 @@ import { type SyncProgress, type SyncProgressListener } from './progress.js';
12
12
  import { type ScopeMap, type WakeReason } from '@syncular/core';
13
13
  import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
14
14
  import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
15
+ import type { DevtoolsRegistrar } from './devtools.js';
15
16
  import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
16
17
  import type { EncryptionConfig } from './encryption.js';
17
18
  import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
@@ -146,6 +147,8 @@ export interface SyncClientLimits {
146
147
  readonly maxPushRequestBytes?: number;
147
148
  }
148
149
  export interface SyncClientConfig {
150
+ /** Explicit development console registry; absent means no registration. */
151
+ readonly devtools?: DevtoolsRegistrar;
149
152
  readonly transportEnabled?: boolean;
150
153
  /** Keep rejected/conflicting local intent visible until explicit resolution. */
151
154
  readonly retainFailedCommits?: boolean;
package/dist/client.js CHANGED
@@ -19,7 +19,6 @@ import { EncryptError } from '@syncular/core';
19
19
  import { EncodeError } from '@syncular/core';
20
20
  import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
21
21
  import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
22
- import { registerDevtools } from './devtools.js';
23
22
  import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
24
23
  import { ClientSyncError, invalidRequest, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, } from './errors.js';
25
24
  import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
@@ -450,7 +449,7 @@ export class SyncClient {
450
449
  this.#emitSyncIntent({ kind: 'interactive' });
451
450
  }
452
451
  // Console introspection is a no-op outside a dev page.
453
- this.#devtoolsUnregister = registerDevtools({
452
+ this.#devtoolsUnregister = this.#config.devtools?.({
454
453
  kind: 'client',
455
454
  ref: this,
456
455
  clientId: () => this.#clientId,
@@ -1323,9 +1322,13 @@ export class SyncClient {
1323
1322
  : this.#lastRound?.status === 'succeeded'
1324
1323
  ? 'online'
1325
1324
  : this.#lastRound?.status === 'failed' &&
1326
- this.#transportFailureCode(this.#lastRound.errorCode)
1325
+ (this.#lastRound.causeKind === 'network' ||
1326
+ this.#lastRound.causeKind === 'connect')
1327
1327
  ? 'offline'
1328
- : 'unknown';
1328
+ : this.#lastRound?.status === 'failed' &&
1329
+ this.#lastRound.httpStatus !== undefined
1330
+ ? 'online'
1331
+ : 'unknown';
1329
1332
  const expectedOrder = new Map(expected.map((item, index) => [item.id, index]));
1330
1333
  const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
1331
1334
  const aExpected = expectedOrder.get(a.id);
@@ -1713,6 +1716,14 @@ export class SyncClient {
1713
1716
  (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
1714
1717
  throw invalidRequest('maxRounds must be a positive integer');
1715
1718
  const { clientCommitId, sequence } = outcome;
1719
+ const provable = (candidate) => candidate !== undefined &&
1720
+ candidate.sequence === sequence &&
1721
+ candidate.resolution === 'active' &&
1722
+ (candidate.status === 'conflict' || candidate.status === 'rejected') &&
1723
+ candidate.operations !== undefined &&
1724
+ candidate.retainedRows !== undefined &&
1725
+ candidate.operations.length === candidate.retainedRows.length &&
1726
+ candidate.retainedRows.length > 0;
1716
1727
  let initial;
1717
1728
  try {
1718
1729
  initial = readCommitOutcome(this.#db, clientCommitId);
@@ -1720,14 +1731,7 @@ export class SyncClient {
1720
1731
  catch {
1721
1732
  return { proven: false, reason: 'snapshot_failed' };
1722
1733
  }
1723
- if (initial === undefined ||
1724
- initial.sequence !== sequence ||
1725
- initial.resolution !== 'active' ||
1726
- (initial.status !== 'conflict' && initial.status !== 'rejected') ||
1727
- initial.operations === undefined ||
1728
- initial.retainedRows === undefined ||
1729
- initial.operations.length !== initial.retainedRows.length ||
1730
- initial.retainedRows.length === 0)
1734
+ if (!provable(initial))
1731
1735
  return { proven: false, reason: 'outcome_unavailable' };
1732
1736
  if (!this.#transportEnabled)
1733
1737
  return { proven: false, reason: 'offline' };
@@ -1778,15 +1782,7 @@ export class SyncClient {
1778
1782
  });
1779
1783
  const delivery = snapshot.deliveries[0];
1780
1784
  const current = readCommitOutcome(this.#db, clientCommitId);
1781
- if (delivery?.status !== 'known' ||
1782
- current === undefined ||
1783
- current.sequence !== sequence ||
1784
- current.resolution !== 'active' ||
1785
- (current.status !== 'conflict' && current.status !== 'rejected') ||
1786
- current.operations === undefined ||
1787
- current.retainedRows === undefined ||
1788
- current.operations.length !== current.retainedRows.length ||
1789
- current.retainedRows.length === 0)
1785
+ if (delivery?.status !== 'known' || !provable(current))
1790
1786
  return {
1791
1787
  proven: false,
1792
1788
  reason: report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
@@ -2895,12 +2891,53 @@ export class SyncClient {
2895
2891
  const error = classifySqliteFailure(caught).error;
2896
2892
  const completedAtMs = this.#now();
2897
2893
  const code = error.code;
2894
+ const details = typeof error === 'object' && error !== null && 'details' in error
2895
+ ? error.details
2896
+ : undefined;
2897
+ const rawCause = typeof details === 'object' &&
2898
+ details !== null &&
2899
+ 'causeKind' in details
2900
+ ? details.causeKind
2901
+ : undefined;
2902
+ let causeKind;
2903
+ switch (rawCause) {
2904
+ case 'network':
2905
+ case 'connect':
2906
+ case 'tls':
2907
+ case 'io':
2908
+ case 'request':
2909
+ case 'protocol':
2910
+ case 'timeout':
2911
+ case 'round_deadline':
2912
+ case 'aborted':
2913
+ case 'body':
2914
+ case 'status':
2915
+ case 'redirect':
2916
+ case 'unknown':
2917
+ causeKind = rawCause;
2918
+ }
2919
+ const rawStatus = typeof details === 'object' &&
2920
+ details !== null &&
2921
+ 'httpStatus' in details
2922
+ ? details.httpStatus
2923
+ : undefined;
2924
+ const httpStatus = (causeKind === 'status' ||
2925
+ causeKind === 'body' ||
2926
+ causeKind === 'redirect') &&
2927
+ typeof rawStatus === 'number' &&
2928
+ Number.isInteger(rawStatus) &&
2929
+ rawStatus >= 100 &&
2930
+ rawStatus <= 599
2931
+ ? rawStatus
2932
+ : undefined;
2898
2933
  this.#progress.update(definedObject({
2899
2934
  state: 'failed',
2900
2935
  errorCode: typeof code === 'string'
2901
2936
  ? this.#diagnosticCode(code)
2902
2937
  : 'client.unknown_failure',
2903
2938
  retryDelayMs: this.#roundRetryDelayMs,
2939
+ causeKind,
2940
+ httpStatus,
2904
2941
  }));
2905
2942
  this.#lastRound = {
2906
2943
  status: 'failed',
@@ -2910,6 +2947,8 @@ export class SyncClient {
2910
2947
  errorCode: typeof code === 'string'
2911
2948
  ? this.#diagnosticCode(code)
2912
2949
  : 'client.unknown_failure',
2950
+ ...(causeKind !== undefined ? { causeKind } : {}),
2951
+ ...(httpStatus !== undefined ? { httpStatus } : {}),
2913
2952
  };
2914
2953
  this.#emitDiagnostics();
2915
2954
  throw error;
@@ -2937,13 +2976,6 @@ export class SyncClient {
2937
2976
  deferredCommits: summary.deferredCommits ?? 0,
2938
2977
  };
2939
2978
  }
2940
- #transportFailureCode(code) {
2941
- return (code === 'transport.failed' ||
2942
- code === 'transport.unavailable' ||
2943
- code === 'sync.transport_failed' ||
2944
- code === 'client.worker_failed' ||
2945
- code === 'client.worker_restart_required');
2946
- }
2947
2979
  #diagnosticCode(code) {
2948
2980
  return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
2949
2981
  ? code
@@ -1,6 +1,6 @@
1
1
  /**
2
- * The client-side introspection registry: every live
3
- * `SyncClient` / `SyncClientHandle` on a page registers itself on
2
+ * The optional client-side introspection registry: a configured
3
+ * `SyncClient` / `SyncClientHandle` on a development page registers itself on
4
4
  * `globalThis.__SYNCULAR__`, so a first integration debugs from the console
5
5
  * instead of hand-exposing the client:
6
6
  *
@@ -11,11 +11,9 @@
11
11
  * // last invalidation
12
12
  * __SYNCULAR__.clients[0].ref // the client itself — full API
13
13
  *
14
- * Gated to development: the registry installs only where a `window` exists
15
- * (worker cores register through their page-side handle) and NODE_ENV is
16
- * anything except `'production'` (bundlers statically replace it, so
17
- * production builds skip installation; environments without `process` are
18
- * treated as dev). Cost when gated off: one function call per client.
14
+ * The host explicitly supplies `registerDevtools` in its client config. The
15
+ * registry also requires a development or test environment signal and a
16
+ * `window`. A browser without a development signal leaves it disabled.
19
17
  */
20
18
  import type { InvalidationListener } from './invalidation.js';
21
19
  /** What a registrant supplies — plain lambdas over its own surface. */
@@ -34,6 +32,8 @@ export interface DevtoolsRegistration {
34
32
  readonly upgrading: () => Promise<boolean>;
35
33
  readonly onInvalidate: (listener: InvalidationListener) => () => void;
36
34
  }
35
+ /** Explicit development registry supplied to a client or worker handle. */
36
+ export type DevtoolsRegistrar = (registration: DevtoolsRegistration) => () => void;
37
37
  /** One live entry on the registry (a registration plus tracked state). */
38
38
  export interface DevtoolsEntry extends DevtoolsRegistration {
39
39
  /** The most recent invalidation event, timestamped (epoch ms). */
package/dist/devtools.js CHANGED
@@ -4,7 +4,13 @@ function registryHost() {
4
4
  const g = globalThis;
5
5
  if (g.window === undefined)
6
6
  return undefined;
7
- if (g.process?.env?.NODE_ENV === 'production')
7
+ if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
8
+ return undefined;
9
+ if (!((typeof import.meta.env !== 'undefined' &&
10
+ import.meta.env.DEV === true) ||
11
+ (typeof process !== 'undefined' &&
12
+ (process.env.NODE_ENV === 'development' ||
13
+ process.env.NODE_ENV === 'test'))))
8
14
  return undefined;
9
15
  return g;
10
16
  }
@@ -13,6 +13,8 @@ export declare const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
13
13
  export type ClientDiagnosticsHostKind = 'direct' | 'worker' | 'tauri' | 'react-native';
14
14
  export type ClientDiagnosticsHostRole = 'single' | 'leader' | 'follower' | 'unknown';
15
15
  export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
16
+ /** Bounded transport classification shared by progress and diagnostics (§1.8). */
17
+ export type TransportCauseKind = 'network' | 'connect' | 'tls' | 'io' | 'request' | 'protocol' | 'timeout' | 'round_deadline' | 'aborted' | 'body' | 'status' | 'redirect' | 'unknown';
16
18
  /**
17
19
  * SPEC §8.8: how a client treats the realtime binding for sync rounds. The
18
20
  * default is `optional`.
@@ -82,6 +84,8 @@ export type DiagnosticLastRound = {
82
84
  readonly durationMs: number;
83
85
  /** Stable code only; never arbitrary transport/server prose. */
84
86
  readonly errorCode: string;
87
+ readonly causeKind?: TransportCauseKind;
88
+ readonly httpStatus?: number;
85
89
  };
86
90
  export interface DiagnosticLastChange {
87
91
  /** Decimal u64 for JSON/IPC parity. */
@@ -1,3 +1,4 @@
1
+ import type { TransportCauseKind } from './diagnostics.js';
1
2
  /** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
2
3
  export interface SyncProgress {
3
4
  readonly attempt: number;
@@ -11,6 +12,8 @@ export interface SyncProgress {
11
12
  readonly rowsProcessed: number;
12
13
  readonly rowsTotal?: number;
13
14
  readonly errorCode?: string;
15
+ readonly causeKind?: TransportCauseKind;
16
+ readonly httpStatus?: number;
14
17
  /** Present on `failed` when the core scheduled a background retry. */
15
18
  readonly retryDelayMs?: number;
16
19
  }
@@ -27,6 +27,7 @@ import type { WakeReason } from '@syncular/core';
27
27
  import type { BlobRef, CachedBlob } from './blob.js';
28
28
  import type { ConflictRecord, CurrentBaseProof, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
29
29
  import type { SqlRow, SqlValue } from './database.js';
30
+ import type { DevtoolsRegistrar } from './devtools.js';
30
31
  import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
31
32
  import type { EncryptionKeyringConfig } from './encryption.js';
32
33
  import { ClientSyncError } from './errors.js';
@@ -65,6 +66,8 @@ export declare function isolatedReplicaNames(options: {
65
66
  readonly replicaId: string;
66
67
  }): IsolatedReplicaNames;
67
68
  export interface SyncClientHandleConfig {
69
+ /** Explicit development console registry for this page's handle. */
70
+ readonly devtools?: DevtoolsRegistrar;
68
71
  /**
69
72
  * Spawns the worker running `startSyncWorker()` (a factory so bundlers
70
73
  * see `new Worker(new URL(...))` at the call site, and so no worker is
@@ -193,6 +196,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
193
196
  leadershipListeners?: Set<(state: LeadershipState) => void>;
194
197
  unreachableListeners?: Set<(event: LeaderUnreachableEvent) => void>;
195
198
  leadership?: LeadershipState;
199
+ devtools?: DevtoolsRegistrar;
196
200
  });
197
201
  /**
198
202
  * @internal — apply a leadership snapshot in place: a promotion flips the
@@ -1,5 +1,4 @@
1
1
  import { ProgressEmitter, } from './progress.js';
2
- import { registerDevtools } from './devtools.js';
3
2
  import { ClientDiagnosticsEmitter, withClientDiagnosticsHost, } from './diagnostics.js';
4
3
  import { ClientSyncError } from './errors.js';
5
4
  import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
@@ -107,7 +106,7 @@ export class SyncClientHandle {
107
106
  this.#leadershipListeners = internals.leadershipListeners ?? new Set();
108
107
  this.#unreachableListeners = internals.unreachableListeners ?? new Set();
109
108
  // Console introspection is a no-op outside a dev page.
110
- this.#devtoolsUnregister = registerDevtools({
109
+ this.#devtoolsUnregister = internals.devtools?.({
111
110
  kind: 'handle',
112
111
  ref: this,
113
112
  clientId: () => this.#clientId,
@@ -442,7 +441,7 @@ export class SyncClientHandle {
442
441
  return;
443
442
  this.#closed = true;
444
443
  this.#progress.clear();
445
- this.#devtoolsUnregister();
444
+ this.#devtoolsUnregister?.();
446
445
  await this.#tabs?.close();
447
446
  if (this.#core !== undefined) {
448
447
  const core = this.#core;
@@ -660,6 +659,9 @@ export async function createSyncClientHandle(config) {
660
659
  roleListeners,
661
660
  leadershipListeners,
662
661
  unreachableListeners,
662
+ ...(resolvedConfig.devtools !== undefined
663
+ ? { devtools: resolvedConfig.devtools }
664
+ : {}),
663
665
  };
664
666
  if (resolvedConfig.multiTab === false) {
665
667
  // Single-tab contract: the leader runs its core with no channel; a losing
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.52.0",
3
+ "version": "0.53.1",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -97,11 +97,12 @@
97
97
  },
98
98
  "dependencies": {
99
99
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
100
- "@syncular/core": "0.52.0"
100
+ "@syncular/core": "0.53.1"
101
101
  },
102
102
  "devDependencies": {
103
- "@syncular/server": "0.52.0",
103
+ "@syncular/server": "0.53.1",
104
104
  "playwright": "1.63.0",
105
- "@electric-sql/pglite": "^0.5.4"
105
+ "@electric-sql/pglite": "^0.5.4",
106
+ "vite": "8.3.4"
106
107
  }
107
108
  }
package/src/client.ts CHANGED
@@ -86,7 +86,7 @@ import {
86
86
  serializeBlobRef,
87
87
  } from './blob';
88
88
  import type { ClientDatabase, SqlRow, SqlValue } from './database';
89
- import { registerDevtools } from './devtools';
89
+ import type { DevtoolsRegistrar } from './devtools';
90
90
  import {
91
91
  CLIENT_DIAGNOSTICS_VERSION,
92
92
  ClientDiagnosticsEmitter,
@@ -104,6 +104,7 @@ import {
104
104
  MAX_DIAGNOSTIC_QUERY_FAILURES,
105
105
  type RealtimePolicy,
106
106
  type RealtimeState,
107
+ type TransportCauseKind,
107
108
  } from './diagnostics';
108
109
  import type { EncryptionConfig } from './encryption';
109
110
  import {
@@ -416,6 +417,8 @@ export interface SyncClientLimits {
416
417
  }
417
418
 
418
419
  export interface SyncClientConfig {
420
+ /** Explicit development console registry; absent means no registration. */
421
+ readonly devtools?: DevtoolsRegistrar;
419
422
  readonly transportEnabled?: boolean;
420
423
  /** Keep rejected/conflicting local intent visible until explicit resolution. */
421
424
  readonly retainFailedCommits?: boolean;
@@ -1251,7 +1254,7 @@ export class SyncClient {
1251
1254
  this.#emitSyncIntent({ kind: 'interactive' });
1252
1255
  }
1253
1256
  // Console introspection is a no-op outside a dev page.
1254
- this.#devtoolsUnregister = registerDevtools({
1257
+ this.#devtoolsUnregister = this.#config.devtools?.({
1255
1258
  kind: 'client',
1256
1259
  ref: this,
1257
1260
  clientId: () => this.#clientId,
@@ -2290,9 +2293,13 @@ export class SyncClient {
2290
2293
  : this.#lastRound?.status === 'succeeded'
2291
2294
  ? 'online'
2292
2295
  : this.#lastRound?.status === 'failed' &&
2293
- this.#transportFailureCode(this.#lastRound.errorCode)
2296
+ (this.#lastRound.causeKind === 'network' ||
2297
+ this.#lastRound.causeKind === 'connect')
2294
2298
  ? 'offline'
2295
- : 'unknown';
2299
+ : this.#lastRound?.status === 'failed' &&
2300
+ this.#lastRound.httpStatus !== undefined
2301
+ ? 'online'
2302
+ : 'unknown';
2296
2303
  const expectedOrder = new Map(
2297
2304
  expected.map((item, index) => [item.id, index] as const),
2298
2305
  );
@@ -2776,22 +2783,26 @@ export class SyncClient {
2776
2783
  )
2777
2784
  throw invalidRequest('maxRounds must be a positive integer');
2778
2785
  const { clientCommitId, sequence } = outcome;
2786
+ const provable = (
2787
+ candidate: CommitOutcome | undefined,
2788
+ ): candidate is CommitOutcome & {
2789
+ readonly retainedRows: readonly RetainedCommitRow[];
2790
+ } =>
2791
+ candidate !== undefined &&
2792
+ candidate.sequence === sequence &&
2793
+ candidate.resolution === 'active' &&
2794
+ (candidate.status === 'conflict' || candidate.status === 'rejected') &&
2795
+ candidate.operations !== undefined &&
2796
+ candidate.retainedRows !== undefined &&
2797
+ candidate.operations.length === candidate.retainedRows.length &&
2798
+ candidate.retainedRows.length > 0;
2779
2799
  let initial: CommitOutcome | undefined;
2780
2800
  try {
2781
2801
  initial = readCommitOutcome(this.#db, clientCommitId);
2782
2802
  } catch {
2783
2803
  return { proven: false, reason: 'snapshot_failed' };
2784
2804
  }
2785
- if (
2786
- initial === undefined ||
2787
- initial.sequence !== sequence ||
2788
- initial.resolution !== 'active' ||
2789
- (initial.status !== 'conflict' && initial.status !== 'rejected') ||
2790
- initial.operations === undefined ||
2791
- initial.retainedRows === undefined ||
2792
- initial.operations.length !== initial.retainedRows.length ||
2793
- initial.retainedRows.length === 0
2794
- )
2805
+ if (!provable(initial))
2795
2806
  return { proven: false, reason: 'outcome_unavailable' };
2796
2807
  if (!this.#transportEnabled) return { proven: false, reason: 'offline' };
2797
2808
  await this.#opChain;
@@ -2841,17 +2852,7 @@ export class SyncClient {
2841
2852
  });
2842
2853
  const delivery = snapshot.deliveries[0];
2843
2854
  const current = readCommitOutcome(this.#db, clientCommitId);
2844
- if (
2845
- delivery?.status !== 'known' ||
2846
- current === undefined ||
2847
- current.sequence !== sequence ||
2848
- current.resolution !== 'active' ||
2849
- (current.status !== 'conflict' && current.status !== 'rejected') ||
2850
- current.operations === undefined ||
2851
- current.retainedRows === undefined ||
2852
- current.operations.length !== current.retainedRows.length ||
2853
- current.retainedRows.length === 0
2854
- )
2855
+ if (delivery?.status !== 'known' || !provable(current))
2855
2856
  return {
2856
2857
  proven: false,
2857
2858
  reason:
@@ -4227,6 +4228,49 @@ export class SyncClient {
4227
4228
  const error = classifySqliteFailure(caught).error;
4228
4229
  const completedAtMs = this.#now();
4229
4230
  const code = (error as { code?: unknown }).code;
4231
+ const details =
4232
+ typeof error === 'object' && error !== null && 'details' in error
4233
+ ? error.details
4234
+ : undefined;
4235
+ const rawCause =
4236
+ typeof details === 'object' &&
4237
+ details !== null &&
4238
+ 'causeKind' in details
4239
+ ? details.causeKind
4240
+ : undefined;
4241
+ let causeKind: TransportCauseKind | undefined;
4242
+ switch (rawCause) {
4243
+ case 'network':
4244
+ case 'connect':
4245
+ case 'tls':
4246
+ case 'io':
4247
+ case 'request':
4248
+ case 'protocol':
4249
+ case 'timeout':
4250
+ case 'round_deadline':
4251
+ case 'aborted':
4252
+ case 'body':
4253
+ case 'status':
4254
+ case 'redirect':
4255
+ case 'unknown':
4256
+ causeKind = rawCause;
4257
+ }
4258
+ const rawStatus =
4259
+ typeof details === 'object' &&
4260
+ details !== null &&
4261
+ 'httpStatus' in details
4262
+ ? details.httpStatus
4263
+ : undefined;
4264
+ const httpStatus =
4265
+ (causeKind === 'status' ||
4266
+ causeKind === 'body' ||
4267
+ causeKind === 'redirect') &&
4268
+ typeof rawStatus === 'number' &&
4269
+ Number.isInteger(rawStatus) &&
4270
+ rawStatus >= 100 &&
4271
+ rawStatus <= 599
4272
+ ? rawStatus
4273
+ : undefined;
4230
4274
  this.#progress.update(
4231
4275
  definedObject({
4232
4276
  state: 'failed',
@@ -4235,6 +4279,8 @@ export class SyncClient {
4235
4279
  ? this.#diagnosticCode(code)
4236
4280
  : 'client.unknown_failure',
4237
4281
  retryDelayMs: this.#roundRetryDelayMs,
4282
+ causeKind,
4283
+ httpStatus,
4238
4284
  }),
4239
4285
  );
4240
4286
  this.#lastRound = {
@@ -4246,6 +4292,8 @@ export class SyncClient {
4246
4292
  typeof code === 'string'
4247
4293
  ? this.#diagnosticCode(code)
4248
4294
  : 'client.unknown_failure',
4295
+ ...(causeKind !== undefined ? { causeKind } : {}),
4296
+ ...(httpStatus !== undefined ? { httpStatus } : {}),
4249
4297
  };
4250
4298
  this.#emitDiagnostics();
4251
4299
  throw error;
@@ -4275,16 +4323,6 @@ export class SyncClient {
4275
4323
  };
4276
4324
  }
4277
4325
 
4278
- #transportFailureCode(code: string): boolean {
4279
- return (
4280
- code === 'transport.failed' ||
4281
- code === 'transport.unavailable' ||
4282
- code === 'sync.transport_failed' ||
4283
- code === 'client.worker_failed' ||
4284
- code === 'client.worker_restart_required'
4285
- );
4286
- }
4287
-
4288
4326
  #diagnosticCode(code: string): string {
4289
4327
  return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
4290
4328
  ? code
package/src/devtools.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
- * The client-side introspection registry: every live
3
- * `SyncClient` / `SyncClientHandle` on a page registers itself on
2
+ * The optional client-side introspection registry: a configured
3
+ * `SyncClient` / `SyncClientHandle` on a development page registers itself on
4
4
  * `globalThis.__SYNCULAR__`, so a first integration debugs from the console
5
5
  * instead of hand-exposing the client:
6
6
  *
@@ -11,11 +11,9 @@
11
11
  * // last invalidation
12
12
  * __SYNCULAR__.clients[0].ref // the client itself — full API
13
13
  *
14
- * Gated to development: the registry installs only where a `window` exists
15
- * (worker cores register through their page-side handle) and NODE_ENV is
16
- * anything except `'production'` (bundlers statically replace it, so
17
- * production builds skip installation; environments without `process` are
18
- * treated as dev). Cost when gated off: one function call per client.
14
+ * The host explicitly supplies `registerDevtools` in its client config. The
15
+ * registry also requires a development or test environment signal and a
16
+ * `window`. A browser without a development signal leaves it disabled.
19
17
  */
20
18
  import type { InvalidationEvent, InvalidationListener } from './invalidation';
21
19
 
@@ -36,6 +34,11 @@ export interface DevtoolsRegistration {
36
34
  readonly onInvalidate: (listener: InvalidationListener) => () => void;
37
35
  }
38
36
 
37
+ /** Explicit development registry supplied to a client or worker handle. */
38
+ export type DevtoolsRegistrar = (
39
+ registration: DevtoolsRegistration,
40
+ ) => () => void;
41
+
39
42
  /** One live entry on the registry (a registration plus tracked state). */
40
43
  export interface DevtoolsEntry extends DevtoolsRegistration {
41
44
  /** The most recent invalidation event, timestamped (epoch ms). */
@@ -55,12 +58,20 @@ const KEY = '__SYNCULAR__';
55
58
 
56
59
  /** The page global to install on, or undefined when gated off. */
57
60
  function registryHost(): Record<string, unknown> | undefined {
58
- const g = globalThis as Record<string, unknown> & {
59
- window?: unknown;
60
- process?: { env?: { NODE_ENV?: string } };
61
- };
61
+ const g = globalThis as Record<string, unknown> & { window?: unknown };
62
62
  if (g.window === undefined) return undefined;
63
- if (g.process?.env?.NODE_ENV === 'production') return undefined;
63
+ if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
64
+ return undefined;
65
+ if (
66
+ !(
67
+ (typeof import.meta.env !== 'undefined' &&
68
+ (import.meta.env.DEV as boolean | string | undefined) === true) ||
69
+ (typeof process !== 'undefined' &&
70
+ (process.env.NODE_ENV === 'development' ||
71
+ process.env.NODE_ENV === 'test'))
72
+ )
73
+ )
74
+ return undefined;
64
75
  return g;
65
76
  }
66
77
 
@@ -23,6 +23,21 @@ export type ClientDiagnosticsHostRole =
23
23
  | 'follower'
24
24
  | 'unknown';
25
25
  export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
26
+ /** Bounded transport classification shared by progress and diagnostics (§1.8). */
27
+ export type TransportCauseKind =
28
+ | 'network'
29
+ | 'connect'
30
+ | 'tls'
31
+ | 'io'
32
+ | 'request'
33
+ | 'protocol'
34
+ | 'timeout'
35
+ | 'round_deadline'
36
+ | 'aborted'
37
+ | 'body'
38
+ | 'status'
39
+ | 'redirect'
40
+ | 'unknown';
26
41
  /**
27
42
  * SPEC §8.8: how a client treats the realtime binding for sync rounds. The
28
43
  * default is `optional`.
@@ -115,6 +130,8 @@ export type DiagnosticLastRound =
115
130
  readonly durationMs: number;
116
131
  /** Stable code only; never arbitrary transport/server prose. */
117
132
  readonly errorCode: string;
133
+ readonly causeKind?: TransportCauseKind;
134
+ readonly httpStatus?: number;
118
135
  };
119
136
 
120
137
  export interface DiagnosticLastChange {
package/src/progress.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import type { TransportCauseKind } from './diagnostics';
2
+
1
3
  /** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
2
4
  export interface SyncProgress {
3
5
  readonly attempt: number;
@@ -11,6 +13,8 @@ export interface SyncProgress {
11
13
  readonly rowsProcessed: number;
12
14
  readonly rowsTotal?: number;
13
15
  readonly errorCode?: string;
16
+ readonly causeKind?: TransportCauseKind;
17
+ readonly httpStatus?: number;
14
18
  /** Present on `failed` when the core scheduled a background retry. */
15
19
  readonly retryDelayMs?: number;
16
20
  }
@@ -49,7 +49,7 @@ import type {
49
49
  WindowState,
50
50
  } from './client';
51
51
  import type { SqlRow, SqlValue } from './database';
52
- import { registerDevtools } from './devtools';
52
+ import type { DevtoolsRegistrar } from './devtools';
53
53
  import {
54
54
  ClientDiagnosticsEmitter,
55
55
  type ClientDiagnosticsListener,
@@ -178,6 +178,8 @@ export function isolatedReplicaNames(options: {
178
178
  }
179
179
 
180
180
  export interface SyncClientHandleConfig {
181
+ /** Explicit development console registry for this page's handle. */
182
+ readonly devtools?: DevtoolsRegistrar;
181
183
  /**
182
184
  * Spawns the worker running `startSyncWorker()` (a factory so bundlers
183
185
  * see `new Worker(new URL(...))` at the call site, and so no worker is
@@ -337,7 +339,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
337
339
  readonly #roleListeners: Set<(role: HandleRole) => void>;
338
340
  readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
339
341
  readonly #unreachableListeners: Set<(event: LeaderUnreachableEvent) => void>;
340
- readonly #devtoolsUnregister: () => void;
342
+ readonly #devtoolsUnregister: (() => void) | undefined;
341
343
  #closed = false;
342
344
 
343
345
  /** @internal — use {@link createSyncClientHandle}. */
@@ -355,6 +357,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
355
357
  leadershipListeners?: Set<(state: LeadershipState) => void>;
356
358
  unreachableListeners?: Set<(event: LeaderUnreachableEvent) => void>;
357
359
  leadership?: LeadershipState;
360
+ devtools?: DevtoolsRegistrar;
358
361
  }) {
359
362
  this.#role = internals.role;
360
363
  this.#clientId = internals.clientId;
@@ -380,7 +383,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
380
383
  this.#leadershipListeners = internals.leadershipListeners ?? new Set();
381
384
  this.#unreachableListeners = internals.unreachableListeners ?? new Set();
382
385
  // Console introspection is a no-op outside a dev page.
383
- this.#devtoolsUnregister = registerDevtools({
386
+ this.#devtoolsUnregister = internals.devtools?.({
384
387
  kind: 'handle',
385
388
  ref: this,
386
389
  clientId: () => this.#clientId,
@@ -832,7 +835,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
832
835
  if (this.#closed) return;
833
836
  this.#closed = true;
834
837
  this.#progress.clear();
835
- this.#devtoolsUnregister();
838
+ this.#devtoolsUnregister?.();
836
839
  await this.#tabs?.close();
837
840
  if (this.#core !== undefined) {
838
841
  const core = this.#core;
@@ -1076,6 +1079,9 @@ export async function createSyncClientHandle(
1076
1079
  roleListeners,
1077
1080
  leadershipListeners,
1078
1081
  unreachableListeners,
1082
+ ...(resolvedConfig.devtools !== undefined
1083
+ ? { devtools: resolvedConfig.devtools }
1084
+ : {}),
1079
1085
  };
1080
1086
 
1081
1087
  if (resolvedConfig.multiTab === false) {