@vrtmrz/livesync-commonlib 0.1.19 → 0.1.20

package/dist/replication/RemoteResource.d.ts

@@ -0,0 +1,85 @@
+import type { RemoteDBSettings, RemotePreferredTweakResult } from "../common/types.js";
+import type { RemoteDBStatus } from "./LiveSyncAbstractReplicator.js";
+import { type CapabilitySupport } from "./ProviderCapability.js";
+/** Stable machine identifiers for finite provider-owned remote resources. */
+export declare const REMOTE_RESOURCE_KINDS: Readonly<{
+    readonly CONNECTION: "connection";
+    readonly PREFERRED_TWEAK: "preferred-tweak";
+    readonly SECURITY_SEED: "security-seed";
+    readonly SYNCHRONISATION_INFORMATION: "synchronisation-information";
+}>;
+export type RemoteResourceKind = (typeof REMOTE_RESOURCE_KINDS)[keyof typeof REMOTE_RESOURCE_KINDS];
+/** Options understood by a provider's finite remote-connection resource. */
+export interface RemoteConnectionProbeOptions {
+    /** Permit a provider which supports provisioning to create the selected remote. */
+    readonly createIfMissing?: boolean;
+    /** Permit the provider to emit its ordinary user-facing connection result. */
+    readonly showResult?: boolean;
+}
+/** Result of checking one trial remote configuration. */
+export type RemoteConnectionProbeResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason?: unknown;
+};
+/**
+ * A finite connection and status resource bound to one trial configuration.
+ *
+ * The owner must call {@link RemoteConnectionProbe.dispose} even when an
+ * operation rejects. Disposal is asynchronous and must be idempotent.
+ */
+export interface RemoteConnectionProbe {
+    check(options?: RemoteConnectionProbeOptions): Promise<RemoteConnectionProbeResult>;
+    getStatus(): Promise<false | RemoteDBStatus>;
+    dispose(): Promise<void>;
+}
+/** A finite preferred-tweak reader bound to one trial configuration. */
+export interface PreferredTweakProbe {
+    read(): Promise<RemotePreferredTweakResult>;
+    /** Release every resource owned by this probe. Repeated calls must settle safely. */
+    dispose(): Promise<void>;
+}
+/**
+ * An owned reader for the remote Security Seed used to derive replication keys.
+ *
+ * Each read observes the remote for this resource's settings snapshot rather
+ * than reusing process-cached parameters from an earlier workflow. Reading the
+ * seed may create explicitly missing remote synchronisation parameters. The
+ * caller must therefore treat this as a bounded remote operation and dispose
+ * the resource in `finally`.
+ */
+export interface SecuritySeedResource {
+    read(): Promise<Uint8Array<ArrayBuffer>>;
+    dispose(): Promise<void>;
+}
+/**
+ * An owned verifier for the remote synchronisation-information document.
+ *
+ * A successful check proves that the document can be decrypted. When the
+ * document is absent, a provider may create it as part of the check. The owner
+ * must dispose the resource in `finally`.
+ */
+export interface SynchronisationInformationResource {
+    check(): Promise<boolean>;
+    dispose(): Promise<void>;
+}
+export type RemoteResourceMap = {
+    readonly [REMOTE_RESOURCE_KINDS.CONNECTION]: RemoteConnectionProbe;
+    readonly [REMOTE_RESOURCE_KINDS.PREFERRED_TWEAK]: PreferredTweakProbe;
+    readonly [REMOTE_RESOURCE_KINDS.SECURITY_SEED]: SecuritySeedResource;
+    readonly [REMOTE_RESOURCE_KINDS.SYNCHRONISATION_INFORMATION]: SynchronisationInformationResource;
+};
+export type RemoteResourceFactoryMap = {
+    readonly [K in RemoteResourceKind]: (setting: RemoteDBSettings) => Promise<RemoteResourceMap[K]>;
+};
+/** Exhaustive resource support catalogue supplied by one provider. */
+export type RemoteResourceCapabilities = {
+    readonly [K in RemoteResourceKind]: CapabilitySupport<RemoteResourceFactoryMap[K]>;
+};
+/** Explicit catalogue for providers which own no finite remote resources. */
+export declare const NO_REMOTE_RESOURCE_CAPABILITIES: RemoteResourceCapabilities;
+export type ConnectionProbeFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.CONNECTION];
+export type PreferredTweakProbeFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.PREFERRED_TWEAK];
+export type SecuritySeedResourceFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.SECURITY_SEED];
+export type SynchronisationInformationResourceFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.SYNCHRONISATION_INFORMATION];

