@syncular/client 0.15.16 → 0.15.18

package/dist/diagnostics.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.js';
+export declare const CLIENT_DIAGNOSTICS_VERSION: 1;
+export declare const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
+export declare 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 declare class ClientDiagnosticsEmitter {
+    #private;
+    get observed(): boolean;
+    on(listener: ClientDiagnosticsListener): () => void;
+    emit(snapshot: ClientDiagnosticsSnapshot): void;
+}
+/** Host wrappers replace topology facts without changing core evidence. */
+export declare function withClientDiagnosticsHost(snapshot: ClientDiagnosticsSnapshot, host: ClientDiagnosticsHost): ClientDiagnosticsSnapshot;

package/dist/diagnostics.js

@@ -0,0 +1,27 @@
+export const CLIENT_DIAGNOSTICS_VERSION = 1;
+export const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
+export const MAX_DIAGNOSTIC_DOMAINS = 256;
+export class ClientDiagnosticsEmitter {
+    #listeners = new Set();
+    get observed() {
+        return this.#listeners.size > 0;
+    }
+    on(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    emit(snapshot) {
+        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, host) {
+    return { ...snapshot, host };
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/worker-entry.js

@@ -14,6 +14,7 @@
  * the core owns exactly one loop.
  */
 import { SyncClient } from './client.js';
+import { withClientDiagnosticsHost, } from './diagnostics.js';
 import { encryptionConfigFromKeyring } from './encryption.js';
 import { ClientSyncError } from './errors.js';
 import { httpBlobTransport, httpSegmentDownloader, httpSyncTransport, webSocketRealtimeConnector, } from './http.js';
@@ -251,6 +252,23 @@ export function startSyncWorker(overrides = {}) {
             if (!closed)
                 post({ t: 'event', event: { kind: 'change', batch } });
         });
+        const postDiagnostics = (snapshot) => {
+            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
@@ -315,6 +333,15 @@ export function startSyncWorker(overrides = {}) {
         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) => requireClient().commitOutcome(clientCommitId),
@@ -337,6 +364,21 @@ export function startSyncWorker(overrides = {}) {
             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/dist/worker-host.d.ts

@@ -25,6 +25,7 @@ import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
 import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
+import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
 import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLease, type LeaderLock } from './leader-lock.js';
@@ -107,6 +108,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;
 }
 /**
  * A running worker core owned by THIS tab (the leader). Wraps the worker,
@@ -145,6 +148,7 @@ export declare 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;
@@ -163,6 +167,7 @@ export declare class SyncClientHandle {
      */
     onInvalidate(listener: InvalidationListener): () => void;
     onChange(listener: ClientChangeListener): () => void;
+    onDiagnostics(listener: ClientDiagnosticsListener): () => void;
     /**
      * §8.6: subscribe to presence changes — the identical surface as
      * `SyncClient.onPresence`. Returns an unsubscribe function.
@@ -190,6 +195,7 @@ export declare class SyncClientHandle {
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
     localRevision(): Promise<LocalRevision>;
     statusSnapshot(): Promise<SyncStatusSnapshot>;
+    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
     conflicts(): Promise<readonly ConflictRecord[]>;
     rejections(): Promise<readonly RejectionRecord[]>;
     commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;

package/dist/worker-host.js

@@ -1,4 +1,5 @@
 import { registerDevtools } from './devtools.js';
+import { ClientDiagnosticsEmitter, withClientDiagnosticsHost, } from './diagnostics.js';
 import { ClientSyncError } from './errors.js';
 import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
@@ -60,6 +61,7 @@ export class SyncClientHandle {
     #invalidation;
     #changes;
     #presence;
+    #diagnostics;
     #roleListeners;
     #leadershipListeners;
     #devtoolsUnregister;
@@ -84,6 +86,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.
@@ -150,6 +153,13 @@ export class SyncClientHandle {
             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,
+            }));
+        }
     }
     /**
      * TODO 3.1 / I1: subscribe to fine-grained invalidation — the identical
@@ -163,6 +173,9 @@ export class SyncClientHandle {
     onChange(listener) {
         return this.#changes.on(listener);
     }
+    onDiagnostics(listener) {
+        return this.#diagnostics.on(listener);
+    }
     /**
      * §8.6: subscribe to presence changes — the identical surface as
      * `SyncClient.onPresence`. Returns an unsubscribe function.
@@ -252,6 +265,14 @@ export class SyncClientHandle {
     statusSnapshot() {
         return this.#call('statusSnapshot', []);
     }
+    async diagnosticsSnapshot(request = {}) {
+        const snapshot = await this.#call('diagnosticsSnapshot', [request]);
+        return withClientDiagnosticsHost(snapshot, {
+            ...snapshot.host,
+            kind: 'worker',
+            role: this.#role,
+        });
+    }
     conflicts() {
         return this.#call('conflicts', []);
     }
@@ -470,6 +491,9 @@ function fireConfigCallbacks(config, event) {
             ...(event.error !== undefined ? { error: event.error } : {}),
         });
     }
+    else if (event.kind === 'diagnostics') {
+        config.onDiagnostics?.(event.snapshot);
+    }
 }
 /**
  * Acquire leadership, spawn the worker, initialize the core inside it.
@@ -485,6 +509,7 @@ export async function createSyncClientHandle(config) {
     const invalidation = new InvalidationEmitter();
     const changes = new ChangeEmitter();
     const presence = new Set();
+    const diagnostics = new ClientDiagnosticsEmitter();
     const roleListeners = new Set();
     if (resolvedConfig.onRoleChange !== undefined)
         roleListeners.add(resolvedConfig.onRoleChange);
@@ -507,6 +532,7 @@ export async function createSyncClientHandle(config) {
             invalidation,
             changes,
             presence,
+            diagnostics,
             roleListeners,
             leadershipListeners,
         });
@@ -521,6 +547,7 @@ export async function createSyncClientHandle(config) {
             invalidation,
             changes,
             presence,
+            diagnostics,
             roleListeners,
             leadershipListeners,
         });
@@ -530,6 +557,7 @@ export async function createSyncClientHandle(config) {
         invalidation,
         changes,
         presence,
+        diagnostics,
         roleListeners,
         leadershipListeners,
     });
@@ -571,6 +599,7 @@ async function bootLeader(config, lockName, lease, parts) {
         invalidation: parts.invalidation,
         changes: parts.changes,
         presence: parts.presence,
+        diagnostics: parts.diagnostics,
         roleListeners: parts.roleListeners,
         leadershipListeners: parts.leadershipListeners,
     });
@@ -659,6 +688,7 @@ async function bootFollower(config, lockName, lock, parts) {
         invalidation: parts.invalidation,
         changes: parts.changes,
         presence: parts.presence,
+        diagnostics: parts.diagnostics,
         roleListeners: parts.roleListeners,
         leadershipListeners: parts.leadershipListeners,
     });

package/dist/worker-protocol.d.ts

@@ -20,6 +20,7 @@ import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
 import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
+import type { ClientDiagnosticsRequest, ClientDiagnosticsSnapshot } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
 import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
@@ -107,6 +108,7 @@ 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;
@@ -180,6 +182,10 @@ 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 = {
     readonly t: 'ready';

package/package.json

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