@syncular/client 0.15.16 → 0.15.18

package/src/diagnostics.ts

@@ -0,0 +1,192 @@
+/**
+ * Privacy-safe client diagnostics shared by direct, Worker, Tauri, React
+ * Native, and normalized React hosts. The snapshot deliberately excludes
+ * requested/effective scope values, row/cardinality data, SQL, database paths,
+ * auth material, lease ids, encryption keys, mutation bodies, and arbitrary
+ * diagnostic prose.
+ */
+import type { SecurityLifecycle } from './client';
+
+export const CLIENT_DIAGNOSTICS_VERSION = 1 as const;
+export const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
+export const MAX_DIAGNOSTIC_DOMAINS = 256;
+
+export type ClientDiagnosticsHostKind =
+  | 'direct'
+  | 'worker'
+  | 'tauri'
+  | 'react-native';
+export type ClientDiagnosticsHostRole =
+  | 'single'
+  | 'leader'
+  | 'follower'
+  | 'unknown';
+export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
+export type ClientDiagnosticsRealtime =
+  | 'connected'
+  | 'disconnected'
+  | 'unsupported'
+  | 'unknown';
+
+export interface ClientDiagnosticsHost {
+  readonly kind: ClientDiagnosticsHostKind;
+  readonly role: ClientDiagnosticsHostRole;
+  readonly connectivity: ClientDiagnosticsConnectivity;
+  readonly realtime: ClientDiagnosticsRealtime;
+}
+
+export interface ExpectedDiagnosticSubscription {
+  /** Application-owned stable identifier. It must never contain PHI. */
+  readonly id: string;
+  /** Generated schema table name. */
+  readonly table: string;
+}
+
+export interface ClientDiagnosticsRequest {
+  /**
+   * Optional bounded intent list. Missing registrations are returned as
+   * `unregistered`, allowing a zero-row security scope to fail closed without
+   * reading private Syncular tables. Values/scopes are intentionally absent.
+   */
+  readonly expectedSubscriptions?: readonly ExpectedDiagnosticSubscription[];
+}
+
+export type DiagnosticSubscriptionState =
+  | 'unregistered'
+  | 'bootstrapping'
+  | 'complete'
+  | 'reset'
+  | 'revoked'
+  | 'failed';
+
+export interface DiagnosticSubscription {
+  readonly id: string;
+  readonly table: string;
+  readonly state: DiagnosticSubscriptionState;
+  readonly complete: boolean;
+  /** Last fully applied local commit sequence; absent when unregistered. */
+  readonly cursor?: number;
+  readonly reasonCode?: string;
+}
+
+export interface DiagnosticRoundCounters {
+  readonly pushed: number;
+  readonly applied: number;
+  readonly rejected: number;
+  readonly retryable: number;
+  readonly conflicts: number;
+  readonly commitsApplied: number;
+  readonly segmentRowsApplied: number;
+  readonly bootstrapping: number;
+  readonly resets: number;
+  readonly revoked: number;
+  readonly failed: number;
+  readonly deferredCommits: number;
+}
+
+export type DiagnosticLastRound =
+  | {
+      readonly status: 'succeeded';
+      readonly startedAtMs: number;
+      readonly completedAtMs: number;
+      readonly durationMs: number;
+      readonly counters: DiagnosticRoundCounters;
+    }
+  | {
+      readonly status: 'failed';
+      readonly startedAtMs: number;
+      readonly completedAtMs: number;
+      readonly durationMs: number;
+      /** Stable code only; never arbitrary transport/server prose. */
+      readonly errorCode: string;
+    };
+
+export interface DiagnosticLastChange {
+  /** Decimal u64 for JSON/IPC parity. */
+  readonly revision: string;
+  readonly recordedAtMs: number;
+  /** Generated table names only; no scope keys or row ids. */
+  readonly tables: readonly string[];
+  /** Generated table names for changed window registrations/completeness. */
+  readonly windows: readonly string[];
+  readonly domainsTruncated: boolean;
+  readonly statusChanged: boolean;
+  readonly conflictsChanged: boolean;
+  readonly rejectionsChanged: boolean;
+  readonly outcomesChanged: boolean;
+}
+
+export interface ClientDiagnosticsStorage {
+  readonly status: 'healthy' | 'pressure' | 'unreadable';
+  /** SQLite page estimate. No path, filename, or per-domain row counts. */
+  readonly databaseBytesApprox?: number;
+  readonly pendingOutboxBytesApprox?: number;
+  readonly retainedOutcomeBytesApprox?: number;
+  readonly retainedOutcomeEntries?: number;
+  readonly blobCacheBytesApprox?: number;
+  readonly pressureReasonCode?: 'client.blob_cache_over_limit';
+}
+
+export interface ClientDiagnosticsSnapshot {
+  readonly version: typeof CLIENT_DIAGNOSTICS_VERSION;
+  readonly capturedAtMs: number;
+  readonly host: ClientDiagnosticsHost;
+  readonly securityLifecycle: SecurityLifecycle;
+  readonly schema: {
+    readonly currentVersion: number;
+    readonly upgrading: boolean;
+    readonly requiredVersion?: number;
+    readonly latestVersion?: number;
+  };
+  readonly replica: {
+    /** Decimal u64 for JSON/IPC parity. */
+    readonly localRevision: string;
+    readonly syncNeeded: boolean;
+    readonly pendingOutbox: number;
+  };
+  readonly lease: {
+    readonly state: 'none' | 'active' | 'expired' | 'stopped';
+    readonly expiresAtMs?: number;
+    readonly errorCode?: string;
+  };
+  readonly subscriptions: readonly DiagnosticSubscription[];
+  readonly subscriptionsTruncated: boolean;
+  readonly lastRound?: DiagnosticLastRound;
+  readonly lastChange?: DiagnosticLastChange;
+  readonly storage: ClientDiagnosticsStorage;
+}
+
+export type ClientDiagnosticsListener = (
+  snapshot: ClientDiagnosticsSnapshot,
+) => void;
+
+export class ClientDiagnosticsEmitter {
+  readonly #listeners = new Set<ClientDiagnosticsListener>();
+
+  get observed(): boolean {
+    return this.#listeners.size > 0;
+  }
+
+  on(listener: ClientDiagnosticsListener): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  emit(snapshot: ClientDiagnosticsSnapshot): void {
+    for (const listener of this.#listeners) {
+      try {
+        listener(snapshot);
+      } catch {
+        // Diagnostics observers cannot alter sync correctness.
+      }
+    }
+  }
+}
+
+/** Host wrappers replace topology facts without changing core evidence. */
+export function withClientDiagnosticsHost(
+  snapshot: ClientDiagnosticsSnapshot,
+  host: ClientDiagnosticsHost,
+): ClientDiagnosticsSnapshot {
+  return { ...snapshot, host };
+}

