@vrtmrz/livesync-commonlib 0.1.25 → 0.1.26

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;