@vrtmrz/livesync-commonlib 0.1.25 → 0.1.27

package/dist/serviceModules/ServiceDatabaseFileAccessBase.d.ts

@@ -26,21 +26,45 @@ export declare class ServiceDatabaseFileAccessBase extends ServiceModuleBase<Ser
     delete(file: UXFileInfoStub | FilePathWithPrefix, rev?: string): Promise<boolean>;
     createChunks(file: UXFileInfo, force?: boolean, skipCheck?: boolean): Promise<boolean>;
     store(file: UXFileInfo, force?: boolean, skipCheck?: boolean): Promise<boolean>;
+    /** Force a child below the supplied base, even if advanced; an undefined base uses the winner. */
     storeWithBaseRevision(file: UXFileInfo, baseRevision: string | undefined, skipCheck?: boolean): Promise<string | false>;
+    /** Extend a current leaf with ordinary MVCC; an advanced base returns `false`. */
     storeWithLiveBaseRevision(file: UXFileInfo, baseRevision: string, skipCheck?: boolean): Promise<string | false>;
+    /**
+     * Store Chunks and a fresh Metadata root for content with unknown ancestry.
+     * Return its exact revision for provenance, or `false` if no Metadata write succeeded.
+     */
+    storeIndependentRevision(file: UXFileInfo, skipCheck?: boolean): Promise<string | false>;
     storeAsConflictedRevision(file: UXFileInfo, currentRev: string, skipCheck?: boolean): Promise<boolean>;
+    /** Create a sibling of the selected revision; refuse when its parent cannot be found. */
     storeAsConflictedRevisionWithResult(file: UXFileInfo, currentRev: string, skipCheck?: boolean): Promise<string | false>;
+    /** Record a logical deletion below the displayed branch and return its exact revision. */
     storeDeletionWithBaseRevision(file: UXFileInfoStub | FilePathWithPrefix, baseRevision: string): Promise<string | false>;
     storeContent(path: FilePathWithPrefix, content: string): Promise<boolean>;
     private __store;
+    /** Reconstruct the immediate parent ID from revision history, or return `false` if unavailable. */
     private getParentRev;
+    /**
+     * Search available revision bodies across branches and their ancestors.
+     * `stopAfterFirstMatch` serves existence checks without decoding the remaining candidates.
+     * Historical matches alone do not establish the origin of current storage content.
+     */
     private findContentRevisionsInternal;
+    /** Find matching content throughout available history, including non-leaf revisions. */
     findContentRevisions(file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string): Promise<string[]>;
+    /**
+     * Find live leaves which already represent these bytes, for deduplication when provenance
+     * is unknown. `open_revs` includes conflicting branches; both deletion markers are excluded.
+     * Unlike the historical search, ancestors cannot match and missing Chunks are not fetched.
+     * A read failure yields no confirmed match. Callers decide whether the result identifies a
+     * unique origin; this method does not mutate provenance or hold the revision tree stable.
+     */
+    findLiveContentRevisions(file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer): Promise<string[]>;
     hasContentInRevisionHistory(file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string): Promise<boolean>;
     getConflictedRevs(file: UXFileInfoStub | FilePathWithPrefix): Promise<string[]>;
     fetch(file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean): Promise<UXFileInfo | false>;
     fetchEntryMeta(file: UXFileInfoStub | FilePathWithPrefix, rev?: string, skipCheck?: boolean): Promise<MetaEntry | false>;
-    fetchEntryFromMeta(meta: MetaEntry, waitForReady?: boolean, skipCheck?: boolean): Promise<LoadedEntry | false>;
-    fetchEntry(file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean): Promise<LoadedEntry | false>;
+    fetchEntryFromMeta(meta: MetaEntry, waitForReady?: boolean, skipCheck?: boolean, localOnly?: boolean): Promise<LoadedEntry | false>;
+    fetchEntry(file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean, localOnly?: boolean): Promise<LoadedEntry | false>;
     deleteFromDBbyPath(fullPath: FilePath | FilePathWithPrefix, rev?: string): Promise<boolean>;
 }

package/dist/serviceModules/ServiceDatabaseFileAccessBase.js

@@ -52,6 +52,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
   async store(file, force = false, skipCheck) {
     return await this.__store(file, force, skipCheck, false) !== false;
   }
+  /** Force a child below the supplied base, even if advanced; an undefined base uses the winner. */
   async storeWithBaseRevision(file, baseRevision, skipCheck) {
     const result = await this.__store(file, true, skipCheck, false, {
       mode: "force-base",
@@ -59,6 +60,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     });
     return result !== null && typeof result === "object" && "rev" in result ? result.rev : false;
   }
