@syncular/client 0.15.15 → 0.15.17

package/README.md

@@ -179,6 +179,35 @@ The state is a discriminated union covering startup, migration,
 children; a blocked live query has `phase === 'blocked'`, never an indefinite
 loading state.
 
+## Privacy-safe support diagnostics
+
+Every direct and Worker/multi-tab client exposes the same versioned snapshot:
+
+```ts
+const snapshot = await client.diagnosticsSnapshot({
+  expectedSubscriptions: [
+    { id: 'membership-security', table: 'facility_memberships' },
+    { id: 'scheduler-window', table: 'surgeries' },
+  ],
+});
+
+const off = client.onDiagnostics(() => refreshSupportView());
+```
+
+`expectedSubscriptions` contains application intent only—stable PHI-free ids
+and generated table names, never scopes. It lets a support screen distinguish
+an absent registration from a legitimate zero-row completed bootstrap. The
+snapshot also distinguishes reset, revocation, failure, schema floor, lease
+stop, pending outbox, offline transport, and storage pressure/unreadability.
+Worker leaders and followers return identical evidence with their honest role.
+
+The contract intentionally excludes scope values, rows and clinical row
+counts, SQL, paths, client/actor/lease ids, auth, keys, mutation bodies, stack
+traces, and arbitrary prose. It is safe to copy the JSON snapshot into a
+redacted support ticket as long as the application also keeps subscription ids
+free of patient/user data. Do not attach database files, console dumps, query
+results, or app state alongside it. See SPEC §7.6.
+
 ## Durable commit outcomes
 
 `SyncClient` and every host bridge expose `commitOutcome(id)`,

package/dist/client.d.ts

@@ -10,6 +10,7 @@
 import { type ScopeMap, type WakeReason } from '@syncular/core';
 import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
 import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
+import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
 import type { EncryptionConfig } from './encryption.js';
 import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLock } from './leader-lock.js';
@@ -283,6 +284,13 @@ export declare class SyncClient {
     onInvalidate(listener: InvalidationListener): () => void;
     /** Subscribe to exact revisioned observer transactions (SPEC §7.5). */
     onChange(listener: ClientChangeListener): () => void;
+    /** Subscribe to complete, privacy-safe diagnostic snapshots. */
+    onDiagnostics(listener: ClientDiagnosticsListener): () => void;
+    /**
+     * One atomic support/product-health view. It never returns scope values,
+     * rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
+     */
+    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): ClientDiagnosticsSnapshot;
     /** One call for the complete status domain used by reactive hosts. */
     statusSnapshot(): SyncStatusSnapshot;
     /**

package/dist/client.js

@@ -11,6 +11,7 @@ import { canonicalScopeJson, decodeMessage, decodeRow, decodeRowsSegment, encode
 import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, upsertLocalRow, } from './apply.js';
 import { clearPendingUpload, computeBlobId, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, reconcileBlobRefcounts, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
+import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, } from './diagnostics.js';
 import { ClientSyncError } from './errors.js';
 import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
@@ -110,6 +111,9 @@ export class SyncClient {
     #invalidation = new InvalidationEmitter();
     /** §8.6: subscribable presence-change listeners (twin of onPresence). */
     #presenceListeners = new Set();