package/dist/replication/RemoteResource.js

@@ -0,0 +1,17 @@
+import { CAPABILITY_NOT_APPLICABLE } from "./ProviderCapability.js";
+const REMOTE_RESOURCE_KINDS = Object.freeze({
+  CONNECTION: "connection",
+  PREFERRED_TWEAK: "preferred-tweak",
+  SECURITY_SEED: "security-seed",
+  SYNCHRONISATION_INFORMATION: "synchronisation-information"
+});
+const NO_REMOTE_RESOURCE_CAPABILITIES = Object.freeze({
+  [REMOTE_RESOURCE_KINDS.CONNECTION]: CAPABILITY_NOT_APPLICABLE,
+  [REMOTE_RESOURCE_KINDS.PREFERRED_TWEAK]: CAPABILITY_NOT_APPLICABLE,
+  [REMOTE_RESOURCE_KINDS.SECURITY_SEED]: CAPABILITY_NOT_APPLICABLE,
+  [REMOTE_RESOURCE_KINDS.SYNCHRONISATION_INFORMATION]: CAPABILITY_NOT_APPLICABLE
+});
+export {
+  NO_REMOTE_RESOURCE_CAPABILITIES,
+  REMOTE_RESOURCE_KINDS
+};

package/dist/replication/ReplicatorInstance.d.ts

@@ -0,0 +1,23 @@
+import type { RemoteDBSettings } from "../common/types.js";
+/**
+ * Minimal lifecycle contract shared by active Replicator instances.
+ *
+ * Providers may expose additional operations through focused capability facets;
+ * this contract contains only the lifecycle operations required by the host.
+ */
+export interface ReplicatorInstance {
+    /** Initialise local database state required by replication before publication. */
+    initializeDatabaseForReplication(): Promise<boolean>;
+    /**
+     * Invoke the legacy replication entry point.
+     *
+     * A `void` settlement may mean an accepted long-lived start, while finite
+     * adapters require an explicit `true`. Provider runners convert this
+     * compatibility result to a typed outcome before exposing it to callers.
+     */
+    openReplication(setting: RemoteDBSettings, keepAlive: boolean, showResult: boolean, ignoreCleanLock: boolean): Promise<void | boolean>;
+    /** Stop active transfer work; providers may settle this synchronously. */
+    terminateSync(): void | Promise<void>;
+    /** Close the instance; providers may settle this synchronously. */
+    closeReplication(): void | Promise<void>;
+}

package/dist/replication/ReplicatorProvider.d.ts

