@vrtmrz/livesync-commonlib 0.1.19 → 0.1.20

package/dist/services/base/ReplicationService.js

@@ -6,12 +6,91 @@ import {
 import { handlers } from "../lib/HandlerUtils.js";
 import { ServiceBase } from "./ServiceBase.js";
 import { reactiveSource } from "octagonal-wheels/dataobject/reactive";
-import { createInstanceLogFunction, MARK_LOG_NETWORK_ERROR } from "../lib/logUtils.js";
+import { createInstanceLogFunction } from "../lib/logUtils.js";
+import {
+  CAPABILITY_SUPPORT_KINDS,
+  NO_INTERACTION,
+  CENTRAL_REMOTE_REPLICATION_READINESS,
+  USER_INITIATED_REPLICATION_AUTHORITY,
+  isActiveReplicatorContextBoundToSetting,
+  isReplicationCompleted,
+  replicationBlocked,
+  replicationFailed,
+  outcomeFromFiniteOpenReplication
+} from "../../replication/ReplicatorProvider.js";
 import { UnresolvedErrorManager } from "./UnresolvedErrorManager.js";
 import { isLockAcquired, shareRunningResult } from "octagonal-wheels/concurrency/lock";
+import {
+  createReplicationReadinessEvaluator
+} from "./ReplicationService.readiness.js";
+import { TypedReplicationCoordinator } from "./ReplicationService.typedReplication.js";
+import { asCopy } from "../../common/utils.object.js";
 const REPLICATION_ON_EVENT_FORECASTED_TIME = 5e3;
+const DIRECTIONAL_REPLICATION = Object.freeze({
+  UPLOAD: "upload",
+  DOWNLOAD: "download"
+});
+const DIRECTIONAL_REPLICATION_ADMISSION = Object.freeze({
+  ORDINARY: "ordinary",
+  EXPLICIT_REBUILD: "explicit-rebuild"
+});
+function canUploadAll(replicator) {
+  return "replicateAllToServer" in replicator && typeof replicator.replicateAllToServer === "function";
+}
+function canUploadAllWithOutcome(replicator) {
+  return "replicateAllToServerWithOutcome" in replicator && typeof replicator.replicateAllToServerWithOutcome === "function";
+}
+function canDownloadAll(replicator) {
+  return "replicateAllFromServer" in replicator && typeof replicator.replicateAllFromServer === "function";
+}
+function canDownloadAllWithOutcome(replicator) {
+  return "replicateAllFromServerWithOutcome" in replicator && typeof replicator.replicateAllFromServerWithOutcome === "function";
+}
+function canAdministerLegacyCentralRemote(replicator) {
+  return "markRemoteLocked" in replicator && typeof replicator.markRemoteLocked === "function" && "markRemoteResolved" in replicator && typeof replicator.markRemoteResolved === "function";
+}
+async function stopActiveTransferForDirectionalReplication(context) {
+  const capability = context.provider.stopActiveTransfer;
+  if (capability.kind !== CAPABILITY_SUPPORT_KINDS.SUPPORTED) {
+    return replicationBlocked(capability.reason);
+  }
+  try {
+    const outcome = await capability.run(context.replicator);
+    return outcome.status === "failed" ? replicationBlocked("not-ready") : outcome;
+  } catch {
+    return replicationBlocked("not-ready");
+  }
+}
+async function runDirectionalReplication(context, setting, direction, showingNotice) {
+  if (!isActiveReplicatorContextBoundToSetting(context, setting)) {
+    return replicationBlocked("not-ready");
+  }
+  const stopOutcome = await stopActiveTransferForDirectionalReplication(context);
+  if (!isReplicationCompleted(stopOutcome)) return stopOutcome;
+  try {
+    let result;
+    if (direction === DIRECTIONAL_REPLICATION.UPLOAD) {
+      if (canUploadAllWithOutcome(context.replicator)) {
+        return await context.replicator.replicateAllToServerWithOutcome(setting, showingNotice);
+      }
+      if (!canUploadAll(context.replicator)) return replicationBlocked("capability-not-applicable");
+      result = await context.replicator.replicateAllToServer(setting, showingNotice);
+    } else {
+      if (canDownloadAllWithOutcome(context.replicator)) {
+        return await context.replicator.replicateAllFromServerWithOutcome(setting, showingNotice);
+      }
+      if (!canDownloadAll(context.replicator)) return replicationBlocked("capability-not-applicable");
+      result = await context.replicator.replicateAllFromServer(setting, showingNotice);
+    }
+    return outcomeFromFiniteOpenReplication(result);
+  } catch (error) {
+    return replicationFailed(error);
+  }
+}
 class ReplicationService extends ServiceBase {
   _unresolvedErrorManager;
+  _evaluateReadiness;
+  _typedReplication;
   showError(msg, max_log_level = LOG_LEVEL_NOTICE) {
     this._unresolvedErrorManager.showError(msg, max_log_level);
   }
@@ -38,6 +117,36 @@ class ReplicationService extends ServiceBase {
       dependencies.appLifecycleService,
       this.context.events
     );
+    this._evaluateReadiness = createReplicationReadinessEvaluator({
+      gates: {
+        isApplicationReady: () => this.appLifecycleService.isReady(),
+        runPolicyChecks: (showMessage) => this.onCheckReplicationReady(showMessage),
+        currentSettings: () => this.settingService.currentSettings(),
+        isCleanupRunning: () => isLockAcquired("cleanup"),
+        isOnline: () => this.APIService.isOnline
+      },
+      preparation: {
+        commitPendingFileEvents: () => this.fileProcessing.commitPendingFileEvents(),
+        prepareCentralRemote: (showMessage) => this.onPrepareCentralRemoteReplication(showMessage),
+        runBeforeReplicate: (showMessage) => this.onBeforeReplicate(showMessage)
+      },
+      diagnostics: {
+        getUnresolvedMessages: () => this.appLifecycleService.getUnresolvedMessages(),
+        translate: (key) => this.context.translate(key),
+        log: this._log,
+        showError: (message, maxLogLevel) => this.showError(message, maxLogLevel),
+        clearErrors: () => this.clearErrors()
+      }
+    });
+    this._typedReplication = new TypedReplicationCoordinator({
+      replicatorService: this.replicatorService,
+      currentSettings: () => this.settingService.currentSettings(),
+      checkReadiness: (showMessage, readiness) => this.isReplicationReady(showMessage, readiness),
+      handleFailure: (request) => this.onReplicationFailed(request),
+      recordFiniteAttempt: () => {
+        this.previousReplicated = Date.now();
+      }
+    });
   }
   /**
    * Process a synchronisation result document.
@@ -62,6 +171,10 @@ class ReplicationService extends ServiceBase {
    * An event triggered before starting replication.
    */
   onBeforeReplicate = handlers().bailFirstFailure("onBeforeReplicate");
+  /** Provider preparation which applies only to the central remote. */
+  onPrepareCentralRemoteReplication = handlers().bailFirstFailure(
+    "onPrepareCentralRemoteReplication"
+  );
   /**
    * Lightweight, repeatable policy checks shared by every replication entry point.
    * Handlers must remain idempotent because a high-level replication may cross
@@ -69,47 +182,61 @@ class ReplicationService extends ServiceBase {
    */
   onCheckReplicationReady = handlers().bailFirstFailure("onCheckReplicationReady");
   /**
-   *  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.
    */
-  async isReplicationReady(showMessage = false) {
-    if (!this.appLifecycleService.isReady()) {
-      this._log(`Not ready`);
-      return false;
-    }
-    if (!await this.onCheckReplicationReady(showMessage)) {
-      return false;
-    }
-    const currentSettings = this.settingService.currentSettings();
-    if (isLockAcquired("cleanup")) {
-      this._log(this.context.translate("Replicator.Message.Cleaned"), LOG_LEVEL_NOTICE);
-      return false;
-    }
-    if (currentSettings.versionUpFlash != "") {
-      this._log(this.context.translate("Replicator.Message.VersionUpFlash"), LOG_LEVEL_NOTICE);
-      return false;
-    }
-    if (!await this.fileProcessing.commitPendingFileEvents()) {
-      this.showError(this.context.translate("Replicator.Message.Pending"), LOG_LEVEL_NOTICE);
-      return false;
-    }
-    if (!this.APIService.isOnline) {
-      this.showError("Network is offline", showMessage ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO);
-      return false;
-    }
-    if (!await this.onBeforeReplicate(showMessage)) {
-      const hasNetworkError = (await this.appLifecycleService.getUnresolvedMessages()).flat().some((e) => typeof e == "string" && e.indexOf(MARK_LOG_NETWORK_ERROR) !== -1);
-      if (!hasNetworkError) {
-        this.showError(this.context.translate("Replicator.Message.SomeModuleFailed"), LOG_LEVEL_NOTICE);
-      } else {
-        this._log(this.context.translate("Replicator.Message.SomeModuleFailed"), LOG_LEVEL_INFO);
-      }
-      return false;
-    }
-    this.clearErrors();
-    return true;
+  async isReplicationReady(showMessage = false, readiness = CENTRAL_REMOTE_REPLICATION_READINESS) {
+    return (await this._evaluateReadiness({ showMessage, requirements: readiness })).ready;
   }
   onReplicationFailed = handlers().bailFirstFailure("onReplicationFailed");
+  async replicateUserInitiated(request = {
+    trigger: "manual",
+    interaction: USER_INITIATED_REPLICATION_AUTHORITY
+  }) {
+    return await this._typedReplication.runUserInitiated(request);
+  }
+  async replicateUnattended(request) {
+    return await this._typedReplication.runUnattended(request);
+  }
+  replicateUnattendedByEvent(request) {
+    return shareRunningResult(`replication`, async () => {
+      const currentSettings = this.settingService.currentSettings();
+      const least = currentSettings.syncMinimumInterval;
+      if (least > 0) {
+        const now = Date.now();
+        const elapsed = now - this.previousReplicated;
+        if (elapsed < least) {
+          this._log(
+            `Replication triggered by event is rate limited. Elapsed: ${elapsed}ms, Least interval: ${least}ms`,
+            LOG_LEVEL_VERBOSE
+          );
+          return replicationBlocked("rate-limited");
+        }
+        this.previousReplicated = now + REPLICATION_ON_EVENT_FORECASTED_TIME;
+      }
+      return await this.replicateUnattended(request);
+    });
+  }
+  async startContinuous(request) {
+    return await this._typedReplication.startContinuous(request);
+  }
+  /**
+   * 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.
+   */
+  async stopActiveTransfer() {
+    return await this._typedReplication.stopActiveTransfer();
+  }
   async performReplicationRequest(showMessage) {
     const activeReplicator = this.replicatorService.getActiveReplicator();
     if (!activeReplicator) {
@@ -125,7 +252,9 @@ class ReplicationService extends ServiceBase {
    */
   async performReplication(showMessage) {
     const result = await this.performReplicationRequest(showMessage);
-    if (!result) return await this.onReplicationFailed(showMessage);
+    if (!result) {
+      return false;
+    }
     return result;
   }
   /**
@@ -133,6 +262,13 @@ class ReplicationService extends ServiceBase {
    * @param showMessage Whether to show messages to the user.
    */
   async replicate(showMessage) {
+    if (await this.replicatorService.acquireActiveReplicatorContext()) {
+      const outcome = showMessage ? await this.replicateUserInitiated() : await this.replicateUnattended({
+        trigger: "database-event",
+        interaction: NO_INTERACTION
+      });
+      return outcome.status === "completed";
+    }
     try {
       const checkBeforeReplicate = await this.isReplicationReady(showMessage);
       if (!checkBeforeReplicate) return false;
@@ -140,7 +276,9 @@ class ReplicationService extends ServiceBase {
         () => this.performReplicationRequest(showMessage),
         { label: "replication" }
       );
-      if (!result) return await this.onReplicationFailed(showMessage);
+      if (!result) {
+        return false;
+      }
       return result;
     } finally {
       this.previousReplicated = Date.now();
@@ -151,7 +289,13 @@ class ReplicationService extends ServiceBase {
    * Start the replication process triggered by an event (e.g., file change).
    * @param showMessage Whether to show messages to the user.
    */
-  replicateByEvent(showMessage) {
+  async replicateByEvent(showMessage) {
+    if (await this.replicatorService.acquireActiveReplicatorContext()) {
+      return await this.replicateUnattendedByEvent({
+        trigger: "database-event",
+        interaction: NO_INTERACTION
+      }).then((outcome) => outcome.status === "completed");
+    }
     return shareRunningResult(`replication`, async () => {
       const currentSettings = this.settingService.currentSettings();
       const least = currentSettings.syncMinimumInterval;
@@ -178,51 +322,53 @@ class ReplicationService extends ServiceBase {
   databaseQueueCount = reactiveSource(0);
   storageApplyingCount = reactiveSource(0);
   replicationResultCount = reactiveSource(0);
-  getActiveReplicatorFor(usage) {
-    const activeReplicator = this.replicatorService.getActiveReplicator();
-    if (!activeReplicator) {
-      this._log(`Active replicator not found during ${usage}`, LOG_LEVEL_NOTICE);
-      return false;
-    }
-    return activeReplicator;
-  }
-  async performReplicateAllToRemote(showingNotice) {
-    if (!await this.onBeforeReplicate(showingNotice)) {
+  /**
+   * 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.
+   */
+  async performDirectionalReplication(direction, showingNotice, admission = DIRECTIONAL_REPLICATION_ADMISSION.ORDINARY) {
+    if (direction === DIRECTIONAL_REPLICATION.UPLOAD && !await this.onBeforeReplicate(showingNotice)) {
       this._log(this.context.translate("Replicator.Message.SomeModuleFailed"), LOG_LEVEL_NOTICE);
       return false;
     }
-    const currentSettings = this.settingService.currentSettings();
-    const activeReplicator = this.getActiveReplicatorFor("sending data to remote");
-    if (!activeReplicator) {
-      return false;
-    }
-    const ret = await activeReplicator.replicateAllToServer(currentSettings, showingNotice);
-    if (ret) return true;
-    const checkResult = await this.checkConnectionFailure();
-    if (checkResult == "CHECKAGAIN")
-      return await activeReplicator.replicateAllToServer(currentSettings, showingNotice);
-    return !checkResult;
-  }
-  async performReplicateAllFromRemote(showingNotice) {
-    const activeReplicator = this.getActiveReplicatorFor("fetching data from remote");
-    if (!activeReplicator) {
-      return false;
+    const detachedSetting = asCopy(this.settingService.currentSettings());
+    if (admission === DIRECTIONAL_REPLICATION_ADMISSION.EXPLICIT_REBUILD) {
+      detachedSetting.versionUpFlash = "";
     }
-    const currentSettings = this.settingService.currentSettings();
-    const ret = await activeReplicator.replicateAllFromServer(currentSettings, showingNotice);
-    if (ret) return true;
-    const checkResult = await this.checkConnectionFailure();
-    if (checkResult == "CHECKAGAIN")
-      return await activeReplicator.replicateAllFromServer(currentSettings, showingNotice);
-    return !checkResult;
+    const setting = Object.freeze(detachedSetting);
+    let expectedContext;
+    const run = async () => {
+      const admitted = await this.replicatorService.runWithActiveReplicatorContext((context) => {
+        if (expectedContext && context !== expectedContext) {
+          return replicationBlocked("not-ready");
+        }
+        expectedContext ??= context;
+        return runDirectionalReplication(context, setting, direction, showingNotice);
+      });
+      if (admitted) return admitted;
+      this._log(`Active replicator not found during directional ${direction}`, LOG_LEVEL_NOTICE);
+      return replicationBlocked("no-active-replicator");
+    };
+    const outcome = await run();
+    if (isReplicationCompleted(outcome)) return true;
+    if (outcome.status !== "failed") return false;
+    const failedContext = expectedContext;
+    if (!failedContext) return false;
+    const failure = Object.freeze({ context: failedContext, setting, outcome });
+    const checkResult = await this.checkConnectionFailure(failure);
+    return checkResult === "CHECKAGAIN" && isReplicationCompleted(await run());
   }
   async replicateAllToRemote(showingNotice = false) {
     if (!this.appLifecycleService.isReady()) return false;
-    return await this.performReplicateAllToRemote(showingNotice);
+    return await this.performDirectionalReplication(DIRECTIONAL_REPLICATION.UPLOAD, showingNotice);
   }
   async replicateAllFromRemote(showingNotice = false) {
     if (!this.appLifecycleService.isReady()) return false;
-    return await this.performReplicateAllFromRemote(showingNotice);
+    return await this.performDirectionalReplication(DIRECTIONAL_REPLICATION.DOWNLOAD, showingNotice);
   }
   /**
    * Perform a full upload owned by an active rebuild while the physical database is ready.
@@ -235,7 +381,11 @@ class ReplicationService extends ServiceBase {
       this._log("The selected local database is not ready for the rebuild upload.", LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.performReplicateAllToRemote(showingNotice);
+    return await this.performDirectionalReplication(
+      DIRECTIONAL_REPLICATION.UPLOAD,
+      showingNotice,
+      DIRECTIONAL_REPLICATION_ADMISSION.EXPLICIT_REBUILD
+    );
   }
   /**
    * Perform a full download owned by an active rebuild while the physical database is ready.
@@ -248,38 +398,45 @@ class ReplicationService extends ServiceBase {
       this._log("The selected local database is not ready for the rebuild download.", LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.performReplicateAllFromRemote(showingNotice);
+    return await this.performDirectionalReplication(
+      DIRECTIONAL_REPLICATION.DOWNLOAD,
+      showingNotice,
+      DIRECTIONAL_REPLICATION_ADMISSION.EXPLICIT_REBUILD
+    );
+  }
+  getActiveReplicatorFor(usage) {
+    const activeReplicator = this.replicatorService.getActiveReplicator();
+    if (!activeReplicator) {
+      this._log(`Active replicator not found during ${usage}`, LOG_LEVEL_NOTICE);
+      return false;
+    }
+    return activeReplicator;
   }
   _getReplicatorAndPerform(action, perform) {
     const activeReplicator = this.getActiveReplicatorFor(action);
-    if (!activeReplicator) {
+    if (!activeReplicator) return Promise.resolve();
+    if (!canAdministerLegacyCentralRemote(activeReplicator)) {
+      this._log(`Active replicator does not support ${action}`, LOG_LEVEL_NOTICE);
       return Promise.resolve();
     }
-    const currentSettings = this.settingService.currentSettings();
-    return perform(currentSettings, activeReplicator);
+    return perform(this.settingService.currentSettings(), activeReplicator);
   }
   async markLocked(lockByClean = false) {
     return await this._getReplicatorAndPerform(
       "marking remote locked",
-      async (currentSettings, activeReplicator) => {
-        return await activeReplicator.markRemoteLocked(currentSettings, true, lockByClean);
-      }
+      async (currentSettings, activeReplicator) => await activeReplicator.markRemoteLocked(currentSettings, true, lockByClean)
     );
   }
   async markUnlocked() {
     return await this._getReplicatorAndPerform(
       "marking remote unlocked",
-      async (currentSettings, activeReplicator) => {
-        return await activeReplicator.markRemoteLocked(currentSettings, false, false);
-      }
+      async (currentSettings, activeReplicator) => await activeReplicator.markRemoteLocked(currentSettings, false, false)
     );
   }
   async markResolved() {
     return await this._getReplicatorAndPerform(
       "marking remote resolved",
-      async (currentSettings, activeReplicator) => {
-        return await activeReplicator.markRemoteResolved(currentSettings);
-      }
+      async (currentSettings, activeReplicator) => await activeReplicator.markRemoteResolved(currentSettings)
     );
   }
 }

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

@@ -0,0 +1,52 @@
+import { type LOG_LEVEL, type ObsidianLiveSyncSettings } from "../../common/types.js";
+import { type ReplicationReadinessRequirements } from "../../replication/ReplicatorProvider.js";
+import { type LogFunction } from "../lib/logUtils.js";
+import type { MessageTranslator } from "./MessageTranslator.js";
+import { type ReadinessEvaluationResult } from "./ReadinessEvaluator.js";
+/** State and policy gates consulted without beginning remote preparation. */
+export interface ReplicationReadinessGates {
+    readonly isApplicationReady: () => boolean;
+    readonly runPolicyChecks: (showMessage: boolean) => Promise<boolean>;
+    readonly currentSettings: () => Pick<ObsidianLiveSyncSettings, "versionUpFlash">;
+    readonly isCleanupRunning: () => boolean;
+    readonly isOnline: () => boolean;
+}
+/** Ordered operational gates which may release or prepare replication work. */
+export interface ReplicationReadinessPreparation {
+    readonly commitPendingFileEvents: () => Promise<boolean>;
+    readonly prepareCentralRemote: (showMessage: boolean) => Promise<boolean>;
+    readonly runBeforeReplicate: (showMessage: boolean) => Promise<boolean>;
+}
+/** Diagnostic state, presentation, and unresolved-error output for readiness. */
+export interface ReplicationReadinessDiagnostics {
+    readonly getUnresolvedMessages: () => Promise<(string | Error)[][]>;
+    readonly translate: MessageTranslator;
+    readonly log: LogFunction;
+    readonly showError: (message: string, maxLogLevel?: LOG_LEVEL) => void;
+    readonly clearErrors: () => void;
+}
+/** Role-grouped collaborators for the common replication readiness sequence. */
+export interface ReplicationReadinessDependencies {
+    readonly gates: ReplicationReadinessGates;
+    readonly preparation: ReplicationReadinessPreparation;
+    readonly diagnostics: ReplicationReadinessDiagnostics;
+}
+export interface ReplicationReadinessContext {
+    readonly showMessage: boolean;
+    readonly requirements: ReplicationReadinessRequirements;
+}
+/** Optional inputs accepted by the host-facing replication readiness evaluator. */
+export interface ReplicationReadinessRequest {
+    readonly showMessage?: boolean;
+    readonly requirements?: ReplicationReadinessRequirements;
+}
+export type ReplicationReadinessEvaluator = (context?: ReplicationReadinessRequest) => Promise<ReadinessEvaluationResult>;
+/**
+ * Compose the ordered readiness conditions shared by replication entry points.
+ *
+ * The returned evaluator owns readiness decisions and their diagnostics only.
+ * It does not acquire a Replicator, run provider capabilities, or account for
+ * remote activity. Provider-specific preparation is selected by the supplied
+ * requirements while the common conditions retain their declaration order.
+ */
+export declare function createReplicationReadinessEvaluator(dependencies: ReplicationReadinessDependencies): ReplicationReadinessEvaluator;

package/dist/services/base/ReplicationService.readiness.js

@@ -0,0 +1,87 @@
+import { LOG_LEVEL_INFO, LOG_LEVEL_NOTICE } from "../../common/types.js";
+import {
+  CENTRAL_REMOTE_REPLICATION_READINESS
+} from "../../replication/ReplicatorProvider.js";
+import { MARK_LOG_NETWORK_ERROR } from "../lib/logUtils.js";
+import { evaluateReadiness } from "./ReadinessEvaluator.js";
+function createReplicationReadinessEvaluator(dependencies) {
+  const { diagnostics, gates, preparation } = dependencies;
+  const reportPreparationFailure = async () => {
+    const hasNetworkError = (await diagnostics.getUnresolvedMessages()).flat().some((entry) => typeof entry == "string" && entry.includes(MARK_LOG_NETWORK_ERROR));
+    const message = diagnostics.translate("Replicator.Message.SomeModuleFailed");
+    if (hasNetworkError) {
+      diagnostics.log(message, LOG_LEVEL_INFO);
+    } else {
+      diagnostics.showError(message, LOG_LEVEL_NOTICE);
+    }
+  };
+  const conditions = [
+    {
+      name: "application-ready",
+      evaluate: () => {
+        if (gates.isApplicationReady()) return true;
+        diagnostics.log("Not ready");
+        return false;
+      }
+    },
+    {
+      name: "replication-policy-approved",
+      evaluate: ({ showMessage }) => gates.runPolicyChecks(showMessage)
+    },
+    {
+      name: "local-replication-state-ready",
+      evaluate: () => {
+        const currentSettings = gates.currentSettings();
+        if (gates.isCleanupRunning()) {
+          diagnostics.log(diagnostics.translate("Replicator.Message.Cleaned"), LOG_LEVEL_NOTICE);
+          return false;
+        }
+        if (currentSettings.versionUpFlash != "") {
+          diagnostics.log(diagnostics.translate("Replicator.Message.VersionUpFlash"), LOG_LEVEL_NOTICE);
+          return false;
+        }
+        return true;
+      }
+    },
+    {
+      name: "pending-file-events-committed",
+      evaluate: () => preparation.commitPendingFileEvents(),
+      onRejected: () => {
+        diagnostics.showError(diagnostics.translate("Replicator.Message.Pending"), LOG_LEVEL_NOTICE);
+      }
+    },
+    {
+      name: "network-online",
+      evaluate: () => gates.isOnline(),
+      onRejected: ({ showMessage }) => {
+        diagnostics.showError("Network is offline", showMessage ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO);
+      }
+    },
+    {
+      name: "central-remote-prepared",
+      appliesTo: ({ requirements }) => requirements.centralRemotePreparation === "required",
+      evaluate: ({ showMessage }) => preparation.prepareCentralRemote(showMessage),
+      onRejected: reportPreparationFailure
+    },
+    {
+      name: "general-replication-prepared",
+      evaluate: ({ showMessage }) => preparation.runBeforeReplicate(showMessage),
+      onRejected: reportPreparationFailure
+    }
+  ];
+  return async (context = {}) => {
+    const result = await evaluateReadiness({
+      purpose: "replication",
+      context: {
+        showMessage: context.showMessage ?? false,
+        requirements: context.requirements ?? CENTRAL_REMOTE_REPLICATION_READINESS
+      },
+      conditions
+    });
+    if (result.ready) diagnostics.clearErrors();
+    return result;
+  };
+}
+export {
+  createReplicationReadinessEvaluator
+};

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

@@ -0,0 +1,83 @@
+import type { ObsidianLiveSyncSettings } from "../../common/types.js";
+import { type ContinuousReplicationRequest, type ReplicationFailureRequest, type ReplicationOutcome, type ReplicationReadinessRequirements, type UnattendedOneShotRequest, type UserInitiatedOneShotRequest } from "../../replication/ReplicatorProvider.js";
+import type { IReplicatorService } from "./IService.js";
+/** ReplicationService collaborators required to execute typed provider roles. */
+export interface TypedReplicationCoordinatorDependencies {
+    readonly replicatorService: Pick<IReplicatorService, "acquireActiveReplicatorContext" | "hasActiveReplicator" | "runWithActiveReplicatorContext" | "runFiniteReplicationActivity">;
+    readonly currentSettings: () => ObsidianLiveSyncSettings;
+    readonly checkReadiness: (showMessage: boolean, readiness: ReplicationReadinessRequirements) => Promise<boolean>;
+    readonly handleFailure: (request: ReplicationFailureRequest) => Promise<boolean>;
+    /**
+     * Advance the host's finite-attempt clock after readiness admits dispatch.
+     *
+     * This includes a provider-declared blocked capability, because the legacy
+     * service advanced its event rate-limit clock at the same boundary.
+     */
+    readonly recordFiniteAttempt: () => void;
+}
+/**
+ * Execute typed provider capabilities against one captured active context.
+ *
+ * The coordinator owns capability selection, readiness dispatch, finite
+ * activity accounting, and failure notification. It does not own event rate
+ * limiting, legacy Replicator calls, or the active Replicator lifecycle.
+ *
+ * Each role is deliberately expressed as a separate control flow. Readiness,
+ * interaction authority, activity accounting, and failure handling differ by
+ * role, so a flag-driven capability table would conceal lifecycle decisions
+ * which callers and reviewers need to see explicitly.
+ */
+export declare class TypedReplicationCoordinator {
+    private readonly dependencies;
+    constructor(dependencies: TypedReplicationCoordinatorDependencies);
+    /**
+     * Execute a user-initiated finite role with the request's interaction authority.
+     *
+     * The active context is acquired atomically, readiness runs before
+     * capability dispatch, and the settings snapshot is captured before the
+     * finite activity begins. A failed result invokes recovery only after that
+     * activity has settled.
+     */
+    runUserInitiated(request: UserInitiatedOneShotRequest): Promise<ReplicationOutcome>;
+    /**
+     * Execute an unattended finite role without granting interaction authority.
+     *
+     * Requests carrying interaction authority are rejected before context
+     * acquisition. Accepted requests otherwise retain the same readiness,
+     * settings-snapshot, activity, and recovery ordering as user work.
+     */
+    runUnattended(request: UnattendedOneShotRequest): Promise<ReplicationOutcome>;
+    /**
+     * Start the provider's continuous role outside finite activity accounting.
+     *
+     * Capability applicability is established before readiness, because an
+     * inapplicable long-lived role must not trigger unrelated preparation or
+     * diagnostics. After readiness, the short startup call is admitted against
+     * that exact publication. The provider owns the registered long-lived task
+     * after startup settles; it does not retain this admission for its lifetime.
+     * Startup failures become typed outcomes without invoking the finite-operation
+     * recovery handler.
+     */
+    startContinuous(request: ContinuousReplicationRequest): Promise<ReplicationOutcome>;
+    /**
+     * Request transfer cancellation on one atomically acquired active context.
+     *
+     * Cancellation deliberately bypasses readiness, activity accounting, and
+     * failure-recovery handlers: it is an operator control over existing work,
+     * not a request to begin new remote work.
+     */
+    stopActiveTransfer(): Promise<ReplicationOutcome>;
+    private finishFiniteAttempt;
+    private acquireContext;
+    private acquireReadyContext;
+    private runFiniteActivity;
+    /**
+     * Reserve the readiness-tested publication for provider dispatch.
+     *
+     * Readiness and settings capture intentionally happen before admission. If
+     * an ownership transition completes in between, the newly admitted context
+     * is rejected instead of running work prepared for an older publication.
+     * Failure recovery runs only after the reservation has been released.
+     */
+    private runAdmittedFiniteActivity;
+}