@vrtmrz/livesync-commonlib 0.1.19 → 0.1.20

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

@@ -0,0 +1,191 @@
+import {
+  CAPABILITY_SUPPORT_KINDS,
+  NO_INTERACTION,
+  isActiveReplicatorContextBoundToSetting,
+  replicationBlocked,
+  replicationFailed
+} from "../../replication/ReplicatorProvider.js";
+import { asCopy } from "../../common/utils.object.js";
+class TypedReplicationCoordinator {
+  constructor(dependencies) {
+    this.dependencies = dependencies;
+  }
+  dependencies;
+  /**
+   * 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.
+   */
+  async runUserInitiated(request) {
+    const showMessage = request.interaction.kind === "permitted" && request.interaction.permissions.failureRecovery;
+    const ready = await this.acquireReadyContext(showMessage);
+    if ("status" in ready) return ready;
+    const capability = ready.provider.userInitiatedOneShot;
+    if (capability.kind !== CAPABILITY_SUPPORT_KINDS.SUPPORTED) {
+      return this.finishFiniteAttempt(replicationBlocked(capability.reason));
+    }
+    const settings = Object.freeze(asCopy(this.dependencies.currentSettings()));
+    return this.finishFiniteAttempt(
+      await this.runAdmittedFiniteActivity(
+        ready,
+        (context) => capability.run(context.replicator, settings, request),
+        settings,
+        request.interaction,
+        showMessage
+      )
+    );
+  }
+  /**
+   * 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.
+   */
+  async runUnattended(request) {
+    if (request.interaction.kind !== NO_INTERACTION.kind) {
+      return replicationBlocked("interaction-required");
+    }
+    const ready = await this.acquireReadyContext(false);
+    if ("status" in ready) return ready;
+    const capability = ready.provider.unattendedOneShot;
+    if (capability.kind !== CAPABILITY_SUPPORT_KINDS.SUPPORTED) {
+      return this.finishFiniteAttempt(replicationBlocked(capability.reason));
+    }
+    const settings = Object.freeze(asCopy(this.dependencies.currentSettings()));
+    return this.finishFiniteAttempt(
+      await this.runAdmittedFiniteActivity(
+        ready,
+        (context) => capability.run(context.replicator, settings, request),
+        settings,
+        NO_INTERACTION,
+        false
+      )
+    );
+  }
+  /**
+   * 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.
+   */
+  async startContinuous(request) {
+    if (request.interaction.kind !== NO_INTERACTION.kind) {
+      return replicationBlocked("interaction-required");
+    }
+    const context = await this.acquireContext();
+    if ("status" in context) return context;
+    const capability = context.provider.continuous;
+    if (capability.kind !== CAPABILITY_SUPPORT_KINDS.SUPPORTED) {
+      return replicationBlocked(capability.reason);
+    }
+    const ready = await this.acquireReadyContext(false, context);
+    if ("status" in ready) return ready;
+    const setting = Object.freeze(asCopy(this.dependencies.currentSettings()));
+    const admitted = await this.dependencies.replicatorService.runWithActiveReplicatorContext(
+      async (activeContext) => {
+        if (activeContext !== ready || !isActiveReplicatorContextBoundToSetting(activeContext, setting)) {
+          return replicationBlocked("not-ready");
+        }
+        try {
+          return await capability.run(activeContext.replicator, setting, request);
+        } catch (error) {
+          return replicationFailed(error);
+        }
+      }
+    );
+    return admitted ?? replicationBlocked("no-active-replicator");
+  }
+  /**
+   * 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.
+   */
+  async stopActiveTransfer() {
+    const context = await this.acquireContext();
+    if ("status" in context) return context;
+    const capability = context.provider.stopActiveTransfer;
+    if (capability.kind !== CAPABILITY_SUPPORT_KINDS.SUPPORTED) {
+      return replicationBlocked(capability.reason);
+    }
+    const admitted = await this.dependencies.replicatorService.runWithActiveReplicatorContext(
+      async (activeContext) => {
+        if (activeContext !== context) return replicationBlocked("not-ready");
+        try {
+          return await capability.run(activeContext.replicator);
+        } catch (error) {
+          return replicationFailed(error);
+        }
+      }
+    );
+    return admitted ?? replicationBlocked("no-active-replicator");
+  }
+  finishFiniteAttempt(outcome) {
+    this.dependencies.recordFiniteAttempt();
+    return outcome;
+  }
+  async acquireContext() {
+    const context = await this.dependencies.replicatorService.acquireActiveReplicatorContext();
+    if (context) return context;
+    return this.dependencies.replicatorService.hasActiveReplicator() ? replicationBlocked("provider-not-composed") : replicationBlocked("no-active-replicator");
+  }
+  async acquireReadyContext(showMessage, contextOverride) {
+    const context = contextOverride ?? await this.acquireContext();
+    if ("status" in context) return context;
+    if (!await this.dependencies.checkReadiness(showMessage, context.provider.readiness)) {
+      return replicationBlocked("not-ready");
+    }
+    return context;
+  }
+  async runFiniteActivity(run) {
+    try {
+      return await this.dependencies.replicatorService.runFiniteReplicationActivity(run, {
+        label: "replication"
+      });
+    } catch (error) {
+      return replicationFailed(error);
+    }
+  }
+  /**
+   * 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.
+   */
+  async runAdmittedFiniteActivity(expectedContext, run, setting, interaction, showMessage) {
+    const admitted = await this.dependencies.replicatorService.runWithActiveReplicatorContext((context) => {
+      if (context !== expectedContext || !isActiveReplicatorContextBoundToSetting(context, setting)) {
+        return replicationBlocked("not-ready");
+      }
+      return this.runFiniteActivity(() => run(context));
+    });
+    const result = admitted ?? replicationBlocked("no-active-replicator");
+    if (result.status === "failed") {
+      await this.dependencies.handleFailure(
+        Object.freeze({
+          context: expectedContext,
+          setting,
+          outcome: result,
+          showMessage,
+          interaction
+        })
+      );
+    }
+    return result;
+  }
+}
+export {
+  TypedReplicationCoordinator
+};

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

