@vrtmrz/livesync-commonlib 0.1.19 → 0.1.20

package/docs/p2p-transport-lifecycle.md

@@ -1,23 +1,135 @@
-# P2P transport lifecycle
+---
+date: 2026-08-28
+commonlib-version: "0.1.20"
+self-hosted-livesync-version: "1.0.21"
+status: unreleased
+---
 
-This guide is for developers composing Commonlib's Trystero P2P service. It describes resource ownership and shutdown semantics; it is not a general Trystero API reference.
+# P2P service and transport lifecycle
+
+This design document records the implemented Commonlib Trystero P2P service. It defines the current resource owners, demand and automation lifecycles, replacement fences, and shutdown semantics. It is not a migration plan or a general Trystero API reference.
 
 ## Ownership layers
 
-The P2P composition has three distinct owners:
+The P2P composition deliberately separates stable host policy from one replaceable room membership:
 
-- `useP2PReplicatorFeature` owns the current `LiveSyncTrysteroReplicator` exposed to a host;
-- the Commonlib P2P host owns LiveSync RPC, advertisements, client proxies, diagnostics, and one Trystero room binding; and
+- `useP2PReplicatorFeature` creates one P2P service composition for the host lifetime and registers non-owning active-provider adapters over it;
+- the service composition holds focused stable contract views and one host lifecycle view over a private context;
+- the private context owns explicit-connect and explicit-disconnect intent, the disconnect veto, host lifecycle closure, application lifecycle generation, delayed AutoStart work, and the resource references shared by those views;
+- `P2PRoomSessionOwner` owns persistent and finite room demands, serialised room construction and retirement, effective-binding comparison, publication of the current session, and the stable `P2PAutomationCoordinator`;
+- `P2PAutomationCoordinator` owns baseline-transfer de-duplication across room replacement, including in-flight work until settlement and completed peer baselines for the current automation generation and logical database identity;
+- each `P2PRoomSession` owns one Trystero room binding, its LiveSync RPC surface, advertisements, client proxies, diagnostics, its session-lifetime controller, and the finite replication operations admitted through that room; and
 - Trystero owns the underlying shared WebRTC peers and Nostr relay clients.
 