+  /** Extend a current leaf with ordinary MVCC; an advanced base returns `false`. */
   async storeWithLiveBaseRevision(file, baseRevision, skipCheck) {
     const result = await this.__store(file, true, skipCheck, false, {
       mode: "live-base",
@@ -66,9 +68,18 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     });
     return result !== null && typeof result === "object" && "rev" in result ? result.rev : false;
   }
+  /**
+   * Store Chunks and a fresh Metadata root for content with unknown ancestry.
+   * Return its exact revision for provenance, or `false` if no Metadata write succeeded.
+   */
+  async storeIndependentRevision(file, skipCheck) {
+    const result = await this.__store(file, true, skipCheck, false, { mode: "independent-root" });
+    return result !== null && typeof result === "object" && "rev" in result ? result.rev : false;
+  }
   async storeAsConflictedRevision(file, currentRev, skipCheck) {
     return await this.storeAsConflictedRevisionWithResult(file, currentRev, skipCheck) !== false;
   }
+  /** Create a sibling of the selected revision; refuse when its parent cannot be found. */
   async storeAsConflictedRevisionWithResult(file, currentRev, skipCheck) {
     const conflictBaseRev = await this.getParentRev(file, currentRev);
     if (!conflictBaseRev) {
@@ -77,6 +88,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     }
     return await this.storeWithBaseRevision(file, conflictBaseRev, skipCheck);
   }