@@ -0,0 +1,47 @@
+import type { ReplicatorInstance } from "../../replication/ReplicatorInstance.js";
+import type { ActiveReplicatorContext, ReplicatorProviderDefinition } from "../../replication/ReplicatorProvider.js";
+/** Atomic service publication used as both the active view and generation identity. */
+export interface ActiveReplicatorPublication {
+    readonly replicator: ReplicatorInstance;
+    readonly replicatorType: string;
+    readonly context: ActiveReplicatorContext | undefined;
+}
+/** One admitted use of an exact active publication. */
+export interface ActiveReplicatorReservation {
+    readonly context: ActiveReplicatorContext;
+    /** Release this reservation. Repeated calls have no effect. */
+    release(): void;
+}
+/** Private service-side control over one fenced publication. */
+export interface ActiveReplicatorRetirement {
+    readonly publication: ActiveReplicatorPublication;
+    /** Wait until every use admitted before the fence has settled. */
+    waitForDemandSettlement(): Promise<void>;
+    /** Mark physical close complete. Repeated calls have no effect. */
+    complete(): void;
+}
+/**
+ * Keep active publication, admission, and quiescing retirement as one state.
+ *
+ * The publication object itself is the generation identity. Retirement first
+ * removes it from `current`, then waits only for reservations captured from
+ * that object. A replacement cannot be published until physical retirement is
+ * explicitly completed.
+ */
+export declare class ActiveReplicatorState {
+    private activeOwner;
+    private retiringOwner;
+    private retirement;
+    get current(): ActiveReplicatorPublication | undefined;
+    publish(provider: ReplicatorProviderDefinition | undefined, replicator: ReplicatorInstance, replicatorType: string, configurationIdentity: string | undefined): void;
+    /** Reserve the current typed publication, or reject admission while quiescing. */
+    reserve(): ActiveReplicatorReservation | undefined;
+    /**
+     * Fence the current publication and begin its explicit quiescing transition.
+     *
+     * Completion is separate from demand settlement so callers cannot publish a
+     * replacement between draining admitted work and physically closing the old
+     * Replicator.
+     */
+    beginRetirement(): ActiveReplicatorRetirement | undefined;
+}

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

