@vrtmrz/livesync-commonlib 0.3.2 → 0.4.0

package/docs/journal-receive-recovery.md

@@ -2,14 +2,17 @@
 date: 2026-11-04
 commonlib-version: "0.3.1"
 self-hosted-livesync-version: "1.0.44"
-status: unreleased
+status: published
+published-in: "0.3.2"
+publication-date: 2026-11-05
 ---
 
 # Journal receive failures and recovery
 
-This document describes unreleased receive behaviour. Hosts choose when to
-offer the manual skip operation and remain responsible for Vault reflection
-and conflict handling.
+This document describes receive behaviour published in
+[Commonlib 0.3.2](https://github.com/vrtmrz/livesync-commonlib/releases/tag/0.3.2).
+Hosts choose when to offer the manual skip operation and remain responsible
+for Vault reflection and conflict handling.
 
 ## Stop and retry by default
 

package/docs/p2p-transport-lifecycle.md

@@ -55,19 +55,126 @@ Ordinary consumers use the focused views returned by the service feature. They d
 
 The stable view objects close over the same private context, but do not expose that context or one another. They are capability boundaries for consumers, not separately allocated owners. A consumer receives only the views it needs.
 
-| View                          | Implemented responsibility                                                                                               |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `P2PTransportLifecycle`       | observe the current connection and accept explicit connect or disconnect intent                                          |
-| `P2PConnectionProbeAdmission` | arbitrate a complete Setup signalling check against the current relay binding                                            |
-| `P2PPeerDirectory`            | supply a current peer advertisement snapshot                                                                             |
-| `P2PPeerAdmission`            | apply or revoke temporary and persisted acceptance decisions                                                             |
-| `P2PTargetedTransfer`         | pull, request push, synchronise one peer, or execute the persisted configured-target set without peer-selection dialogue |
-| `P2PChangeRelay`              | watch or unwatch a peer and enable or disable local-change broadcast                                                     |
-| `P2PConfigurationExchange`    | retrieve configuration from one explicitly selected peer                                                                 |
-| `P2PDiagnostics`              | request status and project RTC metrics without exposing the room or peer connection                                      |
+| View                          | Implemented responsibility                                                                                                     |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `P2PTransportLifecycle`       | observe the current connection and accept explicit connect or disconnect intent                                                |
+| `P2PConnectionProbeAdmission` | arbitrate a complete Setup signalling check against the current relay binding                                                  |
+| `P2PPeerDirectory`            | supply a current peer advertisement snapshot                                                                                   |
+| `P2PPeerAdmission`            | apply or revoke temporary and persisted acceptance decisions                                                                   |
+| `P2PTargetedTransfer`         | pull, request push, synchronise one peer, or execute the persisted configured-target set without peer-selection dialogue       |
+| `P2PChangeRelay`              | watch or unwatch a peer and enable or disable local-change broadcast                                                           |
+| `P2PConfigurationExchange`    | retrieve configuration from one explicitly selected peer                                                                       |
+| `P2PDiagnostics`              | observe diagnostic events and replication progress, request status, and project RTC metrics without exposing transport handles |
 
 The optional host UI factory is an explicit compatibility boundary. Commonlib supplies both the deprecated compatibility Replicator and the stable views. Maintained modal transport and status controls use the views; legacy interactive execution and rebuild-specific setup markers may still use the compatibility Replicator. Receiving that façade does not transfer ownership of the room. `UseP2PReplicatorResult.replicator` remains deprecated for the same bounded migration work.
 
+## Per-peer replication progress
+
+`P2PDiagnostics.getReplicationProgress?()` supplies a read-only snapshot sorted by
+peer ID. `onReplicationProgress?(listener)` observes subsequent snapshots and
+returns a subscription disposer. Hosts should check that these optional methods
+exist when composing an older implementation. The service owns a `P2PLogCollector`
+for these views, and releases its event registrations on platform unload. Peer
+departure removes that peer, and room disconnect or replacement clears the snapshot.
+Repeated advertisements update the peer name and retain its structured progress;
+the legacy map and text keep their existing advertisement reset behaviour.
+
+Each direction retains the established `current` and `max` numeric source sequence
+values and `isActive` flag. `P2PLogCollector.p2pReplicationResult` and
+`p2pReplicationLine` keep those sequence units and the existing text format.
+Sequence subtraction does not measure transferred documents.
+
+A direction may additionally supply `statistics: { documents, checkedChanges }`:
+
+- `documents` counts successfully transferred database document revisions, including
+  Metadata and Chunks. It excludes already-held revisions and refresh reads. Two
+  missing conflict revisions of one document count as two transfers.
+- `checkedChanges` counts changes-feed entries processed for revision comparison,
+  including entries which require no transfer and repeated entries checked again.
+
+Both counters start at zero for each finite pull attempt, accumulate across its
+batches, and retain their final values when the direction becomes inactive. The
+sending direction observes the receiver's acknowledgements. An absent
+`statistics` field means the peer has not supplied these counts; it differs from
+an observed zero. A completed all-known batch updates statistics without invoking
+the legacy document-processing callback. That callback still receives the
+refreshed documents only when the batch has missing revisions.
+
+The shim's optional `onStatistics` observer also reports accepted writes when a
+later write, refresh, or checkpoint step fails. These counts do not establish a
+committed checkpoint or a completed replication attempt. The observer's sequence
+retains the latest successfully processed batch boundary when a later batch fails
+or is cancelled before writing; the document callback keeps its original batch
+sequence values. Observer failures do not change document processing or checkpoint
+safety.
+
+Progress uses the existing `onProgressAcknowledged` RPC. An optional third argument
+carries a transient attempt number, allocated monotonically across room sessions
+within the receiver's module lifetime. Trystero's default peer ID is also generated
+for that module lifetime. The sending observer ignores older attempts, reordered
+batch counts, and updates received after the same attempt's terminal marker. The
+terminal acknowledgement keeps the legacy absent progress argument and adds the
+final progress in its optional metadata, so a terminal marker which overtakes a
+batch still supplies final sequences and counts. Older peers can ignore the extra
+argument and continue using sequence progress. No handshake, retry, heartbeat, or
+persistent replication state is added.
+
+## Latest diagnostic observations
+
+The optional `P2PDiagnostics.getDiagnosticSnapshot()` and
+`onDiagnosticEvent(listener)` methods expose the latest `relay`, `peer`, and
+`sync` observations. A missing category is unobserved, rather than a successful
+result or a measured zero. Each immutable event contains a source timestamp in
+milliseconds since the Unix epoch, a fixed code, an optional fixed reason, and an
+optional peer ID. Events do not include device names, settings, room IDs, keys,
+SDP, IP addresses, or arbitrary error text.
+
+The stable service owns only one latest event per category. Peer departure and
+room closure retain the latest peer and sync evidence after the peer row has
+disappeared. Room replacement fences the previous session's reporting port before
+retirement, so a late authentication result, notification, or transport callback
+cannot overwrite the current session's evidence. Platform unload detaches the
+store and its subscribers. Older diagnostics implementations may omit both methods.
+
+Accepted observations are also published once through the context-owned
+`EVENT_P2P_DIAGNOSTIC` channel exported from `/p2p`. Hosts can format that same
+stream for their summary and diagnostic log. Identical events with the same source
+timestamp are coalesced; repeated advertisements of an already-known peer and
+unchanged watch decisions do not produce another diagnostic transition. No
+server-snapshot, document, or batch progress subscription is used for this stream.
+Diagnostic subscribers and source reporting callbacks cannot change authentication,
+replication outcomes, or room lifecycle control flow. Hosts using the general
+EventHub channel should contain exceptions in their own listener, as with their
+other EventHub listeners.
+
+Owned observations include room opening, opening completion or failure, closure,
+join-error callbacks, validated first peer advertisements, peer departure,
+authentication acceptance or refusal, classified RPC failures, finite pull
+outcomes, and watch or change-notification boundaries. Authentication refusal,
+RPC timeout, cancellation, and other RPC errors have distinct fixed codes while
+retaining the existing boolean and replication result contracts. Only an explicit
+`false` authentication response indicates refusal. Missing or non-boolean responses
+use `auth-error` with `authentication-unobserved`, while keeping the existing return
+value and admission policy. An unavailable
+remote broadcast status remains unobserved rather than being reported as an
+explicit false result. Broadcast enablement is observed only after feed creation,
+and an unexpected feed error supplies a fixed failure reason when broadcasting
+stops. No diagnostic operation retries, reconnects, or alters a checkpoint.
+
+A room-opened observation means that the owned Trystero room is active. It does
+not establish that a Nostr relay accepted its advertisement. In the reviewed
+`@trystero-p2p/nostr` 0.26.0 API, relay `NOTICE`, rejected `OK`, and `CLOSED`
+messages are written internally to the console without an owned callback. The
+public socket getter is shared across rooms and replaces sockets during
+reconnection. This diagnostic stream therefore uses `relay-details-unobserved`
+and does not intercept console output or WebSocket globals, attach to shared
+sockets, or poll. Relay rejection text remains unavailable through this API.
+
+The existing detailed RTC failure subscription is also process-wide and supplies
+no peer or room attribution. Its typed failure reasons remain in the existing
+Diag logging path. They are not presented as a failure of an arbitrary owned room
+or peer in the new stream.
+
 ## Room demands and automation generations
 
 `P2PRoomSessionOwner` opens a room while at least one room demand exists. Persistent demands are currently `explicit`, `automatic`, and `rebuild-continuation`. A finite target operation receives an unexported symbol demand for its own lifetime. Removing one demand cannot close a room retained by another persistent or finite demand.

package/docs/releasing.md

@@ -67,6 +67,12 @@ For 0.2.3, the documented exceptions are the `HandlerFunction.setHandler` and `L
 
 Version 0.3.0 introduces a source compatibility change: the custom client passed to `LiveSyncJournalReplicator.ensureBucketIsCompatible` must provide `hasRemoteJournals(): Promise<boolean>`. The operation distinguishes an empty bucket from Journal files left without an identifying milestone. Keeping it required makes missing client capability a type error. The standard `JournalSyncCore` client already supplies it. This change uses the next minor version under the policy above.
 
+Version 0.4.0 changes the P2P action wire format by adopting Trystero 0.26.0.
+Communicating peers must use compatible transport versions. Custom `IAPIService`
+implementations must also provide `registerCleanup(callback: () => void): void`;
+subclasses of `APIService` inherit its default terminal-unload implementation.
+These changes use the next minor version under the compatibility policy.
+
 ## Preparing a release
 
 Choose the version explicitly. For the 0.2 line, start at 0.2.0. A stable candidate can use its final version on the `next` dist-tag, then be checked by exact source revision and tarball SHA-256 before the same version is promoted to `latest`. No `-next.N` or `-rc.N` version is required; use a separate prerelease version only when it is useful for a distinct candidate. Package-proof versions are local artefacts and cannot be staged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -1020,7 +1020,7 @@
     "@smithy/middleware-apply-body-checksum": "^4.3.9",
     "@smithy/types": "^4.14.3",
     "@smithy/util-retry": "^4.4.5",
-    "@trystero-p2p/nostr": "0.25.3",
+    "@trystero-p2p/nostr": "0.26.0",
     "@vrtmrz/value-store": "0.1.0",
     "diff-match-patch": "^1.0.5",
     "events": "^3.3.0",