-Consumers must retain the service-feature result and resolve `result.replicator` at the point of use. A settings or database lifecycle transition can replace the replicator. A command, event listener, or view which captured the former instance could otherwise reopen a transport which the current service no longer owns.
+The implemented ownership topology is:
+
+```text
+host composition
+└── useP2PReplicatorFeature()
+    └── P2P service composition                    stable projection identity
+        ├── host lifecycle view                    host-only application lifecycle operations
+        ├── focused views                          stable, non-owning capability projections
+        ├── compatibility Replicator               deprecated, non-owning façade
+        └── private P2P service context            stable policy and shared references
+            └── P2PRoomSessionOwner                stable session owner and lifecycle queue
+                ├── P2PAutomationCoordinator       stable across room replacement
+                └── current P2PRoomSession         replaceable room-membership owner
+                    ├── P2PHost and TrysteroReplicator
+                    │                               session-bound RPC and transfer state
+                    └── Trystero room              membership and action namespace
+                        └── Trystero runtime       shared relay clients and physical peers
+```
+
+Only `P2PRoomSessionOwner` constructs, publishes, replaces, and retires the current `P2PRoomSession`. Module-level service operations change its demand set through the private context. Views, active-provider adapters, the host lifecycle projection, and the compatibility Replicator do not acquire session ownership.
+
+| Owner                       | State which survives room replacement                                                            | State retired with one room session                                                                                                |
+| --------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| P2P service composition     | stable lifecycle and contract-view identity                                                      | none                                                                                                                               |
+| private P2P service context | explicit-disconnect veto, host lifecycle closure, and lifecycle generation                       | delayed AutoStart callback is cancelled or invalidated before lifecycle retirement                                                 |
+| `P2PRoomSessionOwner`       | persistent and finite room-demand bookkeeping, lifecycle queue, and automation coordinator       | published session and its effective binding                                                                                        |
+| `P2PAutomationCoordinator`  | completed baseline peer names for the current generation and in-flight promises until settlement | none merely because a room session retires; a lifecycle or identity change clears completed records and prevents stale publication |
+| `P2PRoomSession`            | none                                                                                             | room, host, Replicator, advertisements, clients, callbacks, feeds, and admitted finite-operation controllers                       |
+| Trystero                    | implementation-owned relay clients and potentially shared physical peers                         | the departed LiveSync room's membership, action namespace, and callbacks are detached through the Trystero room API                |
+
+Ordinary consumers use the focused views returned by the service feature. They do not receive the room session, raw host, raw peer connection, or concrete Replicator. `ReplicatorService` receives a fresh non-owning active adapter when it selects P2P as the main remote. Disposing or replacing that adapter neither leaves the service-owned room nor cancels work owned by another service consumer. The explicit stop capability cancels current finite transfers without retiring the room.
+
+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                                      |
+
+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.
+
+## 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.
+
+Acquiring a finite room demand opens or reuses a session and then supplies that session to the operation. `P2PRoomSession.runFiniteOperation()` has a different responsibility: it admits one abortable transfer into an already owned session. It does not acquire or release a room demand. Configured-target discovery and execution are admitted as one such session operation, so retirement cancels and awaits the outer orchestration as well as any peer transfer which it has started. This separation prevents the settlement of one transfer from closing a room retained by AutoStart or another operation.
+
+The private service state owns the explicit-disconnect veto. A finite demand or AutoStart cannot reopen the room while that veto is set. A later explicit connect clears it. A completed Rebuild may acquire the distinct `rebuild-continuation` demand because that action continues an already authorised workflow; it does not clear the veto for later AutoStart work.
+
+Host lifecycle closure also sets a separate private reversible state before it invalidates delayed automation and closes the room. Settings reconciliation and finite stable-view operations cannot add a room demand while that state is set. Explicit connect, a separately authorised Rebuild continuation, or AutoStart scheduling after host resume clears it; settings reconciliation alone does not. Clearing this lifecycle state does not clear the explicit-disconnect veto: resumed AutoStart still observes the veto, while Rebuild retains its separate authority.
+
+AutoStart is scheduled against the current application lifecycle generation. Suspension, unload, explicit disconnect, and other lifecycle closes invalidate the generation and clear the delayed callback. The host's resumed-lifecycle scheduling establishes the next generation in which AutoStart may clear host lifecycle closure, and the callback then re-reads current settings before it asks the owner to add the `automatic` demand. WebPeer and other maintained hosts dispatch the shared resumed-lifecycle hook rather than scheduling a second raw room open.
+
+The stable `P2PAutomationCoordinator` de-duplicates the initial baseline for one normalised peer name across AutoSync and configured-target synchronisation. A transport-only room replacement does not repeat a completed baseline when the peer namespace and local database identity remain unchanged. Profile selection and policy changes do not replace the room. A new application lifecycle, a changed effective P2P peer namespace, or a different local database object clears completed baselines. The persisted profile identifier is not part of that namespace. In-flight operations are neither cancelled nor cleared by the coordinator: a request for the same normalised peer name may continue to share the existing promise until it settles. Work admitted under an older generation may settle, but cannot publish completion into the current generation. AutoWatch is not another baseline transfer: after an accepted peer advertises that it is broadcasting, it subscribes to later changes.
+
+## Unattended target orchestration
+
+Configured `P2P_SyncOnReplication` targets use `P2PTargetedTransfer.synchroniseConfiguredTargets()`. The generic unattended OneShot provider delegates to the same operation without peer-selection or peer-acceptance dialogues. The operation:
+
+1. acquires a finite room demand;
+2. waits for configured peer advertisements for a bounded period;
+3. evaluates each advertised peer against persisted and automatic admission policy without prompting;
+4. shares an accepted peer's baseline with AutoSync through `P2PAutomationCoordinator`; and
+5. returns an explicit completed, partial, blocked, cancelled, or failed provider outcome.
+
+Missing, rejected, and undecided targets remain visible in the target result rather than being reported as a successful headless operation. Denial takes precedence over acceptance. A headless undecided peer is not prompted and is not synchronised.
+
+Peer replication uses the ordinary common readiness gates, but declares central-remote preparation as not applicable. It therefore retains online, version, pending-file, clean-up, and host policy checks without trying to retrieve or initialise a CouchDB Security Seed. CouchDB and Object Storage providers declare central-remote preparation as required.
+
+## Setup connection-probe admission
+
+The current P2P Setup check establishes only whether its signalling transport can be opened. It does not validate peer discovery, room credentials against another device, or a TURN or WebRTC data path. Self-hosted LiveSync injects the service's `P2PConnectionProbeAdmission` view into every maintained opening of that Setup dialogue.
+
+The view delegates one complete decision to `P2PRoomSessionOwner`'s existing lifecycle queue. It receives the requested relay settings and a continuation which owns any short-lived raw Replicator and temporary database:
+
+- a serving room whose active relay set covers every requested relay settles as `observed-active` without entering the continuation;
+- a serving room which does not cover the requested relay set settles as `blocked` with `active-p2p-relay-binding-conflict`, again without entering the continuation; and
+- an idle owner runs the continuation and does not settle admission until that caller-owned trial has released its resources.
+
+Relay admission shares the transport's split-and-trim projection and compares de-duplicated sets. Ordering, duplicates, and surrounding whitespace therefore do not require another relay for this admission decision. It deliberately does not infer URI canonicalisation which Trystero's relay key does not implement.
+
+The continuation runs while the lifecycle queue owns serialisation. It must not await another lifecycle transition on the same service. A rejected continuation leaves the queue usable for a later request.
+
+This boundary adds no second room owner, process-global relay lease, or reference count. It does not change raw `TrysteroReplicator.dispose()` semantics. Observation and blocking never construct the raw trial, while idle admission keeps construction, probe execution, disposal, and temporary-database destruction inside one awaited continuation.
+
+## Active transfer cancellation
+
+The provider's active-transfer stop capability asks the current `P2PRoomSession` to cancel every finite replication operation which it has admitted. The request returns after cancellation has been delivered; the operations then settle cooperatively. The session keeps the room, peer discovery, and RPC service available for later work. Stopping an active transfer is therefore distinct from disconnecting or replacing the P2P transport.
+
+Each finite operation receives an effective abort signal derived from the session lifetime, its operation controller, and any caller or incoming RPC request signal. Cancellation is cooperative: an atomic database write which has already begun may settle, and its matching checkpoint may be recorded, before the operation reports cancellation. It is not a rollback promise.
+
+Retiring the session first rejects new finite work, then aborts and awaits all admitted operations before releasing the room. Code admitted into the session must observe its effective signal and must not detach unowned work.
+
+Configuration exchange and diagnostic reads are session-scoped requests, but are not finite replication operations. A request admitted before retirement may therefore settle against its originating session. Peer-admission decisions are persisted policy changes and intentionally settle independently of room replacement. None of these operations is included in active-transfer cancellation; peer callback and status fencing remains part of session retirement.
 
 ## Normal close
 