+    #diagnostics = new ClientDiagnosticsEmitter();
+    #lastRound;
+    #lastChange;
     /** The batch accumulator; non-undefined only inside `#applyBatch`. */
     #batch;
     /**
@@ -224,6 +228,7 @@ export class SyncClient {
             upgrading: async () => this.upgrading,
             onInvalidate: (listener) => this.onInvalidate(listener),
         });
+        this.#emitDiagnostics();
     }
     /**
      * §7.4.1/§7.4.2: compare the generated schema version to the persisted
@@ -359,6 +364,7 @@ export class SyncClient {
             this.#config.onSyncNeeded?.('startup');
             this.#config.onSyncIntent?.({ kind: 'interactive' });
         }
+        this.#emitDiagnostics();
     }
     // -- accessors ------------------------------------------------------------
     get clientId() {
@@ -452,6 +458,182 @@ export class SyncClient {
     onChange(listener) {
         return this.#changes.on(listener);
     }
+    /** Subscribe to complete, privacy-safe diagnostic snapshots. */
+    onDiagnostics(listener) {
+        return this.#diagnostics.on(listener);
+    }
+    /**
+     * One atomic support/product-health view. It never returns scope values,
+     * rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
+     */
+    diagnosticsSnapshot(request = {}) {
+        this.#requireActive();
+        const expected = request.expectedSubscriptions ?? [];
+        if (expected.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS) {
+            throw new ClientSyncError('sync.invalid_request', `diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`);
+        }
+        const registered = loadSubscriptions(this.#db);
+        const subscriptions = new Map();
+        for (const sub of registered) {
+            const reset = sub.cursor < 0 && sub.reasonCode === 'sync.cursor_expired';
+            const complete = sub.status === 'active' &&
+                sub.cursor >= 0 &&
+                sub.bootstrapState === undefined;
+            subscriptions.set(sub.id, {
+                id: sub.id,
+                table: sub.table,
+                state: sub.status === 'revoked'
+                    ? 'revoked'
+                    : sub.status === 'failed'
+                        ? 'failed'
+                        : reset
+                            ? 'reset'
+                            : complete
+                                ? 'complete'
+                                : 'bootstrapping',
+                complete,
+                cursor: sub.cursor,
+                ...(sub.reasonCode !== undefined
+                    ? { reasonCode: this.#diagnosticCode(sub.reasonCode) }
+                    : {}),
+            });
+        }
+        for (const item of expected) {
+            if (typeof item.id !== 'string' ||
+                item.id.length === 0 ||
+                typeof item.table !== 'string' ||
+                item.table.length === 0) {
+                throw new ClientSyncError('sync.invalid_request', 'diagnosticsSnapshot expected subscriptions require non-empty id and table strings');
+            }
+            const registeredSubscription = subscriptions.get(item.id);
+            if (registeredSubscription !== undefined &&
+                registeredSubscription.table !== item.table) {
+                subscriptions.set(item.id, {
+                    id: item.id,
+                    table: item.table,
+                    state: 'failed',
+                    complete: false,
+                    reasonCode: 'client.subscription_intent_mismatch',
+                });
+            }
+            else if (registeredSubscription === undefined) {
+                subscriptions.set(item.id, {
+                    id: item.id,
+                    table: item.table,
+                    state: 'unregistered',
+                    complete: false,
+                });
+            }
+        }
+        const capturedAtMs = this.#now();
+        const leaseState = this.#diagnosticLease(capturedAtMs);
+        const connectivity = this.#lastRound?.status === 'succeeded'
+            ? 'online'
+            : this.#lastRound?.status === 'failed' &&
+                this.#transportFailureCode(this.#lastRound.errorCode)
+                ? 'offline'
+                : 'unknown';
+        const expectedOrder = new Map(expected.map((item, index) => [item.id, index]));
+        const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
+            const aExpected = expectedOrder.get(a.id);
+            const bExpected = expectedOrder.get(b.id);
+            if (aExpected !== undefined || bExpected !== undefined) {
+                return ((aExpected ?? Number.MAX_SAFE_INTEGER) -
+                    (bExpected ?? Number.MAX_SAFE_INTEGER));
+            }
+            return a.id.localeCompare(b.id);
+        });
+        return {
+            version: CLIENT_DIAGNOSTICS_VERSION,
+            capturedAtMs,
+            host: {
+                kind: 'direct',
+                role: 'single',
+                connectivity,
+                realtime: this.#config.realtime === undefined
+                    ? 'unsupported'
+                    : this.#socket === undefined
+                        ? 'disconnected'
+                        : 'connected',
+            },
+            securityLifecycle: this.#securityLifecycle,
+            schema: {
+                currentVersion: this.#config.schema.version,
+                upgrading: this.#upgrading,
+                ...(this.#schemaFloor?.requiredSchemaVersion !== undefined
+                    ? { requiredVersion: this.#schemaFloor.requiredSchemaVersion }
+                    : {}),
+                ...(this.#schemaFloor?.latestSchemaVersion !== undefined
+                    ? { latestVersion: this.#schemaFloor.latestSchemaVersion }
+                    : {}),
+            },
+            replica: {
+                localRevision: getLocalRevision(this.#db).toString(),
+                syncNeeded: this.#needsPull,
+                pendingOutbox: listOutbox(this.#db).length,
+            },
+            lease: leaseState,
+            subscriptions: allSubscriptions.slice(0, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS),
+            subscriptionsTruncated: allSubscriptions.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
+            ...(this.#lastRound !== undefined ? { lastRound: this.#lastRound } : {}),
+            ...(this.#lastChange !== undefined
+                ? { lastChange: this.#lastChange }
+                : {}),
+            storage: this.#diagnosticStorage(),
+        };
+    }
+    #diagnosticLease(nowMs) {
+        const lease = this.#leaseState;
+        if (lease?.errorCode !== undefined) {
+            return {
+                state: 'stopped',
+                errorCode: this.#diagnosticCode(lease.errorCode),
+                ...(lease.expiresAtMs !== undefined
+                    ? { expiresAtMs: lease.expiresAtMs }
+                    : {}),
+            };
+        }
+        if (lease?.expiresAtMs === undefined)
+            return { state: 'none' };
+        return {
+            state: lease.expiresAtMs <= nowMs ? 'expired' : 'active',
+            expiresAtMs: lease.expiresAtMs,
+        };
+    }
+    #diagnosticStorage() {
+        try {
+            const pageCount = Number(this.#db.query('PRAGMA page_count')[0]?.page_count ?? 0);
+            const pageSize = Number(this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0);
+            const outboxBytes = Number(this.#db.query('SELECT COALESCE(SUM(LENGTH(operations)), 0) AS bytes FROM _syncular_outbox')[0]?.bytes ?? 0);
+            const outcome = this.#db.query(`SELECT COUNT(*) AS entries,
+                COALESCE(SUM(LENGTH(results) + COALESCE(LENGTH(operations), 0)), 0) AS bytes
+           FROM _syncular_commit_outcomes`)[0];
+            const blobBytes = this.#hasBlobs
+                ? Number(this.#db.query('SELECT COALESCE(SUM(byte_length), 0) AS bytes FROM _syncular_blobs')[0]?.bytes ?? 0)
+                : 0;
+            const pressure = this.#config.blobCacheMaxBytes !== undefined &&
+                blobBytes > this.#config.blobCacheMaxBytes;
+            return {
+                status: pressure ? 'pressure' : 'healthy',
+                databaseBytesApprox: Math.max(0, pageCount * pageSize),
+                pendingOutboxBytesApprox: Math.max(0, outboxBytes),
+                retainedOutcomeBytesApprox: Math.max(0, Number(outcome?.bytes ?? 0)),
+                retainedOutcomeEntries: Math.max(0, Number(outcome?.entries ?? 0)),
+                blobCacheBytesApprox: Math.max(0, blobBytes),
+                ...(pressure
+                    ? { pressureReasonCode: 'client.blob_cache_over_limit' }
+                    : {}),
+            };
+        }
+        catch {
+            return { status: 'unreadable' };
+        }
+    }
+    #emitDiagnostics() {
+        if (!this.#started || this.#securityLifecycle !== 'active')
+            return;
+        this.#diagnostics.emit(this.diagnosticsSnapshot());
+    }
     /** One call for the complete status domain used by reactive hosts. */
     statusSnapshot() {
         this.#requireStarted();
@@ -502,10 +684,25 @@ export class SyncClient {
         }
         if (revision !== undefined) {
             const event = batch.finish(revision, status);
+            const tables = [...new Set(event.tables.map((entry) => entry.table))];
+            const windows = [...new Set(event.windows.map((entry) => entry.table))];
+            this.#lastChange = {
+                revision: revision.toString(),
+                recordedAtMs: this.#now(),
+                tables: tables.slice(0, MAX_DIAGNOSTIC_DOMAINS),
+                windows: windows.slice(0, MAX_DIAGNOSTIC_DOMAINS),
+                domainsTruncated: tables.length > MAX_DIAGNOSTIC_DOMAINS ||
+                    windows.length > MAX_DIAGNOSTIC_DOMAINS,
+                statusChanged: event.status !== undefined,
+                conflictsChanged: event.conflictsChanged,
+                rejectionsChanged: event.rejectionsChanged,
+                outcomesChanged: event.outcomesChanged,
+            };
             this.#changes.emit(event);
             const legacy = invalidationFromChange(event);
             if (legacy !== undefined)
                 this.#invalidation.emit(legacy);
+            this.#emitDiagnostics();
         }
         return result;
     }
@@ -870,6 +1067,7 @@ export class SyncClient {
                 scopes: input.scopes,
                 ...(input.params !== undefined ? { params: input.params } : {}),
             });
+            this.#emitDiagnostics();
             return;
         }
         saveSubscription(this.#db, {
@@ -880,10 +1078,12 @@ export class SyncClient {
             cursor: -1,
             status: 'active',
         });
+        this.#emitDiagnostics();
     }
     unsubscribe(id) {
         this.#requireActive();
         deleteSubscription(this.#db, id);
+        this.#emitDiagnostics();
     }
     // -- windowed subscriptions (§4.8) ------------------------------------------
     /**
@@ -1403,10 +1603,65 @@ export class SyncClient {
             return Promise.reject(new ClientSyncError('sync.invalid_request', 'sync() is already running — the core owns one loop (coalesce wake-ups)'));
         }
         this.#syncOutstanding = true;
-        return this.#serialize(() => this.#runSync()).finally(() => {
+        const startedAtMs = this.#now();
+        return this.#serialize(() => this.#runSync())
+            .then((summary) => {
+            const completedAtMs = this.#now();
+            this.#lastRound = {
+                status: 'succeeded',
+                startedAtMs,
+                completedAtMs,
+                durationMs: Math.max(0, completedAtMs - startedAtMs),
+                counters: this.#diagnosticRoundCounters(summary),
+            };
+            this.#emitDiagnostics();
+            return summary;
+        }, (error) => {
+            const completedAtMs = this.#now();
+            const code = error.code;
+            this.#lastRound = {
+                status: 'failed',
+                startedAtMs,
+                completedAtMs,
+                durationMs: Math.max(0, completedAtMs - startedAtMs),
+                errorCode: typeof code === 'string'
+                    ? this.#diagnosticCode(code)
+                    : 'client.unknown_failure',
+            };
+            this.#emitDiagnostics();
+            throw error;
+        })
+            .finally(() => {
             this.#syncOutstanding = false;
         });
     }
+    #diagnosticRoundCounters(summary) {
+        return {
+            pushed: summary.pushed,
+            applied: summary.applied.length,
+            rejected: summary.rejected.length,
+            retryable: summary.retryable.length,
+            conflicts: summary.conflicts.length,
+            commitsApplied: summary.commitsApplied,
+            segmentRowsApplied: summary.segmentRowsApplied,
+            bootstrapping: summary.bootstrapping.length,
+            resets: summary.resets.length,
+            revoked: summary.revoked.length,
+            failed: summary.failed.length,
+            deferredCommits: summary.deferredCommits ?? 0,
+        };
+    }
+    #transportFailureCode(code) {
+        return (code === 'transport.failed' ||
+            code === 'transport.unavailable' ||
+            code === 'sync.transport_failed' ||
+            code === 'client.worker_failed');
+    }
+    #diagnosticCode(code) {
+        return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
+            ? code
+            : 'client.unknown_failure';
+    }
     async #runSync() {
         if (this.#schemaFloor !== undefined) {
             return {
@@ -1547,8 +1802,17 @@ export class SyncClient {
      */
     #roundTrip(request) {
         const socket = this.#socket;
-        if (socket === undefined)
-            return this.#config.transport(request);
+        if (socket === undefined) {
+            return Promise.resolve()
+                .then(() => this.#config.transport(request))
+                .catch((error) => {
+                if (error instanceof ClientSyncError ||
+                    typeof error?.code === 'string') {
+                    throw error;
+                }
+                throw new ClientSyncError('sync.transport_failed', `transport round failed: ${error instanceof Error ? error.message : String(error)}`, true);
+            });
+        }
         return new Promise((resolve, reject) => {
             // sync() already enforces one round in flight (§8.7).
             this.#pendingRound = {
@@ -1592,6 +1856,7 @@ export class SyncClient {
                 this.#socket = undefined;
                 this.#presence.clear(); // §8.6.1: presence is per-connection
                 this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
+                this.#emitDiagnostics();
             },
         });
         if (this.#securityLifecycle === 'preflight') {
@@ -1599,12 +1864,14 @@ export class SyncClient {
             throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'realtime connected after the client entered security preflight');
         }
         this.#socket = socket;
+        this.#emitDiagnostics();
     }
     disconnectRealtime() {
         this.#socket?.close();
         this.#socket = undefined;
         this.#presence.clear(); // §8.6.1: presence is per-connection
         this.#abortPendingRound('realtime socket disconnected mid-round (§8.7)');
+        this.#emitDiagnostics();
     }
     /**
      * §8.7 channel-tag routing (synchronous, so chunk order is preserved):

package/dist/diagnostics.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 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;
+    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,24 @@
+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();
+    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;