@rljson/rljson 0.0.76 → 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/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from './rljson.ts';
 export * from './route/route.ts';
 export * from './sync/ack-payload.ts';
 export * from './sync/client-id.ts';
+export * from './sync/conflict.ts';
 export * from './sync/connector-payload.ts';
 export * from './sync/gap-fill.ts';
 export * from './sync/sync-config.ts';

package/dist/sync/conflict.d.ts

@@ -0,0 +1,39 @@
+import { InsertHistoryTimeId } from '../insertHistory/insertHistory.ts';
+/**
+ * The type of conflict detected in the InsertHistory DAG.
+ *
+ * - `'dagBranch'` — Two or more InsertHistory rows share the same
+ *   predecessor, creating divergent branches. This indicates concurrent
+ *   writes from different clients that have not yet been merged.
+ */
+export type ConflictType = 'dagBranch';
+/**
+ * Represents a detected conflict in the InsertHistory DAG.
+ *
+ * A `Conflict` is emitted when the system detects that the InsertHistory
+ * for a table has diverged into multiple branches (multiple "tips" that
+ * are not ancestors of each other).
+ * Detection only — no resolution: this type signals that a conflict
+ * exists. Resolution logic is left to upper layers (application code).
+ */
+export interface Conflict {
+    /** The table where the conflict was detected (without InsertHistory suffix). */
+    table: string;
+    /** The type of conflict. */
+    type: ConflictType;
+    /** Timestamp (ms since epoch) when the conflict was detected. */
+    detectedAt: number;
+    /**
+     * The InsertHistory tip timeIds that form the branches.
+     *
+     * A "tip" is a timeId that is not referenced as `previous` by any other
+     * InsertHistory row. Multiple tips indicate a DAG fork.
+     *
+     * Always contains at least two entries when `type === 'dagBranch'`.
+     */
+    branches: InsertHistoryTimeId[];
+}
+/**
+ * Callback invoked when a conflict is detected.
+ */
+export type ConflictCallback = (conflict: Conflict) => void;

package/package.json

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