-`LiveSyncTrysteroReplicator.close()` serialises the close with any in-flight open operation. It stops LiveSync-owned work, closes the RPC room, calls `room.leave()`, clears instance references, pauses relay reconnection, and closes the current Nostr relay WebSockets.
+The transport lifecycle view delegates an explicit disconnect to its module-level service operation. That operation sets the private disconnect veto, invalidates delayed automation, and asks `P2PRoomSessionOwner.close()` to clear every current demand and serialise retirement with any in-flight open operation. Retirement stops LiveSync-owned work, closes the RPC room, calls `room.leave()`, clears instance references, pauses relay reconnection, and closes the current Nostr relay WebSockets.
 
 Normal close deliberately does not call `close()` on the `RTCPeerConnection` values returned by `room.getPeers()`. Trystero 0.25 may share a physical peer across rooms. Leaving a room detaches its callbacks and action namespace, while Trystero may retain the idle physical peer for approximately 123 seconds for reuse. The retained peer cannot carry traffic for the departed room.
 
+A host which constructs a raw `TrysteroReplicator` inside an admitted idle trial must call `dispose()` when it discards that object. `close()` releases the current transport while preserving host-lifetime subscriptions for a possible later open; `dispose()` performs that close and then releases those subscriptions permanently.
+
 Likewise, an incoming peer-leave notification removes LiveSync advertisement and client state without directly closing the underlying peer. Trystero decides whether that peer is shared, stale, or ready for destruction.
 
 The host command named 'Disconnect from the Signalling Server' means:
@@ -31,11 +143,21 @@ It is therefore a logical LiveSync disconnection and a physical signalling-serve
 
 ## Reconnection and replacement
 
-An explicit open resumes Trystero relay reconnection before joining the configured room. Settings application may change the relay URLs, room ID, passphrase, or TURN configuration, so the owning service normally closes and discards the former LiveSync instance before constructing the replacement. Concurrent replacement requests share the same in-flight replacement and receive the same new owner.
+An explicit connect resumes Trystero relay reconnection before joining the configured room. Active-provider adapter acquisition is independent of that room lifecycle and cannot replace or close the service context.
+
+The room-session owner compares an explicit effective-transport identity, device identity, and the local database object on every open. The transport identity contains the effective App ID, room ID, passphrase, normalised signalling relay and TURN configuration, effective connection path, RPC message-size bound, and diagnostic RTC mode. Persisted profile identifiers, P2P enablement, and automation or admission policy are not transport identity. An equivalent representation, such as surrounding whitespace in a relay list, therefore keeps the serving room. A changed binding serialises retirement of the complete session before opening and publishing its replacement.
+
+Each room session captures one immutable settings snapshot for room join options, RPC framing, device identity, and the database object. A separate `currentSettings()` host port supplies policy evaluated on the open room. AutoSync and AutoWatch read it when a peer advertises, configured-target synchronisation reads it when the operation starts, and admission and headless policy are read when a peer is evaluated. A settings save does not replay an existing advertisement or infer whether an existing watch was manual or automatic. AutoBroadcast is reconciled explicitly on the current Replicator, without replacing the room. Configuration exchange continues to use the immutable session snapshot.
+
+After a candidate room opens, the owner rechecks current enablement, demand, database identity, device identity, and effective transport identity before publication. This prevents changed credentials, transport, or database state from being applied partly to the former room or exposed through a stale candidate. No fixed close-to-open delay is required: lifecycle operations are serialised, and peer readiness is observed through discovery.
+
+The stable service also participates directly in the local database lifecycle. Reset preparation and explicit database close await room retirement before the database managers are torn down and the physical PouchDB handle is destroyed or closed. The later database-initialisation hook remains a defensive retirement boundary before a replacement session is opened. The non-owning active adapter does not provide this fencing.
+
+Saving settings reconciles the demand owned by AutoStart and applies AutoBroadcast to the current room, but cannot clear host lifecycle closure. Disabling AutoStart removes the `automatic` demand but leaves a room retained by explicit connect, a Rebuild continuation, or finite work. Disabling P2P clears every demand and retires the room through the lifecycle queue, including an in-flight open. An explicit disconnect establishes a service-lifetime veto which a later automatic-start event cannot clear; a later explicit connect clears it.
 
-A retained `LiveSyncTrysteroReplicator` also compares the effective outgoing message bound and connection path on every open. An unchanged signature keeps the serving transport, while a changed signature serialises closure of that transport before opening its replacement. This prevents a selected compatibility profile from appearing to take effect while the former room binding is still active. No fixed close-to-open delay is required: lifecycle operations are serialised, and peer readiness is observed through discovery.
+A successful rebuild notification is a separately authorised continuation of the owning rebuild workflow, rather than an automatic-start request. It may therefore reopen the room independently of that automatic-start veto after the replacement database is ready.
 
