@vrtmrz/livesync-commonlib 0.1.19 → 0.1.20

package/dist/pouchdb/ReplicatorShim.d.ts

@@ -1,8 +1,11 @@
+/** A stored document carrying the change-feed metadata used by the shim. */
 export type SomeDocument<T extends object> = PouchDB.Core.ExistingDocument<T> & PouchDB.Core.ChangesMeta;
 /**
- * Minimal subset of the PouchDB public API required by {@link replicateShim}.
- * Both a real `PouchDB.Database` and an {@link RpcPouchDBProxy} satisfy this
- * interface, allowing replication across an RPC transport.
+ * Structural database boundary required by {@link replicateShim}.
+ *
+ * Listing only the operations used by the algorithm lets a local
+ * `PouchDB.Database` and an RPC-backed proxy participate without presenting
+ * the proxy as a complete PouchDB implementation.
  */
 export type PouchDBShim<T extends object> = {
     info: () => Promise<PouchDB.Core.DatabaseInfo>;
@@ -13,26 +16,62 @@ export type PouchDBShim<T extends object> = {
     put: (doc: PouchDB.Core.PutDocument<T>, options?: PouchDB.Core.PutOptions) => Promise<PouchDB.Core.Response>;
     get: (id: string, options?: PouchDB.Core.GetOptions) => Promise<T & PouchDB.Core.IdMeta & PouchDB.Core.GetMeta>;
 };
+/** A local PouchDB database or a structural shim with the same required operations. */
 type CompatibleDatabase<T extends object> = PouchDB.Database<SomeDocument<T>> | PouchDBShim<SomeDocument<T>>;
 /** Upserts a document by `id`, calling `func` to produce the updated version. */
 export declare function upsert<V extends object, TDB extends CompatibleDatabase<object> = CompatibleDatabase<any>, T extends SomeDocument<V> = SomeDocument<V>>(db: TDB, id: string, func: (doc: T) => T): Promise<T>;
+/** Batch and cancellation policy shared by finite and continuous shim replication. */
 export type ShimReplicationOptionBase = {
     rewind?: boolean;
     batch_size?: number;
+    /** Abort before a new batch starts, or after the current batch settles. */
+    signal?: AbortSignal;
 };
+/** Options for a finite replication which settles after catching up or cancellation. */
 export type ShimReplicationOneShot = {
     live?: false;
+    /** Legacy cancellation option retained for existing callers. */
     controller?: AbortController;
 } & ShimReplicationOptionBase;
+/** Options for replication which continues watching until its controller cancels it. */
 export type ShimReplicationOptionContinuous = {
     live: true;
     controller: AbortController;
 } & ShimReplicationOptionBase;
+/** Selects finite or continuous shim replication. */
 export type ShimReplicationOption = ShimReplicationOneShot | ShimReplicationOptionContinuous;
+/** Explicit terminal state returned by {@link replicateShim}. */
+export type ShimReplicationOutcome = ShimReplicationCompleted | ShimReplicationCancelled;
+export type ShimReplicationCompleted = {
+    readonly status: "completed";
+};
+export type ShimReplicationCancelled = {
+    readonly status: "cancelled";
+};
+/** Details of a document whose requested bulk write did not succeed. */
+export type ShimReplicationWriteFailure = {
+    readonly index: number;
+    readonly id: string;
+    readonly revision: string | undefined;
+    readonly result: PouchDB.Core.Response | PouchDB.Core.Error | undefined;
+};
+/**
+ * Raised when a batch cannot be committed safely.
+ *
+ * PouchDB resolves `bulkDocs` even when an individual document fails.  The
+ * replication shim exposes that failure as an error so that callers cannot
+ * mistake a partially written batch for a committed checkpoint.
+ */
+export declare class ShimReplicationError extends Error {
+    readonly failures: readonly ShimReplicationWriteFailure[];
+    constructor(message: string, failures: readonly ShimReplicationWriteFailure[]);
+}
+/** Sequence boundary committed by one successfully written batch. */
 export type ProgressInfo = {
     lastSeq: number;
     maxSeqInBatch: number;
 };
+/** Receives the documents and committed sequence boundary for each completed batch. */
 export type ShimReplicationProgressReportFunc<T extends object> = (progress: SomeDocument<T>[], progressInfo: ProgressInfo) => Promise<void>;
 /**
  * Replicate documents from `sourceDB` into `targetDB` using a CouchDB-style
@@ -47,5 +86,5 @@ export type ShimReplicationProgressReportFunc<T extends object> = (progress: Som
  * @param progress  Called after each batch with the written documents.
  * @param option    Replication options (live mode, batch size, abort signal).
  */
-export declare function replicateShim<T extends CompatibleDatabase<V>, U extends CompatibleDatabase<V>, V extends object>(targetDB: T, sourceDB: U, progress: ShimReplicationProgressReportFunc<V>, option?: ShimReplicationOption): Promise<void>;
+export declare function replicateShim<T extends CompatibleDatabase<V>, U extends CompatibleDatabase<V>, V extends object>(targetDB: T, sourceDB: U, progress: ShimReplicationProgressReportFunc<V>, option?: ShimReplicationOption): Promise<ShimReplicationOutcome>;
 export {};

package/dist/pouchdb/ReplicatorShim.js

@@ -23,6 +23,14 @@ async function upsert(db, id, func) {
     throw ex;
   }
 }
