@vrtmrz/livesync-commonlib 0.3.1 → 0.4.0

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>;

package/docs/adr/2026_11_shared_storage_path_resolution.md

@@ -2,7 +2,7 @@
 date: 2026-11-03
 commonlib-version: "0.3.0"
 self-hosted-livesync-version: "1.0.44"
-status: accepted-unreleased
+status: published
 ---
 
 # Architectural Decision Record: Shared Storage Path Resolution
@@ -16,7 +16,9 @@ lifecycle. The [design](../design_docs/storage_path_resolution.md) defines the
 accepted contract and remaining adoption work.
 
 Accepted on 2026-11-03 against the versions recorded above. The implementation
-is unreleased. Publication does not by itself enable NFC in WebApp or Bridge.
+is published in [Commonlib 0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1).
+The original date and reviewed versions retain the accepted baseline.
+Publication does not by itself enable NFC in WebApp or Bridge.
 
 ## Context
 

package/docs/design_docs/storage_path_resolution.md

@@ -2,7 +2,7 @@
 date: 2026-11-03
 commonlib-version: "0.3.0"
 self-hosted-livesync-version: "1.0.44"
-status: accepted-unreleased
+status: published
 ---
 
 # Shared storage path resolution
@@ -10,8 +10,8 @@ status: accepted-unreleased
 This design moves the CLI's existing Unicode-aware path resolution into
 Commonlib so Node, File System Access, and Bridge can apply the same naming
 rules. The shared resolver, path types, and Node and File System Access
