@fairfox/polly 0.65.0 → 0.67.0

package/dist/src/shared/lib/mesh-client.d.ts

@@ -164,6 +164,56 @@ export interface CreateMeshClientOptions {
  * production call site is inside {@link createMeshClient}.
  */
 export declare function resolveIceServers(rtc: CreateMeshClientOptions["rtc"]): Promise<RTCIceServer[] | undefined>;
+/** Per-(docId, peerId) view into Automerge's `CollectionSynchronizer`.
+ * Built once per snapshot read and consulted from {@link buildHandleEntry}.
+ * Structured this way so the docSynchronizer lookup is paid once per
+ * docId, not once per (docId × peer). */
+interface PerPeerDocSyncView {
+    /** `true` iff Automerge's `CollectionSynchronizer.docSynchronizers`
+     * has an entry for this documentId. A handle that exists in
+     * `repo.handles` but has no corresponding `docSynchronizer` is the
+     * `addDocument`-was-never-called fingerprint — Automerge's
+     * NetworkSubsystem can never invoke `send` for it because no
+     * synchronizer is wired up. */
+    docSynchronizerExists: boolean;
+    /** `true` iff the docSynchronizer for this documentId has registered
+     * this peer in its internal peer list (`#peers`). `false` with
+     * `docSynchronizerExists: true` is the symmetric polly#107 gap: the
+     * synchronizer exists (`addDocument` ran) but `addPeer` was never
+     * called for this peer on this doc — typically because the handle
+     * was created AFTER `peer-candidate` fired and Automerge's
+     * `addDocument`-iterates-known-peers path missed it. `undefined`
+     * when no docSynchronizer exists. */
+    docSynchronizerKnowsPeer: boolean | undefined;
+    /** Automerge's `DocSynchronizer.peerStates[peerId]` — one of
+     * `"unknown"`, `"has"`, `"unavailable"`, `"wants"`. `"unknown"`
+     * with `lastSyncMessageOutAt` set means the local side sent its
+     * opening handshake but never advanced past it; this is the
+     * wedged-pair fingerprint #112 names. `undefined` when no
+     * docSynchronizer exists OR when the synchronizer exists but
+     * doesn't track this peer. */
+    peerDocumentStatus: string | undefined;
+}
+/** Minimal structural shape we lift off Automerge's hidden
+ * `Repo.synchronizer` / `CollectionSynchronizer` types. Kept narrow
+ * so a future Automerge bump that renames a private rip doesn't
+ * topple the snapshot path. */
+interface SynchronizerStructural {
+    docSynchronizers?: Record<string, {
+        hasPeer?: (peerId: string) => boolean;
+        peerStates?: Record<string, string>;
+    }>;
+}
+/** Internal — exported for direct unit-test coverage of the #112
+ * structural reader and snapshot wiring. Not part of the public API. */
+export declare const __test__: {
+    buildSyncView: (synchronizer: SynchronizerStructural | undefined, docId: string, peerId: string) => PerPeerDocSyncView;
+    EMPTY_SYNC_VIEW: PerPeerDocSyncView;
+    getCollectionSynchronizer: (repo: Repo) => SynchronizerStructural | undefined;
+    enrichPeerSlot: (peer: ReturnType<MeshWebRTCAdapter["getPeerStateSnapshot"]>["peers"][number], knownHandleIds: string[], repoHandles: Record<string, {
+        state: unknown;
+    } | undefined>, synchronizer: SynchronizerStructural | undefined) => MeshClientPeerStateSnapshot["peers"][number];
+};
 /** Polly#107 post-v0.60 instrumentation. Walks the lazy-wrapper log
  * and groups records by `docId`; emits one entry per `docId` that
  * appears in more than one record. Surfaces the "17 wrappers / 16
@@ -221,6 +271,31 @@ export interface MeshClientHandleSnapshot {
      * `"sync"` after handshake, `"request"` while the local side is
      * asking. */
     lastSyncMessageOutType: string | undefined;
+    /** #112 diagnostic. `true` iff Automerge's `CollectionSynchronizer`
+     * has a `docSynchronizer` entry for this document. A handle in
+     * `repo.handles` with no docSynchronizer is the
+     * `addDocument`-never-ran fingerprint: Automerge's NetworkSubsystem
+     * can never call `send` for it because no synchronizer is wired up. */
+    docSynchronizerExists: boolean;
+    /** #112 diagnostic. `true` iff the docSynchronizer for this document
+     * has this peer in its internal peer list. `false` with
+     * `docSynchronizerExists: true` is the symmetric polly#107 gap —
+     * the synchronizer exists but `addPeer` was never invoked on it for
+     * this peer, typically because the handle was created AFTER
+     * `peer-candidate` fired and Automerge's
+     * `addDocument`-iterates-peers path missed it. `undefined` when no
+     * docSynchronizer exists. */
+    docSynchronizerKnowsPeer: boolean | undefined;
+    /** #112 diagnostic. Automerge's
+     * `DocSynchronizer.peerStates[peerId]` — one of `"unknown"`,
+     * `"has"`, `"unavailable"`, `"wants"`. `"unknown"` together with a
+     * set `lastSyncMessageOutAt` is the wedged-pair fingerprint this
+     * ticket names: the opening handshake left the wire but the
+     * synchronizer never learned whether the remote has the doc, so
+     * `generateSyncMessage` quiesces. `undefined` when no
+     * docSynchronizer exists OR when the synchronizer does not track
+     * this peer. */
+    peerDocumentStatus: string | undefined;
 }
 /** Polly#107 H5 diagnostics: surfaces the `mesh-state` module
  * instance identity so a single snapshot read tells the operator
@@ -414,3 +489,4 @@ export interface MeshClient {
  * peer connections negotiate asynchronously in the background.
  */
 export declare function createMeshClient(options: CreateMeshClientOptions): Promise<MeshClient>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairfox/polly",
-  "version": "0.65.0",
+  "version": "0.67.0",
   "private": false,
   "type": "module",
   "description": "Multi-execution-context framework with reactive state and cross-context messaging for Chrome extensions, PWAs, and worker-based applications",