@@ -0,0 +1,107 @@
+class ActiveReplicatorPublicationOwner {
+  constructor(publication) {
+    this.publication = publication;
+  }
+  publication;
+  accepting = true;
+  demandCount = 0;
+  demandSettlement;
+  settleDemand;
+  reserve() {
+    const context = this.publication.context;
+    if (!this.accepting || !context) {
+      return void 0;
+    }
+    this.demandCount++;
+    let released = false;
+    return {
+      context,
+      release: () => {
+        if (released) return;
+        released = true;
+        this.demandCount--;
+        if (this.demandCount === 0) {
+          this.settleDemand?.();
+          this.settleDemand = void 0;
+        }
+      }
+    };
+  }
+  stopAccepting() {
+    this.accepting = false;
+  }
+  waitForDemandSettlement() {
+    if (this.demandCount === 0) {
+      return Promise.resolve();
+    }
+    this.demandSettlement ??= new Promise((resolve) => {
+      this.settleDemand = resolve;
+    });
+    return this.demandSettlement;
+  }
+  get hasDemand() {
+    return this.demandCount !== 0;
+  }
+}
+class ActiveReplicatorState {
+  activeOwner;
+  retiringOwner;
+  retirement;
+  get current() {
+    return this.activeOwner?.publication;
+  }
+  publish(provider, replicator, replicatorType, configurationIdentity) {
+    if (this.activeOwner) {
+      throw new Error("Cannot replace an active Replicator without beginning retirement.");
+    }
+    if (this.retiringOwner) {
+      throw new Error("Cannot publish an active Replicator before retirement has completed.");
+    }
+    this.activeOwner = new ActiveReplicatorPublicationOwner({
+      replicator,
+      replicatorType,
+      context: provider && configurationIdentity !== void 0 ? { provider, replicator, configurationIdentity } : void 0
+    });
+  }
+  /** Reserve the current typed publication, or reject admission while quiescing. */
+  reserve() {
+    return this.activeOwner?.reserve();
+  }
+  /**
+   * Fence the current publication and begin its explicit quiescing transition.
+   *
+   * Completion is separate from demand settlement so callers cannot publish a
+   * replacement between draining admitted work and physically closing the old
+   * Replicator.
+   */
+  beginRetirement() {
+    if (this.retirement) return this.retirement;
+    const owner = this.activeOwner;
+    if (!owner) return void 0;
+    owner.stopAccepting();
+    this.activeOwner = void 0;
+    this.retiringOwner = owner;
+    let completed = false;
+    const retirement = {
+      publication: owner.publication,
+      waitForDemandSettlement: () => owner.waitForDemandSettlement(),
+      complete: () => {
+        if (completed) return;
+        if (owner.hasDemand) {
+          throw new Error("Cannot complete active Replicator retirement while admitted work remains.");
+        }
+        if (this.retiringOwner !== owner) {
+          throw new Error("Active Replicator retirement no longer owns the quiescing state.");
+        }
+        completed = true;
+        this.retiringOwner = void 0;
+        this.retirement = void 0;
+      }
+    };
+    this.retirement = retirement;
+    return retirement;
+  }
+}
+export {
+  ActiveReplicatorState
+};

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

@@ -0,0 +1,5 @@
+import type { RemoteDBSettings } from "../../common/types.js";
+import { type CentralRemoteAdministrationRequest, type CentralRemoteAdministrationResult } from "../../replication/CentralRemoteAdministration.js";
+import { type ActiveReplicatorContext } from "../../replication/ReplicatorProvider.js";
+/** Stop, then dispatch central-remote administration through the atomically captured provider. */
+export declare function runCentralRemoteAdministrationWithContext(context: ActiveReplicatorContext | undefined, setting: RemoteDBSettings, request: CentralRemoteAdministrationRequest): Promise<CentralRemoteAdministrationResult>;

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

