@vrtmrz/livesync-commonlib 0.1.19 → 0.1.20

package/dist/rpc/types.d.ts

@@ -9,6 +9,29 @@ export type RpcErrorShape = {
     message: string;
     details?: JsonLike;
 };
+/**
+ * Options which control one outbound RPC invocation.
+ *
+ * The numeric timeout overload remains supported by {@link RpcSession.call}
+ * and {@link RpcRoom.invoke}; use this object when a caller also needs an
+ * abort signal.
+ */
+export type RpcCallOptions = {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+};
+/**
+ * Context supplied to handlers registered through the cancellation-aware
+ * registration API.
+ *
+ * Cancellation is cooperative: the handler must observe `signal.aborted` or
+ * otherwise pass the signal to an abort-capable operation. The RPC layer still
+ * suppresses a response after cancellation when a handler does not stop
+ * immediately.
+ */
+export type RpcRequestContext = {
+    readonly signal: AbortSignal;
+};
 export type RpcRequestEnvelope = {
     kind: "request";
     requestId: string;
@@ -66,10 +89,12 @@ export type RpcRoomOptions = {
     transport: TransportAdapter;
     maxWirePayloadBytes?: number;
     chunkMissingRetryMs?: number;
-    canAcceptRequest?: (peerId: string, method: string) => boolean | Promise<boolean>;
+    canAcceptRequest?: (peerId: string, method: string, context: RpcRequestContext) => boolean | Promise<boolean>;
     onProtocolWarning?: (message: string, peerId?: string) => void;
 };
 export type RpcMethodHandler<T extends JsonLike[], U> = (peerId: string, ...args: T) => U | Promise<U>;
+/** Handler which can stop cooperative work when its request is cancelled. */
+export type RpcCancellationAwareMethodHandler<T extends JsonLike[], U> = (context: RpcRequestContext, peerId: string, ...args: T) => U | Promise<U>;
 export type RpcRegisterOptions = {
     serial?: boolean;
 };

package/dist/serviceFeatures/checkRemoteSize.js

@@ -4,6 +4,9 @@ import { createInstanceLogFunction } from "../services/lib/logUtils.js";
 import { EVENT_REQUEST_CHECK_REMOTE_SIZE } from "../events/coreEvents.js";
 import { fireAndForget } from "../common/utils.js";
 const REMOTE_SIZE_NOTICE_DURATION_MS = 5 * 60 * 1e3;
+function canReadRemoteStatus(replicator) {
+  return replicator !== void 0 && "getRemoteStatus" in replicator && typeof replicator.getRemoteStatus === "function";
+}
 function configureReviewAnchor(anchor, label, review) {
   anchor.href = "#";
   anchor.textContent = label;
@@ -84,13 +87,13 @@ function onNotifyRemoteSizeExceedFactory(host, log, mode = "notice") {
       return true;
     }
     const replicator = host.services.replicator.getActiveReplicator();
-    const remoteStat = await replicator?.getRemoteStatus(host.services.setting.currentSettings());
+    const remoteStat = canReadRemoteStatus(replicator) ? await replicator.getRemoteStatus(settings) : false;
     if (!remoteStat) {
       log("Failed to get remote status, skipping remote size exceed check.", LOG_LEVEL_INFO);
       return true;
     }
     const estimatedSize = remoteStat.estimatedSize;
-    if (estimatedSize) {
+    if (estimatedSize !== void 0) {
       const maxSize = settings.notifyThresholdOfRemoteStorageSize * 1024 * 1024;
       if (estimatedSize <= maxSize) {
         log(

package/dist/serviceModules/Rebuilder.js

@@ -10,8 +10,12 @@ import { getConfiguredFunctionsForEncryption } from "../pouchdb/encryption.js";
 import { AuthorizationHeaderGenerator, generateCredentialObject } from "../replication/httplib.js";
 import { parseHeaderValues } from "../common/utils.js";
 import { sizeToHumanReadable } from "octagonal-wheels/number";
+import { REMOTE_RESOURCE_KINDS } from "../replication/index.js";
 const FAST_FETCH_CHECKPOINT_KEY = "fast-fetch-checkpoint";
 const FAST_FETCH_RETRY_DELAYS = [2e3, 5e3, 1e4, 2e4];
+function canResetCentralRemote(replicator) {
+  return "tryResetRemoteDatabase" in replicator && typeof replicator.tryResetRemoteDatabase === "function";
+}
 class ServiceRebuilder extends ServiceModuleBase {
   events;
   appLifecycle;
@@ -180,6 +184,9 @@ Please enable them from the settings screen after setup is complete.`,
       this._log("No active replicator found when trying to reset remote database.", LOG_LEVEL_NOTICE);
       return;
     }
+    if (!canResetCentralRemote(currentReplicator)) {
+      throw new Error("The active replicator does not support resetting a central remote database.");
+    }
     await currentReplicator.tryResetRemoteDatabase(settings);
   }
   // private async _tryCreateRemoteDatabase(): Promise<void> {
@@ -397,67 +404,70 @@ Are you sure you wish to proceed?`;
       localDB = this.database.localDatabase.localDatabase;
       since = "0";
     }
-    const replicator = this.replicator.getActiveReplicator() ?? await this.replicator.getNewReplicator();
-    if (!replicator) {
-      throw new Error("No active replicator found for fast fetch.");
+    const securitySeed = await this.replicator.createRemoteResource(REMOTE_RESOURCE_KINDS.SECURITY_SEED, settings);
+    if (!securitySeed) {
+      throw new Error("The selected provider cannot supply a Security Seed for Fast Fetch.");
     }
-    const salt = () => replicator.getReplicationPBKDF2Salt(settings);
-    const enc = getConfiguredFunctionsForEncryption(
-      settings.passphrase,
-      false,
-      false,
-      salt,
-      settings.E2EEAlgorithm
-    );
-    const authHeader = await new AuthorizationHeaderGenerator().getAuthorizationHeader(
-      generateCredentialObject(settings)
-    );
-    const customHeaders = parseHeaderValues(settings.couchDB_CustomHeaders);
-    for (let attempt = 0; ; attempt++) {
-      try {
-        await fetchChangesForInitialSync(
-          localDB,
-          remote,
-          authHeader,
-          enc.outgoing,
-          since,
-          (progress) => {
-            this._log(
-              `Fast fetch progress: ${progress.totalValidFetched} / ${progress.docsToFetch}
+    try {
+      const enc = getConfiguredFunctionsForEncryption(
+        settings.passphrase,
+        false,
+        false,
+        () => securitySeed.read(),
+        settings.E2EEAlgorithm
+      );
+      const authHeader = await new AuthorizationHeaderGenerator().getAuthorizationHeader(
+        generateCredentialObject(settings)
+      );
+      const customHeaders = parseHeaderValues(settings.couchDB_CustomHeaders);
+      for (let attempt = 0; ; attempt++) {
+        try {
+          await fetchChangesForInitialSync(
+            localDB,
+            remote,
+            authHeader,
+            enc.outgoing,
+            since,
+            (progress) => {
+              this._log(
+                `Fast fetch progress: ${progress.totalValidFetched} / ${progress.docsToFetch}
 Total bytes fetched: ${sizeToHumanReadable(progress.totalBytes)}`,
-              LOG_LEVEL_NOTICE,
-              "fetch-init-progress"
-            );
-          },
-          (sequence) => this.saveFastFetchCheckpoint(remote, sequence),
-          customHeaders
-        );
-        break;
-      } catch (ex) {
-        if (!isRetryableStreamingFetchFailure(ex) || attempt >= FAST_FETCH_RETRY_DELAYS.length) throw ex;
-        checkpoint = this.getFastFetchCheckpoint(remote);
-        since = checkpoint?.sequence ?? since;
-        this._log(
-          `Fast fetch interrupted. Retrying from sequence: ${since}`,
-          LOG_LEVEL_NOTICE,
-          "fetch-init-resume"
-        );
-        await delay(FAST_FETCH_RETRY_DELAYS[attempt]);
+                LOG_LEVEL_NOTICE,
+                "fetch-init-progress"
+              );
+            },
+            (sequence) => this.saveFastFetchCheckpoint(remote, sequence),
+            customHeaders
+          );
+          break;
+        } catch (ex) {
+          if (!isRetryableStreamingFetchFailure(ex) || attempt >= FAST_FETCH_RETRY_DELAYS.length) throw ex;
+          checkpoint = this.getFastFetchCheckpoint(remote);
+          since = checkpoint?.sequence ?? since;
+          this._log(
+            `Fast fetch interrupted. Retrying from sequence: ${since}`,
+            LOG_LEVEL_NOTICE,
+            "fetch-init-resume"
+          );
+          await delay(FAST_FETCH_RETRY_DELAYS[attempt]);
+        }
       }
-    }
-    const allDocs = await localDB.allDocs({ include_docs: false });
-    this._log(
-      `Fast database fetch completed. Total documents in local database: ${allDocs.total_rows}`,
-      LOG_LEVEL_NOTICE,
-      "fetch-init-complete"
-    );
-    await this.replication.markResolved();
-    if (autoResume) {
-      if (!await this.finishRebuild()) {
-        throw new Error("Fast Fetch could not be finalised.");
+      const allDocs = await localDB.allDocs({ include_docs: false });
+      this._log(
+        `Fast database fetch completed. Total documents in local database: ${allDocs.total_rows}`,
+        LOG_LEVEL_NOTICE,
+        "fetch-init-complete"
+      );
+      await this.replication.markResolved();
+      if (autoResume) {
+        if (!await this.finishRebuild()) {
+          throw new Error("Fast Fetch could not be finalised.");
+        }
       }
+      this.clearFastFetchCheckpoint();
+    } finally {
+      await securitySeed.dispose();
     }
-    this.clearFastFetchCheckpoint();
   }
   /**
    * Complete the final rebuild phases and establish application readiness.

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

@@ -65,6 +65,9 @@ export declare abstract class AppLifecycleService<T extends ServiceContext = Ser
     readonly onBeforeUnload: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<() => Promise<boolean>>;
     /**
      * Event triggered when the plug-in is being unloaded.
+     *
+     * Resource owners complete terminal retirement here. `ControlService`
+     * awaits every handler before it closes the local database.
      */
     readonly onUnload: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<() => Promise<boolean>>;
     /**
@@ -85,6 +88,7 @@ export declare abstract class AppLifecycleService<T extends ServiceContext = Ser
     abstract scheduleRestart(): void;
     /**
      * Event triggered when the application is being suspended (e.g., system sleep).
+     * Suspension is reversible and is not equivalent to terminal unload.
      */
     readonly onSuspending: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<() => Promise<boolean>>;
     /**

package/dist/services/base/AppLifecycleService.js

@@ -62,10 +62,14 @@ class AppLifecycleService extends ServiceBase {
   onBeforeUnload = handlers().all("onBeforeUnload");
   /**
    * Event triggered when the plug-in is being unloaded.
+   *
+   * Resource owners complete terminal retirement here. `ControlService`
+   * awaits every handler before it closes the local database.
    */
   onUnload = handlers().all("onUnload");
   /**
    * Event triggered when the application is being suspended (e.g., system sleep).
+   * Suspension is reversible and is not equivalent to terminal unload.
    */
   onSuspending = handlers().bailFirstFailure("onSuspending");
   /**

package/dist/services/base/ControlService.js

@@ -58,10 +58,6 @@ class ControlService extends ServiceBase {
     this._unloaded = true;
     const localDatabase = this.services.databaseService.localDatabaseDirect;
     if (localDatabase != null) {
-      const activeReplicator = this.services.replicatorService.getActiveReplicator();
-      if (activeReplicator) {
-        activeReplicator.closeReplication();
-      }
       localDatabase.onunload();
       await localDatabase.close();
     }

package/dist/services/base/DatabaseEventService.js

@@ -8,7 +8,7 @@ class DatabaseEventService extends ServiceBase {
   /**
    * Event triggered when the database is about to be closed.
    */
-  onCloseDatabase = handlers().all("onCloseDatabase");
+  onCloseDatabase = handlers().allSettled("onCloseDatabase");
   /**
    * Event triggered when the database is being initialized.
    */

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

@@ -2,7 +2,7 @@ import type { FetchHttpHandler } from "@smithy/fetch-http-handler";
 import { type LOG_LEVEL } from "octagonal-wheels/common/logger";
 import type { AnyEntry, AUTO_MERGED, CouchDBCredentials, diff_result, DocumentID, EntryDoc, EntryHasPath, FileEventItem, FilePath, FilePathWithPrefix, LoadedEntry, MetaEntry, MISSING_OR_ERROR, ObsidianLiveSyncSettings, RemoteDBSettings, RemotePreferredTweakResult, SettingsMigrationState, TweakValues, UXFileInfo, UXFileInfoStub } from "../../common/types.js";
 import type { LiveSyncLocalDB } from "../../pouchdb/LiveSyncLocalDB.js";
-import type { LiveSyncAbstractReplicator } from "../../replication/LiveSyncAbstractReplicator.js";
+import type { ReplicatorInstance } from "../../replication/ReplicatorInstance.js";
 import type { SimpleStore } from "octagonal-wheels/databases/SimpleStoreBase";
 import type { Confirm } from "../../interfaces/Confirm.js";
 import type { ReactiveSource } from "octagonal-wheels/dataobject/reactive";
@@ -12,6 +12,10 @@ import type { DatabaseEventService } from "./DatabaseEventService.js";
 import type { BASE_IS_NEW, EVEN, TARGET_IS_NEW } from "../../common/models/shared.const.symbols.js";
 import type { AsyncActivityOptions } from "../../interfaces/AsyncActivityRunner.js";
 import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "./RemoteConnection.js";
+import type { ActiveReplicatorContext, ContinuousReplicationRequest, ReplicationAttemptFailure, ReplicationFailureRequest, ReplicatorProviderDefinitionMap, ReplicationOutcome, ReplicationReadinessRequirements, UnattendedOneShotRequest, UserInitiatedOneShotRequest } from "../../replication/ReplicatorProvider.js";
+import type { RemoteResourceKind, RemoteResourceMap } from "../../replication/RemoteResource.js";
+import type { CentralRemoteAdministrationRequest, CentralRemoteAdministrationResult } from "../../replication/CentralRemoteAdministration.js";
+import type { MultipleHandlerFunction } from "../lib/HandlerUtils.js";
 declare global {
     interface OPTIONAL_SYNC_FEATURES {
         DISABLE: "DISABLE";
@@ -99,10 +103,63 @@ export interface IFileProcessingService {
     onStorageFileEvent(): void;
 }
 export interface IReplicatorService {
+    /**
+     * Fence new work, drain admitted work, and close the active Replicator.
+     *
+     * Do not await this command from an admitted active-context callback: the
+     * retirement command waits for that callback to settle.
+     */
     onCloseActiveReplication(): Promise<boolean>;
-    onReplicatorInitialised(): Promise<boolean>;
-    getNewReplicator(settingOverride?: Partial<ObsidianLiveSyncSettings>): Promise<LiveSyncAbstractReplicator | undefined | false>;
-    getActiveReplicator(): LiveSyncAbstractReplicator | undefined;
+    /**
+     * Run host preparation after candidate initialisation and before active publication.
+     *
+     * This hook runs inside the ownership transition. A handler must not call or await
+     * `acquireActiveReplicatorContext()` or `runWithActiveReplicatorContext()`, because
+     * both wait for that same transition. Work which requires the new active context
+     * belongs after publication.
+     */
+    onBeforeReplicatorPublication(): Promise<boolean>;
+    getNewReplicator: ReplicatorFactoryHandler;
+    /** Add the fixed provider definitions composed by the current host. */
+    registerReplicatorProviderDefinitions(definitions: ReplicatorProviderDefinitionMap): void;
+    /** Resolve one provider-owned finite resource without changing active publication. */
+    createRemoteResource<TKind extends RemoteResourceKind>(kind: TKind, setting: RemoteDBSettings): Promise<RemoteResourceMap[TKind] | undefined>;
+    /** Apply and verify one typed provider-specific central-remote administration action. */
+    runCentralRemoteAdministration(request: CentralRemoteAdministrationRequest): Promise<CentralRemoteAdministrationResult>;
+    /** Wait for queued ownership transitions, then return the published active context. */
+    acquireActiveReplicatorContext(): Promise<ActiveReplicatorContext | undefined>;
+    /**
+     * Run one task against an exact active publication admitted before later transitions.
+     *
+     * Invocation is ordered with replacement and disposal. A later
+     * transition fences new admission, requests transfer cancellation, waits for
+     * admitted tasks, and only then closes the old Replicator. The
+     * callback must not initiate or await settings realisation, database
+     * replacement, Replicator retirement, or another operation which queues that
+     * same lifecycle transition. Stage such recovery after this promise settles.
+     * Terminal plug-in unload uses the same retirement drain before the local
+     * database closes. Reversible host suspension only requests transfer
+     * cancellation and retains the publication, so it is not a retirement fence.
+     *
+     * The callback is not invoked when no typed publication can be admitted.
+     */
+    runWithActiveReplicatorContext<TResult>(task: (context: ActiveReplicatorContext) => TResult | PromiseLike<TResult>): Promise<TResult | undefined>;
+    /**
+     * Return the legacy unreserved view of the active Replicator.
+     *
+     * Missing active state retains its established diagnostic. New work must
+     * acquire or admit an `ActiveReplicatorContext` instead.
+     */
+    getActiveReplicator(): ReplicatorInstance | undefined;
+    /**
+     * Return 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(): boolean;
     replicationStatics: ReactiveSource<ReplicationStatics>;
     /** Number of finite remote operations currently in progress. */
     boundedRemoteActivityCount: ReactiveSource<number>;
@@ -113,19 +170,59 @@ export interface IReplicatorService {
     /** Runs finite replication which may place documents in the local database. */
     runFiniteReplicationActivity<T>(task: () => T | PromiseLike<T>, options?: AsyncActivityOptions): Promise<T>;
 }
+export type ReplicatorFactoryCallback = (settingOverride?: Partial<ObsidianLiveSyncSettings>) => Promise<ReplicatorInstance | undefined | false>;
+export type ReplicatorFactoryHandler = MultipleHandlerFunction<ReplicatorFactoryCallback>;
 export interface IReplicationService {
     processSynchroniseResult(doc: MetaEntry): Promise<boolean>;
     processOptionalSynchroniseResult(doc: LoadedEntry): Promise<boolean>;
     processVirtualDocument(docs: PouchDB.Core.ExistingDocument<EntryDoc>): Promise<boolean>;
     onBeforeReplicate(showMessage: boolean): Promise<boolean>;
-    checkConnectionFailure(): Promise<boolean | "CHECKAGAIN" | undefined>;
+    /** Prepare provider state which exists only for the central remote. */
+    onPrepareCentralRemoteReplication(showMessage: boolean): Promise<boolean>;
+    checkConnectionFailure(failure: ReplicationAttemptFailure): Promise<boolean | "CHECKAGAIN" | undefined>;
     /** Lightweight, idempotent policy checks which every replication entry point may invoke. */
     onCheckReplicationReady(showMessage: boolean): Promise<boolean>;
-    isReplicationReady(showMessage: boolean): Promise<boolean>;
+    /**
+     * Evaluate ordered host and provider readiness without acquiring a Replicator.
+     *
+     * The provider requirements determine whether central-remote preparation
+     * applies. A false result means no remote work has been admitted.
+     */
+    isReplicationReady(showMessage: boolean, readiness?: ReplicationReadinessRequirements): Promise<boolean>;
+    /**
+     * Run one user-initiated typed capability against an atomically acquired context.
+     *
+     * Readiness precedes finite activity, and failure recovery receives only
+     * the interaction authority carried by the request.
+     */
+    replicateUserInitiated(request?: UserInitiatedOneShotRequest): Promise<ReplicationOutcome>;
+    /**
+     * Run one unattended typed capability without granting interaction authority.
+     *
+     * Readiness precedes finite activity, and failed outcomes reach unattended
+     * recovery only after activity accounting has settled.
+     */
+    replicateUnattended(request: UnattendedOneShotRequest): Promise<ReplicationOutcome>;
+    /** Serialise and rate-limit an unattended event-triggered finite capability. */
+    replicateUnattendedByEvent(request: UnattendedOneShotRequest): Promise<ReplicationOutcome>;
+    /**
+     * Start a supported continuous capability after its provider-specific readiness.
+     *
+     * Applicability is checked before readiness. Continuous work is not wrapped
+     * as finite activity and does not use the finite-operation recovery handler.
+     */
+    startContinuous(request: ContinuousReplicationRequest): Promise<ReplicationOutcome>;
+    /**
+     * Stop finite transfer work on the current typed active Replicator.
+     *
+     * This operator action bypasses readiness, finite activity accounting, and
+     * failure-recovery handlers.
+     */
+    stopActiveTransfer(): Promise<ReplicationOutcome>;
     performReplication(showMessage?: boolean): Promise<boolean | void>;
     replicate(showMessage?: boolean): Promise<boolean | void>;
     replicateByEvent(showMessage?: boolean): Promise<boolean | void>;
-    onReplicationFailed(showMessage?: boolean): Promise<boolean>;
+    onReplicationFailed(request: ReplicationFailureRequest): Promise<boolean>;
     parseSynchroniseResult(docs: Array<PouchDB.Core.ExistingDocument<EntryDoc>>): Promise<boolean>;
     databaseQueueCount: ReactiveSource<number>;
     storageApplyingCount: ReactiveSource<number>;
@@ -238,7 +335,7 @@ export interface ISettingService {
 export interface ITweakValueService {
     fetchRemotePreferred(trialSetting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     checkAndAskResolvingMismatched(preferred: Partial<TweakValues>): Promise<[TweakValues | boolean, boolean]>;
-    askResolvingMismatched(preferredSource: TweakValues): Promise<"OK" | "CHECKAGAIN" | "IGNORE">;
+    askResolvingMismatched(preferredSource: TweakValues, updatePreferredRemote?: (setting: ObsidianLiveSyncSettings) => Promise<boolean>): Promise<"OK" | "CHECKAGAIN" | "IGNORE">;
     checkAndAskUseRemoteConfiguration(settings: RemoteDBSettings): Promise<{
         result: false | TweakValues;
         requireFetch: boolean;

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

@@ -0,0 +1,40 @@
+/** One ordered condition in a readiness evaluation. */
+export interface ReadinessCondition<TContext> {
+    /** Stable diagnostic name for the condition; it is not user-facing text. */
+    readonly name: string;
+    /**
+     * Return whether this condition applies to the current evaluation.
+     *
+     * Applicability checks must be side-effect-free. Conditions without this
+     * callback always apply.
+     */
+    readonly appliesTo?: (context: TContext) => boolean;
+    /** Return whether the condition admits the requested operation. */
+    readonly evaluate: (context: TContext) => boolean | Promise<boolean>;
+    /** Perform condition-specific reporting after a false result. */
+    readonly onRejected?: (context: TContext) => void | Promise<void>;
+}
+/** A purpose and its ordered readiness conditions. */
+export interface ReadinessEvaluationRequest<TContext> {
+    /** Stable diagnostic purpose; it is not user-facing text. */
+    readonly purpose: string;
+    readonly context: TContext;
+    readonly conditions: readonly ReadinessCondition<TContext>[];
+}
+/** Structured result from an ordered readiness evaluation. */
+export type ReadinessEvaluationResult = {
+    readonly ready: true;
+    readonly purpose: string;
+} | {
+    readonly ready: false;
+    readonly purpose: string;
+    readonly rejectedCondition: string;
+};
+/**
+ * Evaluate applicable conditions in declaration order until one rejects.
+ *
+ * Rejection reporting completes before the result is returned. Exceptions
+ * from applicability, evaluation, or reporting callbacks propagate unchanged;
+ * the evaluator does not reinterpret operational failures as policy results.
+ */
+export declare function evaluateReadiness<TContext>(request: ReadinessEvaluationRequest<TContext>): Promise<ReadinessEvaluationResult>;

package/dist/services/base/ReadinessEvaluator.js

@@ -0,0 +1,16 @@
+async function evaluateReadiness(request) {
+  for (const condition of request.conditions) {
+    if (condition.appliesTo && !condition.appliesTo(request.context)) continue;
+    if (await condition.evaluate(request.context)) continue;
+    await condition.onRejected?.(request.context);
+    return {
+      ready: false,
+      purpose: request.purpose,
+      rejectedCondition: condition.name
+    };
+  }
+  return { ready: true, purpose: request.purpose };
+}
+export {
+  evaluateReadiness
+};

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

@@ -1,8 +1,11 @@
+import type { E2EEAlgorithm } from "../../common/types.js";
 /**
  * Options which bind requests made through a remote CouchDB connection to the
  * operation which owns it.
  */
 export interface RemoteConnectionOpenOptions {
+    /** Encryption algorithm captured with the settings which own this connection. */
+    readonly encryptionAlgorithm?: E2EEAlgorithm;
     /**
      * Cancels abort-capable requests made through the connection when the
      * owning operation is cancelled.

package/dist/services/base/RemoteService.js

@@ -275,7 +275,7 @@ class RemoteService extends ServiceBase {
         }
       }
     };
-    const setting = this._settingService.currentSettings();
+    const encryptionAlgorithm = connectionOptions.encryptionAlgorithm ?? this._settingService.currentSettings().E2EEAlgorithm;
     let db;
     try {
       db = new this._pouchDB(uri, conf);
@@ -297,7 +297,7 @@ class RemoteService extends ServiceBase {
       replicationFilter(db, compression);
       disableEncryption();
       if (passphrase !== "false" && typeof passphrase === "string") {
-        enableEncryption(db, passphrase, useDynamicIterationCount, false, getPBKDF2Salt, setting.E2EEAlgorithm);
+        enableEncryption(db, passphrase, useDynamicIterationCount, false, getPBKDF2Salt, encryptionAlgorithm);
       }
     } catch (ex) {
       await closeAfterConnectionFailure();

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

@@ -2,7 +2,7 @@ import { type LOG_LEVEL } from "../../common/types.js";
 import type { IAPIService, IDatabaseService, IFileProcessingService, IReplicationService, IReplicatorService, ISettingService } from "./IService.js";
 import { ServiceBase, type ServiceContext } from "./ServiceBase.js";
 import { type LogFunction } from "../lib/logUtils.js";
-import type { LiveSyncAbstractReplicator } from "../../replication/LiveSyncAbstractReplicator.js";
+import { type ContinuousReplicationRequest, type ReplicationAttemptFailure, type ReplicationOutcome, type ReplicationReadinessRequirements, type UnattendedOneShotRequest, type UserInitiatedOneShotRequest } from "../../replication/ReplicatorProvider.js";
 import type { AppLifecycleService } from "./AppLifecycleService.js";
 export interface ReplicationServiceDependencies {
     APIService: IAPIService;
@@ -13,10 +13,17 @@ export interface ReplicationServiceDependencies {
     fileProcessingService: IFileProcessingService;
 }
 /**
- * The ReplicationService provides methods for managing replication processes.
+ * Host-facing replication façade for handlers, legacy entry points, and counters.
+ *
+ * Ordered readiness evaluation and typed capability dispatch are delegated to
+ * focused collaborators. Handler objects remain on this service so existing
+ * hosts retain their registration identity, priority ordering, and failure
+ * semantics. Active Replicator ownership remains with `ReplicatorService`.
  */
 export declare abstract class ReplicationService<T extends ServiceContext = ServiceContext> extends ServiceBase<T> implements IReplicationService {
     private _unresolvedErrorManager;
+    private readonly _evaluateReadiness;
+    private readonly _typedReplication;
     showError(msg: string, max_log_level?: LOG_LEVEL): void;
     clearErrors(): void;
     _log: LogFunction;
@@ -48,6 +55,8 @@ export declare abstract class ReplicationService<T extends ServiceContext = Serv
      * An event triggered before starting replication.
      */
     readonly onBeforeReplicate: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(showMessage: boolean) => Promise<boolean>>;
+    /** Provider preparation which applies only to the central remote. */
+    readonly onPrepareCentralRemoteReplication: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(showMessage: boolean) => Promise<boolean>>;
     /**
      * Lightweight, repeatable policy checks shared by every replication entry point.
      * Handlers must remain idempotent because a high-level replication may cross
@@ -55,11 +64,30 @@ export declare abstract class ReplicationService<T extends ServiceContext = Serv
      */
     readonly onCheckReplicationReady: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(showMessage: boolean) => Promise<boolean>>;
     /**
-     *  Check if the replication is ready to start.
-     * @param showMessage Whether to show messages to the user.
+     * Evaluate the ordered readiness conditions for an operation.
+     *
+     * This method does not acquire a Replicator or begin activity accounting.
+     * Provider requirements select whether central-remote preparation applies.
+     *
+     * @param showMessage Whether condition-specific diagnostics may be prominent.
+     * @param readiness Provider-owned preparation requirements.
      */
-    isReplicationReady(showMessage?: boolean): Promise<boolean>;
-    onReplicationFailed: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(showMessage?: boolean) => Promise<boolean>>;
+    isReplicationReady(showMessage?: boolean, readiness?: ReplicationReadinessRequirements): Promise<boolean>;
+    onReplicationFailed: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(request: import("../../replication/ReplicatorProvider.js").ReplicationFailureRequest) => Promise<boolean>>;
+    replicateUserInitiated(request?: UserInitiatedOneShotRequest): Promise<ReplicationOutcome>;
+    replicateUnattended(request: UnattendedOneShotRequest): Promise<ReplicationOutcome>;
+    replicateUnattendedByEvent(request: UnattendedOneShotRequest): Promise<ReplicationOutcome>;
+    startContinuous(request: ContinuousReplicationRequest): Promise<ReplicationOutcome>;
+    /**
+     * Stop finite transfer work on the active provider without entering the
+     * replication readiness or activity accounting paths.
+     *
+     * The provider and replicator are obtained together so that a concurrent
+     * replacement cannot pair a capability from one provider with a
+     * replicator from another. Stopping is an operator action, not a failed
+     * replication, so it does not invoke failure-recovery handlers.
+     */
+    stopActiveTransfer(): Promise<ReplicationOutcome>;
     private performReplicationRequest;
     /**
      * Perform replication and handle a failed result.
@@ -80,13 +108,19 @@ export declare abstract class ReplicationService<T extends ServiceContext = Serv
     /**
      * Check if there is a connection failure with the remote database.
      */
-    readonly checkConnectionFailure: import("../lib/HandlerUtils.js").MultipleHandlerFunction<() => Promise<boolean | "CHECKAGAIN" | undefined>, unknown>;
+    readonly checkConnectionFailure: import("../lib/HandlerUtils.js").MultipleHandlerFunction<(failure: ReplicationAttemptFailure) => Promise<boolean | "CHECKAGAIN" | undefined>, unknown>;
     databaseQueueCount: import("octagonal-wheels/dataobject/reactive_v2").ReactiveSource<number>;
     storageApplyingCount: import("octagonal-wheels/dataobject/reactive_v2").ReactiveSource<number>;
     replicationResultCount: import("octagonal-wheels/dataobject/reactive_v2").ReactiveSource<number>;
-    getActiveReplicatorFor(usage: string): false | LiveSyncAbstractReplicator;
-    private performReplicateAllToRemote;
-    private performReplicateAllFromRemote;
+    /**
+     * Dispatch one directional full transfer through one admitted publication.
+     *
+     * Each attempt owns a separate reservation. Compatibility recovery runs
+     * between those reservations, and a retry is admitted only when the exact
+     * first-attempt context remains active. Both attempts use one detached
+     * settings snapshot.
+     */
+    private performDirectionalReplication;
     replicateAllToRemote(showingNotice?: boolean): Promise<boolean>;
     replicateAllFromRemote(showingNotice?: boolean): Promise<boolean>;
     /**
@@ -103,6 +137,7 @@ export declare abstract class ReplicationService<T extends ServiceContext = Serv
      * it is not a general application-readiness bypass.
      */
     replicateAllFromRemoteForRebuild(showingNotice?: boolean): Promise<boolean>;
+    private getActiveReplicatorFor;
     private _getReplicatorAndPerform;
     markLocked(lockByClean?: boolean): Promise<void>;
     markUnlocked(): Promise<void>;