@vrtmrz/livesync-commonlib 0.1.19 → 0.1.21

package/dist/services/base/ReplicatorService.js

@@ -1,15 +1,21 @@
-import { handlers } from "../lib/HandlerUtils.js";
+import { firstResultFunction, handlers } from "../lib/HandlerUtils.js";
 import { ServiceBase } from "./ServiceBase.js";
 import { createInstanceLogFunction } from "../lib/logUtils.js";
 import { UnresolvedErrorManager } from "./UnresolvedErrorManager.js";
 import { yieldMicrotask } from "octagonal-wheels/promises";
 import { LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "../../common/logger.js";
-import { RemoteTypes } from "../../common/types.js";
 import { DEFAULT_REPLICATION_STATICS } from "../../common/models/shared.definition.js";
 import { reactiveSource } from "octagonal-wheels/dataobject/reactive";
 import {
   runWithOptionalActivity
 } from "../../interfaces/AsyncActivityRunner.js";
+import { CAPABILITY_SUPPORT_KINDS } from "../../replication/ProviderCapability.js";
+import {
+  ActiveReplicatorState
+} from "./ReplicatorService.activeReplicatorState.js";
+import { resolveRemoteResource } from "./ReplicatorService.remoteResourceResolver.js";
+import { runCentralRemoteAdministrationWithContext } from "./ReplicatorService.centralRemoteAdministration.js";
+import { asCopy } from "../../common/utils.object.js";
 class ReplicatorService extends ServiceBase {
   constructor(context, dependencies) {
     super(context);
@@ -23,11 +29,11 @@ class ReplicatorService extends ServiceBase {
     this.databaseEventService = dependencies.databaseEventService;
     if (dependencies.registerLifecycleHandlers ?? true) {
       this.settingService.onRealiseSetting.addHandler(this._initialiseReplicator.bind(this));
-      this.databaseEventService.onResetDatabase.addHandler(this.disposeReplicator.bind(this));
-      this.databaseEventService.onDatabaseInitialisation.addHandler(this.disposeReplicator.bind(this));
+      this.databaseEventService.onDatabaseInitialisation.addHandler(this.onCloseActiveReplication.bind(this));
       this.databaseEventService.onDatabaseInitialised.addHandler(this.reinitialiseReplicator.bind(this));
       this.databaseEventService.onDatabaseHasReady.addHandler(this.reinitialiseReplicator.bind(this));
       this.appLifecycleService.onSuspending.addHandler(this.suspendReplication.bind(this));
+      this.appLifecycleService.onUnload.addHandler(this.onCloseActiveReplication.bind(this));
     }
   }
   dependencies;
@@ -36,8 +42,9 @@ class ReplicatorService extends ServiceBase {
   _log = createInstanceLogFunction("ReplicatorService");
   settingService;
   databaseEventService;
-  _activeReplicator;
-  _replicatorType;
+  _activeReplicatorState = new ActiveReplicatorState();
+  _providerDefinitions = /* @__PURE__ */ new Map();
+  _transition = Promise.resolve();
   appLifecycleService;
   _unresolvedErrorManager;
   /**
@@ -65,32 +72,68 @@ class ReplicatorService extends ServiceBase {
       this.boundedRemoteActivityCount.value--;
     }
   }
-  suspendReplication() {
-    const activeReplicator = this._activeReplicator;
-    if (activeReplicator) {
-      activeReplicator.closeReplication();
-    }
-    return Promise.resolve(true);
+  /** Request a reversible transfer stop without retiring the active publication. */
+  async suspendReplication() {
+    return await this.enqueueTransition(async () => {
+      const publication = this._activeReplicatorState.current;
+      if (publication) {
+        await this.requestPublicationTransferStop(publication, "suspension");
+      }
+      return true;
+    });
   }
   async reinitialiseReplicator() {
-    await this.disposeReplicator();
-    await yieldMicrotask();
-    return this._initialiseReplicator();
+    return await this.enqueueTransition(async () => {
+      await this.disposeReplicatorNow();
+      await yieldMicrotask();
+      return await this.initialiseReplicatorNow();
+    });
   }
-  async disposeReplicator() {
-    this._log("Detect database reset, closing active replicator if exists.");
-    if (this._activeReplicator) {
-      await Promise.resolve(this._activeReplicator.closeReplication());
+  /** Request transfer cancellation for either a reversible pause or terminal retirement. */
+  async requestPublicationTransferStop(publication, reason) {
+    try {
+      const capability = publication.context?.provider.stopActiveTransfer;
+      if (capability?.kind === CAPABILITY_SUPPORT_KINDS.SUPPORTED) {
+        const outcome = await capability.run(publication.replicator);
+        if (outcome.status !== "completed") {
+          this._log(
+            `Active Replicator transfer stop settled as '${outcome.status}' during ${reason}.`,
+            LOG_LEVEL_VERBOSE
+          );
+        }
+        return;
+      }
+      if (!publication.context) {
+        await Promise.resolve(publication.replicator.terminateSync());
+      }
+    } catch (error) {
+      this._log(`Failed to request active Replicator transfer cancellation during ${reason}.`, LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
     }
-    this._activeReplicator = void 0;
-    this._replicatorType = void 0;
+  }
+  /** Fence new work, request cancellation, and drain only this publication's admitted tasks. */
+  async quiesceActiveReplicator() {
+    const retirement = this._activeReplicatorState.beginRetirement();
+    if (!retirement) return void 0;
+    await this.requestPublicationTransferStop(retirement.publication, "retirement");
+    await retirement.waitForDemandSettlement();
+    return retirement;
+  }
+  /** Close one drained publication and release its private retirement state. */
+  async closeRetiringReplicator(retirement) {
+    await Promise.resolve(retirement.publication.replicator.closeReplication());
+    retirement.complete();
+  }
+  async disposeReplicatorNow(reason) {
+    const retirement = await this.quiesceActiveReplicator();
+    if (!retirement) return true;
+    this._log(
+      reason === "configuration transition" ? "Configuration changed, closing active replicator." : "Closing active replicator."
+    );
+    await this.closeRetiringReplicator(retirement);
     return true;
   }
   async discardFailedReplicator(replicator) {
-    if (this._activeReplicator === replicator) {
-      this._activeReplicator = void 0;
-      this._replicatorType = void 0;
-    }
     try {
       await Promise.resolve(replicator.closeReplication());
     } catch (error) {
@@ -98,44 +141,82 @@ class ReplicatorService extends ServiceBase {
       this._log(error, LOG_LEVEL_VERBOSE);
     }
   }
+  enqueueTransition(operation) {
+    const transition = this._transition.then(operation, operation);
+    this._transition = transition.then(
+      () => void 0,
+      () => void 0
+    );
+    return transition;
+  }
   async _initialiseReplicator() {
+    return await this.enqueueTransition(() => this.initialiseReplicatorNow());
+  }
+  getProviderDefinition(setting) {
+    return this._providerDefinitions.get(setting.remoteType);
+  }
+  async createReplicator(settingOverride = {}) {
+    const currentSettings = this.settingService.currentSettings();
+    const setting = { ...currentSettings, ...settingOverride };
+    return await this.createReplicatorForSetting(setting, settingOverride);
+  }
+  async createReplicatorForSetting(setting, legacySettingOverride = {}) {
+    const provider = this.getProviderDefinition(setting);
+    if (provider) {
+      return await provider.create(setting);
+    }
+    return await this.legacyGetNewReplicator(legacySettingOverride);
+  }
+  isCurrentProviderConfiguration(provider, configurationIdentity) {
+    const currentSetting = this.settingService.currentSettings();
+    return !!currentSetting && this.getProviderDefinition(currentSetting) === provider && provider.isConfigured(currentSetting) && provider.configurationIdentity(currentSetting) === configurationIdentity;
+  }
+  publishActiveReplicator(provider, replicator, replicatorType, configurationIdentity) {
+    this._activeReplicatorState.publish(provider, replicator, replicatorType, configurationIdentity);
+  }
+  async initialiseReplicatorNow() {
     const message = this.context.translate("Replicator.Message.InitialiseFatalError");
     const setting = this.settingService.currentSettings();
     if (!setting) {
-      this._activeReplicator = void 0;
-      this._replicatorType = void 0;
+      await this.disposeReplicatorNow("configuration transition");
       this._unresolvedErrorManager.clearError(message);
       return true;
     }
     const replicatorType = setting.remoteType;
-    const isCouchDBConfigured = replicatorType === RemoteTypes.REMOTE_COUCHDB && !!setting.couchDB_URI?.trim() && !!setting.couchDB_DBNAME?.trim();
-    const isMinioConfigured = replicatorType === RemoteTypes.REMOTE_MINIO && !!setting.endpoint?.trim() && !!setting.bucket?.trim();
-    const isP2PEnabled = replicatorType === RemoteTypes.REMOTE_P2P && setting.P2P_Enabled;
-    const hasReplicatorConfig = isCouchDBConfigured || isMinioConfigured || isP2PEnabled;
+    const provider = this.getProviderDefinition(setting);
+    let hasReplicatorConfig;
+    let configurationIdentity;
+    try {
+      hasReplicatorConfig = provider ? provider.isConfigured(setting) : this._providerDefinitions.size === 0;
+      configurationIdentity = provider && hasReplicatorConfig ? provider.configurationIdentity(setting) : void 0;
+    } catch (error) {
+      await this.disposeReplicatorNow("configuration transition");
+      this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
+      throw error;
+    }
     if (!hasReplicatorConfig) {
-      this._activeReplicator = void 0;
-      this._replicatorType = void 0;
+      await this.disposeReplicatorNow("configuration transition");
       this._unresolvedErrorManager.clearError(message);
       this._log("No remote replicator configuration found. Skipping replicator initialisation.");
       return true;
     }
-    if (replicatorType === this._replicatorType && this._activeReplicator) {
+    const activePublication = this._activeReplicatorState.current;
+    const isSameProvider = replicatorType === activePublication?.replicatorType && (!provider || activePublication.context?.provider === provider);
+    if (isSameProvider && (!provider || configurationIdentity === activePublication?.context?.configurationIdentity)) {
       this._unresolvedErrorManager.clearError(message);
       this._log("Active replicator has been kept", LOG_LEVEL_VERBOSE);
       return true;
     } else {
       this._log("Acquiring new replicator");
-      const newReplicator = await this.getNewReplicator();
+      await this.disposeReplicatorNow("configuration transition");
+      if (activePublication) {
+        this._log("Active replicator closed", LOG_LEVEL_VERBOSE);
+      }
+      const newReplicator = await this.createReplicatorForSetting(setting);
       if (!newReplicator) {
         this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
         return false;
       }
-      if (this._activeReplicator) {
-        await Promise.resolve(this._activeReplicator.closeReplication());
-        this._log("Active replicator closed", LOG_LEVEL_VERBOSE);
-      }
-      this._activeReplicator = newReplicator;
-      this._replicatorType = replicatorType;
       this.replicationStatics.value = { ...DEFAULT_REPLICATION_STATICS };
       await yieldMicrotask();
       try {
@@ -145,45 +226,143 @@ class ReplicatorService extends ServiceBase {
           this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
           return false;
         }
-        if (!await this.onReplicatorInitialised()) {
-          this._log("Failed to initialise the replicator, onReplicatorInitialised reported some problems.");
+        if (!await this.onBeforeReplicatorPublication()) {
+          this._log(
+            "Failed to initialise the replicator, onBeforeReplicatorPublication reported some problems."
+          );
           await this.discardFailedReplicator(newReplicator);
           this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
           return false;
         }
+        if (provider && (configurationIdentity === void 0 || !this.isCurrentProviderConfiguration(provider, configurationIdentity))) {
+          await this.discardFailedReplicator(newReplicator);
+          this._unresolvedErrorManager.clearError(message);
+          this._log(
+            "Discarded a replicator whose configuration changed before publication.",
+            LOG_LEVEL_VERBOSE
+          );
+          return true;
+        }
       } catch (error) {
         await this.discardFailedReplicator(newReplicator);
         this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
         throw error;
       }
-      const remoteTypeDisplay = replicatorType === RemoteTypes.REMOTE_COUCHDB ? "CouchDB" : replicatorType;
+      this.publishActiveReplicator(provider, newReplicator, replicatorType, configurationIdentity);
+      const remoteTypeDisplay = provider?.diagnosticName ?? (replicatorType || "CouchDB");
       this._log(`Replicator (${remoteTypeDisplay}) initialised and activated`, LOG_LEVEL_VERBOSE);
       this._unresolvedErrorManager.clearError(message);
       return true;
     }
   }
   /**
-   * Close the active replication if any.
-   * Not used currently.
+   * Fence new work, drain admitted work, and close the active Replicator.
+   *
+   * The command is serialised with every other ownership transition. Callers
+   * must not await it from inside `runWithActiveReplicatorContext()`, because
+   * retirement waits for that admitted callback to settle.
    */
-  onCloseActiveReplication = handlers().anySuccess("onCloseActiveReplication");
+  async onCloseActiveReplication() {
+    return await this.enqueueTransition(() => this.disposeReplicatorNow());
+  }
   /**
    * Get a new replicator instance based on the provided settings.
    */
-  getNewReplicator = handlers().firstResult("getNewReplicator");
-  onReplicatorInitialised = handlers().bailFirstFailure("onReplicatorInitialised");
+  legacyGetNewReplicator = firstResultFunction("getNewReplicator");
+  getNewReplicator = Object.assign(
+    async (settingOverride = {}) => await this.createReplicator(settingOverride),
+    {
+      addHandler: (callback) => this.legacyGetNewReplicator.addHandler(callback),
+      removeHandler: (callback) => this.legacyGetNewReplicator.removeHandler(callback)
+    }
+  );
+  registerReplicatorProviderDefinitions(definitions) {
+    for (const [kind, definition] of definitions) {
+      const existing = this._providerDefinitions.get(kind);
+      if (existing && existing !== definition) {
+        throw new Error(`Replicator provider '${kind}' is already composed.`);
+      }
+      this._providerDefinitions.set(kind, definition);
+    }
+  }
+  /**
+   * Return a non-owning synchronous view for lifecycle diagnostics and focused tests.
+   *
+   * Production work must use an admitted acquisition or callback boundary so that
+   * the context cannot be retired while it is in use.
+   */
+  inspectActiveReplicatorContext() {
+    return this._activeReplicatorState.current?.context;
+  }
+  async createRemoteResource(kind, setting) {
+    const provider = this.getProviderDefinition(setting);
+    if (!provider || !provider.isConfigured(setting)) {
+      return void 0;
+    }
+    return await resolveRemoteResource(provider.remoteResources, kind, setting);
+  }
+  /** Apply and verify one provider-declared action before permitting a later switch. */
+  async runCentralRemoteAdministration(request) {
+    const setting = asCopy(this.settingService.currentSettings());
+    const result = await this.runWithActiveReplicatorContext(
+      (context) => runCentralRemoteAdministrationWithContext(context, setting, request)
+    );
+    return result ?? await runCentralRemoteAdministrationWithContext(void 0, setting, request);
+  }
+  async acquireActiveReplicatorContext() {
+    while (true) {
+      const transition = this._transition;
+      await transition;
+      if (transition === this._transition) {
+        return this._activeReplicatorState.current?.context;
+      }
+    }
+  }
+  /**
+   * Admit one callback against the publication ordered before later transitions.
+   *
+   * Release never enters the transition queue. The callback must not initiate
+   * or await a settings, database, or Replicator lifecycle transition which
+   * would wait for this same reservation.
+   */
+  async runWithActiveReplicatorContext(task) {
+    const reservation = await this.enqueueTransition(async () => this._activeReplicatorState.reserve());
+    if (!reservation) return void 0;
+    try {
+      return await task(reservation.context);
+    } finally {
+      reservation.release();
+    }
+  }
+  onBeforeReplicatorPublication = handlers().bailFirstFailure(
+    "onBeforeReplicatorPublication"
+  );
   /**
-   * Get the currently active replicator instance.
-   * If no active replicator, return undefined but that is the fatal situation (on Obsidian).
+   * Return the legacy unreserved view of the active Replicator.
+   *
+   * Missing active state retains its established Notice-level diagnostic.
+   * New work must acquire or admit an `ActiveReplicatorContext` instead.
    */
   getActiveReplicator() {
     const message = "No replicator has been activated or has not been initialised yet.";
-    if (!this._activeReplicator) {
+    const activeReplicator = this._activeReplicatorState.current?.replicator;
+    if (!activeReplicator) {
       this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
       return void 0;
     }
     this._unresolvedErrorManager.clearError(message);
-    return this._activeReplicator;
+    return activeReplicator;
+  }
+  /**
+   * Classify whether a compatibility active Replicator exists without
+   * acquiring or returning it.
+   *
+   * This side-effect-free, non-owning predicate exists only for
+   * compatibility-state classification. Work must acquire or admit an
+   * `ActiveReplicatorContext` before using a Replicator.
+   */
+  hasActiveReplicator() {
+    return this._activeReplicatorState.current !== void 0;
   }
   replicationStatics = reactiveSource({ ...DEFAULT_REPLICATION_STATICS });
 }

package/dist/services/base/ReplicatorService.remoteResourceResolver.d.ts

@@ -0,0 +1,4 @@
+import type { RemoteDBSettings } from "../../common/types.js";
+import type { RemoteResourceCapabilities, RemoteResourceKind, RemoteResourceMap } from "../../replication/RemoteResource.js";
+/** Resolve one ReplicatorService-owned finite resource without adding a method per role. */
+export declare function resolveRemoteResource<TKind extends RemoteResourceKind>(capabilities: RemoteResourceCapabilities, kind: TKind, setting: RemoteDBSettings): Promise<RemoteResourceMap[TKind] | undefined>;

package/dist/services/base/ReplicatorService.remoteResourceResolver.js

@@ -0,0 +1,11 @@
+import { CAPABILITY_SUPPORT_KINDS } from "../../replication/ProviderCapability.js";
+async function resolveRemoteResource(capabilities, kind, setting) {
+  const capability = capabilities[kind];
+  if (capability.kind !== CAPABILITY_SUPPORT_KINDS.SUPPORTED) {
+    return void 0;
+  }
+  return await capability.run(setting);
+}
+export {
+  resolveRemoteResource
+};

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

@@ -1,4 +1,4 @@
-import type { RemoteDBSettings, RemotePreferredTweakResult, TweakValues } from "../../common/types.js";
+import type { ObsidianLiveSyncSettings, RemoteDBSettings, RemotePreferredTweakResult, TweakValues } from "../../common/types.js";
 import type { ITweakValueService } from "./IService.js";
 import { ServiceBase, type ServiceContext } from "./ServiceBase.js";
 /**
@@ -18,8 +18,9 @@ export declare abstract class TweakValueService<T extends ServiceContext = Servi
     /**
      * Ask the user to resolve any mismatched tweak values.
      * @param preferredSource The preferred tweak values to resolve against.
+     * @param updatePreferredRemote Optional exact-context writer supplied by the failed operation.
      */
-    abstract askResolvingMismatched(preferredSource: TweakValues): Promise<"OK" | "CHECKAGAIN" | "IGNORE">;
+    abstract askResolvingMismatched(preferredSource: TweakValues, updatePreferredRemote?: (setting: ObsidianLiveSyncSettings) => Promise<boolean>): Promise<"OK" | "CHECKAGAIN" | "IGNORE">;
     /**
      * Check and ask the user to use the remote configuration.
      * @param settings The remote database settings to connect.

package/dist/services/implements/injectable/InjectableTweakValueService.d.ts

@@ -3,7 +3,7 @@ import { TweakValueService } from "../../base/TweakValueService.js";
 export declare class InjectableTweakValueService<T extends ServiceContext> extends TweakValueService<T> {
     fetchRemotePreferred: import("../../lib/HandlerUtils.js").HandlerFunction<(trialSetting: import("../../../settings.js").RemoteDBSettings) => Promise<import("../../../common/types.js").RemotePreferredTweakResult>, unknown>;
     checkAndAskResolvingMismatched: import("../../lib/HandlerUtils.js").HandlerFunction<(preferred: Partial<import("../../../common/types.js").TweakValues>) => Promise<[import("../../../common/types.js").TweakValues | boolean, boolean]>, unknown>;
-    askResolvingMismatched: import("../../lib/HandlerUtils.js").HandlerFunction<(preferredSource: import("../../../common/types.js").TweakValues) => Promise<"OK" | "CHECKAGAIN" | "IGNORE">, unknown>;
+    askResolvingMismatched: import("../../lib/HandlerUtils.js").HandlerFunction<(preferredSource: import("../../../common/types.js").TweakValues, updatePreferredRemote?: (setting: import("../../../settings.js").ObsidianLiveSyncSettings) => Promise<boolean>) => Promise<"OK" | "CHECKAGAIN" | "IGNORE">, unknown>;
     checkAndAskUseRemoteConfiguration: import("../../lib/HandlerUtils.js").HandlerFunction<(settings: import("../../../settings.js").RemoteDBSettings) => Promise<{
         result: false | import("../../../common/types.js").TweakValues;
         requireFetch: boolean;

package/dist/services/lib/HandlerUtils.d.ts

@@ -182,6 +182,22 @@ export declare class AllHandler<T extends unknown[]> extends BooleanHandlerBase<
      */
     invoke(...args: T): Promise<boolean>;
 }
+/**
+ * A handler that invokes every added handler sequentially and reports whether
+ * all of them succeeded.
+ *
+ * Unlike {@link AllHandler}, a failure does not prevent later cleanup handlers
+ * from settling.
+ */
+export declare class SettledAllHandler<T extends unknown[]> extends BooleanHandlerBase<T> {
+    /**
+     * Invokes every handler in order, treating a false result or an exception
+     * as an aggregate failure.
+     * @param args The arguments to pass to the handlers.
+     * @returns True only when every handler succeeds.
+     */
+    invoke(...args: T): Promise<boolean>;
+}
 /**
  * A handler that invokes all added handler functions in parallel and returns true only if all return true.
  */
@@ -316,6 +332,7 @@ export interface MultiBinderInstance<T extends unknown[], U> extends InvokableHa
 export interface BooleanMultiBinderInstance<T extends unknown[]> extends InvokableBooleanHandler<T>, MultiRegisterHandler<T, boolean> {
 }
 export declare function allFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
+export declare function allSettledFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
 export declare function bailFirstFailureFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
 export declare function allParallelFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
 export declare function anySuccessFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
@@ -333,6 +350,13 @@ export declare function handlers<T extends object>(): {
      * @returns
      */
     all<K extends FunctionKeys<T>>(name: K): BooleanMultipleHandlerFunction<Extract<T[K], (...args: any[]) => Promise<boolean>>>;
+    /**
+     * Create a handler that invokes every added handler sequentially and
+     * returns true only if all of them succeed.
+     * @param name
+     * @returns
+     */
+    allSettled<K extends FunctionKeys<T>>(name: K): BooleanMultipleHandlerFunction<Extract<T[K], (...args: any[]) => Promise<boolean>>>;
     /**
      * Create a handler that invokes all added handler functions in parallel and returns true only if all return true.
      * @param name

package/dist/services/lib/HandlerUtils.js

@@ -207,6 +207,31 @@ class AllHandler extends BooleanHandlerBase {
     return true;
   }
 }
+class SettledAllHandler extends BooleanHandlerBase {
+  /**
+   * Invokes every handler in order, treating a false result or an exception
+   * as an aggregate failure.
+   * @param args The arguments to pass to the handlers.
+   * @returns True only when every handler succeeds.
+   */
+  async invoke(...args) {
+    let succeeded = true;
+    const callbacks = [...this._callbacks];
+    for (const callback of callbacks) {
+      try {
+        const result = await Promise.resolve(callback(...args));
+        if (result === false) {
+          succeeded = false;
+        }
+      } catch (error) {
+        Logger(`SettledAllHandler ${this._name} treated error as failure!`, LOG_LEVEL_VERBOSE);
+        Logger(error, LOG_LEVEL_VERBOSE);
+        succeeded = false;
+      }
+    }
+    return succeeded;
+  }
+}
 class ParallelAllHandler extends BooleanHandlerBase {
   /**
    * Invoke all handlers in parallel
@@ -288,6 +313,10 @@ function allFunction(name) {
   const handler = new AllHandler(name ?? "handleAllFunc");
   return getMultipleBound(handler);
 }
+function allSettledFunction(name) {
+  const handler = new SettledAllHandler(name ?? "allSettledFunction");
+  return getMultipleBound(handler);
+}
 function bailFirstFailureFunction(name) {
   const handler = new AllHandler(name ?? "bailFirstFailureFunction");
   return getMultipleBound(handler);
@@ -336,6 +365,15 @@ function handlers() {
     all(name) {
       return allFunction(String(name));
     },
+    /**
+     * Create a handler that invokes every added handler sequentially and
+     * returns true only if all of them succeed.
+     * @param name
+     * @returns
+     */
+    allSettled(name) {
+      return allSettledFunction(String(name));
+    },
     /**
      * Create a handler that invokes all added handler functions in parallel and returns true only if all return true.
      * @param name
@@ -400,8 +438,10 @@ export {
   LazyBinder,
   MultiBinder,
   ParallelAllHandler,
+  SettledAllHandler,
   allFunction,
   allParallelFunction,
+  allSettledFunction,
   anySuccessFunction,
   bailFirstFailureFunction,
   bindableFunction,

package/docs/development.md

@@ -6,7 +6,8 @@ This document is for Commonlib developers. Package consumers should begin with t
 
 The source tree is larger than the supported package surface. Consumers may import only paths in the generated package export map:
 
-- `src/index.ts`, `src/context.ts`, `src/settings.ts`, `src/remoteConfigurations.ts`, `src/platform/browser/index.ts`, and `src/platform/node/index.ts` define the focused entries;
+- `src/index.ts`, `src/context.ts`, `src/settings.ts`, `src/remoteConfigurations.ts`, `src/p2p/index.ts`, `src/platform/browser/index.ts`, and `src/platform/node/index.ts` define the focused entries;
+- `src/replication/index.ts` defines the focused provider-capability and interaction contract for hosts which compose replication;
 - `src/rpc/index.ts` defines a transitional entry for the existing LiveSync P2P composition, not a stable Commonlib 1.0 contract;
 - `_tools/build-package.mjs` compiles those entries and creates the publishable manifest under `.package`;
 - `docs/migration/downstream-imports.json` is the reviewed inventory from which explicit `compat/*` exports are generated;
@@ -16,6 +17,29 @@ The source tree is larger than the supported package surface. Consumers may impo
 
 Files elsewhere under `src` are implementation details unless a focused entry re-exports them or the compatibility inventory names them. Do not use the source layout, TypeScript path aliases, or the presence of generated declarations as evidence of a supported consumer import.
 
+## Service composition and state ownership
+
+Commonlib uses four related forms of composition. Choose between them by ownership and dependency direction, not merely by whether an implementation has mutable state.
+
+- A **Service** is a long-lived contract in the Service Hub. Add a handler to an existing Service when the behaviour is a simple extension of that contract.
+- A **serviceFeature** is a typed composition function. It accepts only the Services and ServiceModules named by `NecessaryServices`, then registers handlers, commands, lifecycle bindings, or other host glue. It is not added to a runtime registry. A serviceFeature may return a focused view or controller, and may retain bounded private state when that state belongs only to the composed feature.
+- A **ServiceModule** is a long-lived stateful or resource-owning object constructed by the host and shared through the typed `ServiceModules` record. Use one when several consumers need the same operational capability or lifecycle, such as storage access, file handling, or database rebuilding. State alone does not make a ServiceModule necessary.
+- An **AbstractModule** is the legacy application module layer. Existing modules may continue to own application behaviour, but new composition should not acquire the broad core merely to gain lifecycle access or shared dependencies.
+
+When a feature needs state, separate the component which owns that state, its transitions, and its invariants from the code which connects it to application lifecycle events and downstream effects. Give the stateful component narrow collaborators or callbacks rather than the complete Service Hub or application core. Keep application-level handler registration and host-specific presentation in the surrounding serviceFeature. A handler or effect which is part of the state contract, such as querying unresolved errors or reporting their first occurrence, may remain inside the stateful component when its input and output ports are explicit and bounded.
+
+Existing features illustrate this direction:
+
+- `targetFilter.ts` keeps each cache or readiness gate inside the factory which owns the corresponding predicate. `useTargetFilters` composes those predicates and registers them in the required order.
+- `prepareDatabaseForUse.ts` keeps the initialisation sequence independently testable. `usePrepareDatabaseForUse` constructs its error manager and binds the operation to the database lifecycle.
+- the P2P composition keeps durable policy and room-session transitions in focused state owners, while `useP2PReplicatorFeature` connects those owners to Services and exposes narrow consumer views.
+
+Older code does not apply this boundary consistently. Improve it when changing the affected ownership or lifecycle; do not perform an unrelated mechanical conversion merely to change the abstraction name.
+
+Use interaction-based, London School unit tests at a serviceFeature boundary. Verify which collaborator is called, in which order, what is not called after a failure, and which handler receives the composed operation. Test the focused state owner separately for its transitions and invariants. If a unit test requires a broad core fixture, a deep chain of mocks, import-order substitution, or knowledge of unrelated services, stop and review the responsibility and dependency boundary before adding more test machinery. Difficulty writing a clean interaction test is a design-review signal, not a reason to expose more internals.
+
+See [Service feature composition](service-feature-composition.md) for the decision table, current examples, state-ownership rules, legacy Module boundary, and London School testing guidance.
+
 ## Local validation
 
 For a complete local package gate, run:
@@ -71,19 +95,28 @@ The one-shot CouchDB connectivity preflight is the first bounded consumer. It ap
 
 The active local database identity, settings-selected reset sequence, and lifecycle event phases are specified in [Local database lifecycle](database-lifecycle.md). Extend that document and the focused service and rebuild tests whenever database selection, reset ownership, event ordering, or failure propagation changes.
 
+### Replication control boundaries
+
+`ReplicationService` remains the host-facing façade for handler registration, legacy entry points, mutable counters, event rate limiting, full transfers, and rebuild maintenance. It delegates ordered readiness evaluation and typed provider dispatch to focused collaborators without moving the handler objects, changing their priority semantics, or taking active Replicator ownership from `ReplicatorService`.
+
+`evaluateReadiness` is a domain-neutral, ordered evaluator. Its input states the diagnostic purpose and supplies named conditions; applicable conditions run sequentially, the first rejection short-circuits later work, condition-specific rejection reporting completes before return, and callback exceptions propagate unchanged. `createReplicationReadinessEvaluator` supplies the Replication-specific condition list, including the conditional central-remote preparation gate. Add a new readiness requirement as a named condition with focused ordering and short-circuit tests rather than extending one compound boolean expression.
+
+`TypedReplicationCoordinator` keeps user-initiated, unattended, continuous, and stop roles as explicit control flows. Their interaction authority, readiness position, activity accounting, and failure handling differ, so these roles must not be collapsed into a flag-driven capability table. Share only mechanics whose lifecycle meaning is identical, such as atomic context acquisition and finite activity accounting, and retain a focused sequencing test for each role.
+
 ### P2P composition ownership
 
-`useP2PReplicatorFeature` is the sole owner of the active `LiveSyncTrysteroReplicator` and its lifecycle bindings. It creates or replaces the outer replicator when `ReplicatorService` requests one, closes the previous instance before replacement, shares an in-flight replacement between concurrent callers, and returns a stable result object whose `replicator` property resolves the current instance.
+`useP2PReplicatorFeature` composes one stable P2P service owner, one room-session owner, and their lifecycle bindings. The service exposes focused views, including owner-arbitrated connection-probe admission, over that same state. When `ReplicatorService` requests a P2P Replicator, the provider returns a fresh non-owning adapter. Replacing or disposing that active adapter does not cancel service-owned work or retire the room; the explicit stop capability and transport lifecycle view own those distinct operations. Database reset and explicit close reach the stable service through their pre-destruction lifecycle hooks, so non-ownership by the active adapter cannot leave a room using an unavailable local database.
+
+Every composed provider projects its effective connection settings to an opaque configuration identity. A changed identity replaces the active Replicator; there is no same-instance rebind branch. The projection follows provider-owned resource binding rather than the stored Setup URI grammar, and it remains private because it can contain credentials. `ReplicatorService` serialises those transitions, clears the old context before retirement, rechecks the candidate identity after asynchronous initialisation, and publishes the provider and Replicator together. Typed consumers use `acquireActiveReplicatorContext()` when they only need to wait for a queued transition, and `runWithActiveReplicatorContext()` when work must reserve the exact publication against later retirement.
 
-Consumers must preserve that result object and read `result.replicator` at the point of use. Do not destructure the property into a command, event handler, view, or other long-lived closure: a database reinitialisation or remote-type transition can close and replace the captured instance, and calling `open()` on that obsolete outer object can create a second connection outside the active service state.
+Consumers must request only the focused view which they need. Commands which connect or disconnect consume `transportLifecycle`; P2P Setup consumes `connectionProbe`; peer lists consume `peerDirectory`; RTC inspection consumes `diagnostics`. Ordinary consumers must not receive a raw room, raw host, or concrete Replicator. The result's `replicator` property is a deprecated compatibility façade for panes which have not yet migrated, not the active provider adapter.
 
 The similarly named compositions have narrower roles:
 
-- `useP2PReplicatorCommands` adds host commands and resolves the current instance when a command is checked or invoked;
-- host UI features add views, status presentation, and injected peer-selection callbacks without owning the replicator lifecycle; and
-- the deprecated `useP2PReplicator` entry is a compatibility composition which delegates ownership to `useP2PReplicatorFeature`.
+- `useP2PReplicatorCommands` adds host commands against the transport lifecycle view;
+- host UI features add views, status presentation, and injected peer-selection callbacks without owning the replicator lifecycle.
 
-When registering P2P event handlers for a replaceable instance, pass a provider to `addP2PEventHandlers`. Passing a fixed instance remains supported only for compositions whose instance cannot change. Extend the focused feature, command, event-hub, and compatibility-wrapper tests whenever this ownership boundary changes.
+The compatibility event bridge delegates lifecycle and status requests to the stable service while remaining panes migrate. Peer arrival and departure are handled inside their originating room session; the global peer events remain observational and are not routed into the current session. Do not add another consumer to the compatibility bridge. Extend the focused feature, command, session-fencing, and event-hub tests whenever this ownership boundary changes.
 
 The physical room, WebRTC peer, and relay-socket boundaries are documented in [P2P transport lifecycle](p2p-transport-lifecycle.md). In particular, normal shutdown leaves the Trystero room without closing raw peer connections directly.