@rljson/fs-agent 0.0.12 → 0.0.15

package/dist/fs-conflict-resolver.d.ts

@@ -0,0 +1,181 @@
+import { Conflict } from '@rljson/db';
+import { InsertHistoryRow } from '@rljson/rljson';
+import { FsTree } from './fs-scanner.js';
+/**
+ * Nextcloud-style conflict resolution for forked FS-tree DAGs.
+ *
+ * When two peers edit a shared tree while one is offline, the InsertHistory
+ * DAG forks into two tips (B and C, both descending from a common ancestor A).
+ * `@rljson/db` fires a `dagBranch` conflict. This module resolves it on the
+ * **client** by performing a deterministic three-way file-level merge and
+ * writing a single **merge revision D** whose `InsertHistory.previous`
+ * references *both* tips — collapsing the fork back to one tip.
+ *
+ * The pure functions (merge, naming, ancestor walk, winner selection) are
+ * deterministic: every peer resolving the same fork produces the identical D,
+ * so resolution converges instead of forking again.
+ *
+ * See `doc/conflict-resolution-design.md`.
+ */
+/** relativePath → blobId. Directories are recorded as {@link DIR_MARKER}. */
+export type ContentMap = Map<string, string>;
+/** Sentinel blobId used for directory entries in a {@link ContentMap}. */
+export declare const DIR_MARKER = "<dir>";
+/**
+ * Builds a {@link ContentMap} (relativePath → blobId) from an FsTree, ignoring
+ * mtime so two trees with identical content compare equal regardless of when
+ * they were written.
+ * @param tree - The FsTree to flatten
+ * @returns A map of relativePath → blobId (directories use {@link DIR_MARKER})
+ */
+export declare function fsTreeToContentMap(tree: FsTree): ContentMap;
+/** A branch tip's identity, used for deterministic winner selection. */
+export interface BranchTip {
+    /** InsertHistory timeId of the tip (per-db; used only for local lookups). */
+    timeId: string;
+    /** Shared content ref of the tip — the cross-client deterministic tiebreak. */
+    ref: string;
+    /** Originating client id (InsertHistory `origin`). Empty string if unknown. */
+    clientId: string;
+    /** InsertHistory client timestamp (ms). 0 if unknown. */
+    timestamp: number;
+}
+/**
+ * Total, deterministic order over two tips. Returns a positive number when `a`
+ * outranks `b`. Greater timestamp wins; ties broken by greater clientId, then
+ * greater **content ref**. The final tiebreak is the ref (not the timeId)
+ * because timeIds are per-db — using them would make different peers pick
+ * different winners and never converge; the ref is shared, so every peer agrees.
+ * @param a - First tip
+ * @param b - Second tip
+ * @returns Positive if `a` outranks `b`, negative if `b` outranks `a`, else 0
+ */
+export declare function compareTips(a: BranchTip, b: BranchTip): number;
+/**
+ * Picks the path-owning winner of a conflict. Per design decision §11.1 the
+ * revision with the greater InsertHistory timestamp keeps the original path;
+ * the loser's content is preserved under a renamed conflict copy.
+ * @param a - First tip
+ * @param b - Second tip
+ * @returns The winning and losing tips
+ */
+export declare function decideWinner(a: BranchTip, b: BranchTip): {
+    winner: BranchTip;
+    loser: BranchTip;
+};
+/**
+ * Finds the nearest common ancestor timeId of two tips by walking the
+ * InsertHistory `previous` chains. Returns null when the tips share no
+ * ancestor (treat as an empty ancestor — everything is an add/add).
+ * @param rows - All InsertHistory rows for the table
+ * @param tipA - First tip timeId
+ * @param tipB - Second tip timeId
+ * @returns The nearest common ancestor timeId, or null if none
+ */
+export declare function findCommonAncestor(rows: InsertHistoryRow<string>[], tipA: string, tipB: string): string | null;
+/**
+ * Formats a timestamp as a stable UTC `YYYY-MM-DD HHMMSS` string. UTC keeps the
+ * conflict-copy name identical across peers in different timezones.
+ * @param ms - Milliseconds since the epoch
+ * @returns The formatted UTC timestamp
+ */
+export declare function formatConflictTimestamp(ms: number): string;
+/**
+ * Derives a Nextcloud-style conflict-copy path:
+ * `document.txt` → `document (conflicted copy <clientId> <ts>).txt`.
+ *
+ * - The suffix is inserted before the final extension; dotfiles / extensionless
+ *   names get it appended.
+ * - Identity + timestamp come from the *losing* revision, so every peer derives
+ *   the same name (determinism).
+ * - If the candidate name is already taken, a numeric ` (n)` is appended; the
+ *   chosen name is added to `taken`.
+ * @param relativePath - The original conflicting path
+ * @param clientId - The losing revision's client id
+ * @param timestamp - The losing revision's InsertHistory timestamp (ms)
+ * @param taken - Set of already-used paths; the chosen name is added to it
+ * @returns A unique conflict-copy path
+ */
+export declare function conflictCopyName(relativePath: string, clientId: string, timestamp: number, taken: Set<string>): string;
+/** A conflict copy to materialise: the losing content under a renamed path. */
+export interface ConflictCopy {
+    /** The renamed path the losing content is written to. */
+    path: string;
+    /** The losing blobId (content preserved, nothing lost). */
+    blobId: string;
+}
+/** The result of a three-way merge. */
+export interface MergePlan {
+    /** Final tree content (winner-resolved): relativePath → blobId. */
+    merged: ContentMap;
+    /** Extra files to write beside the merged set (the renamed losers). */
+    copies: ConflictCopy[];
+    /** Original paths that genuinely conflicted (both sides changed differently). */
+    conflictPaths: string[];
+}
+/**
+ * Three-way file-level merge of ancestor `o`, branch `ours`, branch `theirs`.
+ * `winnerSide` decides who keeps the path on a real conflict; the loser's
+ * content is preserved under a {@link conflictCopyName}. Pure & deterministic.
+ *
+ * Per relative path (see design §4.4):
+ * - both sides equal → keep it (covers unchanged + add-same + delete-both)
+ * - only theirs changed (`ours === o`) → take theirs
+ * - only ours changed (`theirs === o`) → take ours
+ * - both changed differently → CONFLICT: winner keeps path, loser renamed
+ * @param o - Ancestor content map
+ * @param ours - Our branch content map
+ * @param theirs - Their branch content map
+ * @param winnerSide - Which side keeps the path on a real conflict
+ * @param loserClientId - The losing revision's client id (for copy names)
+ * @param loserTimestamp - The losing revision's timestamp (for copy names)
+ * @returns The merge plan (merged set, conflict copies, conflicting paths)
+ */
+export declare function threeWayMerge(o: ContentMap, ours: ContentMap, theirs: ContentMap, winnerSide: 'ours' | 'theirs', loserClientId: string, loserTimestamp: number): MergePlan;
+/**
+ * The capabilities the resolver needs from its host FsAgent + Db. Injected so
+ * the orchestration is unit-testable with in-memory fakes (no real db/fs).
+ */
+export interface ConflictResolverDeps {
+    /** The tree table key (route is `/${treeKey}`). */
+    treeKey: string;
+    /** All InsertHistory rows for `treeKey`. */
+    getInsertHistory: (table: string) => Promise<InsertHistoryRow<string>[]>;
+    /** Resolve a tip timeId to its tree root ref. */
+    getRefOfTimeId: (table: string, timeId: string) => Promise<string | null>;
+    /** Fetch a full FsTree by its root ref. */
+    fetchTree: (rootRef: string) => Promise<FsTree>;
+    /** Read a blob's bytes by blobId. */
+    getBlobContent: (blobId: string) => Promise<Buffer>;
+    /** Restore an FsTree onto the working dir, pruning extraneous entries. */
+    restoreTree: (tree: FsTree) => Promise<void>;
+    /** Write bytes to a relative path under the working dir (mkdir -p). */
+    writeFileAt: (relativePath: string, content: Buffer) => Promise<void>;
+    /** Remove a relative path under the working dir (best effort). */
+    deleteFileAt: (relativePath: string) => Promise<void>;
+    /** Re-scan the working dir into a fresh, hashed FsTree. */
+    scan: () => Promise<FsTree>;
+    /** Store the merge revision with explicit predecessors; returns its root ref. */
+    storeMerge: (tree: FsTree, previous: string[]) => Promise<string>;
+    /** Notified with the stored merge ref so the host can suppress the echo. */
+    onMergeStored?: (ref: string) => void;
+    /** Optional structured logger. */
+    log?: (level: 'info' | 'warn' | 'error', msg: string) => void;
+}
+/**
+ * Resolves a single `dagBranch` conflict into a merge revision. For more than
+ * two tips it merges the two lowest-identity tips per call; the resulting
+ * smaller fork re-fires the observer and converges in further rounds.
+ */
+export declare class FsConflictResolver {
+    private readonly deps;
+    constructor(deps: ConflictResolverDeps);
+    private _log;
+    /**
+     * Resolves the conflict, returning the stored merge ref, or null when the
+     * conflict is not ours / not actionable.
+     * @param conflict - The detected DAG-branch conflict
+     * @returns The stored merge revision's root ref, or null
+     */
+    resolve(conflict: Conflict): Promise<string | null>;
+}