-integrations are implemented as unreleased additions. Installing the package
-does not enable NFC in an existing host or migrate its database.
+integrations are published in Commonlib 0.3.1. Installing the package does
+not enable NFC in an existing host or migrate its database.
 
 Accepted on 2026-11-03. The [decision record](../adr/2026_11_shared_storage_path_resolution.md)
 records the ownership and compatibility choices. The [platform guide](../platform-storage.md#unicode-path-resolution)
@@ -258,10 +258,11 @@ of state, including hosts which report them as deletion and creation.
 ## Current adoption and publication status
 
 The shared `/storage` contract, Node and File System Access adapters, and
-explicit `DirectFileManipulator` path-version option are unreleased additions
-after the published Commonlib `0.3.0` artefact. They require a new immutable
-package version; a source checkout with version string `0.3.0` is not the
-registry artefact.
+explicit `DirectFileManipulator` path-version option are published in
+[Commonlib 0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1).
+The original decision date and reviewed versions above retain the accepted
+baseline. These additions are absent from the registry artefact `0.3.0`;
+a source checkout carrying that version label is not the published artefact.
 
 The CLI candidate uses the shared Node resolver, and the current Obsidian
 candidate uses shared namespace and comparison helpers while retaining Vault

package/docs/development.md

@@ -21,8 +21,8 @@ Files elsewhere under `src` are implementation details unless a focused entry re
 
 ## Storage path boundary
 
-The unreleased `/storage` entry owns namespace helpers, comparison keys, and
-strict component resolution. The [design](design_docs/storage_path_resolution.md)
+The `/storage` entry, published in Commonlib 0.3.1, owns namespace helpers,
+comparison keys, and strict component resolution. The [design](design_docs/storage_path_resolution.md)
 and [decision record](adr/2026_11_shared_storage_path_resolution.md) separate
 that contract from host handles, caches, watchers, and migration. See the
 [platform guide](platform-storage.md#unicode-path-resolution) for composition.

package/docs/journal-receive-recovery.md

@@ -0,0 +1,69 @@
+---
+date: 2026-11-04
+commonlib-version: "0.3.1"
+self-hosted-livesync-version: "1.0.44"
+status: published
+published-in: "0.3.2"
+publication-date: 2026-11-05
+---
+
+# Journal receive failures and recovery
+
+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
+
+A per-Journal decode, record-processing, or write failure stops receipt. The
+failed Journal and all later Journals remain unacknowledged. The next normal
+receive attempt retries the failed Journal before proceeding to later Journals.
+Partial progress does not change this rule.
+
+Chunks are written before Metadata, so a Chunk failure prevents that Journal's
+Metadata stage. Metadata retains its received revision ancestry through
+`new_edits: false`, whose empty success result is valid. Successfully written
+records remain in the database when another record fails. There is no rollback.
+
+A retry avoids rewriting existing records and delivers accepted Metadata to
+the host again, including revisions saved before an earlier partial failure.
+The host must tolerate repeated delivery. Chunk-arrival events describe only
+successful writes. The `knownIDs` set suppresses unnecessary
+outbound transfer; it does not prove that a receive has completed locally.
+
+Warnings identify the failed Journal key and the stage where receipt stopped,
+without logging document contents. A stop request lets current I/O settle and
+closes the receive operation; it is not a Journal failure.
+
+## Skip the stopped Journal and resume
+
+When receipt stops on a Journal failure, a host may offer the explicit
+'Skip stopped Journal and resume' operation. It accepts the exact stopped
+failure snapshot, marks only that Journal received, and resumes receipt of the
+remaining Journals. If another Journal fails, receipt stops at that Journal
+and requires a separate decision.
+
+Skipping does not roll back partial writes. It can leave content or revision
+history missing, and receipt of later Journals does not prove that every file
+can be reconstructed or reflected to storage. Each skip acknowledges the
+failed Journal despite its warning.
+
+The stopped failure is runtime state, not a persistent skip mode or failure
+queue. After a restart, normal receipt must encounter the failure again before
+the host can offer a skip for it.
+
+## Replay and host boundaries
+
+The existing 'Reset journal received history' operation clears `receivedFiles`
+and `knownIDs`, while retaining the local database and `sentFiles`. After the
+failure has been corrected, resetting this history lets receipt replay remote
+Journals other than those sent by this device. Replay requires the affected
+remote objects to remain available and readable; resetting history cannot
+recreate missing remote bytes.
+
+A host operation which replaces the local database, such as CLI Fetch, has
+separate reconstruction and completion rules. Repeating Fetch is not the
+same-database retry described above. Journal receipt also remains separate
+from Vault reflection and conflict handling; hosts must preserve their own
+failure and content-protection checks.

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/platform-storage.md

@@ -63,8 +63,8 @@ The File System Access API does not expose portable creation times or permit set
 
 ## Unicode path resolution
 
-The following APIs are unreleased additions after Commonlib 0.3.0. Node and
-File System Access hosts can use the same NFC comparison and component
+These APIs are published in [Commonlib 0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1).
+Node and File System Access hosts can use the same NFC comparison and component
 resolution while retaining the names listed by their filesystem. Hosts still
 own the selected identity mode and its database migration.
 

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/docs/unicode-path-identity.md

@@ -109,11 +109,13 @@ the package protocol support alone does not mean those host integrations have
 shipped.
 
 The shared `/storage` resolver, Node and File System Access adapters, and
-explicit `DirectFileManipulator` path-version option are later unpublished
-additions described in the [shared storage path design](design_docs/storage_path_resolution.md).
-They are not in the registry artefact `0.3.0` and require a new immutable
-Commonlib package version. A source checkout carrying the same version string
-does not make these additions part of the published artefact.
+explicit `DirectFileManipulator` path-version option are published in
+[Commonlib 0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1),
+as described in the [shared storage path design](design_docs/storage_path_resolution.md).
+They are absent from the registry artefact `0.3.0`; select the new immutable
+version rather than a source checkout carrying an older version label. Shared
+path adoption remains in [LiveSync #1315](https://github.com/vrtmrz/obsidian-livesync/pull/1315)
+and [Bridge #92](https://github.com/vrtmrz/livesync-bridge/pull/92).
 
 | Consumer surface | Published baseline | Current candidate status |
 | --- | --- | --- |
@@ -122,7 +124,7 @@ does not make these additions part of the published artefact.
 | Bridge | Legacy version `0` remains the default baseline. | The Bridge candidate enables version `1` only by explicit peer opt-in; every peer in a group must use the same path version. Its ordinary case-mismatch check remains separate from the required version check. |
 | WebApp | Legacy version `0` only. | WebApp remains Legacy-only; an explicit version `1` is rejected at startup. The browser storage primitive alone does not enable application support. |
 | WebPeer | A vaultless P2P utility. | It is not an NFC filesystem host. |
-| `DirectFileManipulator` | The published package rejects a remote declaring the NFC feature. | The unpublished option defaults to version `0`, accepts explicit `0` or `1`, and rejects a populated database in the opposite mode. The caller still owns physical path handling. |
+| `DirectFileManipulator` | Commonlib `0.3.1` supports explicit version `1`; omitted or `0` retains Legacy identity. A populated database in the opposite mode is rejected. | The caller still owns physical path handling and coordinated migration. |
 
 `PathService` owns logical ID derivation. In the unreleased LiveSync host
 candidate, the CLI resolves NFC-equivalent names against directory entries
@@ -172,8 +174,7 @@ checkpoints; the P2P source mark and target checkpoint handle database
 replacement. These operations do not rewrite IDs or merge histories in place.
 P2P retains its existing source selection during Fetch.
 
-Published Commonlib direct file access refuses a remote which declares the NFC
-feature. The unpublished `DirectFileManipulator` addition exposes explicit
+Commonlib 0.3.1 `DirectFileManipulator` exposes explicit
 `pathNormalizationVersion` options, defaulting to `0`: missing or `0` retains
 Legacy and rejects an NFC database; `1` accepts NFC and rejects a populated
 Legacy database before feature negotiation can change its declaration. A

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.3.1",
+  "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",