package/src/index.ts

@@ -15,6 +15,7 @@ export * from './client';
 export * from './content-type';
 export * from './database';
 export * from './devtools';
+export * from './diagnostics';
 export * from './encryption';
 export * from './errors';
 export * from './http';

package/src/worker-entry.ts

@@ -15,6 +15,10 @@
  */
 import { SyncClient } from './client';
 import type { ClientDatabase } from './database';
+import {
+  type ClientDiagnosticsSnapshot,
+  withClientDiagnosticsHost,
+} from './diagnostics';
 import { encryptionConfigFromKeyring } from './encryption';
 import { ClientSyncError } from './errors';
 import {
@@ -338,6 +342,22 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     started.onChange((batch) => {
       if (!closed) post({ t: 'event', event: { kind: 'change', batch } });
     });
+    const postDiagnostics = (snapshot: ClientDiagnosticsSnapshot): void => {
+      if (closed) return;
+      post({
+        t: 'event',
+        event: {
+          kind: 'diagnostics',
+          snapshot: withClientDiagnosticsHost(snapshot, {
+            kind: 'worker',
+            role: 'leader',
+            connectivity: offline ? 'offline' : snapshot.host.connectivity,
+            realtime: snapshot.host.realtime,
+          }),
+        },
+      });
+    };
+    started.onDiagnostics(postDiagnostics);
     await started.start();
     realtimeConnector =
       overrides.createRealtime !== undefined
@@ -411,6 +431,15 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     querySnapshot: (spec) => requireClient().querySnapshot(spec),
     localRevision: () => requireClient().localRevision,
     statusSnapshot: () => requireClient().statusSnapshot(),
+    diagnosticsSnapshot: (request) => {
+      const snapshot = requireClient().diagnosticsSnapshot(request);
+      return withClientDiagnosticsHost(snapshot, {
+        kind: 'worker',
+        role: 'leader',
+        connectivity: offline ? 'offline' : snapshot.host.connectivity,
+        realtime: snapshot.host.realtime,
+      });
+    },
     conflicts: () => requireClient().conflicts,
     rejections: () => requireClient().rejections,
     commitOutcome: (clientCommitId) =>
@@ -434,6 +463,21 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     setOffline: (value) => {
       offline = value;
       if (offline) client?.disconnectRealtime();
+      else if (client !== undefined) {
+        const snapshot = client.diagnosticsSnapshot();
+        post({
+          t: 'event',
+          event: {
+            kind: 'diagnostics',
+            snapshot: withClientDiagnosticsHost(snapshot, {
+              kind: 'worker',
+              role: 'leader',
+              connectivity: snapshot.host.connectivity,
+              realtime: snapshot.host.realtime,
+            }),
+          },
+        });
+      }
     },
     close: async () => {
       closed = true;

package/src/worker-host.ts

@@ -40,6 +40,13 @@ import type {
 } from './client';
 import type { SqlRow, SqlValue } from './database';
 import { registerDevtools } from './devtools';
+import {
+  ClientDiagnosticsEmitter,
+  type ClientDiagnosticsListener,
+  type ClientDiagnosticsRequest,
+  type ClientDiagnosticsSnapshot,
+  withClientDiagnosticsHost,
+} from './diagnostics';
 import type { EncryptionKeyringConfig } from './encryption';
 import { ClientSyncError } from './errors';
 import {
@@ -180,6 +187,8 @@ export interface SyncClientHandleConfig {
   readonly onUpgrading?: (upgrading: boolean) => void;
   /** §8.6: presence on a scope key changed. */
   readonly onPresence?: (scopeKey: string) => void;
+  /** Atomic privacy-safe diagnostics changed. */
+  readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
 }
 
 interface Pending {
@@ -247,6 +256,7 @@ export class SyncClientHandle {
   readonly #invalidation: InvalidationEmitter;
   readonly #changes: ChangeEmitter;
   readonly #presence: Set<(scopeKey: string) => void>;
+  readonly #diagnostics: ClientDiagnosticsEmitter;
   readonly #roleListeners: Set<(role: HandleRole) => void>;
   readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
   readonly #devtoolsUnregister: () => void;
@@ -262,6 +272,7 @@ export class SyncClientHandle {
     invalidation: InvalidationEmitter;
     changes: ChangeEmitter;
     presence: Set<(scopeKey: string) => void>;
+    diagnostics: ClientDiagnosticsEmitter;
     roleListeners?: Set<(role: HandleRole) => void>;
     leadershipListeners?: Set<(state: LeadershipState) => void>;
     leadership?: LeadershipState;
@@ -284,6 +295,7 @@ export class SyncClientHandle {
     this.#invalidation = internals.invalidation;
     this.#changes = internals.changes;
     this.#presence = internals.presence;
+    this.#diagnostics = internals.diagnostics;
     this.#roleListeners = internals.roleListeners ?? new Set();
     this.#leadershipListeners = internals.leadershipListeners ?? new Set();
     // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
@@ -346,6 +358,14 @@ export class SyncClientHandle {
       this.#changes.emit(event.batch);
       const legacy = invalidationFromChange(event.batch);
       if (legacy !== undefined) this.#invalidation.emit(legacy);
+    } else if (event.kind === 'diagnostics') {
+      this.#diagnostics.emit(
+        withClientDiagnosticsHost(event.snapshot, {
+          ...event.snapshot.host,
+          kind: 'worker',
+          role: this.#role,
+        }),
+      );
     }
   }
 
@@ -363,6 +383,10 @@ export class SyncClientHandle {
     return this.#changes.on(listener);
   }
 
+  onDiagnostics(listener: ClientDiagnosticsListener): () => void {
+    return this.#diagnostics.on(listener);
+  }
+
   /**
    * §8.6: subscribe to presence changes — the identical surface as
    * `SyncClient.onPresence`. Returns an unsubscribe function.
@@ -495,6 +519,17 @@ export class SyncClientHandle {
     return this.#call('statusSnapshot', []);
   }
 
+  async diagnosticsSnapshot(
+    request: ClientDiagnosticsRequest = {},
+  ): Promise<ClientDiagnosticsSnapshot> {
+    const snapshot = await this.#call('diagnosticsSnapshot', [request]);
+    return withClientDiagnosticsHost(snapshot, {
+      ...snapshot.host,
+      kind: 'worker',
+      role: this.#role,
+    });
+  }
+
   conflicts(): Promise<readonly ConflictRecord[]> {
     return this.#call('conflicts', []);
   }
@@ -767,6 +802,8 @@ function fireConfigCallbacks(
       ...(event.summary !== undefined ? { summary: event.summary } : {}),
       ...(event.error !== undefined ? { error: event.error } : {}),
     });
+  } else if (event.kind === 'diagnostics') {
+    config.onDiagnostics?.(event.snapshot);
   }
 }
 
@@ -786,6 +823,7 @@ export async function createSyncClientHandle(
   const invalidation = new InvalidationEmitter();
   const changes = new ChangeEmitter();
   const presence = new Set<(scopeKey: string) => void>();
+  const diagnostics = new ClientDiagnosticsEmitter();
   const roleListeners = new Set<(role: HandleRole) => void>();
   if (resolvedConfig.onRoleChange !== undefined)
     roleListeners.add(resolvedConfig.onRoleChange);
@@ -811,6 +849,7 @@ export async function createSyncClientHandle(
       invalidation,
       changes,
       presence,
+      diagnostics,
       roleListeners,
       leadershipListeners,
     });
@@ -826,6 +865,7 @@ export async function createSyncClientHandle(
       invalidation,
       changes,
       presence,
+      diagnostics,
       roleListeners,
       leadershipListeners,
     });
@@ -836,6 +876,7 @@ export async function createSyncClientHandle(
     invalidation,
     changes,
     presence,
+    diagnostics,
     roleListeners,
     leadershipListeners,
   });
@@ -846,6 +887,7 @@ interface HandleParts {
   invalidation: InvalidationEmitter;
   changes: ChangeEmitter;
   presence: Set<(scopeKey: string) => void>;
+  diagnostics: ClientDiagnosticsEmitter;
   roleListeners: Set<(role: HandleRole) => void>;
   leadershipListeners: Set<(state: LeadershipState) => void>;
 }
@@ -904,6 +946,7 @@ async function bootLeader(
     invalidation: parts.invalidation,
     changes: parts.changes,
     presence: parts.presence,
+    diagnostics: parts.diagnostics,
     roleListeners: parts.roleListeners,
     leadershipListeners: parts.leadershipListeners,
   });
@@ -1009,6 +1052,7 @@ async function bootFollower(
     invalidation: parts.invalidation,
     changes: parts.changes,
     presence: parts.presence,
+    diagnostics: parts.diagnostics,
     roleListeners: parts.roleListeners,
     leadershipListeners: parts.leadershipListeners,
   });

package/src/worker-protocol.ts

@@ -34,6 +34,10 @@ import type {
   WindowState,
 } from './client';
 import type { SqlRow, SqlValue } from './database';
+import type {
+  ClientDiagnosticsRequest,
+  ClientDiagnosticsSnapshot,
+} from './diagnostics';
 import type { EncryptionKeyringConfig } from './encryption';
 import type {
   ClientChangeBatch,
@@ -153,6 +157,9 @@ export interface WorkerApi {
   querySnapshot(spec: QueryReadSpec): QuerySnapshot;
   localRevision(): LocalRevision;
   statusSnapshot(): SyncStatusSnapshot;
+  diagnosticsSnapshot(
+    request?: ClientDiagnosticsRequest,
+  ): ClientDiagnosticsSnapshot;
   conflicts(): readonly ConflictRecord[];
   rejections(): readonly RejectionRecord[];
   commitOutcome(clientCommitId: string): CommitOutcome | undefined;
@@ -240,6 +247,11 @@ export type SyncWorkerEvent =
       /** Exact revisioned core transaction; Sets and bigint clone directly. */
       readonly kind: 'change';
       readonly batch: ClientChangeBatch;
+    }
+  | {
+      /** Atomic privacy-safe health/support evidence from the worker core. */
+      readonly kind: 'diagnostics';
+      readonly snapshot: ClientDiagnosticsSnapshot;
     };
 
 export type WorkerToMainMessage =