package/dist/fs-db-adapter.d.ts

@@ -1,4 +1,5 @@
 import { Db } from '@rljson/db';
+import { InsertHistoryTimeId } from '@rljson/rljson';
 import { FsTree } from './fs-scanner.js';
 /**
  * Options for storing filesystem trees in database
@@ -10,6 +11,13 @@ export interface StoreFsTreeOptions {
      * via the standard db.insertTrees() pipeline.
      */
     skipNotification?: boolean;
+    /**
+     * Explicit predecessor override for the InsertHistory row. When set, the
+     * stored revision's `previous` references exactly these timeIds instead of
+     * the controller-derived predecessor. Used to write a **merge revision**
+     * whose parents are both tips of a forked DAG, collapsing the fork.
+     */
+    previous?: InsertHistoryTimeId[];
 }
 /**
  * Adapter for storing filesystem trees in a database.

package/dist/fs-scanner.d.ts

@@ -9,16 +9,23 @@ export interface FsNodeMeta extends Json {
     name: string;
     /** Type of node */
     type: 'file' | 'directory';
-    /** Absolute path */
-    path: string;
-    /** Relative path from scan root */
+    /** Relative path from scan root (the cross-client-stable content identity) */
     relativePath: string;
     /** File size in bytes (for files) */
     size?: number;
