@rljson/rljson 0.0.77 → 0.0.78

package/README.architecture.md

@@ -678,6 +678,32 @@ ephemeral Connector `origin` (which changes on every instantiation), a
 
 Format: `"client_"` + 12-character nanoid (e.g. `"client_V1StGXR8_Z5j"`).
 
+### Conflict Detection Types
+
+The sync protocol includes types for detecting DAG branch conflicts in the
+InsertHistory. A **DAG branch** occurs when two or more InsertHistory rows
+share the same predecessor, creating divergent branches from concurrent
+writes by different clients.
+
+| Type               | Description                                                           |
+| ------------------ | --------------------------------------------------------------------- |
+| `ConflictType`     | String literal union — currently `'dagBranch'`                        |
+| `Conflict`         | Interface describing a detected conflict: table, type, time, branches |
+| `ConflictCallback` | `(conflict: Conflict) => void` — callback type for observers          |
+
+**Conflict interface fields:**
+
+| Field        | Type                    | Description                                           |
+| ------------ | ----------------------- | ----------------------------------------------------- |
+| `table`      | `string`                | Table where the conflict was detected (no suffix)     |
+| `type`       | `ConflictType`          | `'dagBranch'`                                         |
+| `detectedAt` | `number`                | Timestamp (ms since epoch) of detection               |
+| `branches`   | `InsertHistoryTimeId[]` | Tip timeIds forming the DAG fork (always ≥ 2 entries) |
+
+Detection is protocol-level only — no resolution logic. Upper layers
+(application code or `@rljson/db`) use these types to signal and react
+to conflicts.
+
 ## Package Structure
 
 ```

package/README.public.md

@@ -360,6 +360,32 @@ isClientId(id);                // true
 isClientId('not-a-client-id'); // false
 ```
 
+### Conflict Detection Types
+
+Protocol-level types for DAG branch conflict detection. A conflict occurs when the InsertHistory for a table has diverged into multiple branches (multiple "tips" that are not ancestors of each other), indicating concurrent writes from different clients.
+
+Detection only — no resolution: these types signal that a conflict exists. Resolution logic is left to upper layers (application code).
+
+```typescript
+import type { Conflict, ConflictCallback, ConflictType } from '@rljson/rljson';
+
+// ConflictType — currently only 'dagBranch'
+const type: ConflictType = 'dagBranch';
+
+// Conflict — describes a detected fork in InsertHistory
+const conflict: Conflict = {
+  table: 'cars',                           // Table where the conflict was detected
+  type: 'dagBranch',                       // Type of conflict
+  detectedAt: Date.now(),                  // Detection timestamp (ms since epoch)
+  branches: ['17000…:AbCd', '17000…:EfGh'] // InsertHistory tip timeIds forming the fork
+};
+
+// ConflictCallback — fires when a conflict is detected
+const onConflict: ConflictCallback = (conflict: Conflict) => {
+  console.log(`Conflict in ${conflict.table}:`, conflict.branches);
+};
+```
+
 ## Utilities
 
 ### TimeId

package/dist/README.architecture.md

@@ -678,6 +678,32 @@ ephemeral Connector `origin` (which changes on every instantiation), a
 
 Format: `"client_"` + 12-character nanoid (e.g. `"client_V1StGXR8_Z5j"`).
 
+### Conflict Detection Types
+
+The sync protocol includes types for detecting DAG branch conflicts in the
+InsertHistory. A **DAG branch** occurs when two or more InsertHistory rows
+share the same predecessor, creating divergent branches from concurrent
+writes by different clients.
+
+| Type               | Description                                                           |
+| ------------------ | --------------------------------------------------------------------- |
+| `ConflictType`     | String literal union — currently `'dagBranch'`                        |
+| `Conflict`         | Interface describing a detected conflict: table, type, time, branches |
+| `ConflictCallback` | `(conflict: Conflict) => void` — callback type for observers          |
+
+**Conflict interface fields:**
+
+| Field        | Type                    | Description                                           |
+| ------------ | ----------------------- | ----------------------------------------------------- |
+| `table`      | `string`                | Table where the conflict was detected (no suffix)     |
+| `type`       | `ConflictType`          | `'dagBranch'`                                         |
+| `detectedAt` | `number`                | Timestamp (ms since epoch) of detection               |
+| `branches`   | `InsertHistoryTimeId[]` | Tip timeIds forming the DAG fork (always ≥ 2 entries) |
+
+Detection is protocol-level only — no resolution logic. Upper layers
+(application code or `@rljson/db`) use these types to signal and react
+to conflicts.
+
 ## Package Structure
 
 ```

package/dist/README.public.md

@@ -360,6 +360,32 @@ isClientId(id);                // true
 isClientId('not-a-client-id'); // false
 ```
 
+### Conflict Detection Types
+
+Protocol-level types for DAG branch conflict detection. A conflict occurs when the InsertHistory for a table has diverged into multiple branches (multiple "tips" that are not ancestors of each other), indicating concurrent writes from different clients.
+
+Detection only — no resolution: these types signal that a conflict exists. Resolution logic is left to upper layers (application code).
+
+```typescript
+import type { Conflict, ConflictCallback, ConflictType } from '@rljson/rljson';
+
+// ConflictType — currently only 'dagBranch'
+const type: ConflictType = 'dagBranch';
+
+// Conflict — describes a detected fork in InsertHistory
+const conflict: Conflict = {
+  table: 'cars',                           // Table where the conflict was detected
+  type: 'dagBranch',                       // Type of conflict
+  detectedAt: Date.now(),                  // Detection timestamp (ms since epoch)
+  branches: ['17000…:AbCd', '17000…:EfGh'] // InsertHistory tip timeIds forming the fork
+};
+
+// ConflictCallback — fires when a conflict is detected
+const onConflict: ConflictCallback = (conflict: Conflict) => {
+  console.log(`Conflict in ${conflict.table}:`, conflict.branches);
+};
+```
+
 ## Utilities
 
 ### TimeId

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/rljson",
-  "version": "0.0.77",
+  "version": "0.0.78",
   "description": "The RLJSON data format specification",
   "homepage": "https://github.com/rljson/rljson",
   "bugs": "https://github.com/rljson/rljson/issues",