@rljson/db 0.0.15 → 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

@@ -10,6 +10,7 @@ export declare class Connector {
     private _origin;
     private _callbacks;
     private _conflictCallbacks;
+    private _missedRef;
     private _isListening;
     private _sentRefsCurrent;
     private _sentRefsPrevious;

package/dist/db.js

@@ -23,6 +23,7 @@ class Connector {
   _origin;
   _callbacks = [];
   _conflictCallbacks = [];
+  _missedRef = null;
   _isListening = false;
   // Two-generation dedup sets — bounded memory
   _sentRefsCurrent = /* @__PURE__ */ new Set();
@@ -46,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
@@ -106,6 +108,11 @@ 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);
+    }
   }
   // ...........................................................................
   /**
@@ -202,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);
     });