@@ -0,0 +1,44 @@
+import {
+  CENTRAL_REMOTE_ADMINISTRATION_FAILURE_REASONS,
+  centralRemoteAdministrationVerificationFailed
+} from "../../replication/CentralRemoteAdministration.js";
+import { CAPABILITY_SUPPORT_KINDS } from "../../replication/ProviderCapability.js";
+import {
+  isActiveReplicatorContextBoundToSetting
+} from "../../replication/ReplicatorProvider.js";
+async function stopActiveTransfer(context) {
+  const capability = context.provider.stopActiveTransfer;
+  if (capability.kind !== CAPABILITY_SUPPORT_KINDS.SUPPORTED) {
+    throw new Error("The active Replicator does not support the stop required for central remote administration.");
+  }
+  const outcome = await capability.run(context.replicator);
+  if (outcome.status === "completed") return;
+  if (outcome.status === "failed") throw outcome.error;
+  throw new Error("The active Replicator transfer did not stop before central remote administration.");
+}
+async function runCentralRemoteAdministrationWithContext(context, setting, request) {
+  if (!context) {
+    return centralRemoteAdministrationVerificationFailed(
+      CENTRAL_REMOTE_ADMINISTRATION_FAILURE_REASONS.NO_ACTIVE_REPLICATOR
+    );
+  }
+  if (!isActiveReplicatorContextBoundToSetting(context, setting)) {
+    return centralRemoteAdministrationVerificationFailed(
+      CENTRAL_REMOTE_ADMINISTRATION_FAILURE_REASONS.ACTIVE_CONFIGURATION_MISMATCH
+    );
+  }
+  const capability = context.provider.centralRemoteAdministration;
+  if (!capability) {
+    return centralRemoteAdministrationVerificationFailed(
+      CENTRAL_REMOTE_ADMINISTRATION_FAILURE_REASONS.CAPABILITY_NOT_APPLICABLE
+    );
+  }
+  if (capability.kind !== CAPABILITY_SUPPORT_KINDS.SUPPORTED) {
+    return centralRemoteAdministrationVerificationFailed(capability.reason);
+  }
+  await stopActiveTransfer(context);
+  return await capability.run(context.replicator, setting, request);
+}
+export {
+  runCentralRemoteAdministrationWithContext
+};

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

@@ -1,11 +1,16 @@
-import type { LiveSyncAbstractReplicator } from "../../replication/LiveSyncAbstractReplicator.js";
-import type { IReplicatorService } from "./IService.js";
+import type { ReplicatorInstance } from "../../replication/ReplicatorInstance.js";
+import { type MultipleHandlerFunction } from "../lib/HandlerUtils.js";
+import type { IReplicatorService, ReplicatorFactoryCallback } from "./IService.js";
 import { ServiceBase, type ServiceContext } from "./ServiceBase.js";
 import type { SettingService } from "./SettingService.js";
 import type { AppLifecycleService } from "./AppLifecycleService.js";
 import { UnresolvedErrorManager } from "./UnresolvedErrorManager.js";
 import type { DatabaseEventService } from "./DatabaseEventService.js";
 import { type AsyncActivityOptions, type AsyncActivityRunner } from "../../interfaces/AsyncActivityRunner.js";