@@ -0,0 +1,249 @@
+import type { RemoteDBSettings, ObsidianLiveSyncSettings, RemoteType } from "../common/types.js";
+import type { ReplicatorInstance } from "./ReplicatorInstance.js";
+import { type CapabilitySupport, type SupportedCapability } from "./ProviderCapability.js";
+import type { RemoteResourceCapabilities } from "./RemoteResource.js";
+import type { CentralRemoteAdministrationRunner } from "./CentralRemoteAdministration.js";
+import type { CentralCompatibilityRecoveryHint } from "./CentralCompatibility.js";
+export { CAPABILITY_NOT_APPLICABLE, CAPABILITY_NOT_IMPLEMENTED, CAPABILITY_SUPPORT_KINDS, CAPABILITY_UNAVAILABLE_REASONS, supportedCapability, } from "./ProviderCapability.js";
+export type { CapabilitySupport, NotApplicableCapability, NotImplementedCapability, SupportedCapability, } from "./ProviderCapability.js";
+/**
+ * A finite replication trigger which can run without opening a user dialogue.
+ *
+ * This is deliberately a closed list. Adding another automatic trigger must
+ * make its lifecycle ownership visible at the call site and in the provider
+ * contract rather than silently inheriting manual interaction permissions.
+ */
+export type UnattendedReplicationTrigger = "resume" | "periodic" | "database-event" | "editor-save" | "file-open" | "merge" | "daemon";
+/** Automatic trigger which may start or resume a long-lived connection. */
+export type ContinuousReplicationTrigger = "resume" | "daemon";
+/** No user interaction may be requested by an unattended replication path. */
+export declare const NO_INTERACTION: Readonly<{
+    readonly kind: "forbidden";
+}>;
+/**
+ * The authority carried by a user-initiated replication command.
+ *
+ * The permissions are explicit so that a future caller can narrow an
+ * operation without passing a broad boolean such as `showMessage` through
+ * provider code. The common authority grants all currently supported user
+ * actions.
+ */
+export declare const USER_INITIATED_REPLICATION_AUTHORITY: Readonly<{
+    readonly kind: "permitted";
+    readonly permissions: Readonly<{
+        peerSelection: true;
+        localPeerAdmission: true;
+        configurationExchange: true;
+        failureRecovery: true;
+    }>;
+}>;
+export type NoInteraction = typeof NO_INTERACTION;
+/** All interaction permissions understood by the current provider boundary. */
+export interface InteractionPermissions {
+    readonly peerSelection: boolean;
+    readonly localPeerAdmission: boolean;
+    readonly configurationExchange: boolean;
+    readonly failureRecovery: boolean;
+}
+/**
+ * A permitted authority must retain at least one explicit permission.
+ *
+ * This prevents an apparently user-authorised request from carrying an empty
+ * permission set, while allowing a caller to veto or narrow individual
+ * actions without introducing a second authority type.
+ */
+export type PermittedInteractionPermissions = (InteractionPermissions & {
+    readonly peerSelection: true;
+}) | (InteractionPermissions & {
+    readonly localPeerAdmission: true;
+}) | (InteractionPermissions & {
+    readonly configurationExchange: true;
+}) | (InteractionPermissions & {
+    readonly failureRecovery: true;
+});
+export interface UserInitiatedReplicationAuthority {
+    readonly kind: "permitted";
+    readonly permissions: PermittedInteractionPermissions;
+}
+export type ReplicationInteraction = NoInteraction | UserInitiatedReplicationAuthority;
+/** Authority carried through a replication request and its failure path. */
+export type InteractionAuthority = ReplicationInteraction;
+/** A request made by an explicitly user-initiated one-shot command. */
+export interface UserInitiatedOneShotRequest {
+    readonly trigger: "manual";
+    readonly interaction: InteractionAuthority;
+}
+/** A request made by an automatic finite replication trigger. */
+export interface UnattendedOneShotRequest {
+    readonly trigger: UnattendedReplicationTrigger;
+    readonly interaction: NoInteraction;
+}
+/** A request which starts a provider's long-lived/continuous operation. */
+export interface ContinuousReplicationRequest {
+    readonly trigger: ContinuousReplicationTrigger;
+    readonly interaction: NoInteraction;
+}
+/** Stable reasons for which a provider role cannot be run. */
+export type ReplicationBlockReason = "no-active-replicator" | "no-targets" | "not-ready" | "provider-not-composed" | "provider-not-configured" | "capability-not-implemented" | "capability-not-applicable" | "interaction-required" | "replication-in-progress" | "rate-limited";
+/** A finite operation completed without a partial or failed result. */
+export declare const REPLICATION_COMPLETED: Readonly<{
+    readonly status: "completed";
+}>;
+/** A user-initiated operation was cancelled before it completed. */
+export declare const REPLICATION_CANCELLED: Readonly<{
+    readonly status: "cancelled";
+}>;
+export type ReplicationCompleted = typeof REPLICATION_COMPLETED;
+export type ReplicationCancelled = typeof REPLICATION_CANCELLED;
+export type ReplicationBlocked = {
+    readonly status: "blocked";
+    readonly reason: ReplicationBlockReason;
+};
+export type ReplicationPartial = {
+    readonly status: "partial";
+    readonly detail: unknown;
+};
+export type ReplicationFailed = {
+    readonly status: "failed";
+    readonly error: unknown;
+    readonly recoveryHint?: CentralCompatibilityRecoveryHint;
+};
+/**
+ * Result of a typed replication role.
+ *
+ * `completed` is intentionally not represented by a truthy value from the
+ * legacy `openReplication` method. Providers must opt into this singleton,
+ * which keeps `false` and `void` observable as non-completion for finite work.
+ */
+export type ReplicationOutcome = ReplicationCompleted | ReplicationCancelled | ReplicationBlocked | ReplicationPartial | ReplicationFailed;
+/** Preparation required before an ordinary operation may use a provider. */
+export interface ReplicationReadinessRequirements {
+    readonly centralRemotePreparation: "required" | "not-applicable";
+}
+/** Shared readiness contract for providers backed by the central remote. */
+export declare const CENTRAL_REMOTE_REPLICATION_READINESS: Readonly<{
+    readonly centralRemotePreparation: "required";
+}>;
+/** Shared readiness contract for peer-to-peer providers without a central remote. */
+export declare const PEER_REPLICATION_READINESS: Readonly<{
+    readonly centralRemotePreparation: "not-applicable";
+}>;
+/** Return whether a typed replication result represents completed work. */
+export declare function isReplicationCompleted(outcome: ReplicationOutcome): outcome is ReplicationCompleted;
+export declare function replicationBlocked(reason: ReplicationBlockReason): ReplicationBlocked;
+export declare function replicationFailed(error: unknown, recoveryHint?: CentralCompatibilityRecoveryHint): ReplicationFailed;
+export type UserInitiatedOneShotRunner = (replicator: ReplicatorInstance, setting: RemoteDBSettings, request: UserInitiatedOneShotRequest) => Promise<ReplicationOutcome>;
+export type UnattendedOneShotRunner = (replicator: ReplicatorInstance, setting: RemoteDBSettings, request: UnattendedOneShotRequest) => Promise<ReplicationOutcome>;
+/**
+ * Register a provider-owned Continuous task and settle its startup request.
+ *
+ * The runner must return after task ownership and pre-controller cancellation
+ * have been registered. It must not retain the caller's active-publication
+ * admission for the lifetime of the long-lived transfer.
+ */
+export type ContinuousRunner = (replicator: ReplicatorInstance, setting: RemoteDBSettings, request: ContinuousReplicationRequest) => Promise<ReplicationOutcome>;
+/**
+ * Request cancellation of finite transfer work on the currently active
+ * replicator. A `completed` outcome confirms that the stop request was
+ * accepted; it does not claim rollback of work which had already settled.
+ */
+export type StopActiveTransferRunner = (replicator: ReplicatorInstance) => Promise<ReplicationOutcome>;
+/**
+ * Opaque provider-owned projection of every setting which binds an active Replicator.
+ * It is private comparison state and must not be logged, persisted, or displayed.
+ */
+export type ReplicatorConfigurationIdentity = string;
+/** One host-composed provider and every role which may use its active instance. */
+export interface ReplicatorProviderDefinition<TKind extends RemoteType = RemoteType> {
+    /** Canonical persisted remote kind used for provider selection. */
+    readonly kind: TKind;
+    /** Human-readable diagnostic label; never use it as a machine decision. */
+    readonly diagnosticName: string;
+    /** Preparation gates required before an ordinary replication role runs. */
+    readonly readiness: ReplicationReadinessRequirements;
+    /** Return whether the effective settings are sufficient to construct this provider. */
+    readonly isConfigured: (setting: RemoteDBSettings) => boolean;
+    /** Project the fully merged effective settings to this provider's stable binding identity. */
+    readonly configurationIdentity: (setting: RemoteDBSettings) => ReplicatorConfigurationIdentity;
+    /** Construct a replicator from the fully merged effective settings. */
+    readonly create: (setting: ObsidianLiveSyncSettings) => Promise<ReplicatorInstance | undefined | false>;
+    /** Exhaustive provider-owned catalogue for finite remote resources. */
+    readonly remoteResources: RemoteResourceCapabilities;
+    /** Optional provider-owned central-remote administration runner. */
+    readonly centralRemoteAdministration?: CapabilitySupport<CentralRemoteAdministrationRunner>;
+    /** Finite role carrying explicit user-interaction authority. */
+    readonly userInitiatedOneShot: CapabilitySupport<UserInitiatedOneShotRunner>;
+    /** Finite role which must not request user interaction. */
+    readonly unattendedOneShot: CapabilitySupport<UnattendedOneShotRunner>;
+    /** Explicit support decision for ordinary long-lived Continuous replication. */
+    readonly continuous: CapabilitySupport<ContinuousRunner>;
+    /** Bounded cancellation request for transfer work on the active instance. */
+    readonly stopActiveTransfer: CapabilitySupport<StopActiveTransferRunner>;
+}
+/** The atomic provider, Replicator, and binding identity published by the owner service. */
+export interface ActiveReplicatorContext<TKind extends RemoteType = RemoteType> {
+    readonly provider: ReplicatorProviderDefinition<TKind>;
+    readonly replicator: ReplicatorInstance;
+    /** Private comparison state; callers must not log, persist, or display it. */
+    readonly configurationIdentity: ReplicatorConfigurationIdentity;
+}
+/** Immutable source of one failed attempt, safe to carry after its reservation is released. */
+export interface ReplicationAttemptFailure {
+    readonly context: ActiveReplicatorContext;
+    readonly setting: ObsidianLiveSyncSettings;
+    readonly outcome: ReplicationFailed;
+}
+/** Immutable failure source plus the interaction authority of its original request. */
+export interface ReplicationFailureRequest extends ReplicationAttemptFailure {
+    readonly showMessage: boolean;
+    readonly interaction: InteractionAuthority;
+}
+/** Return whether one detached setting still belongs to the admitted publication. */
+export declare function isActiveReplicatorContextBoundToSetting(context: ActiveReplicatorContext, setting: RemoteDBSettings): boolean;
+export type ReplicatorProviderDefinitionMap = ReadonlyMap<RemoteType, ReplicatorProviderDefinition>;
+/**
+ * Define exactly the provider subset composed by a host.
+ *
+ * The tuple is the host's closed catalogue for this composition. The mapped
+ * argument makes every selected kind required at compile time, while the
+ * runtime checks reject duplicate, omitted, or extra definitions. A host can
+ * therefore omit a provider intentionally, but cannot silently select a
+ * partially defined provider.
+ */
+export declare function defineReplicatorProviderDefinitions<const TKind extends readonly RemoteType[]>(kinds: TKind, definitions: {
+    readonly [K in TKind[number]]: ReplicatorProviderDefinition<K>;
+}): ReplicatorProviderDefinitionMap;
+/**
+ * Convert a legacy `openReplication` result to the typed finite outcome.
+ * `void` is not a success signal for a finite operation.
+ */
+export declare function outcomeFromFiniteOpenReplication(result: void | boolean, recoveryHint?: CentralCompatibilityRecoveryHint): ReplicationOutcome;
+/**
+ * Convert a legacy `openReplication` result to a continuous-start outcome.
+ * A provider which returns `void` has accepted the start request, whereas an
+ * explicit `false` still reports a failed start.
+ */
+export declare function outcomeFromContinuousOpenReplication(result: void | boolean): ReplicationOutcome;
+/**
+ * Adapt legacy `openReplication` for package and test compatibility.
+ *
+ * Current central providers use exact-outcome wrappers; this
+ * adapter remains for consumers and tests which still expose the legacy role.
+ */
+export declare function supportedOpenReplicationOneShot(): SupportedCapability<UserInitiatedOneShotRunner>;
+/**
+ * Adapt legacy `openReplication` for unattended package and test compatibility.
+ *
+ * Current central providers use exact-outcome wrappers; this
+ * adapter remains for consumers and tests which still expose the legacy role.
+ */
+export declare function supportedOpenReplicationUnattended(): SupportedCapability<UnattendedOneShotRunner>;
+export declare function supportedOpenReplicationContinuous(): SupportedCapability<ContinuousRunner>;
+/**
+ * Adapt the legacy termination hook to the typed active-transfer capability.
+ *
+ * `terminateSync` is intentionally awaited even though existing replicators
+ * implement it synchronously. This keeps the capability boundary valid for a
+ * provider whose cancellation work needs to settle asynchronously.
+ */
+export declare function supportedStopActiveTransfer(): SupportedCapability<StopActiveTransferRunner>;