-Saving settings with P2P or automatic start disabled always requests `close()`, even when the room has not started serving. This cancels an in-flight open through the same lifecycle queue, so a connection cannot appear after the disabling setting has been applied.
+Peer arrival and departure callbacks are bound directly to the `P2PRoomSession` which created the host. The global peer events remain available for status, logs, and legacy observation, but maintained service composition does not route them back into whichever session happens to be current. Retiring a session detaches its peer callbacks before closing the room, so a late advertisement from the former host cannot start work in its replacement. Once the host is disposed, delayed callbacks can no longer publish peer or status events which might overwrite the replacement's UI state. Host-lifetime subscriptions are released when that session is disposed, rather than during the temporary transport shutdown used before a room join.
 
 Do not replace a relay socket's `onclose` handler. Trystero 0.25 shares relay clients by URL and uses its own handler to retire and recreate them. Use the exported pause and resume functions around explicit disconnection instead.
 
@@ -55,7 +177,9 @@ Commonlib consequently does not expose a forced physical-disconnection command.
 
 Maintain all five boundaries when this lifecycle changes:
 
-- Commonlib unit tests must prove that normal close leaves the room without directly closing Trystero-owned peers, that disabling settings cancel a pending open, that concurrent replacement requests leave one current owner, and that a changed compatibility signature replaces a serving transport while an unchanged signature remains idempotent;
+- Commonlib unit tests must prove that normal close leaves the room without directly closing Trystero-owned peers, that database close handlers all settle before physical close, that disabling P2P cancels a pending open, that host lifecycle closure blocks settings reconciliation and finite room demand until a declared resume boundary, that removing one policy demand retains a room held by another demand, that concurrent replacement requests leave one current owner, that a changed effective binding replaces a serving transport while an equivalent representation, profile-only change, or policy-only change retains it, that AutoBroadcast is reconciled on that retained room, that a rebuild-owned continuation can reopen independently of an automatic-start veto, and that retired peer callbacks and host subscriptions cannot reach a replacement;
+- connection-probe admission tests must prove compatible active observation, typed blocking before an additional relay is opened, complete idle-trial serialisation and clean-up, representation-insensitive relay coverage, and lifecycle-queue recovery after a rejected trial;
+- target-aware automation tests must prove bounded delayed advertisement discovery, non-interactive acceptance outcomes, explicit partial and blocked results, baseline de-duplication across AutoSync and configured targets, cancellation of delayed AutoStart after suspension, and a finite demand beside an AutoStart-held room;
 - Commonlib rebuild tests must prove that first-device P2P initialisation does not reset a remote database and that an additional-device P2P Fetch performs one explicit peer-selection pass before resuming reflection;
 - the Self-hosted LiveSync Compose P2P lifecycle test must replace a current replicator, rediscover the same real peer, perform bidirectional RPC, and verify transferred content from a separate process;
 - the Self-hosted LiveSync real-Obsidian P2P Setup URI workflow must generate the second-device URI on the first device, accept both peer directions visibly, and verify a two-way note round-trip; and

package/docs/proven-in-use.md

@@ -28,6 +28,8 @@ Commonlib's full offline scanner distinguishes completed, deliberately skipped,
 
 Commonlib's local-database lifecycle tests distinguish the settings-selected database from the active wrapper. They verify replacement before a changed-suffix reset, fail-closed cleanup after rejected physical preparation, application readiness after the requested scan and completion hooks, and the prevention of rebuilt events and later remote mutation after a failed local reset. Self-hosted LiveSync owns settings persistence, setup flags, recovery dialogue, and real-Obsidian rebuild confirmation; those host results remain downstream evidence rather than Commonlib guarantees.
 
+The focused `/replication` entry defines the provider capability, configuration identity, same-kind reconciliation, interaction authority, and truthful outcome contracts used when a host composes replication. A host selects its fixed provider subset and registers each definition during composition; an omitted role remains an explicit unsupported result rather than falling back to another provider. Commonlib serialises active replacement, rejects a candidate whose configuration changes before publication, and provides a transition-aware context acquisition boundary. The entry does not own user dialogue, P2P room policy, or selection of unknown providers.
+
 Most replication and storage services used by the plug-in still enter through explicit `compat/*` paths. Those imports prove that the published compatibility boundary supports the current migration; they are not examples of a finished high-level client API.
 
 The plug-in's manual onboarding and Remote Databases pane use the focused `/remote-configurations` entry to create opaque profile IDs, retain user-visible names, and select main and P2P remotes. Commonlib owns the in-memory profile result contract; Self-hosted LiveSync adds dialogue, Setup URI classification, Fetch or Rebuild scheduling, persistence, restart ordering, and real-Obsidian presentation checks.
@@ -56,10 +58,12 @@ The browser and Node storage implementations run through the same Commonlib resu
 
 The browser service composition in `src/apps/browser/createLiveSyncBrowserServiceHub.ts` is owned by Self-hosted LiveSync. It combines Commonlib's injectable service contracts and data implementations with LiveSync-owned browser API, UI, settings persistence, restart policy, and Vault identity. Commonlib therefore does not provide or select a general browser host.
 