+  /** Record a logical deletion below the displayed branch and return its exact revision. */
   async storeDeletionWithBaseRevision(file, baseRevision) {
     if (!await this.checkIsTargetFile(file)) {
       return false;
@@ -193,7 +205,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
       this._log(msg + " Skip " + fullPath, LOG_LEVEL_VERBOSE);
       return true;
     }
-    const ret = revisionTarget.mode === "live-base" ? await this.database.localDatabase.putDBEntryWithLiveBaseRevision(
+    const ret = revisionTarget.mode === "independent-root" ? await this.database.localDatabase.putDBEntryAsIndependentRoot(d) : revisionTarget.mode === "live-base" ? await this.database.localDatabase.putDBEntryWithLiveBaseRevision(
       d,
       revisionTarget.baseRevision,
       onlyChunks
@@ -208,6 +220,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     }
     return ret;
   }
+  /** Reconstruct the immediate parent ID from revision history, or return `false` if unavailable. */
   async getParentRev(file, rev) {
     const filename = getDatabasePathFromUXFileInfo(file);
     try {
@@ -226,6 +239,11 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
       return false;
     }
   }
+  /**
+   * Search available revision bodies across branches and their ancestors.
+   * `stopAfterFirstMatch` serves existence checks without decoding the remaining candidates.
+   * Historical matches alone do not establish the origin of current storage content.
+   */
   async findContentRevisionsInternal(file, content, currentRev, stopAfterFirstMatch = false) {
     const filename = getDatabasePathFromUXFileInfo(file);
     try {
@@ -285,12 +303,46 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     }
     return [];
   }
+  /** Find matching content throughout available history, including non-leaf revisions. */
   async findContentRevisions(file, content, currentRev) {
     if (!await this.checkIsTargetFile(file)) {
       return [];
     }
     return await this.findContentRevisionsInternal(file, content, currentRev);
   }
+  /**
+   * Find live leaves which already represent these bytes, for deduplication when provenance
+   * is unknown. `open_revs` includes conflicting branches; both deletion markers are excluded.
+   * Unlike the historical search, ancestors cannot match and missing Chunks are not fetched.
+   * A read failure yields no confirmed match. Callers decide whether the result identifies a
+   * unique origin; this method does not mutate provenance or hold the revision tree stable.
+   */
+  async findLiveContentRevisions(file, content) {
+    if (!await this.checkIsTargetFile(file)) return [];
+    const filename = getDatabasePathFromUXFileInfo(file);
+    try {
+      const current = await this.database.localDatabase.getDBEntryMeta(filename, void 0, true);
+      if (current === false) return [];
+      const leaves = await this.database.localDatabase.getRaw(current._id, {
+        open_revs: "all"
+      });
+      if (!Array.isArray(leaves)) return [];
+      const matches = [];
+      for (const leaf of leaves) {
+        const rev = leaf.ok?._rev;
+        if (!rev || leaf.ok?.deleted || leaf.ok?._deleted) continue;
+        const entry = await this.database.localDatabase.getDBEntry(filename, { rev }, false, true, true, true);
+        if (entry !== false && !entry.deleted && !entry._deleted && await isDocContentSame(readContent(entry), content)) {
+          matches.push(rev);
+        }
+      }
+      return matches;
+    } catch (ex) {
+      this._log(`Could not check live revision content for ${filename}`, LOG_LEVEL_VERBOSE);
+      this._log(ex, LOG_LEVEL_VERBOSE);
+      return [];
+    }
+  }
   async hasContentInRevisionHistory(file, content, currentRev) {
     if (!await this.checkIsTargetFile(file)) {
       return true;
@@ -346,17 +398,17 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     }
     return doc;
   }
-  async fetchEntryFromMeta(meta, waitForReady = true, skipCheck = false) {
+  async fetchEntryFromMeta(meta, waitForReady = true, skipCheck = false, localOnly = false) {
     if (skipCheck && !await this.checkIsTargetFile(meta.path)) {
       return false;
     }
-    const doc = await this.database.localDatabase.getDBEntryFromMeta(meta, false, waitForReady);
+    const doc = await this.database.localDatabase.getDBEntryFromMeta(meta, false, waitForReady, localOnly);
     if (doc === false) {
       return false;
     }
     return doc;
   }
-  async fetchEntry(file, rev, waitForReady = true, skipCheck = false) {
+  async fetchEntry(file, rev, waitForReady = true, skipCheck = false, localOnly = false) {
     if (skipCheck && !await this.checkIsTargetFile(file)) {
       return false;
     }
@@ -364,7 +416,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     if (entry === false) {
       return false;
     }
-    const doc = await this.fetchEntryFromMeta(entry, waitForReady, true);
+    const doc = await this.fetchEntryFromMeta(entry, waitForReady, true, localOnly);
     return doc;
   }
   async deleteFromDBbyPath(fullPath, rev) {

package/dist/serviceModules/ServiceFileHandlerBase.d.ts

@@ -44,6 +44,7 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     private setting;
     private vault;
     private fileReflectionProvenance?;
+    private readonly deferredConflictChecks;
     constructor(services: ServiceFileHandlerDependencies);
     get db(): DatabaseFileAccess;
     get storage(): StorageAccess;
@@ -52,31 +53,148 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     private deleteProvenance;
     private findUniqueContentRevision;
     private getProvenBaseRevision;
+    /**
+     * Classify a storage read against its displayed database branch.
+     *
+     * A recorded revision identifies the branch and therefore takes precedence
+     * over byte matches. Without a readable base, only current live leaves are
+     * considered. Any match avoids a duplicate write, but only a unique match
+     * identifies provenance; no match is `unknown`.
+     * `preferredPath` selects the provenance key during a rename, and
+     * `currentLoaded` supplies an already decoded candidate body when available.
+     * Missing chunks do not clear provenance unless their metadata is also
+     * missing or deleted.
+     */
+    private classifyStorageContent;
+    /** Record provenance only when storage matches one unambiguous live leaf. */
+    private rememberMatchingLeaf;
+    /**
+     * Read the raw provenance value used by an optimistic storage snapshot.
+     * Unlike `getProvenance`, this does not validate or remove the referenced
+     * database revision; an unreadable value is represented as `undefined`.
+     */
+    private readProvenanceSnapshot;
+    /**
+     * Check that storage still has the same path, bytes, timestamp, and
+     * provenance as a previously captured snapshot.
+     */
+    private currentStorageSnapshotMatches;
+    /**
+     * Publish provenance after a durable database write if storage is unchanged.
+     * A failed revalidation leaves the database revision stored and asks the
+     * caller to reread storage before proceeding.
+     */
+    private finaliseStoredRevision;
+    /**
+     * Reread storage after a restored startup snapshot changed and retry a save.
+     * The bounded counter prevents an unstable file from causing an endless
+     * startup loop; the next event or scan can reconcile a final refusal.
+     */
+    private retryCurrentStorage;
     getPath(entry: AnyEntry): FilePathWithPrefix;
     getPathWithoutPrefix(entry: AnyEntry): FilePathWithPrefix;
     readFileFromStub(file: UXFileInfoStub | UXFileInfo): Promise<UXFileInfo>;
     private infoToStub;
     storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean): Promise<boolean>;
     storeFileToDBWithBaseRevision(info: UXFileInfoStub | UXFileInfo | FilePathWithPrefix, baseRevision: string, createIfDifferent?: boolean): Promise<boolean>;
+    /**
+     * Store current storage content below an exact live revision. A differing
+     * body is rejected when `createIfDifferent` is false; callers hold the
+     * document lock for this core operation.
+     */
+    private storeFileToDBWithBaseRevisionCore;
+    /**
+     * Save one storage snapshot while the caller holds its document lock.
+     * Ordinary saves read once inside the lock and leave retries disabled.
+     * Restored startup events retain bounded rereads because file watching has
+     * not yet started and cannot supply a new event for a concurrent edit.
+     */
     private storeFileToDBFromRevision;
     deleteFileFromDB(info: UXFileInfoStub | UXInternalFileInfoStub | FilePath): Promise<boolean>;
+    /**
+     * Record a storage deletion under the caller's document lock, preserving
+     * the displayed conflict branch when its provenance is known.
+     */
+    private deleteFileFromDBCore;
     renameFileInDB(info: UXFileInfoStub | UXFileInfo, oldPath: FilePath | FilePathWithPrefix): Promise<boolean>;
+    /**
+     * Record a rename under the caller's source and target locks. Case-only
+     * renames retain the source provenance while other renames handle the
+     * source conflict before deleting its old path.
+     */
+    private renameFileInDBCore;
     deleteRevisionFromDB(info: UXFileInfoStub | FilePath | FilePathWithPrefix, rev: string): Promise<boolean | undefined>;
+    /** Delete one selected revision and clear matching provenance under the caller's document lock. */
+    private deleteRevisionFromDBCore;
     resolveConflictedByDeletingRevision(info: UXFileInfoStub | FilePath, rev: string): Promise<boolean | undefined>;
+    /**
+     * Apply the legacy resolve-by-delete sequence while holding one document
+     * lock; metadata is captured before the selected revision is removed.
+     */
+    private resolveConflictedByDeletingRevisionCore;
     dbToStorageWithSpecificRev(info: UXFileInfoStub | UXFileInfo | FilePath | FilePathWithPrefix | null, rev: string, force?: boolean): Promise<boolean>;
+    /**
+     * Reflect a selected live revision under the caller's document lock.
+     * The public wrapper performs the same lock acquisition before entering here.
+     */
+    private dbToStorageWithSpecificRevCore;
     dbToStorage(entryInfo: MetaEntry | FilePathWithPrefix, info: UXFileInfoStub | UXFileInfo | FilePath | null, force?: boolean): Promise<boolean>;
+    /** Fetch the current metadata and reflect it while the caller holds its lock. */
+    private dbToStorageCore;
+    /**
+     * Reflect one database revision while protecting concurrent storage edits.
+     * Overwrite and deletion paths preserve changed bytes first, then revalidate
+     * their snapshot and the current database revision immediately before the
+     * destructive operation.
+     */
     private applyDatabaseEntryToStorage;
+    /**
+     * Preserve storage bytes before an incoming reflection can replace them.
+     *
+     * The initial read and provenance form one candidate snapshot. Classification
+     * gives a recorded branch priority, deduplicates matching live leaves, or
+     * creates an independent root for unknown origin. Optional `incomingContent` avoids
+     * re-reading an already loaded incoming body. Storage is revalidated before
+     * and after the database write; `preserved: true` stops the incoming write,
+     * while a returned `snapshot` lets the caller continue only after revalidation.
+     */
     private preserveUnsyncedStorageAsConflict;
+    /**
+     * Repeat overwrite protection from a fresh storage read after a snapshot
+     * becomes stale. Existing conflicts may defer reflection and request an
+     * open-only check while leaving the current storage untouched.
+     */
+    private recheckIncomingStorage;
+    /**
+     * Re-read database metadata immediately before reflecting an incoming entry.
+     * If the current revision advanced, recurse with fresh storage; force and
+     * explicitly allowed conflict writes retain the caller's selected entry.
+     * `incomingRetry` bounds repeated database churn.
+     */
+    private reconcileAdvancedIncomingRevision;
     private _anyHandlerProcessesFileEvent;
     private canRecordStorageDeletion;
+    /**
+     * Serialise work by every document ID represented by the supplied paths.
+     * IDs are deduplicated and sorted so aliases take one lock and cross-document renames have one order.
+     * The callback runs under those locks and must use core methods; conflict
+     * hooks requested inside it are deferred until all locks have been released.
+     */
     private serializedByFileEventPaths;
+    /**
+     * Queue a conflict hook while its document lock is held, or run it directly
+     * when no matching lock is active. Preserve `ifOpen` across deferral.
+     */
+    private queueConflictCheckFor;
     /**
      * Revalidate a persisted storage operation against the current storage state.
      *
      * Snapshot entries preserve operation intent and ordering only. Their file
      * stub, timestamps, and existence assumptions can be stale after a restart.
      * Current inclusion is therefore read from storage, while destructive work
-     * is allowed only after current absence has been observed.
+     * is allowed only after current absence has been observed. Store and rename
+     * actions use the fresh reread with bounded retry because no later watcher
+     * event is guaranteed after startup reconciliation.
      */
     private _processRestoredFileEvent;
     private _planRestoredFileEvent;