package/dist/replication/ReplicatorProvider.js

@@ -0,0 +1,145 @@
+import { supportedCapability } from "./ProviderCapability.js";
+import {
+  CAPABILITY_NOT_APPLICABLE,
+  CAPABILITY_NOT_IMPLEMENTED,
+  CAPABILITY_SUPPORT_KINDS,
+  CAPABILITY_UNAVAILABLE_REASONS,
+  supportedCapability as supportedCapability2
+} from "./ProviderCapability.js";
+const NO_INTERACTION = Object.freeze({ kind: "forbidden" });
+const USER_INITIATED_REPLICATION_AUTHORITY = Object.freeze({
+  kind: "permitted",
+  permissions: Object.freeze({
+    peerSelection: true,
+    localPeerAdmission: true,
+    configurationExchange: true,
+    failureRecovery: true
+  })
+});
+const REPLICATION_COMPLETED = Object.freeze({ status: "completed" });
+const REPLICATION_CANCELLED = Object.freeze({ status: "cancelled" });
+const CENTRAL_REMOTE_REPLICATION_READINESS = Object.freeze({
+  centralRemotePreparation: "required"
+});
+const PEER_REPLICATION_READINESS = Object.freeze({
+  centralRemotePreparation: "not-applicable"
+});
+function isReplicationCompleted(outcome) {
+  return outcome.status === "completed";
+}
+function replicationBlocked(reason) {
+  return { status: "blocked", reason };
+}
+function replicationFailed(error, recoveryHint) {
+  return {
+    status: "failed",
+    error,
+    ...recoveryHint === void 0 ? {} : { recoveryHint }
+  };
+}
+function isActiveReplicatorContextBoundToSetting(context, setting) {
+  try {
+    return setting.remoteType === context.provider.kind && context.provider.isConfigured(setting) && context.provider.configurationIdentity(setting) === context.configurationIdentity;
+  } catch {
+    return false;
+  }
+}
+function defineReplicatorProviderDefinitions(kinds, definitions) {
+  const selectedKinds = new Set(kinds);
+  if (selectedKinds.size !== kinds.length) {
+    throw new Error("Replicator provider kinds must be unique.");
+  }
+  if (Object.keys(definitions).length !== selectedKinds.size) {
+    throw new Error("Replicator provider definitions must match the selected provider kinds.");
+  }
+  const result = /* @__PURE__ */ new Map();
+  for (const kind of kinds) {
+    const definition = definitions[kind];
+    if (!definition || definition.kind !== kind) {
+      throw new Error(`Replicator provider definition does not match '${kind}'.`);
+    }
+    result.set(kind, definition);
+  }
+  return result;
+}
+function outcomeFromFiniteOpenReplication(result, recoveryHint) {
+  return result === true ? REPLICATION_COMPLETED : replicationFailed(new Error("The provider did not complete finite replication."), recoveryHint);
+}
+function outcomeFromContinuousOpenReplication(result) {
+  return result === false ? replicationFailed(new Error("The provider rejected continuous replication.")) : REPLICATION_COMPLETED;
+}
+function supportedOpenReplicationOneShot() {
+  return supportedCapability(async (replicator, setting, request) => {
+    try {
+      const result = await replicator.openReplication(
+        setting,
+        false,
+        request.interaction.kind === "permitted" && request.interaction.permissions.failureRecovery,
+        false
+      );
+      return outcomeFromFiniteOpenReplication(result);
+    } catch (error) {
+      return replicationFailed(error);
+    }
+  });
+}
+function supportedOpenReplicationUnattended() {
+  return supportedCapability(async (replicator, setting, request) => {
+    if (request.interaction.kind !== NO_INTERACTION.kind) {
+      return replicationBlocked("interaction-required");
+    }
+    try {
+      const result = await replicator.openReplication(setting, false, false, false);
+      return outcomeFromFiniteOpenReplication(result);
+    } catch (error) {
+      return replicationFailed(error);
+    }
+  });
+}
+function supportedOpenReplicationContinuous() {
+  return supportedCapability(async (replicator, setting, request) => {
+    if (request.interaction.kind !== NO_INTERACTION.kind) {
+      return replicationBlocked("interaction-required");
+    }
+    try {
+      const result = await replicator.openReplication(setting, true, false, false);
+      return outcomeFromContinuousOpenReplication(result);
+    } catch (error) {
+      return replicationFailed(error);
+    }
+  });
+}
+function supportedStopActiveTransfer() {
+  return supportedCapability(async (replicator) => {
+    try {
+      await replicator.terminateSync();
+      return REPLICATION_COMPLETED;
+    } catch (error) {
+      return replicationFailed(error);
+    }
+  });
+}
+export {
+  CAPABILITY_NOT_APPLICABLE,
+  CAPABILITY_NOT_IMPLEMENTED,
+  CAPABILITY_SUPPORT_KINDS,
+  CAPABILITY_UNAVAILABLE_REASONS,
+  CENTRAL_REMOTE_REPLICATION_READINESS,
+  NO_INTERACTION,
+  PEER_REPLICATION_READINESS,
+  REPLICATION_CANCELLED,
+  REPLICATION_COMPLETED,
+  USER_INITIATED_REPLICATION_AUTHORITY,
+  defineReplicatorProviderDefinitions,
+  isActiveReplicatorContextBoundToSetting,
+  isReplicationCompleted,
+  outcomeFromContinuousOpenReplication,
+  outcomeFromFiniteOpenReplication,
+  replicationBlocked,
+  replicationFailed,
+  supportedCapability2 as supportedCapability,
+  supportedOpenReplicationContinuous,
+  supportedOpenReplicationOneShot,
+  supportedOpenReplicationUnattended,
+  supportedStopActiveTransfer
+};