-The Obsidian plug-in, CLI, WebApp, and WebPeer compose P2P ownership through `useP2PReplicatorFeature`. Commands and views retain its live result object and resolve the current replicator when an action occurs. Downstream Deno and Compose P2P E2E cover headless peer discovery and synchronisation, including the WebApp-to-WebPeer-to-CLI journey. Application-owned Chromium checks cover the browser UI flows, and the public Pages deployment has separate post-deployment smoke validation. The real-Obsidian Setup URI workflow additionally covers first-device local initialisation, one-pass additional-device Fetch, explicit peer approval, Vault reflection, and a two-way note round-trip.
+The Obsidian plug-in, CLI, WebApp, and WebPeer compose P2P ownership through `useP2PReplicatorFeature`. The feature now returns focused views over one stable service owner, including connection-probe admission, and supplies non-owning adapters when P2P is selected as the main remote. Commands, Setup, and diagnostics can therefore avoid concrete-class checks and raw room access; existing panes retain the deprecated compatibility façade while they migrate. Downstream Deno and Compose P2P E2E cover headless peer discovery and synchronisation, including the WebApp-to-WebPeer-to-CLI journey. Application-owned Chromium checks cover the browser UI flows, and the public Pages deployment has separate post-deployment smoke validation. The real-Obsidian Setup URI workflow additionally covers first-device local initialisation, one-pass additional-device Fetch, explicit peer approval, Vault reflection, and a two-way note round-trip.
 
 Commonlib's focused P2P compatibility tests establish legacy defaulting, bounded outgoing message sizes, connection-string and QR-setting round trips, application of the configured bound across its Trystero server and client surfaces, relay-only ICE mapping when a valid TURN URL is present, and replacement of a serving transport when an effective compatibility value changes. They do not prove that a particular network path requires a smaller preset or that a configured TURN service can allocate a relay. Self-hosted LiveSync owns profile selection, user-facing controls, and real-Obsidian composition; device- and network-specific connectivity remains downstream or reporter-environment evidence.
 
+Focused room-session and RPC tests additionally establish that a manual stop delivers cancellation to every concurrent finite replication while leaving the room reusable, that session retirement rejects new work and awaits admitted work before leaving, and that caller cancellation reaches a cancellation-aware incoming RPC handler. The replication-shim tests establish cancellation at safe batch boundaries and preserve the checkpoint for an atomic database write which has already settled. Self-hosted LiveSync composes the provider stop capability into its manual command; physical transport interruption and operating-system process termination remain host and runtime boundaries rather than rollback guarantees.
+
 This is evidence that the current package boundary can be consumed without the Obsidian host, but it is not yet a recommended standalone Commonlib client factory. The high-level lifecycle, readiness, error, and disposal contract remains future package work after Self-hosted LiveSync 1.0 rather than a gate for that release.
 
 ## LiveSync Bridge

package/docs/remote-configurations.md

