@vrtmrz/livesync-commonlib 0.3.2 → 0.4.0

package/dist/replication/trystero/TrysteroReplicator.js

@@ -1,3 +1,15 @@
+import { reportP2PDiagnostic } from "../../p2p/p2pDiagnostics.js";
+import {
+  authenticationResultDiagnostic,
+  authenticationFailureDiagnostic,
+  pullResultDiagnostic,
+  pullFailureDiagnostic,
+  notificationFailureDiagnostic
+} from "./p2pReplicationDiagnostics.js";
+import {
+  projectDirectionProgress,
+  projectAcknowledgedAttempt
+} from "./p2pReplicationProgress.js";
 import { parsePeerPatterns } from "./peerPatterns.js";
 import {
   TweakValuesShouldMatchedTemplate,
@@ -42,6 +54,7 @@ async function encrypt(data, passphrase) {
 async function decrypt(encryptedData, passphrase) {
   return await decryptWithEphemeralSalt(encryptedData, passphrase);
 }
+let nextProgressAttempt = 0;
 const P2P_REPLICATION_COMPLETED = Object.freeze({ status: "completed", ok: true });
 const P2P_REPLICATION_CANCELLED = Object.freeze({ status: "cancelled" });
 function p2pReplicationFailed(error) {
@@ -59,11 +72,17 @@ class TrysteroReplicator {
   _env;
   finiteOperationOwner;
   disposed = false;
+  acknowledgedAttempts = /* @__PURE__ */ new Map();
   fallbackAutomationCoordinator = new P2PAutomationCoordinator();
   server;
   replicationStatus() {
     return {};
   }
+  reportDiagnostic(input) {
+    if (!this.disposed) {
+      reportP2PDiagnostic(this._env.reportDiagnostic, input);
+    }
+  }
   get settings() {
     return this._env.settings;
   }
@@ -137,6 +156,7 @@ class TrysteroReplicator {
   async close() {
     this.requestStatus();
     await this.server?.shutdown();
+    this.acknowledgedAttempts.clear();
     this._replicateFromPeers.clear();
     this._replicateToPeers.clear();
     this._watchingPeers.clear();
@@ -184,20 +204,46 @@ class TrysteroReplicator {
     const peerName = peer.name;
     const shouldAutoSync = this.autoSyncPeers.some((e) => e.test(peerName));
     const shouldAutoWatch = this.autoWatchPeers.some((e) => e.test(peerName));
-    if (!shouldAutoSync && !shouldAutoWatch) return;
+    if (!shouldAutoSync && !shouldAutoWatch) {
+      return;
+    }
     const acceptance = await this.server?.evaluatePeerAcceptance(peer.peerId);
-    if (acceptance !== "accepted") return;
+    if (acceptance !== "accepted") {
+      if (shouldAutoWatch) {
+        this.reportDiagnostic({
+          category: "sync",
+          code: "watch-skipped",
+          peerId: peer.peerId,
+          reason: "not-accepted"
+        });
+      }
+      return;
+    }
     if (shouldAutoSync) {
       await this.automationCoordinator.runBaseline(
         peerName,
         () => this.runFiniteReplicationActivity(() => this.sync(peer.peerId))
       );
     }
-    if (shouldAutoWatch && await this.getRemoteIsBroadcasting(peer.peerId) === true) {
-      this.watchPeer(peer.peerId);
+    if (shouldAutoWatch) {
+      await this.watchBroadcastingPeer(peer.peerId);
     }
   }
+  async watchBroadcastingPeer(peerId) {
+    const broadcasting = await this.getRemoteIsBroadcasting(peerId);
+    if (broadcasting === true) {
+      this.watchPeer(peerId);
+      return;
+    }
+    this.reportDiagnostic({
+      category: "sync",
+      code: "watch-skipped",
+      peerId,
+      reason: broadcasting === false ? "peer-not-broadcasting" : "peer-broadcast-unobserved"
+    });
+  }
   onPeerLeaved(peerId) {
+    this.acknowledgedAttempts.delete(peerId);
     void this.unwatchPeer(peerId);
   }
   _onSetup = false;
@@ -257,6 +303,12 @@ class TrysteroReplicator {
       },
       onProgress: async (fromPeerId) => {
         if (this._onSetup) {
+          this.reportDiagnostic({
+            category: "sync",
+            code: "change-notification-ignored",
+            peerId: fromPeerId,
+            reason: "setup-in-progress"
+          });
           return { error: toP2PWireError(new Error("The setup is in progress")) };
         }
         await this.onUpdateDatabase(fromPeerId);
@@ -300,9 +352,9 @@ class TrysteroReplicator {
         }
         return encrypt(JSON.stringify(setting), passphrase.trim());
       },
-      onProgressAcknowledged: async (fromPeerId, info) => {
+      onProgressAcknowledged: async (fromPeerId, info, acknowledgement) => {
         try {
-          await Promise.resolve(this.onProgressAcknowledged(fromPeerId, info));
+          await Promise.resolve(this.onProgressAcknowledged(fromPeerId, info, acknowledgement));
         } catch (e) {
           Logger("Error while acknowledging the progress", LOG_LEVEL_VERBOSE);
           Logger(e, LOG_LEVEL_VERBOSE);
@@ -341,8 +393,10 @@ class TrysteroReplicator {
         2e4,
         signal
       );
+      this.reportDiagnostic(authenticationResultDiagnostic(peerId, r));
       return r;
     } catch (e) {
+      this.reportDiagnostic(authenticationFailureDiagnostic(peerId, e, signal));
       Logger("Error while requesting authentication", LOG_LEVEL_VERBOSE);
       Logger(e, LOG_LEVEL_VERBOSE);
       return false;
@@ -402,9 +456,12 @@ class TrysteroReplicator {
   changes;
   _isBroadcasting = false;
   disableBroadcastChanges() {
+    const wasBroadcasting = this._isBroadcasting;
     this.changes?.cancel();
+    const needsDiagnostic = wasBroadcasting && this._isBroadcasting;
     this._isBroadcasting = false;
     this.dispatchStatus();
+    if (needsDiagnostic) this.reportDiagnostic({ category: "sync", code: "broadcast-disabled" });
   }
   enableBroadcastChanges() {
     if (this._isBroadcasting) return;
@@ -429,6 +486,7 @@ class TrysteroReplicator {
       await this.notifyProgress();
     });
     const closeChanges = (reason) => {
+      const wasBroadcasting = this._isBroadcasting;
       if (reason) {
         if (reason instanceof Error) {
           Logger(`Error while broadcasting the changes`, LOG_LEVEL_INFO);
@@ -443,9 +501,16 @@ class TrysteroReplicator {
       this.changes = void 0;
       this._isBroadcasting = false;
       this.dispatchStatus();
+      if (wasBroadcasting)
+        this.reportDiagnostic({
+          category: "sync",
+          code: "broadcast-disabled",
+          ...reason instanceof Error ? { reason: "replication-error" } : {}
+        });
     };
     void this.changes.on("error", closeChanges);
     void this.changes.on("complete", closeChanges);
+    this.reportDiagnostic({ category: "sync", code: "broadcast-enabled" });
     fireAndForget(async () => await this.notifyProgress());
   }
   /** Apply automatic broadcast policy without restarting this room. */
@@ -494,55 +559,51 @@ class TrysteroReplicator {
     this.onReplicationProgress(peerId, info);
   }
   onReplicationProgress(peerId, info) {
-    const name = this.server?._knownAdvertisements.get(peerId)?.name || peerId;
-    const stat = {
+    if (this.disposed) {
+      return false;
+    }
+    const name = this.server?._knownAdvertisements?.get(peerId)?.name || peerId;
+    this._env.events.emitEvent(EVENT_P2P_REPLICATOR_PROGRESS, {
       peerId,
       peerName: name,
-      fetching: {
-        max: 0,
-        current: 0,
-        isActive: false
-      }
-    };
-    if (info) {
-      stat.fetching = {
-        max: info.maxSeqInBatch,
-        current: info.lastSeq,
-        isActive: true
-      };
-    }
-    this._env.events.emitEvent(EVENT_P2P_REPLICATOR_PROGRESS, stat);
+      fetching: projectDirectionProgress(info)
+    });
     return true;
   }
-  onProgressAcknowledged(peerId, info) {
-    const name = this.server?._knownAdvertisements.get(peerId)?.name || peerId;
-    const ack = {
-      peerId,
-      peerName: name,
-      sending: {
-        max: 0,
-        current: 0,
-        isActive: false
+  onProgressAcknowledged(peerId, info, acknowledgement) {
+    if (this.disposed) {
+      return false;
+    }
+    if (acknowledgement) {
+      const next = projectAcknowledgedAttempt(this.acknowledgedAttempts.get(peerId), info, acknowledgement);
+      if (!next) {
+        return false;
       }
-    };
-    if (info) {
-      ack.sending = {
-        max: info.maxSeqInBatch,
-        current: info.lastSeq,
-        isActive: true
-      };
+      this.acknowledgedAttempts.set(peerId, next);
     }
-    this._env.events.emitEvent(EVENT_P2P_REPLICATOR_PROGRESS, ack);
+    const name = this.server?._knownAdvertisements?.get(peerId)?.name || peerId;
+    const sending = projectDirectionProgress(info ?? acknowledgement?.finalProgress);
+    sending.isActive = info != null;
+    this._env.events.emitEvent(EVENT_P2P_REPLICATOR_PROGRESS, {
+      peerId,
+      peerName: name,
+      sending
+    });
     return true;
   }
-  // Sending the progress to the remote peer
-  acknowledgeProgress(remotePeerId, info) {
-    if (!this.server) return;
-    const connection = this.server.getConnection(remotePeerId);
-    void connection.invokeRemoteFunction("onProgressAcknowledged", [this.server.serverPeerId, info], 500).catch((ex) => {
+  // Sending the progress to the remote peer.
+  acknowledgeProgress(remotePeerId, info, acknowledgement) {
+    if (!this.server || this.disposed) return;
+    try {
+      const connection = this.server.getConnection(remotePeerId);
+      void connection.invokeRemoteFunction("onProgressAcknowledged", [this.server.serverPeerId, info, acknowledgement], 500).catch((error) => {
+        Logger("Error while acknowledging the progress", LOG_LEVEL_VERBOSE);
+        Logger(error, LOG_LEVEL_VERBOSE);
+      });
+    } catch (error) {
       Logger("Error while acknowledging the progress", LOG_LEVEL_VERBOSE);
-      Logger(ex, LOG_LEVEL_VERBOSE);
-    });
+      Logger(error, LOG_LEVEL_VERBOSE);
+    }
   }
   async replicateFrom(remotePeer, showNotice = false, fromStart = false, skipOrdinaryReplicationPolicy = false, callerSignal) {
     return await this.runSessionFiniteOperation(
@@ -557,6 +618,23 @@ class TrysteroReplicator {
     );
   }
   async replicateFromWithinSession(remotePeer, showNotice, fromStart, skipOrdinaryReplicationPolicy, signal) {
+    this.reportDiagnostic({ category: "sync", code: "pull-started", peerId: remotePeer });
+    try {
+      const result = await this.pullFromWithinSession(
+        remotePeer,
+        showNotice,
+        fromStart,
+        skipOrdinaryReplicationPolicy,
+        signal
+      );
+      this.reportDiagnostic(pullResultDiagnostic(remotePeer, result.status));
+      return result;
+    } catch (error) {
+      this.reportDiagnostic(pullFailureDiagnostic(remotePeer, signal?.aborted ?? false));
+      throw error;
+    }
+  }
+  async pullFromWithinSession(remotePeer, showNotice, fromStart, skipOrdinaryReplicationPolicy, signal) {
     if (!skipOrdinaryReplicationPolicy && !await this.canStartOrdinaryReplication(showNotice)) {
       return p2pReplicationFailed(new Error("Replication is not ready"));
     }
@@ -571,14 +649,28 @@ class TrysteroReplicator {
     }
     this._replicateFromPeers.add(remotePeer);
     this.dispatchStatus();
+    const acknowledgement = { attempt: ++nextProgressAttempt };
+    let latestProgress = {
+      lastSeq: 0,
+      maxSeqInBatch: 0,
+      statistics: { documents: 0, checkedChanges: 0 }
+    };
+    this.dispatchReplicationProgress(remotePeer, latestProgress);
+    this.acknowledgeProgress(remotePeer, latestProgress, acknowledgement);
     try {
-      return await this.transferFromPeer(remotePeer, fromStart, logLevel, signal);
+      return await this.transferFromPeer(remotePeer, fromStart, logLevel, signal, (info) => {
+        latestProgress = info;
+        this.dispatchReplicationProgress(remotePeer, info);
+        this.acknowledgeProgress(remotePeer, info, acknowledgement);
+      });
     } catch (e) {
       if (signal?.aborted) return P2P_REPLICATION_CANCELLED;
       Logger("Error while P2P replicating", logLevel, "p2p-replicator");
       Logger(e, LOG_LEVEL_VERBOSE);
       return p2pReplicationFailed(e);
     } finally {
+      this.dispatchReplicationProgress(remotePeer);
+      this.acknowledgeProgress(remotePeer, void 0, { ...acknowledgement, finalProgress: latestProgress });
       this._replicateFromPeers.delete(remotePeer);
       this.dispatchStatus();
     }
@@ -605,7 +697,7 @@ class TrysteroReplicator {
     }
     return void 0;
   }
-  async transferFromPeer(remotePeer, fromStart, logLevel, signal) {
+  async transferFromPeer(remotePeer, fromStart, logLevel, signal, onStatistics) {
     if (!this.server) {
       throw new Error("Server is not available");
     }
@@ -640,8 +732,6 @@ class TrysteroReplicator {
       remoteDB,
       async (docs, info) => {
         await this._env.processReplicatedDocs(docs);
-        void this.dispatchReplicationProgress(remotePeer, info);
-        void this.acknowledgeProgress(remotePeer, info);
         void this.notifyProgress(remotePeer);
         Logger(
           `P2P Replication from ${remotePeer}
@@ -650,10 +740,14 @@ ${info.lastSeq} / ${info.maxSeqInBatch})`,
           "p2p-replicator"
         );
       },
-      { live: false, rewind: fromStart, signal }
+      {
+        live: false,
+        rewind: fromStart,
+        signal,
+        onStatistics
+      }
     );
     Logger(`P2P replicateFrom replicateShim returned for ${remotePeer}`, LOG_LEVEL_VERBOSE, "p2p-replicator");
-    void this.acknowledgeProgress(remotePeer, void 0);
     if (outcome.status === "cancelled") {
       Logger(`P2P Replication from ${remotePeer} has been cancelled`, logLevel, "p2p-replicator");
       return P2P_REPLICATION_CANCELLED;
@@ -662,28 +756,43 @@ ${info.lastSeq} / ${info.maxSeqInBatch})`,
     return P2P_REPLICATION_COMPLETED;
   }
   notifyProgress(excludePeerId) {
-    if (!this._isBroadcasting) return;
-    if (!this.server) return;
+    if (!this._isBroadcasting) {
+      return;
+    }
+    if (!this.server) {
+      return;
+    }
     for (const peer of this.server.knownAdvertisements) {
       const peerId = peer.peerId;
-      if (peerId === excludePeerId) continue;
-      void serialized(`notifyProgress-${peerId}`, async () => {
-        const isAcceptable = await this.server?.isAcceptablePeer(peerId);
-        if (isAcceptable) {
-          try {
-            const ret = await this.server?.getConnection(peerId).invokeRemoteFunction("onProgress", [this.server?.serverPeerId], 0);
-            return ret;
-          } catch (e) {
-            Logger(`Error while notifying progress to ${peerId}`, LOG_LEVEL_VERBOSE);
-            Logger(e, LOG_LEVEL_VERBOSE);
-          }
-        } else {
-          Logger(`Peer ${peerId} is not acceptable to notify progress`, LOG_LEVEL_VERBOSE);
-        }
-      });
+      if (peerId === excludePeerId) {
+        continue;
+      }
+      void serialized(`notifyProgress-${peerId}`, () => this.notifyPeerProgress(peerId));
     }
     return Promise.resolve();
   }
+  async notifyPeerProgress(peerId) {
+    const isAcceptable = await this.server?.isAcceptablePeer(peerId);
+    if (!isAcceptable) {
+      this.reportDiagnostic({
+        category: "sync",
+        code: "change-notification-ignored",
+        peerId,
+        reason: "not-accepted"
+      });
+      Logger(`Peer ${peerId} is not acceptable to notify progress`, LOG_LEVEL_VERBOSE);
+      return;
+    }
+    try {
+      const result = await this.server?.getConnection(peerId).invokeRemoteFunction("onProgress", [this.server?.serverPeerId], 0);
+      this.reportDiagnostic({ category: "sync", code: "change-notification-sent", peerId });
+      return result;
+    } catch (error) {
+      this.reportDiagnostic(notificationFailureDiagnostic(peerId, error));
+      Logger(`Error while notifying progress to ${peerId}`, LOG_LEVEL_VERBOSE);
+      Logger(error, LOG_LEVEL_VERBOSE);
+    }
+  }
   async requestBroadcastChanges(peerId) {
     return await this.server?.getConnection(peerId).invokeRemoteFunction("requestBroadcasting", [this.server.serverPeerId], 0);
   }
@@ -697,20 +806,33 @@ ${info.lastSeq} / ${info.maxSeqInBatch})`,
   }
   _watchingPeers = /* @__PURE__ */ new Set();
   watchPeer(peerId) {
+    if (!this._watchingPeers.has(peerId)) {
+      this.reportDiagnostic({ category: "sync", code: "watch-enabled", peerId });
+    }
     this._watchingPeers.add(peerId);
     this.dispatchStatus();
   }
   unwatchPeer(peerId) {
+    if (this._watchingPeers.has(peerId)) {
+      this.reportDiagnostic({ category: "sync", code: "watch-disabled", peerId });
+    }
     this._watchingPeers.delete(peerId);
     this.dispatchStatus();
   }
   async onUpdateDatabase(fromPeerId) {
     if (this._watchingPeers.has(fromPeerId)) {
+      this.reportDiagnostic({ category: "sync", code: "change-notification-received", peerId: fromPeerId });
       Logger(`Progress notification from ${fromPeerId}`, LOG_LEVEL_VERBOSE);
       return await serialized(`onProgress-${fromPeerId}`, async () => {
         return await this.runFiniteReplicationActivity(() => this.replicateFrom(fromPeerId));
       });
     }
+    this.reportDiagnostic({
+      category: "sync",
+      code: "change-notification-ignored",
+      peerId: fromPeerId,
+      reason: "not-watching"
+    });
     return false;
   }
   async getRemoteConfig(peerId) {

package/dist/replication/trystero/TrysteroReplicatorP2PServer.js

@@ -1,3 +1,4 @@
+import { reportP2PDiagnostic } from "../../p2p/p2pDiagnostics.js";
 import { parsePeerPatterns } from "./peerPatterns.js";
 import { selfId, joinRoom } from "@trystero-p2p/nostr";
 import { AutoAccepting, LOG_LEVEL_INFO, LOG_LEVEL_NOTICE } from "../../common/types.js";
@@ -225,7 +226,10 @@ class TrysteroReplicatorP2PServer {
     if (peerId === this.serverPeerId) return;
     if (data.peerId === this.serverPeerId) return;
     if (data.peerId !== peerId) return;
+    const isNewPeer = !this._knownAdvertisements.has(peerId);
     this._knownAdvertisements.set(peerId, data);
+    if (isNewPeer)
+      reportP2PDiagnostic(this._env.reportDiagnostic, { category: "peer", code: "peer-advertised", peerId });
     void this.dispatchConnectionStatus();
     void Promise.resolve().then(() => this._sessionPeerHandlers?.onAdvertisement(data)).catch((error) => Logger(error, LOG_LEVEL_VERBOSE));
     void this._env.events.emitEvent(EVENT_ADVERTISEMENT_RECEIVED, data);
@@ -368,6 +372,7 @@ You can chose as follows:
   _onPeerLeave(peerId) {
     if (this._hostLifetimeEnded) return;
     Logger(`Peer left: ${peerId}`, LOG_LEVEL_VERBOSE);
+    reportP2PDiagnostic(this._env.reportDiagnostic, { category: "peer", code: "peer-left", peerId });
     this._knownAdvertisements.delete(peerId);
     void Promise.resolve().then(() => this._sessionPeerHandlers?.onPeerLeft(peerId)).catch((error) => Logger(error, LOG_LEVEL_VERBOSE));
     void this._env.events.emitEvent(EVENT_DEVICE_LEAVED, peerId);
@@ -459,6 +464,12 @@ You can chose as follows:
     const room = joinRoom(options, roomId, {
       handshakeTimeoutMs: 3e4,
       onJoinError: (error) => {
+        if (!this._hostLifetimeEnded)
+          reportP2PDiagnostic(this._env.reportDiagnostic, {
+            category: "relay",
+            code: "room-join-error",
+            reason: "transport-error"
+          });
         Logger("Some peer Failed to join Trystero room");
         this.logTransportError(error);
       }

package/dist/replication/trystero/p2pReplicationDiagnostics.d.ts

@@ -0,0 +1,9 @@
+import { type P2PDiagnosticInput } from "../../p2p/p2pDiagnostics.js";
+import type { P2PReplicationResult } from "./TrysteroReplicator.js";
+/** Describe an observed response without coercing an unavailable response to refusal. */
+export declare function authenticationResultDiagnostic(peerId: string, response: unknown): P2PDiagnosticInput;
+export declare function authenticationFailureDiagnostic(peerId: string, error: unknown, signal?: AbortSignal): P2PDiagnosticInput;
+/** Classify the result without changing the operation's result object or error. */
+export declare function pullResultDiagnostic(peerId: string, status: P2PReplicationResult["status"]): P2PDiagnosticInput;
+export declare function pullFailureDiagnostic(peerId: string, cancelled: boolean): P2PDiagnosticInput;
+export declare function notificationFailureDiagnostic(peerId: string, error: unknown): P2PDiagnosticInput;

package/dist/replication/trystero/p2pReplicationDiagnostics.js

@@ -0,0 +1,51 @@
+import { classifyP2PRpcFailure } from "../../p2p/p2pDiagnostics.js";
+const authenticationFailureCodes = {
+  "rpc-timeout": "auth-timeout",
+  "rpc-cancelled": "auth-cancelled",
+  "rpc-error": "auth-error"
+};
+const notificationFailureCodes = {
+  "rpc-timeout": "change-notification-timeout",
+  "rpc-cancelled": "change-notification-cancelled",
+  "rpc-error": "change-notification-error"
+};
+function authenticationResultDiagnostic(peerId, response) {
+  if (response === true) {
+    return { category: "peer", code: "auth-accepted", peerId };
+  }
+  if (response === false) {
+    return { category: "peer", code: "auth-refused", reason: "authentication-refused", peerId };
+  }
+  return { category: "peer", code: "auth-error", reason: "authentication-unobserved", peerId };
+}
+function authenticationFailureDiagnostic(peerId, error, signal) {
+  const reason = classifyP2PRpcFailure(error, signal);
+  return { category: "peer", code: authenticationFailureCodes[reason], reason, peerId };
+}
+function pullResultDiagnostic(peerId, status) {
+  switch (status) {
+    case "completed":
+      return { category: "sync", code: "pull-completed", peerId };
+    case "cancelled":
+      return { category: "sync", code: "pull-cancelled", reason: "operation-cancelled", peerId };
+    default:
+      return { category: "sync", code: "pull-failed", reason: "replication-error", peerId };
+  }
+}
+function pullFailureDiagnostic(peerId, cancelled) {
+  if (cancelled) {
+    return pullResultDiagnostic(peerId, "cancelled");
+  }
+  return pullResultDiagnostic(peerId, "failed");
+}
+function notificationFailureDiagnostic(peerId, error) {
+  const reason = classifyP2PRpcFailure(error);
+  return { category: "sync", code: notificationFailureCodes[reason], reason, peerId };
+}
+export {
+  authenticationFailureDiagnostic,
+  authenticationResultDiagnostic,
+  notificationFailureDiagnostic,
+  pullFailureDiagnostic,
+  pullResultDiagnostic
+};

package/dist/replication/trystero/p2pReplicationProgress.d.ts

@@ -0,0 +1,15 @@
+import type { ProgressInfo } from "../../pouchdb/ReplicatorShim.js";
+import type { P2PReplicationDirectionProgress } from "./TrysteroReplicator.js";
+/** Transient attempt correlation; no replication checkpoint is stored here. */
+export type ProgressAcknowledgement = {
+    attempt: number;
+    finalProgress?: ProgressInfo;
+};
+export type AcknowledgedProgressAttempt = {
+    attempt: number;
+    isActive: boolean;
+    checkedChanges: number;
+};
+export declare function projectDirectionProgress(info?: ProgressInfo | null): P2PReplicationDirectionProgress;
+/** Return the next attempt snapshot, or reject stale, reordered, or already-ended progress. */
+export declare function projectAcknowledgedAttempt(previous: AcknowledgedProgressAttempt | undefined, info: ProgressInfo | null | undefined, acknowledgement: ProgressAcknowledgement): AcknowledgedProgressAttempt | undefined;

package/dist/replication/trystero/p2pReplicationProgress.js

@@ -0,0 +1,37 @@
+function projectDirectionProgress(info) {
+  return {
+    max: info?.maxSeqInBatch ?? 0,
+    current: info?.lastSeq ?? 0,
+    isActive: info != null,
+    ...info?.statistics ? { statistics: { ...info.statistics } } : {}
+  };
+}
+function projectAcknowledgedAttempt(previous, info, acknowledgement) {
+  if (!previous) {
+    return {
+      attempt: acknowledgement.attempt,
+      isActive: info != null,
+      checkedChanges: info?.statistics?.checkedChanges ?? 0
+    };
+  }
+  if (acknowledgement.attempt < previous.attempt) {
+    return void 0;
+  }
+  if (acknowledgement.attempt === previous.attempt) {
+    if (!previous.isActive) {
+      return void 0;
+    }
+    if ((info?.statistics?.checkedChanges ?? previous.checkedChanges) < previous.checkedChanges) {
+      return void 0;
+    }
+  }
+  return {
+    attempt: acknowledgement.attempt,
+    isActive: info != null,
+    checkedChanges: info?.statistics?.checkedChanges ?? previous.checkedChanges
+  };
+}
+export {
+  projectAcknowledgedAttempt,
+  projectDirectionProgress
+};

package/dist/replication/trystero/types.d.ts

@@ -5,6 +5,7 @@ import type { Confirm } from "../../interfaces/Confirm.js";
 import type { AsyncActivityRunner } from "../../interfaces/AsyncActivityRunner.js";
 import type { LiveSyncEventHub } from "../../hub/hub.js";
 import type { MessageTranslator } from "../../services/base/MessageTranslator.js";
+import type { P2PDiagnosticReporter } from "../../p2p/p2pDiagnostics.js";
 import type { P2PAutomationCoordinator } from "./P2PAutomationCoordinator.js";
 export declare const DIRECTION_REQUEST = "request";
 export type DIRECTION_REQUEST = typeof DIRECTION_REQUEST;
@@ -78,6 +79,8 @@ export interface ReplicatorHost {
     confirm: Confirm;
 }
 export interface ReplicatorHostEnv extends ReplicatorHost {
+    /** Observation port fenced by the owning room session; it cannot control transport work. */
+    reportDiagnostic?: P2PDiagnosticReporter;
     /** Event channel owned by the containing Commonlib service composition. */
     events: LiveSyncEventHub;
     /** Message translation owned by the containing Commonlib service composition. */

package/dist/services/base/APIService.d.ts

@@ -72,6 +72,16 @@ export declare abstract class APIService<T extends ServiceContext = ServiceConte
      * @param handler The handler function for the protocol.
      */
     abstract registerProtocolHandler(action: string, handler: (params: Record<string, string>) => unknown): void;
+    /**
+     * Register synchronous cleanup for this host's normal terminal unload.
+     * The default uses the context-owned platform-unloaded event once per registration,
+     * after lifecycle handlers and local database closure. An unload interrupted before
+     * that event does not execute these callbacks.
+     * Native hosts may override this to retain their own unload timing. Callbacks are
+     * not awaited; resource retirement which must finish before database closure
+     * belongs to AppLifecycleService.onUnload instead.
+     */
+    registerCleanup(callback: () => void): void;
     /**
      * Get the basic UI component for showing a confirmation dialog to the user.
      */

package/dist/services/base/APIService.js

@@ -1,3 +1,4 @@
+import { EVENT_PLATFORM_UNLOADED } from "../../events/coreEvents.js";
 import { ServiceBase } from "./ServiceBase.js";
 import { reactiveSource } from "octagonal-wheels/dataobject/reactive";
 import { _fetch, compatGlobal } from "../../common/coreEnvFunctions.js";
@@ -9,6 +10,18 @@ class APIService extends ServiceBase {
   showWindowOnRight(type) {
     return this.showWindow(type);
   }
+  /**
+   * Register synchronous cleanup for this host's normal terminal unload.
+   * The default uses the context-owned platform-unloaded event once per registration,
+   * after lifecycle handlers and local database closure. An unload interrupted before
+   * that event does not execute these callbacks.
+   * Native hosts may override this to retain their own unload timing. Callbacks are
+   * not awaited; resource retirement which must finish before database closure
+   * belongs to AppLifecycleService.onUnload instead.
+   */
+  registerCleanup(callback) {
+    this.context.events.onceEvent(EVENT_PLATFORM_UNLOADED, callback);
+  }
   requestCount = reactiveSource(0);
   responseCount = reactiveSource(0);
   get isOnline() {

package/dist/services/base/IService.d.ts

@@ -49,6 +49,8 @@ export interface IAPIService {
     registerWindow<T>(type: string, factory: (leaf: T) => unknown): void;
     addRibbonIcon(icon: string, title: string, callback: (evt: MouseEvent) => unknown): HTMLElement;
     registerProtocolHandler(action: string, handler: (params: Record<string, string>) => unknown): void;
+    /** Registers synchronous cleanup at host terminal unload; callbacks are not awaited. */
+    registerCleanup(callback: () => void): void;
     confirm: Confirm;
     responseCount: ReactiveSource<number>;
     requestCount: ReactiveSource<number>;