package/dist/replication/couchdb/LiveSyncReplicator.d.ts

@@ -1,10 +1,16 @@
 import { type EntryDoc, type RemoteDBSettings, type EntryLeaf, type SyncParameters, type DatabaseEntry, type NodeData, type RemotePreferredTweakResult } from "../../common/types.js";
 import { LiveSyncAbstractReplicator, type LiveSyncReplicatorEnv, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
-import type { ServiceHub } from "../../services/ServiceHub.js";
 import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "../../services/base/RemoteConnection.js";
+import { type CentralCompatibilityDecisionRecorder } from "../CentralCompatibility.js";
+import { type ReplicationOutcome } from "../ReplicatorProvider.js";
 export type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "../../services/base/RemoteConnection.js";
+/**
+ * Compatibility constructor environment for the CouchDB Replicator facade.
+ *
+ * CouchDB adds only the bounded one-shot preflight policy to the shared
+ * Replicator environment. Active-provider capabilities remain separate.
+ */
 export interface LiveSyncCouchDBReplicatorEnv extends LiveSyncReplicatorEnv {
-    services: ServiceHub;
     /** Internal injection point for the bounded one-shot connectivity preflight. */
     oneShotConnectivityTimeoutMs?: number;
 }
@@ -26,6 +32,13 @@ export interface CouchDBReplicationConnection extends OwnedCouchDBConnection<Ent
 }
 export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
     env: LiveSyncCouchDBReplicatorEnv;
