@vrtmrz/livesync-commonlib 0.1.18 → 0.1.19-rc.0

package/dist/services/base/ReplicationService.js

@@ -186,8 +186,7 @@ class ReplicationService extends ServiceBase {
     }
     return activeReplicator;
   }
-  async replicateAllToRemote(showingNotice = false) {
-    if (!this.appLifecycleService.isReady()) return false;
+  async performReplicateAllToRemote(showingNotice) {
     if (!await this.onBeforeReplicate(showingNotice)) {
       this._log(this.context.translate("Replicator.Message.SomeModuleFailed"), LOG_LEVEL_NOTICE);
       return false;
@@ -204,8 +203,7 @@ class ReplicationService extends ServiceBase {
       return await activeReplicator.replicateAllToServer(currentSettings, showingNotice);
     return !checkResult;
   }
-  async replicateAllFromRemote(showingNotice = false) {
-    if (!this.appLifecycleService.isReady()) return false;
+  async performReplicateAllFromRemote(showingNotice) {
     const activeReplicator = this.getActiveReplicatorFor("fetching data from remote");
     if (!activeReplicator) {
       return false;
@@ -218,6 +216,40 @@ class ReplicationService extends ServiceBase {
       return await activeReplicator.replicateAllFromServer(currentSettings, showingNotice);
     return !checkResult;
   }
+  async replicateAllToRemote(showingNotice = false) {
+    if (!this.appLifecycleService.isReady()) return false;
+    return await this.performReplicateAllToRemote(showingNotice);
+  }
+  async replicateAllFromRemote(showingNotice = false) {
+    if (!this.appLifecycleService.isReady()) return false;
+    return await this.performReplicateAllFromRemote(showingNotice);
+  }
+  /**
+   * Perform a full upload owned by an active rebuild while the physical database is ready.
+   *
+   * This concrete maintenance entry point is intentionally absent from `IReplicationService`;
+   * it is not a general application-readiness bypass.
+   */
+  async replicateAllToRemoteForRebuild(showingNotice = false) {
+    if (!this.databaseService.isDatabaseReady()) {
+      this._log("The selected local database is not ready for the rebuild upload.", LOG_LEVEL_NOTICE);
+      return false;
+    }
+    return await this.performReplicateAllToRemote(showingNotice);
+  }
+  /**
+   * Perform a full download owned by an active rebuild while the physical database is ready.
+   *
+   * This concrete maintenance entry point is intentionally absent from `IReplicationService`;
+   * it is not a general application-readiness bypass.
+   */
+  async replicateAllFromRemoteForRebuild(showingNotice = false) {
+    if (!this.databaseService.isDatabaseReady()) {
+      this._log("The selected local database is not ready for the rebuild download.", LOG_LEVEL_NOTICE);
+      return false;
+    }
+    return await this.performReplicateAllFromRemote(showingNotice);
+  }
   _getReplicatorAndPerform(action, perform) {
     const activeReplicator = this.getActiveReplicatorFor(action);
     if (!activeReplicator) {

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

@@ -39,6 +39,7 @@ export declare abstract class ReplicatorService<T extends ServiceContext = Servi
     private suspendReplication;
     private reinitialiseReplicator;
     private disposeReplicator;
+    private discardFailedReplicator;
     private _initialiseReplicator;
     /**
      * Close the active replication if any.

package/dist/services/base/ReplicatorService.js

@@ -15,7 +15,10 @@ class ReplicatorService extends ServiceBase {
     super(context);
     this.dependencies = dependencies;
     this.appLifecycleService = dependencies.appLifecycleService;
-    this._unresolvedErrorManager = new UnresolvedErrorManager(dependencies.appLifecycleService, this.context.events);
+    this._unresolvedErrorManager = new UnresolvedErrorManager(
+      dependencies.appLifecycleService,
+      this.context.events
+    );
     this.settingService = dependencies.settingService;
     this.databaseEventService = dependencies.databaseEventService;
     if (dependencies.registerLifecycleHandlers ?? true) {
@@ -83,6 +86,18 @@ class ReplicatorService extends ServiceBase {
     this._replicatorType = void 0;
     return true;
   }
+  async discardFailedReplicator(replicator) {
+    if (this._activeReplicator === replicator) {
+      this._activeReplicator = void 0;
+      this._replicatorType = void 0;
+    }
+    try {
+      await Promise.resolve(replicator.closeReplication());
+    } catch (error) {
+      this._log("Failed to close a replicator after its initialisation failed.", LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
+    }
+  }
   async _initialiseReplicator() {
     const message = this.context.translate("Replicator.Message.InitialiseFatalError");
     const setting = this.settingService.currentSettings();
@@ -123,19 +138,23 @@ class ReplicatorService extends ServiceBase {
       this._replicatorType = replicatorType;
       this.replicationStatics.value = { ...DEFAULT_REPLICATION_STATICS };
       await yieldMicrotask();
-      if (!await newReplicator.initializeDatabaseForReplication()) {
-        this._log("Failed to initialise the replicator's local node information.");
-        this._activeReplicator = void 0;
-        this._replicatorType = void 0;
+      try {
+        if (!await newReplicator.initializeDatabaseForReplication()) {
+          this._log("Failed to initialise the replicator's local node information.");
+          await this.discardFailedReplicator(newReplicator);
+          this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
+          return false;
+        }
+        if (!await this.onReplicatorInitialised()) {
+          this._log("Failed to initialise the replicator, onReplicatorInitialised reported some problems.");
+          await this.discardFailedReplicator(newReplicator);
+          this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
+          return false;
+        }
+      } catch (error) {
+        await this.discardFailedReplicator(newReplicator);
         this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
-        return false;
-      }
-      if (!await this.onReplicatorInitialised()) {
-        this._log("Failed to initialise the replicator, onReplicatorInitialised reported some problems.");
-        this._activeReplicator = void 0;
-        this._replicatorType = void 0;
-        this._unresolvedErrorManager.showError(message, LOG_LEVEL_NOTICE);
-        return false;
+        throw error;
       }
       const remoteTypeDisplay = replicatorType === RemoteTypes.REMOTE_COUCHDB ? "CouchDB" : replicatorType;
       this._log(`Replicator (${remoteTypeDisplay}) initialised and activated`, LOG_LEVEL_VERBOSE);

package/docs/development.md

@@ -69,6 +69,8 @@ The one-shot CouchDB connectivity preflight is the first bounded consumer. It ap
 
 `openSimpleStore()` may create an inert namespace handle during composition, before the backing key-value database has opened. Maintained hosts must complete their sequential settings lifecycle before scans, watchers, or replication invoke the handle. Operations fail on a lifecycle violation rather than waiting for readiness; do not introduce an implicit wait which can hang after failed initialisation or become self-referential from an initialisation handler. Treat database reset as a transient unavailable boundary and reconstruct derived local state after reopening.
 
+The active local database identity, settings-selected reset sequence, and lifecycle event phases are specified in [Local database lifecycle](database-lifecycle.md). Extend that document and the focused service and rebuild tests whenever database selection, reset ownership, event ordering, or failure propagation changes.
+
 ### P2P composition ownership
 
 `useP2PReplicatorFeature` is the sole owner of the active `LiveSyncTrysteroReplicator` and its lifecycle bindings. It creates or replaces the outer replicator when `ReplicatorService` requests one, closes the previous instance before replacement, shares an in-flight replacement between concurrent callers, and returns a stable result object whose `replicator` property resolves the current instance.

package/docs/proven-in-use.md

@@ -24,7 +24,9 @@ Commonlib's injected remote-service tests verify that an owning operation can ab
 
 Commonlib's remote-preference result contract distinguishes available synchronisation settings, a remote which has not stored those settings yet, a failed read, and a remote type which does not support central preferences. Focused CouchDB and Object Storage tests cover absent milestone data separately from transport failures, while Self-hosted LiveSync owns the initialisation choices, cancellation policy, and user-facing explanation.
 
-Commonlib's full offline scanner distinguishes completed, deliberately skipped, and failed storage/database pairs. Before pair construction, it withholds Metadata whose actual document ID disagrees with its recorded path, without reflection, deletion, or last-seen side effects. A consistently addressed entry for the same logical path continues through the established path-based flow; only a path without such an entry also withholds storage processing. The read-only actual-ID Inspector and separately invoked one-entry repair retain ambiguous states for review, revalidate an exact source revision, verify a target-first copy, and preserve the source on failure. Self-hosted LiveSync keeps the existing Fast Setup aggregate policy and owns confirmation and presentation in its file/database repair interface.
+Commonlib's full offline scanner distinguishes completed, deliberately skipped, and failed storage/database pairs. Before pair construction, it withholds Metadata whose actual document ID disagrees with its recorded path, without reflection, deletion, or last-seen side effects. A consistently addressed entry for the same logical path continues through the established path-based flow; only a path without such an entry also withholds storage processing. The read-only actual-ID Inspector and separately invoked one-entry repair retain ambiguous states for review, revalidate an exact source revision, verify a target-first copy, and preserve the source on failure. Snapshot-restoration tests additionally verify that restored inclusions use current storage content, stale deletions are suppressed, rename halves are admitted from their current path states, and an inspection failure does not become evidence of absence. The following full scan remains the final reconciliation step. Self-hosted LiveSync keeps the existing Fast Setup aggregate policy and owns confirmation and presentation in its file/database repair interface.
+
+Commonlib's local-database lifecycle tests distinguish the settings-selected database from the active wrapper. They verify replacement before a changed-suffix reset, fail-closed cleanup after rejected physical preparation, application readiness after the requested scan and completion hooks, and the prevention of rebuilt events and later remote mutation after a failed local reset. Self-hosted LiveSync owns settings persistence, setup flags, recovery dialogue, and real-Obsidian rebuild confirmation; those host results remain downstream evidence rather than Commonlib guarantees.
 
 Most replication and storage services used by the plug-in still enter through explicit `compat/*` paths. Those imports prove that the published compatibility boundary supports the current migration; they are not examples of a finished high-level client API.
 

package/docs/releasing.md

@@ -92,3 +92,25 @@ gh workflow run publish-npm.yml \
 For a stable release, use `source_ref=main`. The workflow rejects a stable release selected from another branch, rejects a stable release without its trusted workflow commit, and requires the workflow-triggering SHA to equal the packaged `main` SHA. The workflow dispatch itself uses `--ref main` for every release, so an unmerged branch cannot change the trusted publication job or acquire access to the `npm` environment.
 
 The workflow always stages to `next`. Inspect the staged package name, version, access, dist-tag, provenance, checksum, files, selected source branch, and source commit before approving it through npm. Approval and later promotion to `latest` are separate user-authorised operations. Keep the Commonlib and Self-hosted LiveSync consumer pull requests in draft while validating the exact registry pre-release. If validation fails, leave that published version immutable and prepare a new pre-release. After successful consumer validation, merge Commonlib only through its separate maintainer gate. Validate a stable release in Self-hosted LiveSync before promoting it to `latest`.
+
+## Publishing a GitHub Release
+
+Create a GitHub Release for each stable Commonlib release after the exact registry artefact has passed downstream validation and the version has been promoted to `latest`. Target the exact `main` commit used to build the published package.
+
+Protect the GitHub `github-release` environment with a required reviewer and permit only `main`. The manually dispatched workflow first verifies the release with read-only repository access. Only its protected publication job receives `contents: write` access.
+
+Set the exact version and release commit, then dispatch the workflow from `main`:
+
+```bash
+version='<version>'
+release_sha='<full-release-commit>'
+gh workflow run publish-github-release.yml \
+  --ref main \
+  -f version="$version" \
+  -f expected_sha="$release_sha" \
+  -f confirmation="release @vrtmrz/livesync-commonlib@$version from $release_sha"
+```
+
+The workflow requires the release commit to be an ancestor of its trusted `main` commit, reads the exact source version and corresponding release notes from that commit, confirms that npm `latest` points to the version, and rejects an existing version tag. Review those results before approving the `github-release` environment. The protected job rechecks npm `latest`, then creates the version tag and GitHub Release and verifies that the tag points to the selected commit.
+
+Treat dispatching and approving the GitHub Release workflow as separate user-authorised remote operations. Verify the version, exact release commit, and release notes immediately before approval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.18",
+  "version": "0.1.19-rc.0",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",