@@ -26,6 +26,8 @@ const profile: RemoteConfiguration = upsertRemoteConfigurationInPlace(settings,
 
 The helper serialises the connection fields into the profile URI. When `activate` is true, it selects that profile through `activeConfigurationId` and projects the profile back onto the compatibility fields. The host still owns persistence, restart policy, credential acquisition, and user confirmation.
 
+A Setup URI is a compatibility and persistence representation, not the active Replicator identity. Each provider must instead project the effective fields which bind its own connection resources. Either representation can contain connection credentials and must remain private; do not log it or use it as a display label.
+
 ## Identity and display names
 
 Profile IDs are opaque identity. Omit `id` to allocate a new one and preserve every existing profile. Pass a known `id` only when deliberately updating that profile.
@@ -44,6 +46,8 @@ There is no special profile named or identified as `default`. The selected main
 
 The outgoing message bound and connection path are ordinary P2P profile properties retained in its connection URI. Separate profiles may intentionally share a Group ID and credentials while selecting different transport compatibility values; only the profile selected by `P2P_ActiveRemoteConfigurationId` supplies the active flat P2P projection.
 
+The selected profile ID is persisted identity, not an effective transport fingerprint. Selecting another P2P profile which projects the same effective room and transport values retains the current room; a change to those effective values replaces it. Profile presentation and selection changes therefore remain separate from transport lifecycle comparison.
+
 Selecting a profile updates the compatibility fields immediately. Existing replication services may therefore continue to consume those fields while profile-aware hosts treat the profile map and selection IDs as authoritative persisted state.
 
 ## Import and migration boundary

package/docs/service-feature-composition.md

@@ -0,0 +1,250 @@
+---
+date: 2026-08-30
+commonlib-version: "0.1.20"
+self-hosted-livesync-version: "1.0.21"
+status: accepted
+---
+
+# Service feature composition
+
+This guide is for Commonlib and maintained-host developers who are adding behaviour to the Service Hub composition. It explains when to extend a Service, create a serviceFeature, share a ServiceModule, or introduce a class which owns a resource.
+
+The choice is primarily about dependency direction and ownership. Mutable state alone does not require a class or a ServiceModule.
+
+## Choose the narrowest composition form
+
+| Need                                                                              | Preferred form                                                        | Reason                                                                                          |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Add one check, notification, or transformation to an existing contract            | Register a handler on the owning Service                              | The Service already defines the ordering, result, and lifetime.                                 |
+| Connect several Services or ServiceModules to one feature                         | serviceFeature                                                        | Dependencies remain explicit, and host-specific composition stays outside the domain operation. |
+| Retain state used only by one composed feature                                    | Private context created by a serviceFeature                           | State remains bounded without becoming a shared service locator.                                |
+| Share one long-lived operational capability between several consumers             | ServiceModule                                                         | The host constructs one typed capability and makes its lifetime explicit.                       |
+| Own an external resource with identity, replacement, abort, or disposal semantics | Focused class or resource owner, usually composed by a serviceFeature | The object lifetime is part of the contract rather than an implementation convenience.          |
+| Integrate with an existing legacy application Module                              | Keep the existing Module at that boundary                             | Preserve the established integration, but do not widen it into a new general pattern.           |
+
+## Declare dependencies at the boundary
+
+Use `NecessaryServices` to state the exact Services and ServiceModules which a feature consumes:
+
+```typescript
+type IndexFeatureHost = NecessaryServices<"appLifecycle" | "API", "storageAccess">;
+
+export const useIndexFeature = createServiceFeature((host: IndexFeatureHost) => {
+    const { appLifecycle, API } = host.services;
+    const { storageAccess } = host.serviceModules;
+
+    appLifecycle.onLoaded.addHandler(async () => {
+        const paths = await storageAccess.getFileNames();
+        API.addLog(`Indexed ${paths.length} paths`);
+        return true;
+    });
+});
+```
+
+This signature is both documentation and a compile-time boundary. Adding an unrelated Service to the host object does not make it available to the feature. If the operation needs another collaborator, add it deliberately to the declared contract.
+
+A serviceFeature is a composition function, not a runtime registry entry. Call it from the host composition after its dependencies exist:
+
+```typescript
+useIndexFeature({
+    services: {
+        context: serviceHub.context,
+        appLifecycle: serviceHub.appLifecycle,
+        API: serviceHub.API,
+    },
+    serviceModules: { storageAccess },
+});
+```
+
+Do not bind a serviceFeature to an application object merely to obtain `this`. Pass the narrow host value directly.
+
+## Separate an operation from its composition
+
+When an operation has meaningful sequencing or failure behaviour, keep it independently callable and let the serviceFeature own only construction and registration.
+
+`prepareDatabaseForUse.ts` follows this split. Its operation accepts explicit collaborators and returns the application result:
+
+```typescript
+type PrepareDatabaseHost = NecessaryServices<
+    "appLifecycle" | "setting" | "vault" | "path" | "database" | "databaseEvents" | "fileProcessing" | "replicator",
+    never
+>;
+
+export async function prepareDatabaseForUse(
+    host: PrepareDatabaseHost,
+    log: LogFunction,
+    errorManager: UnresolvedErrorManager,
+    showingNotice = false,
+    reopenDatabase = true,
+    ignoreSuspending = false
+): Promise<boolean> {
+    // Open, scan, run completion handlers, commit pending events, and mark ready.
+}
+```
+
+The corresponding composition constructs the owned error manager and registers one adapter function:
+
+```typescript
+export function usePrepareDatabaseForUse(host: PrepareDatabaseHost): void {
+    const log = createInstanceLogFunction("SF:prepareDatabaseForUse", host.services.API);
+    const errorManager = new UnresolvedErrorManager(host.services.appLifecycle, host.services.context.events);
+
+    host.services.databaseEvents.initialiseDatabase.addHandler(
+        (showingNotice = false, reopenDatabase = true, ignoreSuspending = false) =>
+            prepareDatabaseForUse(host, log, errorManager, showingNotice, reopenDatabase, ignoreSuspending)
+    );
+}
+```
+
+Test the operation's sequencing and failure short-circuiting separately from the handler registration. This keeps a lifecycle rename from forcing every domain test through an application-shaped fixture.
+
+## Keep feature-local state private
+
+State which exists for one predicate, cache, queue, or scheduling policy can remain in a factory or private context. It does not need to become a property on the application core.
+
+`targetFilter.ts` uses one factory per stateful predicate. The ignore-file factory owns its settings snapshot and cache:
+
+```typescript
+type IgnoreFileHost = NecessaryServices<"setting" | "appLifecycle", "storageAccess">;
+
+export function isAcceptedByIgnoreFilesFactory(host: IgnoreFileHost, log: LogFunction) {
+    let ignoreFiles: string[] = [];
+    const ignoreFileCacheMap = new Map<string, string[] | undefined | false>();
+
+    const refreshSettings = () => {
+        ignoreFiles = host.services.setting
+            .currentSettings()
+            .ignoreFiles.split(",")
+            .map((value) => value.trim());
+        return Promise.resolve(true);
+    };
+
+    host.services.setting.onSettingRealised.addHandler(refreshSettings);
+    return async function isAcceptedByIgnoreFiles(file: string | UXFileInfoStub): Promise<boolean> {
+        // Evaluate the current path with the private cache.
+    };
+}
+```
+
+`useTargetFilters` then creates the predicates and registers their public effects in the required order. The cache is not exposed merely so that composition code can reach it.
+
+Use one private context when several functions share the same state:
+
+```typescript
+type DeferredTaskHost = NecessaryServices<"appLifecycle", never>;
+
+interface DeferredTaskContext {
+    pending: Set<Promise<unknown>>;
+    stopped: boolean;
+}
+
+interface DeferredTaskControl {
+    track(task: Promise<unknown>): void;
+}
+
+function trackTask(context: DeferredTaskContext, task: Promise<unknown>): void {
+    if (!context.stopped) context.pending.add(task);
+}
+
+function stopTasks(context: DeferredTaskContext): void {
+    context.stopped = true;
+    context.pending.clear();
+}
+
+export function useDeferredTasks(host: DeferredTaskHost): DeferredTaskControl {
+    const context: DeferredTaskContext = { pending: new Set(), stopped: false };
+    host.services.appLifecycle.onUnload.addHandler(() => {
+        stopTasks(context);
+        return Promise.resolve(true);
+    });
+    return { track: (task) => trackTask(context, task) };
+}
+```
+
+Return only the focused view which another consumer needs. Do not return the private context or add it to the complete Service Hub.
+
+## Use a ServiceModule for a shared operational capability
+
+A ServiceModule is appropriate when several consumers must use the same long-lived capability or resource owner. Current examples include `storageAccess`, `databaseFileAccess`, `fileHandler`, and `rebuilder`.
+
+Before adding one, verify all of the following:
+
+- more than one consumer needs the same identity or lifetime;
+- its public operations form a coherent capability;
+- construction and disposal belong to the host composition;
+- its dependencies can be declared without accepting the complete application core; and
+- a private serviceFeature context would not provide the same behaviour more simply.
+
+Do not promote a value to `ServiceModules` merely because a test needs to reach it. Inject the focused view into the current consumer instead.
+
+## Use a class only when identity or lifetime is part of the contract
+
+A class is justified when behaviour depends on stable identity, replaceable implementations, serialised ownership, or an explicit resource lifecycle such as `abort()`, `close()`, or `dispose()`.
+
+The P2P composition is an example at a larger scale: room-session and transport owners have identities, concurrent operations must be fenced, and shutdown order matters. Their classes own those invariants. The surrounding serviceFeature connects them to Services and gives each consumer only a focused view.
+
+A class is usually unnecessary when it would only:
+
+- store collaborators which can be function parameters;
+- group private helper functions;
+- provide a convenient `this` value;
+- mirror the Service Hub; or
+- expose state solely for tests.
+
+## Test interactions at the composition boundary
+
+Use London School tests for a serviceFeature. Verify its observable collaboration rather than reconstructing the complete application:
+
+```typescript
+it("registers the database preparation operation", async () => {
+    let handler: (() => Promise<boolean>) | undefined;
+    const addHandler = vi.fn((value) => {
+        handler = value;
+    });
+    const prepare = vi.fn(async () => true);
+
+    useExampleDatabaseFeature(makeHost({ addHandler, prepare }));
+
+    expect(addHandler).toHaveBeenCalledOnce();
+    await expect(handler?.()).resolves.toBe(true);
+    expect(prepare).toHaveBeenCalledOnce();
+});
+```
+
+For a state owner, test transitions and invariants directly. For an operation, verify collaborator order, the first rejected result, and which later effects do not run.
+
+Stop and review the design when a focused test requires:
+
+- a complete application-core fixture;
+- a deep chain of mocks;
+- import-order substitution or process-global mutation;
+- unrelated Services merely to construct the subject; or
+- access to private state instead of an observable result.
+
+This friction is a design-review signal. It is not a reason to publish more internals or add a broader test helper.
+
+## Working with legacy Modules
+
+Existing hosts may still use `AbstractModule` or an equivalent legacy layer. Retain that boundary when its identity, registration, or host integration is part of the current change. New Commonlib composition must not require a host to provide its complete application core.
+
+When modifying an existing Module:
+
+1. identify the operation or state owner which can have a narrow contract;
+2. move that bounded part only when the current behaviour needs it;
+3. keep host-specific UI and registration at the application boundary;
+4. add interaction tests around the extracted boundary; and
+5. avoid an unrelated mechanical conversion of neighbouring Modules.
+
+The maintained Self-hosted LiveSync guidance documents the additional risks of its `AbstractModule` and `AbstractObsidianModule` implementations.
+
+## Review checklist
+
+Before accepting a new composition, confirm that:
+
+- the owner of each mutable state and external resource is clear;
+- dependencies appear in the function or constructor signature;
+- the feature receives no broader host object than it uses;
+- handler ordering and failure results belong to the owning Service contract;
+- returned values are focused consumer views rather than service locators;
+- disposal and replacement are explicit when resources outlive one call; and
+- focused interaction tests can be written without a broad fixture.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -52,6 +52,16 @@
       "import": "./dist/platform/node/index.js",
       "default": "./dist/platform/node/index.js"
     },