+    /**
+     * Keep Continuous ownership visible before CouchDB has created its live
+     * controller, so a stop request cannot be lost during catch-up.
+     */
+    private continuousTask;
+    private continuousStopWaiter;
+    private continuousStopRequested;
     isMobile(): boolean;
     constructor(env: LiveSyncCouchDBReplicatorEnv);
     getInitialSyncParameters(setting: RemoteDBSettings): Promise<SyncParameters>;
@@ -33,8 +46,23 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
     putSyncParameters(setting: RemoteDBSettings, params: SyncParameters): Promise<boolean>;
     getReplicationPBKDF2Salt(setting: RemoteDBSettings, refresh?: boolean): Promise<Uint8Array<ArrayBuffer>>;
     migrate(from: number, to: number): Promise<boolean>;
-    terminateSync(): void;
+    /** Abort only the active controller; internal transitions must not await their own task. */
+    private abortController;
+    /**
+     * Request cancellation of the current transfer and share the tracked
+     * Continuous settlement when startup has not created a controller yet.
+     */
+    terminateSync(): Promise<void>;
     openReplication(setting: RemoteDBSettings, keepAlive: boolean, showResult: boolean, ignoreCleanLock: boolean): Promise<boolean>;
+    /**
+     * Run one finite CouchDB attempt and retain only its own compatibility result.
+     *
+     * The decision is stack-local. A transport failure before assessment has no
+     * recovery hint, and a rejected assessment cannot leak into a later attempt.
+     */
+    openOneShotReplicationWithOutcome(setting: RemoteDBSettings, showResult: boolean, ignoreCleanLock?: boolean): Promise<ReplicationOutcome>;
+    /** Capture the compatibility decision made by this exact directional connection. */
+    private runOneShotReplicationWithOutcome;
     replicationActivated(showResult: boolean): void;
     replicationChangeDetected(e: PouchDB.Replication.SyncResult<EntryDoc>, showResult: boolean, docSentOnStart: number, docArrivedOnStart: number): Promise<void>;
     replicationCompleted(showResult: boolean): void;
