Tighten provider adapter boundaries

src/common/replicatorResources/connection.ts

@@ -9,10 +9,10 @@ import {
     type LiveSyncCouchDBReplicatorEnv,
 } from "@vrtmrz/livesync-commonlib/compat/replication/couchdb/LiveSyncReplicator";
 import { LiveSyncJournalReplicator } from "@vrtmrz/livesync-commonlib/compat/replication/journal/LiveSyncJournalReplicator";
-import type { LiveSyncJournalReplicatorEnv } from "@vrtmrz/livesync-commonlib/compat/replication/journal/LiveSyncJournalReplicatorEnv";
 import { createReplicatorDisposer, snapshotRemoteSettings } from "./shared";
 
-export type ConnectionResourceHost = LiveSyncCouchDBReplicatorEnv & LiveSyncJournalReplicatorEnv;
+/** Host environment sufficient to construct either central connection probe. */
+export type ConnectionResourceHost = LiveSyncCouchDBReplicatorEnv;
 
 function createCouchDBConnectionProbe(
     replicator: LiveSyncCouchDBReplicator,
@@ -60,7 +60,12 @@ function createObjectStorageConnectionProbe(
     };
 }
 
-/** Build an unpublished CouchDB connection resource for one host. */
+/**
+ * Build an unpublished CouchDB connection probe for one host.
+ *
+ * The probe owns both its concrete Replicator and each connection it opens. It
+ * never publishes that Replicator as the active provider instance.
+ */
 export function createCouchDBConnectionProbeFactory(host: ConnectionResourceHost): ConnectionProbeFactory {
     return (setting) => {
         const snapshot = snapshotRemoteSettings(setting);
@@ -68,7 +73,12 @@ export function createCouchDBConnectionProbeFactory(host: ConnectionResourceHost
     };
 }
 
-/** Build an unpublished Object Storage connection resource for one host. */
+/**
+ * Build an unpublished Object Storage connection probe for one host.
+ *
+ * The probe owns its concrete Replicator and never publishes or replaces the
+ * active provider instance.
+ */
 export function createObjectStorageConnectionProbeFactory(host: ConnectionResourceHost): ConnectionProbeFactory {
     return (setting) => {
         const snapshot = snapshotRemoteSettings(setting);

src/common/replicatorResources/preferredTweak.ts

@@ -5,10 +5,10 @@ import {
     type LiveSyncCouchDBReplicatorEnv,
 } from "@vrtmrz/livesync-commonlib/compat/replication/couchdb/LiveSyncReplicator";
 import { LiveSyncJournalReplicator } from "@vrtmrz/livesync-commonlib/compat/replication/journal/LiveSyncJournalReplicator";
-import type { LiveSyncJournalReplicatorEnv } from "@vrtmrz/livesync-commonlib/compat/replication/journal/LiveSyncJournalReplicatorEnv";
 import { createReplicatorDisposer, snapshotRemoteSettings, type ResourceReplicator } from "./shared";
 
-export type PreferredTweakResourceHost = LiveSyncCouchDBReplicatorEnv & LiveSyncJournalReplicatorEnv;
+/** Host environment sufficient to construct either preferred-tweak probe. */
+export type PreferredTweakResourceHost = LiveSyncCouchDBReplicatorEnv;
 
 interface PreferredTweakReplicator extends ResourceReplicator {
     getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
@@ -24,7 +24,7 @@ function createPreferredTweakProbe(
     };
 }
 
-/** Build an unpublished CouchDB preferred-tweak resource for one host. */
+/** Build an unpublished, independently disposed CouchDB preferred-tweak probe. */
 export function createCouchDBPreferredTweakProbeFactory(host: PreferredTweakResourceHost): PreferredTweakProbeFactory {
     return (setting) => {
         const snapshot = snapshotRemoteSettings(setting);
@@ -32,7 +32,7 @@ export function createCouchDBPreferredTweakProbeFactory(host: PreferredTweakReso
     };
 }
 
-/** Build an unpublished Object Storage preferred-tweak resource for one host. */
+/** Build an unpublished, independently disposed Object Storage preferred-tweak probe. */
 export function createObjectStoragePreferredTweakProbeFactory(
     host: PreferredTweakResourceHost
 ): PreferredTweakProbeFactory {

src/common/replicatorResources/securitySeed.ts

@@ -5,10 +5,10 @@ import {
     type LiveSyncCouchDBReplicatorEnv,
 } from "@vrtmrz/livesync-commonlib/compat/replication/couchdb/LiveSyncReplicator";
 import { LiveSyncJournalReplicator } from "@vrtmrz/livesync-commonlib/compat/replication/journal/LiveSyncJournalReplicator";
-import type { LiveSyncJournalReplicatorEnv } from "@vrtmrz/livesync-commonlib/compat/replication/journal/LiveSyncJournalReplicatorEnv";
 import { createReplicatorDisposer, snapshotRemoteSettings, type ResourceReplicator } from "./shared";
 
-export type SecuritySeedResourceHost = LiveSyncCouchDBReplicatorEnv & LiveSyncJournalReplicatorEnv;
+/** Host environment sufficient to construct either Security Seed resource. */
+export type SecuritySeedResourceHost = LiveSyncCouchDBReplicatorEnv;
 
 /** Minimal private Replicator surface required by a Security Seed resource. */
 interface SecuritySeedReplicator extends ResourceReplicator {
@@ -28,12 +28,12 @@ function createSecuritySeedResourceFactory(
     };
 }
 
-/** Build an unpublished CouchDB Security Seed resource for one host. */
+/** Build an unpublished, independently disposed CouchDB Security Seed resource. */
 export function createCouchDBSecuritySeedResourceFactory(host: SecuritySeedResourceHost): SecuritySeedResourceFactory {
     return createSecuritySeedResourceFactory(() => new LiveSyncCouchDBReplicator(host));
 }
 
-/** Build an unpublished Object Storage Security Seed resource for one host. */
+/** Build an unpublished, independently disposed Object Storage Security Seed resource. */
 export function createObjectStorageSecuritySeedResourceFactory(
     host: SecuritySeedResourceHost
 ): SecuritySeedResourceFactory {

src/common/replicatorResources/shared.ts

@@ -1,5 +1,12 @@
 import type { RemoteDBSettings } from "@vrtmrz/livesync-commonlib/compat/common/types";
 
+/**
+ * Closeable surface of a concrete Replicator owned by one private resource.
+ *
+ * It deliberately exposes no active-provider controls: the resource may use
+ * the helper for one bounded operation, then must dispose it without
+ * publishing or replacing the active Replicator.
+ */
 export interface ResourceReplicator {
     closeReplication(): void | Promise<void>;
 }

src/common/replicatorResources/synchronisationInformation.ts

@@ -6,7 +6,12 @@ import {
 import { checkSyncInfo } from "@vrtmrz/livesync-commonlib/compat/pouchdb/negotiation";
 import { createReplicatorDisposer, snapshotRemoteSettings } from "./shared";
 
-/** Build an owned CouchDB synchronisation-information verifier for one host. */
+/**
+ * Build an unpublished CouchDB synchronisation-information verifier.
+ *
+ * The resource owns its concrete Replicator and connection, and cannot replace
+ * the active provider instance.
+ */
 export function createCouchDBSynchronisationInformationResourceFactory(
     host: LiveSyncCouchDBReplicatorEnv
 ): SynchronisationInformationResourceFactory {