+import type { ActiveReplicatorContext, ReplicatorProviderDefinitionMap } from "../../replication/ReplicatorProvider.js";
+import type { RemoteDBSettings } from "../../common/types.js";
+import type { RemoteResourceKind, RemoteResourceMap } from "../../replication/RemoteResource.js";
+import type { CentralRemoteAdministrationRequest, CentralRemoteAdministrationResult } from "../../replication/CentralRemoteAdministration.js";
 export interface ReplicatorServiceDependencies {
     settingService: SettingService;
     appLifecycleService: AppLifecycleService;
@@ -14,7 +19,13 @@ export interface ReplicatorServiceDependencies {
     registerLifecycleHandlers?: boolean;
 }
 /**
- * The ReplicatorService provides methods for managing replication.
+ * Own the active Replicator publication and its serialised lifecycle transitions.
+ *
+ * This service composes provider definitions, retires active instances when
+ * their configuration identity changes, and publishes the provider and
+ * Replicator atomically. Remote administration is dispatched through the
+ * admitted active context; `ReplicationService` owns synchronisation
+ * readiness and replication dispatch.
  */
 export declare abstract class ReplicatorService<T extends ServiceContext = ServiceContext> extends ServiceBase<T> implements IReplicatorService {
     protected dependencies: ReplicatorServiceDependencies;
@@ -23,8 +34,9 @@ export declare abstract class ReplicatorService<T extends ServiceContext = Servi
     _log: (msg: unknown, level?: import("octagonal-wheels/common/logger").LOG_LEVEL, key?: string) => void;
     private settingService;
     private databaseEventService;
-    private _activeReplicator;
-    private _replicatorType;
+    private readonly _activeReplicatorState;
+    private _providerDefinitions;
+    private _transition;
     private appLifecycleService;
     _unresolvedErrorManager: UnresolvedErrorManager;
     constructor(context: T, dependencies: ReplicatorServiceDependencies);
@@ -36,26 +48,75 @@ export declare abstract class ReplicatorService<T extends ServiceContext = Servi
     /** Runs one finite replication and exposes its document-delivery lifetime. */
     runFiniteReplicationActivity<TValue>(task: () => TValue | PromiseLike<TValue>, options?: AsyncActivityOptions): Promise<TValue>;
     private runRemoteActivity;
+    /** Request a reversible transfer stop without retiring the active publication. */
     private suspendReplication;
     private reinitialiseReplicator;
-    private disposeReplicator;
+    /** Request transfer cancellation for either a reversible pause or terminal retirement. */
+    private requestPublicationTransferStop;
+    /** Fence new work, request cancellation, and drain only this publication's admitted tasks. */
+    private quiesceActiveReplicator;
+    /** Close one drained publication and release its private retirement state. */
+    private closeRetiringReplicator;
+    private disposeReplicatorNow;
     private discardFailedReplicator;
+    private enqueueTransition;
     private _initialiseReplicator;
+    private getProviderDefinition;
+    private createReplicator;
+    private createReplicatorForSetting;
+    private isCurrentProviderConfiguration;
+    private publishActiveReplicator;
+    private initialiseReplicatorNow;
     /**
-     * Close the active replication if any.
-     * Not used currently.
+     * Fence new work, drain admitted work, and close the active Replicator.
+     *
+     * The command is serialised with every other ownership transition. Callers
+     * must not await it from inside `runWithActiveReplicatorContext()`, because
+     * retirement waits for that admitted callback to settle.
      */
-    readonly onCloseActiveReplication: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<() => Promise<boolean>>;
+    onCloseActiveReplication(): Promise<boolean>;
     /**
      * Get a new replicator instance based on the provided settings.
      */
-    readonly getNewReplicator: import("../lib/HandlerUtils.js").MultipleHandlerFunction<(settingOverride?: Partial<import("../../common/types.js").ObsidianLiveSyncSettings>) => Promise<LiveSyncAbstractReplicator | undefined | false>, unknown>;
-    readonly onReplicatorInitialised: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<() => Promise<boolean>>;
+    private readonly legacyGetNewReplicator;
+    readonly getNewReplicator: MultipleHandlerFunction<ReplicatorFactoryCallback>;
+    registerReplicatorProviderDefinitions(definitions: ReplicatorProviderDefinitionMap): void;
     /**
-     * Get the currently active replicator instance.
-     * If no active replicator, return undefined but that is the fatal situation (on Obsidian).
+     * Return a non-owning synchronous view for lifecycle diagnostics and focused tests.
+     *
+     * Production work must use an admitted acquisition or callback boundary so that
+     * the context cannot be retired while it is in use.
      */
-    getActiveReplicator(): LiveSyncAbstractReplicator | undefined;
+    protected inspectActiveReplicatorContext(): ActiveReplicatorContext | undefined;
+    createRemoteResource<TKind extends RemoteResourceKind>(kind: TKind, setting: RemoteDBSettings): Promise<RemoteResourceMap[TKind] | undefined>;
+    /** Apply and verify one provider-declared action before permitting a later switch. */
+    runCentralRemoteAdministration(request: CentralRemoteAdministrationRequest): Promise<CentralRemoteAdministrationResult>;
+    acquireActiveReplicatorContext(): Promise<ActiveReplicatorContext | undefined>;
+    /**
+     * Admit one callback against the publication ordered before later transitions.
+     *
+     * Release never enters the transition queue. The callback must not initiate
+     * or await a settings, database, or Replicator lifecycle transition which
+     * would wait for this same reservation.
+     */
+    runWithActiveReplicatorContext<TResult>(task: (context: ActiveReplicatorContext) => TResult | PromiseLike<TResult>): Promise<TResult | undefined>;
+    readonly onBeforeReplicatorPublication: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<() => Promise<boolean>>;
+    /**
+     * Return the legacy unreserved view of the active Replicator.
+     *
+     * Missing active state retains its established Notice-level diagnostic.
+     * New work must acquire or admit an `ActiveReplicatorContext` instead.
+     */
+    getActiveReplicator(): ReplicatorInstance | undefined;
+    /**
+     * Classify whether a compatibility active Replicator exists without
+     * acquiring or returning it.
+     *
+     * This side-effect-free, non-owning predicate exists only for
+     * compatibility-state classification. Work must acquire or admit an
+     * `ActiveReplicatorContext` before using a Replicator.
+     */
+    hasActiveReplicator(): boolean;
     replicationStatics: import("octagonal-wheels/dataobject/reactive_v2").ReactiveSource<{
         sent: number;
         arrived: number;