@@ -52,21 +80,39 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
     getLastTransferredSeqOfChunks(localDB: PouchDB.Database, remoteID: number): Promise<ReturnType<typeof this.getEmptyMaxEntry>>;
     updateMaxTransferredSeqOnChunks(localDB: PouchDB.Database, remoteID: number, seqStatusMap: Record<number, boolean>): Promise<ReturnType<typeof this.getEmptyMaxEntry>>;
     sendChunks(setting: RemoteDBSettings, remoteDB: PouchDB.Database<EntryDoc> | undefined, showResult: boolean, fromSeq?: number | string): Promise<boolean>;
-    openOneShotReplication(setting: RemoteDBSettings, showResult: boolean, retrying: boolean, syncMode: "sync" | "pullOnly" | "pushOnly", ignoreCleanLock?: boolean): Promise<boolean>;
+    /** Run one finite transfer through the legacy boolean settlement contract. */
+    openOneShotReplication(setting: RemoteDBSettings, showResult: boolean, retrying: boolean, syncMode: "sync" | "pullOnly" | "pushOnly", ignoreCleanLock?: boolean, recordCompatibilityDecision?: CentralCompatibilityDecisionRecorder, cancellationRequested?: () => boolean): Promise<boolean>;
+    /**
+     * Run one finite CouchDB transfer and close its owned remote connection.
+     *
+     * The caller which enters the shared task owns Security Seed preparation,
+     * transfer, and any retry or resurrection continuation. A joining caller
+     * waits for the shared step only so it cannot race the owner, then receives
+     * the internal non-admission result without running that continuation.
+     *
+     * Continuous catch-up supplies `cancellationRequested` so a stop observed
+     * during awaited preparation cannot proceed to a later connection or
+     * controller. The admitted owner retains the established transfer behaviour.
+     */
+    private runOneShotReplication;
     private checkOneShotReplicationConnectivity;
     private closeRemoteConnection;
     private withRemoteConnection;
     replicateAllToServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
