@rljson/fs-agent 0.0.12 → 0.0.15

package/dist/fs-agent.d.ts

@@ -44,6 +44,14 @@ export interface FsAgentOptions {
      * auto-generates its own identity.
      */
     clientIdentity?: ClientId;
+    /**
+     * Enable Nextcloud-style conflict resolution. When true, {@link syncFromDb}
+     * registers a DAG-branch conflict observer that resolves forks into a single
+     * merge revision (winner keeps the path, loser is renamed). This is a
+     * **client-only** behaviour — hubs are dumb relays and must leave it off
+     * (the default). See `doc/conflict-resolution-design.md`.
+     */
+    resolveConflicts?: boolean;
 }
 /** Restore options */
 export interface RestoreOptions {
@@ -85,9 +93,26 @@ export interface TimeoutConfig {
      * Each retry waits `attempt * processRefRetryDelayMs` (i.e. 5s, 10s, 15s).
      */
     processRefRetryDelayMs?: number;
+    /**
+     * Number of **recovery re-queues** for a ref whose per-cycle retries were
+     * all exhausted (e.g. `db.get` kept timing out because the transport was
+     * disconnected/contended during a hub crash, reconnect or restart). Instead
+     * of permanently dropping the ref — which loses the file written in that
+     * window — it is re-queued up to this many times so it is eventually applied
+     * once the transport recovers. A newer incoming ref supersedes a pending
+     * recovery; `tearDown()` stops it. Default: 10. Set 0 to restore the old
+     * drop-on-exhaustion behaviour.
+     */
+    recoveryRetries?: number;
 }
 /** Filename for sync error log written to the sync folder */
 export declare const SYNC_ERROR_FILE = ".sync-errors.log";
+/**
+ * Filename prefix for the staging files used by atomic writes. The scanner
+ * ignores anything starting with this so the transient temp + rename never
+ * pollutes the tree or churns the watcher.
+ */
+export declare const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 /**
  * Orchestrates filesystem operations with tree structures and blob storage
  */
@@ -104,6 +129,15 @@ export declare class FsAgent {
     /** Content fingerprint of the last tree we broadcasted (paths+blobIds) */
     private _lastSentContentKey?;
     private _timeouts;
+    /** Client-only: resolve DAG-branch conflicts into merge revisions. */
+    private _resolveConflicts;
+    /**
+     * Ancestry head: the content ref of the revision currently representing the
+     * filesystem state. New local revisions descend from it; received revisions
+     * advance it. Only tracked when `resolveConflicts` is enabled, so the
+     * InsertHistory predecessor DAG forms only where conflict resolution is on.
+     */
+    private _currentRef?;
     constructor(rootPath: string, bs?: Bs, options?: FsAgentOptions);
     /**
      * Gets the root path
@@ -132,6 +166,38 @@ export declare class FsAgent {
      * @param err - The error value caught
      */
     _writeSyncError(context: string, err: unknown): void;
+    /**
+     * Extracts a human-readable message from a thrown value. The non-`Error`
+     * branch is defensive (the DB/transport always throw `Error`s).
+     * @param err - The caught value.
+     * @returns A message string.
+     */
+    private static _errMessage;
+    /**
+     * Retries an async operation up to `attempts` times with exponential backoff
+     * (each delay doubles from `baseDelayMs`). For transient failures — a file
+     * briefly locked by antivirus or a save-and-rename editor, a peer briefly
+     * unreachable. Non-final failures are logged once at warn level so retry
+     * pressure is visible without log-spam.
+     * @param fn - The operation to run
+     * @param attempts - Maximum number of attempts
+     * @param baseDelayMs - Initial backoff delay (doubles each retry)
+     * @param label - Human-readable label for log messages
+     * @returns The operation's resolved value
+     */
+    private static _withRetry;
+    /**
+     * Atomically writes a file: stages the content in a sibling `.<rand>.tmp`,
+     * then renames over the target. The rename is atomic, so a crash mid-write
+     * leaves only the temp behind — never a half-written target file. (We do not
+     * `fsync` the temp: it adds significant per-file latency under bursty
+     * restores, and durability-on-power-loss is secondary here since the content
+     * is replicated and re-synced.) The random suffix keeps concurrent restores
+     * of the same path from trampling each other.
+     * @param filePath - Destination path
+     * @param content - Bytes to write
+     */
+    private static _atomicWriteFile;
     /**
      * Wraps a promise with a timeout.
      * Rejects with a descriptive error if the promise does not settle
@@ -147,6 +213,9 @@ export declare class FsAgent {
      * otherwise falls back to fire-and-forget `send()`.
      * @param connector - The Connector to send through
      * @param ref - The ref to broadcast
+     * @param predecessorRefs - Causal predecessor content refs to attach (for
+     *   conflict ancestry); set explicitly here because the FsAgent broadcasts
+     *   via an explicit send, which pre-empts the Connector's db-observer path.
      */
     private _sendRef;
     /**
@@ -179,6 +248,14 @@ export declare class FsAgent {
      * @param options - Restore options
      */
     restore(tree: FsTree, targetPath?: string, options?: RestoreOptions): Promise<void>;
+    /**
+     * Recursively collects the absolute paths of all files under `currentDir`.
+     * Used to snapshot the pre-restore file set for prune race-protection.
+     * @param currentDir - Directory to walk
+     * @param out - Accumulator set (created if omitted)
+     * @returns The set of absolute file paths
+     */
+    private _collectAllFiles;
     /**
      * Recursively restores a tree node and its children
      * @param treeHash - Hash of the tree node to restore
@@ -246,10 +323,13 @@ export declare class FsAgent {
      */
     private _collectExpectedPaths;
     /**
-     * Remove files/dirs not present in the expected sets
+     * Remove files/dirs not present in the expected sets, preserving any file
+     * that appeared *during* the restore (not in `preRestore`) — a fresh user
+     * write that must not be clobbered.
      * @param currentDir - Directory currently being inspected
      * @param expectedDirs - Allowed directory paths
      * @param expectedFiles - Allowed file paths
+     * @param preRestore - Files present before the restore (prune candidates)
      */
     private _pruneExtraneous;
     /**
@@ -262,6 +342,44 @@ export declare class FsAgent {
      * @returns Function to stop watching
      */
     syncToDb(db: Db, connector: Connector, treeKey: string, options?: StoreFsTreeOptions): Promise<() => void>;
+    /**
+     * Resolves the `previous` (InsertHistory predecessor timeIds) for a new
+     * revision from the parent's shared content refs. timeIds are per-db, so we
+     * map each shared parent ref to *this* db's local timeId(s). Returns undefined
+     * when ancestry tracking is off (default) or no parent is known — in which
+     * case the store behaves exactly as before.
+     * @param db - Database instance
+     * @param treeKey - Tree table key
+     * @param parentRefs - Parent content refs (local head, or received predecessors)
+     */
+    private _ancestryPrevious;
+    /**
+     * Classifies an incoming revision relative to our current head using the
+     * local InsertHistory DAG (keyed on shared content refs):
+     *  - `behind`   → incoming descends from our head → fast-forward (restore).
+     *  - `ahead`    → our head descends from incoming (e.g. a reconnect bootstrap
+     *                 re-sending an older ancestor) → ignore; we are newer.
+     *  - `diverged` → siblings produced by concurrent edits → resolve the fork.
+     * @param db - Database instance
+     * @param treeKey - Tree table key
+     * @param currentRef - Our current head's content ref
+     * @param incomingRef - The incoming revision's content ref
+     * @param incomingPredecessorRefs - The incoming revision's predecessor refs
+     */
+    private _ancestryRelation;
+    /**
+     * Resolves a divergent incoming revision inline (called from `processRef`
+     * with the watcher paused, so resolution cannot race the sync loop). Records
+     * the incoming revision as a fork tip without clobbering local content, then
+     * merges our head and the incoming tip into a single merge revision D that is
+     * materialised to disk and broadcast.
+     * @param db - Database instance
+     * @param treeKey - Tree table key
+     * @param incomingRef - The incoming revision's content ref
+     * @param incomingTree - The fetched incoming tree
+     * @param predecessorRefs - The incoming revision's predecessor content refs
+     */
+    private _resolveConflictInline;
     /**
      * Builds a map of relativePath → blobId for all files in a tree.
      * Used to compare trees by content rather than by hash (which includes mtime).
@@ -289,6 +407,17 @@ export declare class FsAgent {
      * @param b - Second tree to compare
      */
     private _treesHaveEquivalentContent;
+    /**
+     * Builds the dependency surface a {@link FsConflictResolver} needs, wiring it
+     * to this agent's db, blob store, scanner, and working directory.
+     *
+     * The merge store records the merged ref/content key as the last-sent state,
+     * so the watcher-driven re-scan that follows the on-disk materialisation
+     * settles to a no-op instead of re-broadcasting.
+     * @param db - Database instance
+     * @param treeKey - Tree table key
+     */
+    private _buildConflictResolverDeps;
     /**
      * Watches database for tree changes and syncs to filesystem
      * Uses Connector for socket-based notifications