+    "./p2p": {
+      "types": "./dist/p2p/index.d.ts",
+      "import": "./dist/p2p/index.js",
+      "default": "./dist/p2p/index.js"
+    },
+    "./replication": {
+      "types": "./dist/replication/index.d.ts",
+      "import": "./dist/replication/index.js",
+      "default": "./dist/replication/index.js"
+    },
     "./rpc": {
       "types": "./dist/rpc/index.d.ts",
       "import": "./dist/rpc/index.js",
@@ -626,6 +636,12 @@
       "node": [
         "dist/platform/node/index.d.ts"
       ],
+      "p2p": [
+        "dist/p2p/index.d.ts"
+      ],
+      "replication": [
+        "dist/replication/index.d.ts"
+      ],
       "rpc": [
         "dist/rpc/index.d.ts"
       ],

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

@@ -1,19 +0,0 @@
-import type { LOG_LEVEL } from "octagonal-wheels/common/logger";
-import type { SimpleStore } from "octagonal-wheels/databases/SimpleStoreBase";
-import type { ReactiveSource } from "octagonal-wheels/dataobject/reactive_v2";
-import type { P2PSyncSetting, EntryDoc } from "../../common/types.js";
-import type { Confirm } from "../../interfaces/Confirm.js";
-import type { InjectableServiceHub } from "../../services/InjectableServices.js";
-export interface P2PReplicatorBase {
-    storeP2PStatusLine: ReactiveSource<string>;
-    settings: P2PSyncSetting;
-    _log(msg: unknown, level?: LOG_LEVEL): void;
-    _notice(msg: unknown, key?: string): void;
-    getSettings(): P2PSyncSetting;
-    getDB: () => PouchDB.Database<EntryDoc>;
-    confirm: Confirm;
-    simpleStore(): SimpleStore<unknown>;
-    handleReplicatedDocuments(docs: EntryDoc[]): Promise<boolean>;
-    init(): Promise<this>;
-    services: InjectableServiceHub;
-}

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

@@ -1,8 +0,0 @@
-import type { NecessaryServices } from "../../interfaces/ServiceModule.js";
-import type { P2PPaneParams } from "./UseP2PReplicatorResult.js";
-export type P2PViewFactory = (leaf: unknown) => unknown;
-/**
- * @deprecated Compose `useP2PReplicatorFeature` with host-specific commands
- * and UI instead. This wrapper remains for source compatibility.
- */
-export declare function useP2PReplicator(host: NecessaryServices<"API" | "appLifecycle" | "setting" | "vault" | "database" | "databaseEvents" | "keyValueDB" | "replication" | "config" | "UI" | "replicator" | "remote", never>, viewTypeAndFactory?: [viewType: string, factory: P2PViewFactory]): P2PPaneParams;

package/dist/replication/trystero/P2PReplicatorCore.js

@@ -1,56 +0,0 @@
-import { REMOTE_P2P } from "../../common/types.js";
-import { reactiveSource } from "octagonal-wheels/dataobject/reactive_v2";
-import { EVENT_REQUEST_OPEN_P2P } from "../../events/coreEvents.js";
-import { P2PLogCollector } from "./P2PLogCollector.js";
-import { useP2PReplicatorCommands } from "./useP2PReplicatorCommands.js";
-import { useP2PReplicatorFeature } from "./useP2PReplicatorFeature.js";
-function useP2PReplicator(host, viewTypeAndFactory) {
-  const activeReplicator = useP2PReplicatorFeature(host);
-  const events = host.services.context.events;
-  const p2pLogCollector = new P2PLogCollector(events);
-  const storeP2PStatusLine = reactiveSource("");
-  p2pLogCollector.p2pReplicationLine.onChanged((line) => {
-    storeP2PStatusLine.value = line.value;
-  });
-  if (viewTypeAndFactory) {
-    const [viewType, factory] = viewTypeAndFactory;
-    const openPane = () => host.services.API.showWindow(viewType);
-    useP2PReplicatorCommands(host, activeReplicator);
-    host.services.appLifecycle.onInitialise.addHandler(() => {
-      host.services.API.registerWindow(viewType, factory);
-      events.onEvent(EVENT_REQUEST_OPEN_P2P, () => void openPane());
-      host.services.API.addCommand({
-        id: "open-p2p-replicator",
-        name: "P2P Sync : Open P2P Replicator",
-        callback: () => void openPane()
-      });
-      host.services.API.addCommand({
-        id: "replicate-now-by-p2p",
-        name: "Replicate now by P2P",
-        checkCallback: (isChecking) => {
-          const replicator = activeReplicator.replicator;
-          const settings = host.services.setting.currentSettings();
-          if (isChecking) {
-            if (settings.remoteType == REMOTE_P2P) return false;
-            return replicator.server?.isServing ?? false;
-          }
-          void replicator.replicateFromCommand(false);
-        }
-      });
-      host.services.API.addRibbonIcon("waypoints", "P2P Replicator", () => {
-        void openPane();
-      })?.classList.add("livesync-ribbon-replicate-p2p");
-      return Promise.resolve(true);
-    });
-  }
-  return {
-    get replicator() {
-      return activeReplicator.replicator;
-    },
-    p2pLogCollector,
-    storeP2PStatusLine
-  };
-}
-export {
-  useP2PReplicator
-};

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

@@ -1,2 +0,0 @@
-import { TrysteroReplicatorP2PServer } from "./TrysteroReplicatorP2PServer.js";
-export { TrysteroReplicatorP2PServer as TrysteroConnection };