+    replicateAllToServerWithOutcome(setting: RemoteDBSettings, showingNotice?: boolean): Promise<ReplicationOutcome>;
     replicateAllFromServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
+    replicateAllFromServerWithOutcome(setting: RemoteDBSettings, showingNotice?: boolean): Promise<ReplicationOutcome>;
     private reportConnectivityPreflightTimeout;
-    checkReplicationConnectivity(setting: RemoteDBSettings, keepAlive: boolean, skipCheck: boolean, showResult: boolean, ignoreCleanLock?: boolean, connectionOptions?: RemoteConnectionOpenOptions): Promise<false | CouchDBReplicationConnection>;
+    checkReplicationConnectivity(setting: RemoteDBSettings, keepAlive: boolean, skipCheck: boolean, showResult: boolean, ignoreCleanLock?: boolean, connectionOptions?: RemoteConnectionOpenOptions, recordCompatibilityDecision?: CentralCompatibilityDecisionRecorder): Promise<false | CouchDBReplicationConnection>;
     openContinuousReplication(setting: RemoteDBSettings, showResult: boolean, retrying: boolean): Promise<boolean>;
-    closeReplication(): void;
+    private clearContinuousTask;
+    private runContinuousReplication;
+    closeReplication(): Promise<void>;
     tryResetRemoteDatabase(setting: RemoteDBSettings): Promise<void>;
     tryCreateRemoteDatabase(setting: RemoteDBSettings): Promise<void>;
     markRemoteLocked(setting: RemoteDBSettings, locked: boolean, lockByClean: boolean): Promise<void>;
     markRemoteResolved(setting: RemoteDBSettings): Promise<void>;
-    connectRemoteCouchDBWithSetting(settings: RemoteDBSettings, isMobile: boolean, performSetup?: boolean, skipInfo?: boolean, connectionOptions?: RemoteConnectionOpenOptions): Promise<string | OwnedCouchDBConnection<EntryDoc>> | "Empty passphrases cannot be used without explicit permission";
+    connectRemoteCouchDBWithSetting(settings: RemoteDBSettings, isMobile: boolean, performSetup?: boolean, skipInfo?: boolean, connectionOptions?: RemoteConnectionOpenOptions): Promise<string | OwnedCouchDBConnection<EntryDoc>>;
     private openOwnedConnection;
     /**
      * Opens a raw PouchDB handle for compatibility with earlier Commonlib
@@ -94,7 +140,7 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
      * @throws {Error} If the document could not be put.
      */
     putRemoteDocument<T extends DatabaseEntry>(settings: RemoteDBSettings, doc: T, db?: PouchDB.Database<T>): Promise<PouchDB.Core.Response>;
-    fetchRemoteChunks(missingChunks: string[], showResult: boolean): Promise<false | EntryLeaf[]>;
+    fetchRemoteChunks(missingChunks: string[], showResult: boolean, setting?: RemoteDBSettings): Promise<false | EntryLeaf[]>;
     tryConnectRemote(setting: RemoteDBSettings, showResult?: boolean): Promise<boolean>;
     resetRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
     setPreferredRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;