-    /** Last modified timestamp (milliseconds since epoch) */
-    mtime: number;
     /** Blob ID for file content (files only) */
     blobId?: string;
+    /**
+     * Absolute path — informational only, NOT part of the content identity.
+     * Excluded from stored meta so tree refs are folder-independent (shared
+     * across clients). Retained in the type for back-compat.
+     */
+    path?: string;
+    /**
+     * Last modified timestamp — NOT part of the content identity (environment-
+     * specific). Excluded from stored meta so refs are mtime-independent.
+     */
+    mtime?: number;
 }
 /**
  * Tree structure with hash mapping
@@ -32,7 +39,7 @@ export interface FsTree {
 /**
  * Type of file system change
  */
-export type FsChangeType = 'added' | 'modified' | 'deleted';
+export type FsChangeType = 'added' | 'modified' | 'deleted' | 'safety-rescan';
 /**
  * File system change event
  */
@@ -73,6 +80,10 @@ export declare class FsScanner {
     private _bs;
     private _paused;
     private _missedChangesDuringPause;
+    /** Periodic full-rescan timer that catches events the native watcher drops. */
+    private _safetyTimer;
+    /** Set by stopWatch() so a pending watcher reinstall / rescan bails out. */
+    private _stopRequested;
     constructor(rootPath: string, options?: FsScanOptions);
     get tree(): FsTree | null;
     get rootPath(): string;
@@ -81,6 +92,29 @@ export declare class FsScanner {
     private _scanDirectory;
     private _shouldIgnore;
     watch(): Promise<void>;
+    /**
+     * One safety-rescan pass: rescans the tree and, if its content differs from
+     * the previous scan (the native watcher dropped an event), emits a sync
+     * notification so syncToDb reconciles the drift. Paused/stopped scanners and
+     * scan failures are no-ops.
+     */
+    private _runSafetyRescan;
+    /**
+     * Path+blobId content fingerprint used by the safety rescan to detect drift
+     * the native watcher missed (mtime-independent, same idea as the agent's
+     * content key but local to the scanner).
+     * @param tree - The tree to fingerprint
+     * @returns A stable content key
+     */
+    private _safetyContentKey;
+    /**
+     * Extracts a readable message from a thrown value.
+     * @param err - The caught value
+     * @returns A message string
+     */
+    private static _errMessage;
+    /** Whether the host is Windows — gates Windows-specific watcher hardening. */
+    private static get _isWindows();
     private _handleFileChange;
     private _findTreeByPath;
     private _notifyChange;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { FsAgent, SYNC_ERROR_FILE, type FsAgentOptions, type RestoreOptions, type TimeoutConfig, } from './fs-agent.ts';
 export { FsBlobAdapter, type BlobToFileOptions, type FileBlobMeta, type FileToBlobOptions, } from './fs-blob-adapter.ts';
 export { FsDbAdapter, type StoreFsTreeOptions } from './fs-db-adapter.ts';
+export { compareTips, conflictCopyName, decideWinner, DIR_MARKER, findCommonAncestor, formatConflictTimestamp, FsConflictResolver, fsTreeToContentMap, threeWayMerge, type BranchTip, type ConflictCopy, type ConflictResolverDeps, type ContentMap, type MergePlan, } from './fs-conflict-resolver.ts';
 export { FsScanner, type FsChange, type FsChangeCallback, type FsChangeType, type FsNodeMeta, type FsScanOptions, type FsTree, } from './fs-scanner.ts';
 export { runClientServerSetup, type ClientServerSetupOptions, type ClientServerSetupResult, } from './client-server/client-server-setup.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.12",
+  "version": "0.0.15",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",
@@ -19,6 +19,14 @@
     "dist"
   ],
   "type": "module",
+  "scripts": {
+    "build": "pnpm exec vite build && tsc && node scripts/copy-readme-to-dist.js",
+    "test": "cross-env NODE_OPTIONS=--max-old-space-size=8192 pnpm exec vitest run --coverage && pnpm run lint",
+    "prebuild": "npm run test",
+    "prepublishOnly": "npm run build",
+    "lint": "pnpm exec eslint .",
+    "updateGoldens": "cross-env UPDATE_GOLDENS=true pnpm test"
+  },
   "devDependencies": {
     "@rljson/server": "^0.0.10",
     "@types/node": "^25.3.1",
@@ -43,7 +51,7 @@
   },
   "dependencies": {
     "@rljson/bs": "^0.0.21",
-    "@rljson/db": "^0.0.15",
+    "@rljson/db": "^0.0.22",
     "@rljson/hash": "^0.0.18",
     "@rljson/io": "^0.0.66",
     "@rljson/json": "^0.0.23",
@@ -51,11 +59,13 @@
     "socket.io": "^4.8.3",
     "socket.io-client": "^4.8.3"
   },
-  "scripts": {
-    "build": "pnpm exec vite build && tsc && node scripts/copy-readme-to-dist.js",
-    "test": "cross-env NODE_OPTIONS=--max-old-space-size=8192 pnpm exec vitest run --coverage && pnpm run lint",
-    "prebuild": "npm run test",
-    "lint": "pnpm exec eslint .",
-    "updateGoldens": "cross-env UPDATE_GOLDENS=true pnpm test"
-  }
-}
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ],
+    "overrides": {
+      "@rljson/rljson": "^0.0.78"
+    }
+  },
+  "packageManager": "pnpm@10.11.0"
+}