+class ShimReplicationError extends Error {
+  constructor(message, failures) {
+    super(message);
+    this.failures = failures;
+    this.name = "ShimReplicationError";
+  }
+  failures;
+}
 function parseSeq(seq) {
   return parseInt(String(seq).split("-")[0], 10);
 }
@@ -40,11 +48,24 @@ function sortBySeq(docs, changesResults) {
   }
   return docs.slice().sort((a, b) => (maxSeqById.get(a._id) ?? 0) - (maxSeqById.get(b._id) ?? 0));
 }
+function isSuccessfulBulkDocResult(result) {
+  return typeof result === "object" && result !== null && "ok" in result && result.ok === true;
+}
+function isCancellationError(error) {
+  if (typeof error !== "object" || error === null) return false;
+  return "code" in error && error.code === "CANCELLED" || "name" in error && error.name === "AbortError";
+}
 async function replicateShim(targetDB, sourceDB, progress, option = {}) {
+  const signal = option.signal ?? option.controller?.signal;
+  if (signal?.aborted) {
+    Logger(`Replication cancelled`, LOG_LEVEL_VERBOSE);
+    return { status: "cancelled" };
+  }
   try {
     const [targetDBInfo, sourceDBInfo] = await Promise.all([targetDB.info(), sourceDB.info()]);
     const maxNumSeq = parseSeq(sourceDBInfo.update_seq);
-    await serialized(`replication-${targetDBInfo.db_name}-${sourceDBInfo.db_name}`, async () => {
+    const outcome = await serialized(`replication-${targetDBInfo.db_name}-${sourceDBInfo.db_name}`, async () => {
+      if (signal?.aborted) return { status: "cancelled" };
       Logger(
         `Replication ${sourceDBInfo.db_name} (${sourceDBInfo.update_seq}) \u2192 ${targetDBInfo.db_name} (${targetDBInfo.update_seq})`,
         LOG_LEVEL_VERBOSE
@@ -66,17 +87,62 @@ async function replicateShim(targetDB, sourceDB, progress, option = {}) {
       Logger(`Starting from seq ${since}`, LOG_LEVEL_VERBOSE);
       const batchSize = option.batch_size ?? 33;
       while (true) {
+        if (signal?.aborted) return { status: "cancelled" };
         const changes = await sourceDB.changes({ since, style: "all_docs", limit: batchSize });
-        if (changes.results.length === 0) break;
-        if (option.controller?.signal?.aborted) break;
+        if (changes.results.length === 0) {
+          return signal?.aborted ? { status: "cancelled" } : { status: "completed" };
+        }
+        if (signal?.aborted) return { status: "cancelled" };
         const changesResults = changes.results;
         const revsDiffParam = buildRevsDiffParam(changesResults);
         const diff = await targetDB.revsDiff(revsDiffParam);
+        if (signal?.aborted) return { status: "cancelled" };
         const missingRequests = Object.entries(diff).filter(([, entry]) => entry.missing !== void 0).flatMap(([id, entry]) => entry.missing.map((rev) => ({ id, rev })));
         if (missingRequests.length > 0) {
           const bulkGetResult = await sourceDB.bulkGet({ docs: missingRequests, revs: true });
           const fetchedDocs = bulkGetResult.results.flatMap((r) => r.docs).filter((d) => "ok" in d).map((d) => d.ok);
-          await targetDB.bulkDocs(fetchedDocs, { new_edits: false });
+          if (signal?.aborted) return { status: "cancelled" };
+          const fetchedRevisionKeys = new Set(
+            fetchedDocs.map((doc) => `${doc._id}\0${String(doc._rev)}`)
+          );
+          const unavailableRequests = missingRequests.filter(
+            ({ id, rev }) => !fetchedRevisionKeys.has(`${id}\0${rev}`)
+          );
+          if (unavailableRequests.length > 0) {
+            const unavailableFailures = unavailableRequests.map(
+              (request, index) => ({
+                index,
+                id: request.id,
+                revision: request.rev,
+                result: void 0
+              })
+            );
+            throw new ShimReplicationError(
+              `Could not fetch ${unavailableRequests.length} required revision(s)`,
+              unavailableFailures
+            );
+          }
+          const writeResults = await targetDB.bulkDocs(fetchedDocs, { new_edits: false });
+          const failedWrites = writeResults.flatMap((result, index) => {
+            if (isSuccessfulBulkDocResult(result)) return [];
+            const resultId = typeof result === "object" && result !== null && "id" in result ? result.id : void 0;
+            const owningIndex = typeof resultId === "string" ? fetchedDocs.findIndex((doc) => doc._id === resultId) : -1;
+            const owningDocument = fetchedDocs[owningIndex >= 0 ? owningIndex : index];
+            return [
+              {
+                index: owningIndex >= 0 ? owningIndex : index,
+                id: typeof resultId === "string" ? resultId : owningDocument?._id ?? "",
+                revision: owningDocument?._rev,
+                result
+              }
+            ];
+          });
+          if (failedWrites.length > 0) {
+            throw new ShimReplicationError(
+              `Target rejected ${failedWrites.length} document write(s)`,
+              failedWrites
+            );
+          }
           const uniqueIds = [...new Set(changesResults.map((c) => c.id))];
           const refreshResult = await targetDB.bulkGet({ docs: uniqueIds.map((id) => ({ id })) });
           const refreshedDocs = refreshResult.results.flatMap((r) => r.docs).filter((d) => "ok" in d).map((d) => d.ok);
@@ -94,16 +160,23 @@ async function replicateShim(targetDB, sourceDB, progress, option = {}) {
           ...doc,
           since
         }));
+        if (signal?.aborted) return { status: "cancelled" };
       }
     });
+    Logger(outcome.status === "cancelled" ? `Replication cancelled` : `Replication completed`, LOG_LEVEL_VERBOSE);
+    return outcome;
   } catch (ex) {
+    if (signal?.aborted && isCancellationError(ex)) {
+      Logger(`Replication cancelled`, LOG_LEVEL_VERBOSE);
+      return { status: "cancelled" };
+    }
     Logger(`Replication failed`, LOG_LEVEL_VERBOSE);
     Logger(ex, LOG_LEVEL_VERBOSE);
     throw ex;
   }
-  Logger(`Replication completed`, LOG_LEVEL_VERBOSE);
 }
 export {
+  ShimReplicationError,
   replicateShim,
   upsert
 };

package/dist/replication/CentralCompatibility.d.ts

@@ -0,0 +1,38 @@
+import type { TweakValues } from "../common/types.js";
+/** Stable machine states for one central-remote compatibility assessment. */
+export declare const CENTRAL_COMPATIBILITY_STATUSES: Readonly<{
+    readonly NOT_ASSESSED: "not-assessed";
+    readonly ACCEPTED: "accepted";
+    readonly REJECTED: "rejected";
+}>;
+/** Stable machine reasons carried by a rejected compatibility assessment. */
+export declare const CENTRAL_COMPATIBILITY_REJECTION_REASONS: Readonly<{
+    readonly INCOMPATIBLE_VERSION: "incompatible-version";
+    readonly NODE_LOCKED: "node-locked";
+    readonly NODE_CLEANED: "node-cleaned";
+    readonly TWEAK_MISMATCH: "tweak-mismatch";
+}>;
+export type CentralCompatibilityRejectionReason = (typeof CENTRAL_COMPATIBILITY_REJECTION_REASONS)[keyof typeof CENTRAL_COMPATIBILITY_REJECTION_REASONS];
+export declare const CENTRAL_COMPATIBILITY_NOT_ASSESSED: Readonly<{
+    readonly status: "not-assessed";
+}>;
+export declare const CENTRAL_COMPATIBILITY_ACCEPTED: Readonly<{
+    readonly status: "accepted";
+}>;
+export interface CentralCompatibilityRejected {
+    readonly status: typeof CENTRAL_COMPATIBILITY_STATUSES.REJECTED;
+    readonly reason: CentralCompatibilityRejectionReason;
+    readonly preferredTweakValue?: Readonly<TweakValues>;
+}
+/** Immutable result produced by one provider-local compatibility assessment. */
+export type CentralCompatibilityDecision = typeof CENTRAL_COMPATIBILITY_NOT_ASSESSED | typeof CENTRAL_COMPATIBILITY_ACCEPTED | CentralCompatibilityRejected;
+/** Stack-local sink used while a provider owns the connection or client being assessed. */
+export type CentralCompatibilityDecisionRecorder = (decision: CentralCompatibilityDecision) => void;
+/** Immutable recovery input projected from the exact failed replication attempt. */
+export interface CentralCompatibilityRecoveryHint {
+    readonly reason: CentralCompatibilityRejectionReason;
+    readonly preferredTweakValue?: Readonly<TweakValues>;
+}
+export declare function centralCompatibilityRejected(reason: CentralCompatibilityRejectionReason, preferredTweakValue?: TweakValues): CentralCompatibilityRejected;
+/** Project only a rejected decision into the generic replication failure path. */
+export declare function centralCompatibilityRecoveryHint(decision: CentralCompatibilityDecision): CentralCompatibilityRecoveryHint | undefined;

package/dist/replication/CentralCompatibility.js

@@ -0,0 +1,39 @@
+const CENTRAL_COMPATIBILITY_STATUSES = Object.freeze({
+  NOT_ASSESSED: "not-assessed",
+  ACCEPTED: "accepted",
+  REJECTED: "rejected"
+});
+const CENTRAL_COMPATIBILITY_REJECTION_REASONS = Object.freeze({
+  INCOMPATIBLE_VERSION: "incompatible-version",
+  NODE_LOCKED: "node-locked",
+  NODE_CLEANED: "node-cleaned",
+  TWEAK_MISMATCH: "tweak-mismatch"
+});
+const CENTRAL_COMPATIBILITY_NOT_ASSESSED = Object.freeze({
+  status: CENTRAL_COMPATIBILITY_STATUSES.NOT_ASSESSED
+});
+const CENTRAL_COMPATIBILITY_ACCEPTED = Object.freeze({
+  status: CENTRAL_COMPATIBILITY_STATUSES.ACCEPTED
+});
+function centralCompatibilityRejected(reason, preferredTweakValue) {
+  return Object.freeze({
+    status: CENTRAL_COMPATIBILITY_STATUSES.REJECTED,
+    reason,
+    ...preferredTweakValue === void 0 ? {} : { preferredTweakValue: Object.freeze({ ...preferredTweakValue }) }
+  });
+}
+function centralCompatibilityRecoveryHint(decision) {
+  if (decision.status !== CENTRAL_COMPATIBILITY_STATUSES.REJECTED) return void 0;
+  return Object.freeze({
+    reason: decision.reason,
+    ...decision.preferredTweakValue === void 0 ? {} : { preferredTweakValue: decision.preferredTweakValue }
+  });
+}
+export {
+  CENTRAL_COMPATIBILITY_ACCEPTED,
+  CENTRAL_COMPATIBILITY_NOT_ASSESSED,
+  CENTRAL_COMPATIBILITY_REJECTION_REASONS,
+  CENTRAL_COMPATIBILITY_STATUSES,
+  centralCompatibilityRecoveryHint,
+  centralCompatibilityRejected
+};

package/dist/replication/CentralRemoteAdministration.d.ts

@@ -0,0 +1,84 @@
+import type { RemoteDBSettings } from "../common/types.js";
+import type { ReplicatorInstance } from "./ReplicatorInstance.js";
+/** Stable machine identifiers for central-remote administration mutations. */
+export declare const CENTRAL_REMOTE_ADMINISTRATION_ACTIONS: Readonly<{
+    readonly MARK_RESOLVED: "mark-resolved";
+    readonly LOCK: "lock";
+    readonly UNLOCK: "unlock";
+}>;
+/** Stable machine identifiers for central-remote administration settlement. */
+export declare const CENTRAL_REMOTE_ADMINISTRATION_RESULT_STATUSES: Readonly<{
+    readonly VERIFIED: "verified";
+    readonly VERIFICATION_FAILED: "verification-failed";
+}>;
+/** Stable machine identifiers for provider-specific observations. */
+export declare const CENTRAL_REMOTE_ADMINISTRATION_OBSERVATION_KINDS: Readonly<{
+    readonly MILESTONE: "milestone";
+}>;
+/** Stable machine reasons which must not be used as display or translation keys. */
+export declare const CENTRAL_REMOTE_ADMINISTRATION_FAILURE_REASONS: Readonly<{
+    readonly NO_ACTIVE_REPLICATOR: "no-active-replicator";
+    readonly ACTIVE_CONFIGURATION_MISMATCH: "active-configuration-mismatch";
+    readonly CAPABILITY_NOT_IMPLEMENTED: "capability-not-implemented";
+    readonly CAPABILITY_NOT_APPLICABLE: "capability-not-applicable";
+    readonly LOCAL_IDENTITY_UNAVAILABLE: "local-identity-unavailable";
+    readonly CONNECTION_FAILED: "connection-failed";
+    readonly MILESTONE_NOT_FOUND: "milestone-not-found";
+    readonly MILESTONE_READ_FAILED: "milestone-read-failed";
+    readonly POSTCONDITION_MISMATCH: "postcondition-mismatch";
+}>;
+export type CentralRemoteAdministrationAction = (typeof CENTRAL_REMOTE_ADMINISTRATION_ACTIONS)[keyof typeof CENTRAL_REMOTE_ADMINISTRATION_ACTIONS];
+export type CentralRemoteAdministrationFailureReason = (typeof CENTRAL_REMOTE_ADMINISTRATION_FAILURE_REASONS)[keyof typeof CENTRAL_REMOTE_ADMINISTRATION_FAILURE_REASONS];
+/** One requested mutation of the central milestone protocol. */
+export interface CentralRemoteAdministrationRequest {
+    readonly action: CentralRemoteAdministrationAction;
+}
+/** Provider-independent projection of a central milestone after mutation. */
+export interface MilestoneCentralRemoteAdministrationObservation {
+    readonly kind: typeof CENTRAL_REMOTE_ADMINISTRATION_OBSERVATION_KINDS.MILESTONE;
+    readonly locked: boolean;
+    readonly accepted: boolean;
+    readonly nodeId: string;
+}
+export type CentralRemoteAdministrationObservation = MilestoneCentralRemoteAdministrationObservation;
+/** The requested mutation was observed in the provider's central milestone. */
+export interface CentralRemoteAdministrationVerified {
+    readonly status: typeof CENTRAL_REMOTE_ADMINISTRATION_RESULT_STATUSES.VERIFIED;
+    readonly observation: CentralRemoteAdministrationObservation;
+}
+/** The request settled without a verified postcondition. */
+export interface CentralRemoteAdministrationVerificationFailed {
+    readonly status: typeof CENTRAL_REMOTE_ADMINISTRATION_RESULT_STATUSES.VERIFICATION_FAILED;
+    readonly reason: CentralRemoteAdministrationFailureReason;
+    readonly observation?: CentralRemoteAdministrationObservation;
+    readonly detail?: unknown;
+}
+/**
+ * Settled central-remote administration result.
+ *
+ * Provider runners return verification failures. They must allow mutation
+ * exceptions to reject so a compatibility exit policy cannot hide a failed
+ * write behind an earlier command's historical success code.
+ */
+export type CentralRemoteAdministrationResult = CentralRemoteAdministrationVerified | CentralRemoteAdministrationVerificationFailed;
+/** Operations required by a provider which owns central remote administration. */
+export interface CentralRemoteAdministrationReplicator extends ReplicatorInstance {
+    readonly nodeid: string;
+    markRemoteResolved(setting: RemoteDBSettings): Promise<void>;
+    markRemoteLocked(setting: RemoteDBSettings, locked: boolean, lockByClean: boolean): Promise<void>;
+}
+/** Provider boundary which must narrow the active instance before mutation. */
+export type CentralRemoteAdministrationRunner = (replicator: ReplicatorInstance, setting: RemoteDBSettings, request: CentralRemoteAdministrationRequest) => Promise<CentralRemoteAdministrationResult>;
+/** Construct a verified result from the provider's postcondition observation. */
+export declare function centralRemoteAdministrationVerified(observation: CentralRemoteAdministrationObservation): CentralRemoteAdministrationVerified;
+/** Construct a stable verification failure without converting mutation exceptions. */
+export declare function centralRemoteAdministrationVerificationFailed(reason: CentralRemoteAdministrationFailureReason, options?: {
+    readonly observation?: CentralRemoteAdministrationObservation;
+    readonly detail?: unknown;
+}): CentralRemoteAdministrationVerificationFailed;
+/** Narrow one settled administration result to its verified arm. */
+export declare function isCentralRemoteAdministrationVerified(result: CentralRemoteAdministrationResult): result is CentralRemoteAdministrationVerified;
+/** Apply the legacy mutation selected by a typed administration request. */
+export declare function applyCentralRemoteAdministrationMutation(replicator: CentralRemoteAdministrationReplicator, setting: RemoteDBSettings, action: CentralRemoteAdministrationAction): Promise<void>;
+/** Return whether an observed milestone proves the requested postcondition. */
+export declare function milestoneSatisfiesCentralRemoteAdministration(action: CentralRemoteAdministrationAction, observation: MilestoneCentralRemoteAdministrationObservation): boolean;

package/dist/replication/CentralRemoteAdministration.js

@@ -0,0 +1,71 @@
+import { CAPABILITY_UNAVAILABLE_REASONS } from "./ProviderCapability.js";
+const CENTRAL_REMOTE_ADMINISTRATION_ACTIONS = Object.freeze({
+  MARK_RESOLVED: "mark-resolved",
+  LOCK: "lock",
+  UNLOCK: "unlock"
+});
+const CENTRAL_REMOTE_ADMINISTRATION_RESULT_STATUSES = Object.freeze({
+  VERIFIED: "verified",
+  VERIFICATION_FAILED: "verification-failed"
+});
+const CENTRAL_REMOTE_ADMINISTRATION_OBSERVATION_KINDS = Object.freeze({
+  MILESTONE: "milestone"
+});
+const CENTRAL_REMOTE_ADMINISTRATION_FAILURE_REASONS = Object.freeze({
+  NO_ACTIVE_REPLICATOR: "no-active-replicator",
+  ACTIVE_CONFIGURATION_MISMATCH: "active-configuration-mismatch",
+  CAPABILITY_NOT_IMPLEMENTED: CAPABILITY_UNAVAILABLE_REASONS.NOT_IMPLEMENTED,
+  CAPABILITY_NOT_APPLICABLE: CAPABILITY_UNAVAILABLE_REASONS.NOT_APPLICABLE,
+  LOCAL_IDENTITY_UNAVAILABLE: "local-identity-unavailable",
+  CONNECTION_FAILED: "connection-failed",
+  MILESTONE_NOT_FOUND: "milestone-not-found",
+  MILESTONE_READ_FAILED: "milestone-read-failed",
+  POSTCONDITION_MISMATCH: "postcondition-mismatch"
+});
+function centralRemoteAdministrationVerified(observation) {
+  return { status: CENTRAL_REMOTE_ADMINISTRATION_RESULT_STATUSES.VERIFIED, observation };
+}
+function centralRemoteAdministrationVerificationFailed(reason, options = {}) {
+  return {
+    status: CENTRAL_REMOTE_ADMINISTRATION_RESULT_STATUSES.VERIFICATION_FAILED,
+    reason,
+    ...options
+  };
+}
+function isCentralRemoteAdministrationVerified(result) {
+  return result.status === CENTRAL_REMOTE_ADMINISTRATION_RESULT_STATUSES.VERIFIED;
+}
+async function applyCentralRemoteAdministrationMutation(replicator, setting, action) {
+  switch (action) {
+    case CENTRAL_REMOTE_ADMINISTRATION_ACTIONS.MARK_RESOLVED:
+      await replicator.markRemoteResolved(setting);
+      return;
+    case CENTRAL_REMOTE_ADMINISTRATION_ACTIONS.LOCK:
+      await replicator.markRemoteLocked(setting, true, false);
+      return;
+    case CENTRAL_REMOTE_ADMINISTRATION_ACTIONS.UNLOCK:
+      await replicator.markRemoteLocked(setting, false, false);
+      return;
+  }
+}
+function milestoneSatisfiesCentralRemoteAdministration(action, observation) {
+  switch (action) {
+    case CENTRAL_REMOTE_ADMINISTRATION_ACTIONS.MARK_RESOLVED:
+      return observation.accepted;
+    case CENTRAL_REMOTE_ADMINISTRATION_ACTIONS.LOCK:
+      return observation.locked;
+    case CENTRAL_REMOTE_ADMINISTRATION_ACTIONS.UNLOCK:
+      return !observation.locked;
+  }
+}
+export {
+  CENTRAL_REMOTE_ADMINISTRATION_ACTIONS,
+  CENTRAL_REMOTE_ADMINISTRATION_FAILURE_REASONS,
+  CENTRAL_REMOTE_ADMINISTRATION_OBSERVATION_KINDS,
+  CENTRAL_REMOTE_ADMINISTRATION_RESULT_STATUSES,
+  applyCentralRemoteAdministrationMutation,
+  centralRemoteAdministrationVerificationFailed,
+  centralRemoteAdministrationVerified,
+  isCentralRemoteAdministrationVerified,
+  milestoneSatisfiesCentralRemoteAdministration
+};

package/dist/replication/LiveSyncAbstractReplicator.d.ts

@@ -1,7 +1,8 @@
-import { type EntryDoc, type DatabaseConnectingStatus, type RemoteDBSettings, type EntryLeaf, type TweakValues, type RemotePreferredTweakResult, type NodeData } from "../common/types.js";
+import { type EntryDoc, type DatabaseConnectingStatus, type RemoteDBSettings, type TweakValues, type RemotePreferredTweakResult, type NodeData } from "../common/types.js";
 import type { RequiredServices } from "../interfaces/ServiceModule.js";
 import type { TranslationParameters } from "../services/base/MessageTranslator.js";
 import type { CommonlibMessageKey } from "../services/base/CommonlibMessages.js";
+import type { ReplicatorInstance } from "./ReplicatorInstance.js";
 export type ReplicationCallback = (e: PouchDB.Core.ExistingDocument<EntryDoc>[]) => Promise<boolean> | boolean;
 export type ReplicationStat = {
     sent: number;
@@ -12,6 +13,13 @@ export type ReplicationStat = {
     lastSyncPushSeq: number;
     syncStatus: DatabaseConnectingStatus;
 };
+/**
+ * Constructor environment shared by the legacy concrete Replicator facades.
+ *
+ * This compatibility boundary supplies host services to those facades. Active
+ * provider capabilities and their ownership are declared separately by the
+ * replication provider contracts.
+ */
 export interface LiveSyncReplicatorEnv {
     services: RequiredServices<"API" | "appLifecycle" | "setting" | "vault" | "database" | "databaseEvents" | "keyValueDB" | "replication" | "config" | "UI" | "replicator" | "remote">;
 }
@@ -19,7 +27,14 @@ export type RemoteDBStatus = {
     [key: string]: unknown;
     estimatedSize?: number;
 };
-export declare abstract class LiveSyncAbstractReplicator {
+/**
+ * Legacy compatibility facade around the small active Replicator contract.
+ *
+ * New active-provider control flow depends only on {@link ReplicatorInstance}.
+ * The additional abstract members remain temporarily for existing maintenance
+ * and setup consumers and are not capabilities promised by every provider.
+ */
+export declare abstract class LiveSyncAbstractReplicator implements ReplicatorInstance {
     syncStatus: DatabaseConnectingStatus;
     docArrived: number;
     docSent: number;
@@ -45,23 +60,21 @@ export declare abstract class LiveSyncAbstractReplicator {
     env: LiveSyncReplicatorEnv;
     initializeDatabaseForReplication(): Promise<boolean>;
     constructor(env: LiveSyncReplicatorEnv);
-    abstract terminateSync(): void;
+    abstract terminateSync(): void | Promise<void>;
     abstract openReplication(setting: RemoteDBSettings, keepAlive: boolean, showResult: boolean, ignoreCleanLock: boolean): Promise<void | boolean>;
     updateInfo: () => void;
     abstract tryConnectRemote(setting: RemoteDBSettings, showResult?: boolean): Promise<boolean>;
     abstract replicateAllToServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
     abstract replicateAllFromServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
-    abstract closeReplication(): void;
+    abstract closeReplication(): void | Promise<void>;
     abstract tryResetRemoteDatabase(setting: RemoteDBSettings): Promise<void>;
     abstract tryCreateRemoteDatabase(setting: RemoteDBSettings): Promise<void>;
     abstract markRemoteLocked(setting: RemoteDBSettings, locked: boolean, lockByClean: boolean): Promise<void>;
     abstract markRemoteResolved(setting: RemoteDBSettings): Promise<void>;
     abstract resetRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
     abstract setPreferredRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
-    abstract fetchRemoteChunks(missingChunks: string[], showResult: boolean): Promise<false | EntryLeaf[]>;
     abstract getRemoteStatus(setting: RemoteDBSettings): Promise<false | RemoteDBStatus>;
     abstract getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
-    abstract countCompromisedChunks(setting?: RemoteDBSettings): Promise<number | boolean>;
     abstract getConnectedDeviceList(setting?: RemoteDBSettings): Promise<false | {
         node_info: Record<string, NodeData>;
         accepted_nodes: string[];

package/dist/replication/ProviderCapability.d.ts

@@ -0,0 +1,32 @@
+/** Stable machine values for provider capability availability. */
+export declare const CAPABILITY_SUPPORT_KINDS: Readonly<{
+    readonly SUPPORTED: "supported";
+    readonly NOT_IMPLEMENTED: "not-implemented";
+    readonly NOT_APPLICABLE: "not-applicable";
+}>;
+/** Stable machine reasons for an unavailable provider capability. */
+export declare const CAPABILITY_UNAVAILABLE_REASONS: Readonly<{
+    readonly NOT_IMPLEMENTED: "capability-not-implemented";
+    readonly NOT_APPLICABLE: "capability-not-applicable";
+}>;
+/** A declared role is available, but its implementation is not included. */
+export type NotImplementedCapability = {
+    readonly kind: typeof CAPABILITY_SUPPORT_KINDS.NOT_IMPLEMENTED;
+    readonly reason: typeof CAPABILITY_UNAVAILABLE_REASONS.NOT_IMPLEMENTED;
+};
+/** A declared role does not apply to this provider. */
+export type NotApplicableCapability = {
+    readonly kind: typeof CAPABILITY_SUPPORT_KINDS.NOT_APPLICABLE;
+    readonly reason: typeof CAPABILITY_UNAVAILABLE_REASONS.NOT_APPLICABLE;
+};
+/** One available capability paired with the only runner allowed to perform its role. */
+export type SupportedCapability<TRole> = {
+    readonly kind: typeof CAPABILITY_SUPPORT_KINDS.SUPPORTED;
+    readonly run: TRole;
+};
+/** Provider capability declaration correlated with the role runner. */
+export type CapabilitySupport<TRole> = SupportedCapability<TRole> | NotImplementedCapability | NotApplicableCapability;
+export declare const CAPABILITY_NOT_IMPLEMENTED: NotImplementedCapability;
+export declare const CAPABILITY_NOT_APPLICABLE: NotApplicableCapability;
+/** Declare one implemented provider capability without repeating its machine value. */
+export declare function supportedCapability<TRole>(run: TRole): SupportedCapability<TRole>;

package/dist/replication/ProviderCapability.js

@@ -0,0 +1,27 @@
+const CAPABILITY_SUPPORT_KINDS = Object.freeze({
+  SUPPORTED: "supported",
+  NOT_IMPLEMENTED: "not-implemented",
+  NOT_APPLICABLE: "not-applicable"
+});
+const CAPABILITY_UNAVAILABLE_REASONS = Object.freeze({
+  NOT_IMPLEMENTED: "capability-not-implemented",
+  NOT_APPLICABLE: "capability-not-applicable"
+});
+const CAPABILITY_NOT_IMPLEMENTED = Object.freeze({
+  kind: CAPABILITY_SUPPORT_KINDS.NOT_IMPLEMENTED,
+  reason: CAPABILITY_UNAVAILABLE_REASONS.NOT_IMPLEMENTED
+});
+const CAPABILITY_NOT_APPLICABLE = Object.freeze({
+  kind: CAPABILITY_SUPPORT_KINDS.NOT_APPLICABLE,
+  reason: CAPABILITY_UNAVAILABLE_REASONS.NOT_APPLICABLE
+});
+function supportedCapability(run) {
+  return { kind: CAPABILITY_SUPPORT_KINDS.SUPPORTED, run };
+}
+export {
+  CAPABILITY_NOT_APPLICABLE,
+  CAPABILITY_NOT_IMPLEMENTED,
+  CAPABILITY_SUPPORT_KINDS,
+  CAPABILITY_UNAVAILABLE_REASONS,
+  supportedCapability
+};