@rljson/db 0.0.14 → 0.0.17

package/README.architecture.md

@@ -839,6 +839,46 @@ The Connector registers a listener on `events.bootstrap` in `_init()` via `_regi
 
 The `tearDown()` method cleans up the bootstrap listener alongside all other socket listeners.
 
+### Conflict Detection
+
+The `Db` class integrates DAG branch conflict detection directly into the write path. After every call to `_writeInsertHistory()`, the system invokes `detectDagBranch(table)` to scan the InsertHistory for forks.
+
+**Algorithm (`detectDagBranch`)**:
+
+1. Load all rows from `{table}InsertHistory`.
+2. Build a set of all timeIds that appear as someone's `previous`.
+3. Tips = rows whose `timeId` is **not** in that set (no descendant).
+4. If more than one tip exists → DAG branch conflict.
+
+```text
+       ┌─── tip A  (17000…:AbCd)
+root ──┤
+       └─── tip B  (17000…:EfGh)
+       ↑
+   DAG branch: two concurrent writes, no merge yet
+```
+
+**Observer pipeline:**
+
+```text
+_writeInsertHistory()
+  └──► detectDagBranch(table)
+         └──► if conflict found:
+                _notifyConflict(table, conflict)
+                  └──► fire all callbacks in _conflictCallbacks[route]
+```
+
+**Connector integration**: `Connector.onConflict(callback)` calls `db.registerConflictObserver()` under the hood, so callbacks fire for conflicts on the route managed by that Connector. `tearDown()` calls `db.unregisterAllConflictObservers()` to clean up.
+
+**Key properties:**
+
+| Property          | Value                                                                        |
+| ----------------- | ---------------------------------------------------------------------------- |
+| Detection trigger | Every `_writeInsertHistory()` call                                           |
+| Scope             | Per-table (each table's InsertHistory is independent)                        |
+| Resolution        | Not provided — detection and signaling only                                  |
+| Merge detection   | A conflict **disappears** when a merge row references all tips as `previous` |
+
 ## Future Enhancements
 
 ### Planned Features

package/README.public.md

@@ -979,6 +979,57 @@ connector.tearDown();
 // Removes all socket listeners and clears internal state
 ```
 
+### Conflict Detection
+
+The `Db` class detects DAG branch conflicts in the InsertHistory and notifies registered observers. A **DAG branch** occurs when two or more InsertHistory rows have no descendant — i.e., they are "tips" of the history graph — indicating concurrent writes from different clients that have not yet been merged.
+
+#### Manual Detection
+
+```typescript
+// Check whether a table's InsertHistory has diverged
+const conflict = await db.detectDagBranch('cars');
+if (conflict) {
+  console.log(conflict.table);    // 'cars'
+  console.log(conflict.type);     // 'dagBranch'
+  console.log(conflict.branches); // ['17000…:AbCd', '17000…:EfGh']
+}
+// Returns null when the history is linear (no conflict)
+```
+
+#### Automatic Detection via Observers
+
+Conflict detection runs automatically after every `_writeInsertHistory()` call. Register callbacks on the `Db` to be notified immediately:
+
+```typescript
+import type { Conflict, ConflictCallback } from '@rljson/db';
+
+const onConflict: ConflictCallback = (conflict: Conflict) => {
+  console.warn(`DAG branch in ${conflict.table}:`, conflict.branches);
+};
+
+// Register
+db.registerConflictObserver(route, onConflict);
+
+// Unregister a specific callback
+db.unregisterConflictObserver(route, onConflict);
+
+// Unregister all callbacks for a route
+db.unregisterAllConflictObservers(route);
+```
+
+#### Via Connector
+
+The `Connector` provides a convenience method that wraps the Db observer API:
+
+```typescript
+connector.onConflict((conflict) => {
+  console.warn(`Conflict detected:`, conflict);
+});
+// Cleaned up automatically on connector.tearDown()
+```
+
+**Detection only — no resolution.** The system signals that a conflict exists; merging divergent branches is left to application code.
+
 ## Examples
 
 See [src/example.ts](src/example.ts) for a complete working example demonstrating:

package/dist/README.architecture.md

@@ -839,6 +839,46 @@ The Connector registers a listener on `events.bootstrap` in `_init()` via `_regi
 
 The `tearDown()` method cleans up the bootstrap listener alongside all other socket listeners.
 
+### Conflict Detection
+
+The `Db` class integrates DAG branch conflict detection directly into the write path. After every call to `_writeInsertHistory()`, the system invokes `detectDagBranch(table)` to scan the InsertHistory for forks.
+
+**Algorithm (`detectDagBranch`)**:
+
+1. Load all rows from `{table}InsertHistory`.
+2. Build a set of all timeIds that appear as someone's `previous`.
+3. Tips = rows whose `timeId` is **not** in that set (no descendant).
+4. If more than one tip exists → DAG branch conflict.
+
+```text
+       ┌─── tip A  (17000…:AbCd)
+root ──┤
+       └─── tip B  (17000…:EfGh)
+       ↑
+   DAG branch: two concurrent writes, no merge yet
+```
+
+**Observer pipeline:**
+
+```text
+_writeInsertHistory()
+  └──► detectDagBranch(table)
+         └──► if conflict found:
+                _notifyConflict(table, conflict)
+                  └──► fire all callbacks in _conflictCallbacks[route]
+```
+
+**Connector integration**: `Connector.onConflict(callback)` calls `db.registerConflictObserver()` under the hood, so callbacks fire for conflicts on the route managed by that Connector. `tearDown()` calls `db.unregisterAllConflictObservers()` to clean up.
+
+**Key properties:**
+
+| Property          | Value                                                                        |
+| ----------------- | ---------------------------------------------------------------------------- |
+| Detection trigger | Every `_writeInsertHistory()` call                                           |
+| Scope             | Per-table (each table's InsertHistory is independent)                        |
+| Resolution        | Not provided — detection and signaling only                                  |
+| Merge detection   | A conflict **disappears** when a merge row references all tips as `previous` |
+
 ## Future Enhancements
 
 ### Planned Features

package/dist/README.public.md

@@ -979,6 +979,57 @@ connector.tearDown();
 // Removes all socket listeners and clears internal state
 ```
 
+### Conflict Detection
+
+The `Db` class detects DAG branch conflicts in the InsertHistory and notifies registered observers. A **DAG branch** occurs when two or more InsertHistory rows have no descendant — i.e., they are "tips" of the history graph — indicating concurrent writes from different clients that have not yet been merged.
+
+#### Manual Detection
+
+```typescript
+// Check whether a table's InsertHistory has diverged
+const conflict = await db.detectDagBranch('cars');
+if (conflict) {
+  console.log(conflict.table);    // 'cars'
+  console.log(conflict.type);     // 'dagBranch'
+  console.log(conflict.branches); // ['17000…:AbCd', '17000…:EfGh']
+}
+// Returns null when the history is linear (no conflict)
+```
+
+#### Automatic Detection via Observers
+
+Conflict detection runs automatically after every `_writeInsertHistory()` call. Register callbacks on the `Db` to be notified immediately:
+
+```typescript
+import type { Conflict, ConflictCallback } from '@rljson/db';
+
+const onConflict: ConflictCallback = (conflict: Conflict) => {
+  console.warn(`DAG branch in ${conflict.table}:`, conflict.branches);
+};
+
+// Register
+db.registerConflictObserver(route, onConflict);
+
+// Unregister a specific callback
+db.unregisterConflictObserver(route, onConflict);
+
+// Unregister all callbacks for a route
+db.unregisterAllConflictObservers(route);
+```
+
+#### Via Connector
+
+The `Connector` provides a convenience method that wraps the Db observer API:
+
+```typescript
+connector.onConflict((conflict) => {
+  console.warn(`Conflict detected:`, conflict);
+});
+// Cleaned up automatically on connector.tearDown()
+```
+
+**Detection only — no resolution.** The system signals that a conflict exists; merging divergent branches is left to application code.
+
 ## Examples
 
 See [src/example.ts](src/example.ts) for a complete working example demonstrating:

package/dist/connector/connector.d.ts

@@ -1,5 +1,5 @@
 import { Socket } from '@rljson/io';
-import { AckPayload, ClientId, InsertHistoryTimeId, Route, SyncConfig, SyncEventNames } from '@rljson/rljson';
+import { AckPayload, ClientId, ConflictCallback, InsertHistoryTimeId, Route, SyncConfig, SyncEventNames } from '@rljson/rljson';
 import { Db } from '../db.ts';
 export type { ConnectorPayload } from '@rljson/rljson';
 export type ConnectorCallback = (ref: string) => Promise<any>;
@@ -9,6 +9,8 @@ export declare class Connector {
     private readonly _socket;
     private _origin;
     private _callbacks;
+    private _conflictCallbacks;
+    private _missedRef;
     private _isListening;
     private _sentRefsCurrent;
     private _sentRefsPrevious;
@@ -49,6 +51,18 @@ export declare class Connector {
      * @param callback - The callback to invoke with each deduplicated incoming ref
      */
     listen(callback: ConnectorCallback): void;
+    /**
+     * Registers a callback that fires when a DAG conflict is detected.
+     *
+     * A conflict occurs when the InsertHistory for this route's table
+     * has multiple "tips" (leaf nodes), indicating concurrent writes
+     * from different clients that have not yet been merged.
+     *
+     * Detection-only: the callback receives a `Conflict` object
+     * describing the branches. Resolution is left to upper layers.
+     * @param callback - Invoked with the detected Conflict
+     */
+    onConflict(callback: ConflictCallback): void;
     /**
      * Returns the current sequence number.
      * Only meaningful when `causalOrdering` is enabled.
@@ -83,6 +97,7 @@ export declare class Connector {
      * _processIncoming handles dedup so already-seen refs are filtered out.
      */
     private _registerBootstrapHandler;
+    private _registerConflictObserver;
     private _registerDbObserver;
     get socket(): Socket;
     get route(): Route;

package/dist/db.d.ts

@@ -1,6 +1,6 @@
 import { Io } from '@rljson/io';
 import { Json, JsonValue } from '@rljson/json';
-import { Edit, EditHistory, InsertHistoryRow, InsertHistoryTimeId, MultiEdit, Ref, Rljson, Route, SliceId, TableType, Tree } from '@rljson/rljson';
+import { Conflict, ConflictCallback, Edit, EditHistory, InsertHistoryRow, InsertHistoryTimeId, MultiEdit, Ref, Rljson, Route, SliceId, TableType, Tree } from '@rljson/rljson';
 import { Controller, ControllerChildProperty, ControllerRefs } from './controller/controller.ts';
 import { Core } from './core.ts';
 import { Join } from './join/join.ts';
@@ -43,6 +43,7 @@ export declare class Db {
      * Notification system to register callbacks on data changes
      */
     readonly notify: Notify;
+    private _conflictCallbacks;
     private _cache;
     /**
      * Get data from a route with optional filtering
@@ -137,6 +138,24 @@ export declare class Db {
      * Unregisters all observers from all routes
      */
     unregisterAllObservers(route: Route): void;
+    /**
+     * Registers a callback to be called when a DAG conflict is detected
+     * on the given route.
+     * @param route - The route to register the conflict callback on
+     * @param callback - The callback to invoke with the Conflict
+     */
+    registerConflictObserver(route: Route, callback: ConflictCallback): void;
+    /**
+     * Unregisters a specific conflict callback from the given route.
+     * @param route - The route to unregister the callback from
+     * @param callback - The callback to remove
+     */
+    unregisterConflictObserver(route: Route, callback: ConflictCallback): void;
+    /**
+     * Unregisters all conflict callbacks from the given route.
+     * @param route - The route to clear conflict callbacks for
+     */
+    unregisterAllConflictObservers(route: Route): void;
     /**
      * Get a controller for a specific table
      * @param tableKey - The key of the table to get the controller for
@@ -146,6 +165,22 @@ export declare class Db {
      */
     getController(tableKey: string, refs?: ControllerRefs): Promise<Controller<TableType, any, string>>;
     indexedControllers(route: Route): Promise<Record<string, Controller<any, any, any>>>;
+    /**
+     * Detects whether the InsertHistory for a table has diverged into
+     * multiple branches (multiple "tips" — leaf nodes in the DAG).
+     *
+     * A tip is a timeId that is NOT referenced as `previous` by any other
+     * InsertHistory row. Two or more tips indicate a DAG fork (conflict).
+     * @param table - The table name (without "InsertHistory" suffix)
+     * @returns A Conflict if a DAG branch is detected, or null otherwise
+     */
+    detectDagBranch(table: string): Promise<Conflict | null>;
+    /**
+     * Fires conflict callbacks registered on the route derived from the table.
+     * @param table - The table name
+     * @param conflict - The detected conflict
+     */
+    private _notifyConflict;
     /**
      * Adds an InsertHistory row to the InsertHistory table of a table
      * @param table - The table the Insert was made on

package/dist/db.js

@@ -22,6 +22,8 @@ class Connector {
   }
   _origin;
   _callbacks = [];
+  _conflictCallbacks = [];
+  _missedRef = null;
   _isListening = false;
   // Two-generation dedup sets — bounded memory
   _sentRefsCurrent = /* @__PURE__ */ new Set();
@@ -45,6 +47,7 @@ class Connector {
   send(ref) {
     if (this._hasSentRef(ref) || this._hasReceivedRef(ref)) return;
     this._addSentRef(ref);
+    this._missedRef = null;
     const payload = {
       o: this._origin,
       r: ref
@@ -105,6 +108,26 @@ class Connector {
    */
   listen(callback) {
     this._callbacks.push(callback);
+    if (this._missedRef !== null) {
+      const ref = this._missedRef;
+      this._missedRef = null;
+      Promise.resolve(callback(ref)).catch(console.error);
+    }
+  }
+  // ...........................................................................
+  /**
+   * Registers a callback that fires when a DAG conflict is detected.
+   *
+   * A conflict occurs when the InsertHistory for this route's table
+   * has multiple "tips" (leaf nodes), indicating concurrent writes
+   * from different clients that have not yet been merged.
+   *
+   * Detection-only: the callback receives a `Conflict` object
+   * describing the branches. Resolution is left to upper layers.
+   * @param callback - Invoked with the detected Conflict
+   */
+  onConflict(callback) {
+    this._conflictCallbacks.push(callback);
   }
   // ...........................................................................
   /**
@@ -143,6 +166,7 @@ class Connector {
     this._registerSocketObserver();
     this._registerBootstrapHandler();
     this._registerDbObserver();
+    this._registerConflictObserver();
     if (this._syncConfig?.causalOrdering) {
       this._registerGapFillHandler();
     }
@@ -158,6 +182,7 @@ class Connector {
       this._socket.removeAllListeners(this._events.ack);
     }
     this._db.unregisterAllObservers(this._route);
+    this._db.unregisterAllConflictObservers(this._route);
     this._isListening = false;
   }
   // ...........................................................................
@@ -184,6 +209,10 @@ class Connector {
     }
   }
   _notifyCallbacks(ref) {
+    if (this._callbacks.length === 0) {
+      this._missedRef = ref;
+      return;
+    }
     Promise.all(this._callbacks.map((cb) => cb(ref))).catch((err) => {
       console.error(`Error notifying connector callbacks for ref ${ref}:`, err);
     });
@@ -235,6 +264,13 @@ class Connector {
       this._processIncoming(p);
     });
   }
+  _registerConflictObserver() {
+    this._db.registerConflictObserver(this._route, (conflict) => {
+      for (const cb of this._conflictCallbacks) {
+        cb(conflict);
+      }
+    });
+  }
   _registerDbObserver() {
     this._db.registerObserver(this._route, (ins) => {
       return new Promise((resolve) => {
@@ -3092,6 +3128,7 @@ class Db {
    * Notification system to register callbacks on data changes
    */
   notify;
+  _conflictCallbacks = /* @__PURE__ */ new Map();
   _cache = /* @__PURE__ */ new Map();
   // ...........................................................................
   /**
@@ -4061,6 +4098,44 @@ class Db {
     this.notify.unregisterAll(route);
   }
   // ...........................................................................
+  /**
+   * Registers a callback to be called when a DAG conflict is detected
+   * on the given route.
+   * @param route - The route to register the conflict callback on
+   * @param callback - The callback to invoke with the Conflict
+   */
+  registerConflictObserver(route, callback) {
+    const key = route.flat;
+    this._conflictCallbacks.set(key, [
+      ...this._conflictCallbacks.get(key) || [],
+      callback
+    ]);
+  }
+  // ...........................................................................
+  /**
+   * Unregisters a specific conflict callback from the given route.
+   * @param route - The route to unregister the callback from
+   * @param callback - The callback to remove
+   */
+  unregisterConflictObserver(route, callback) {
+    const key = route.flat;
+    const callbacks = this._conflictCallbacks.get(key);
+    if (callbacks) {
+      this._conflictCallbacks.set(
+        key,
+        callbacks.filter((cb) => cb !== callback)
+      );
+    }
+  }
+  // ...........................................................................
+  /**
+   * Unregisters all conflict callbacks from the given route.
+   * @param route - The route to clear conflict callbacks for
+   */
+  unregisterAllConflictObservers(route) {
+    this._conflictCallbacks.delete(route.flat);
+  }
+  // ...........................................................................
   /**
    * Get a controller for a specific table
    * @param tableKey - The key of the table to get the controller for
@@ -4093,6 +4168,57 @@ class Db {
     return controllers;
   }
   // ...........................................................................
+  /**
+   * Detects whether the InsertHistory for a table has diverged into
+   * multiple branches (multiple "tips" — leaf nodes in the DAG).
+   *
+   * A tip is a timeId that is NOT referenced as `previous` by any other
+   * InsertHistory row. Two or more tips indicate a DAG fork (conflict).
+   * @param table - The table name (without "InsertHistory" suffix)
+   * @returns A Conflict if a DAG branch is detected, or null otherwise
+   */
+  async detectDagBranch(table) {
+    const insertHistoryTable = table + "InsertHistory";
+    const hasTable = await this.core.hasTable(insertHistoryTable);
+    if (!hasTable) return null;
+    const dump = await this.core.dumpTable(insertHistoryTable);
+    const rows = dump[insertHistoryTable]._data;
+    if (rows.length < 2) return null;
+    const referencedAsParent = /* @__PURE__ */ new Set();
+    for (const row of rows) {
+      if (row.previous) {
+        for (const p of row.previous) {
+          referencedAsParent.add(p);
+        }
+      }
+    }
+    const tips = rows.filter((row) => !referencedAsParent.has(row.timeId));
+    if (tips.length > 1) {
+      return {
+        table,
+        type: "dagBranch",
+        detectedAt: Date.now(),
+        branches: tips.map((t) => t.timeId)
+      };
+    }
+    return null;
+  }
+  // ...........................................................................
+  /**
+   * Fires conflict callbacks registered on the route derived from the table.
+   * @param table - The table name
+   * @param conflict - The detected conflict
+   */
+  _notifyConflict(table, conflict) {
+    const route = Route.fromFlat(`/${table}`);
+    const callbacks = this._conflictCallbacks.get(route.flat);
+    if (callbacks) {
+      for (const cb of callbacks) {
+        cb(conflict);
+      }
+    }
+  }
+  // ...........................................................................
   /**
    * Adds an InsertHistory row to the InsertHistory table of a table
    * @param table - The table the Insert was made on
@@ -4107,6 +4233,10 @@ class Db {
         _type: "insertHistory"
       }
     });
+    const conflict = await this.detectDagBranch(table);
+    if (conflict) {
+      this._notifyConflict(table, conflict);
+    }
   }
   // ...........................................................................
   /**