json-patch-to-crdt 0.0.0 → 0.1.1

package/dist/{merge-DikOFBWc.mjs → merge-CKcP1ZPt.mjs}

@@ -194,6 +194,19 @@ const ROOT_KEY = "@@crdt/root";
 
 //#endregion
 //#region src/patch.ts
+/** Structured compile error used to map patch validation failures to typed reasons. */
+var PatchCompileError = class extends Error {
+	reason;
+	path;
+	opIndex;
+	constructor(reason, message, path, opIndex) {
+		super(message);
+		this.name = "PatchCompileError";
+		this.reason = reason;
+		this.path = path;
+		this.opIndex = opIndex;
+	}
+};
 /**
 * Parse an RFC 6901 JSON Pointer into a path array, unescaping `~1` and `~0`.
 * @param ptr - A JSON Pointer string (e.g. `"/a/b"` or `""`).
@@ -202,13 +215,37 @@ const ROOT_KEY = "@@crdt/root";
 function parseJsonPointer(ptr) {
 	if (ptr === "") return [];
 	if (!ptr.startsWith("/")) throw new Error(`Invalid pointer: ${ptr}`);
-	return ptr.slice(1).split("/").map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+	return ptr.slice(1).split("/").map(unescapeJsonPointerToken);
 }
 /** Convert a path array back to an RFC 6901 JSON Pointer string. */
 function stringifyJsonPointer(path) {
 	if (path.length === 0) return "";
 	return `/${path.map(escapeJsonPointer).join("/")}`;
 }
+function unescapeJsonPointerToken(token) {
+	let out = "";
+	for (let i = 0; i < token.length; i++) {
+		const ch = token[i];
+		if (ch !== "~") {
+			out += ch;
+			continue;
+		}
+		const esc = token[i + 1];
+		if (esc === "0") {
+			out += "~";
+			i += 1;
+			continue;
+		}
+		if (esc === "1") {
+			out += "/";
+			i += 1;
+			continue;
+		}
+		const sequence = esc === void 0 ? "~" : `~${esc}`;
+		throw new Error(`Invalid pointer escape sequence '${sequence}'`);
+	}
+	return out;
+}
 /**
 * Navigate a JSON value by path and return the value at that location.
 * Throws if the path is invalid, out of bounds, or traverses a non-container.
@@ -216,8 +253,8 @@ function stringifyJsonPointer(path) {
 function getAtJson(base, path) {
 	let cur = base;
 	for (const seg of path) if (Array.isArray(cur)) {
-		const idx = seg === "-" ? cur.length : Number(seg);
-		if (!Number.isInteger(idx)) throw new Error(`Expected array index, got ${seg}`);
+		if (!ARRAY_INDEX_TOKEN_PATTERN.test(seg)) throw new Error(`Expected array index, got ${seg}`);
+		const idx = Number(seg);
 		if (idx < 0 || idx >= cur.length) throw new Error(`Index out of bounds at ${seg}`);
 		cur = cur[idx];
 	} else if (cur && typeof cur === "object") {
@@ -234,94 +271,15 @@ function getAtJson(base, path) {
 * @param patch - Array of JSON Patch operations.
 * @returns An array of `IntentOp` ready for `applyIntentsToCrdt`.
 */
-function compileJsonPatchToIntent(baseJson, patch) {
+function compileJsonPatchToIntent(baseJson, patch, options = {}) {
+	const semantics = options.semantics ?? "sequential";
+	let workingBase = semantics === "sequential" ? structuredClone(baseJson) : baseJson;
 	const intents = [];
-	for (const op of patch) {
-		if (op.op === "test") {
-			intents.push({
-				t: "Test",
-				path: parseJsonPointer(op.path),
-				value: op.value
-			});
-			continue;
-		}
-		if (op.op === "copy" || op.op === "move") {
-			const val = getAtJson(baseJson, parseJsonPointer(op.from));
-			intents.push(...compileJsonPatchToIntent(baseJson, [{
-				op: "add",
-				path: op.path,
-				value: val
-			}]));
-			if (op.op === "move") intents.push(...compileJsonPatchToIntent(baseJson, [{
-				op: "remove",
-				path: op.from
-			}]));
-			continue;
-		}
-		const path = parseJsonPointer(op.path);
-		const parent = path.slice(0, -1);
-		const last = path[path.length - 1];
-		if (path.length === 0) {
-			if (op.op === "replace" || op.op === "add") intents.push({
-				t: "ObjSet",
-				path: [],
-				key: ROOT_KEY,
-				value: op.value
-			});
-			else if (op.op === "remove") intents.push({
-				t: "ObjSet",
-				path: [],
-				key: ROOT_KEY,
-				value: null
-			});
-			continue;
-		}
-		const isIndexLike = (s) => s === "-" || /^[0-9]+$/.test(s);
-		if (isIndexLike(last)) {
-			const index = last === "-" ? Number.POSITIVE_INFINITY : Number(last);
-			if (op.op === "add") intents.push({
-				t: "ArrInsert",
-				path: parent,
-				index,
-				value: op.value
-			});
-			else if (op.op === "remove") intents.push({
-				t: "ArrDelete",
-				path: parent,
-				index
-			});
-			else if (op.op === "replace") intents.push({
-				t: "ArrReplace",
-				path: parent,
-				index,
-				value: op.value
-			});
-			else assertNever$1(op, "Unsupported op at array index path");
-		} else {
-			const parentValue = pathValueAt(baseJson, parent);
-			if (!isPlainObject(parentValue)) throw new Error(`Expected object parent at ${stringifyJsonPointer(parent)}`);
-			if ((op.op === "replace" || op.op === "remove") && !hasOwn(parentValue, last)) throw new Error(`Missing key ${last} at ${stringifyJsonPointer(parent)}`);
-			if (op.op === "add") intents.push({
-				t: "ObjSet",
-				path: parent,
-				key: last,
-				value: op.value,
-				mode: "add"
-			});
-			else if (op.op === "replace") intents.push({
-				t: "ObjSet",
-				path: parent,
-				key: last,
-				value: op.value,
-				mode: "replace"
-			});
-			else if (op.op === "remove") intents.push({
-				t: "ObjRemove",
-				path: parent,
-				key: last
-			});
-			else assertNever$1(op, "Unsupported op");
-		}
+	for (let opIndex = 0; opIndex < patch.length; opIndex++) {
+		const op = patch[opIndex];
+		const compileBase = semantics === "sequential" ? workingBase : baseJson;
+		intents.push(...compileSingleOp(compileBase, op, opIndex, semantics));
+		if (semantics === "sequential") workingBase = applyPatchOpToJson(workingBase, op, opIndex);
 	}
 	return intents;
 }
@@ -463,6 +421,7 @@ function jsonEquals(a, b) {
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+const ARRAY_INDEX_TOKEN_PATTERN = /^(0|[1-9][0-9]*)$/;
 function hasOwn(value, key) {
 	return Object.prototype.hasOwnProperty.call(value, key);
 }
@@ -473,6 +432,223 @@ function pathValueAt(base, path) {
 function assertNever$1(_value, message) {
 	throw new Error(message);
 }
+function compileSingleOp(baseJson, op, opIndex, semantics) {
+	if (op.op === "test") return [{
+		t: "Test",
+		path: parsePointerOrThrow(op.path, op.path, opIndex),
+		value: op.value
+	}];
+	if (op.op === "copy" || op.op === "move") {
+		const fromPath = parsePointerOrThrow(op.from, op.from, opIndex);
+		const toPath = parsePointerOrThrow(op.path, op.path, opIndex);
+		if (op.op === "move" && isStrictDescendantPath(fromPath, toPath)) throw compileError("INVALID_MOVE", `cannot move a value into one of its descendants at ${op.path}`, op.path, opIndex);
+		const val = lookupValueOrThrow(baseJson, fromPath, op.from, opIndex);
+		if (op.op === "move" && isSamePath(fromPath, toPath)) return [];
+		if (op.op === "move" && semantics === "sequential") {
+			const removeOp = {
+				op: "remove",
+				path: op.from
+			};
+			const addOp = {
+				op: "add",
+				path: op.path,
+				value: val
+			};
+			const baseAfterRemove = applyPatchOpToJson(baseJson, removeOp, opIndex);
+			return [...compileSingleOp(baseJson, removeOp, opIndex, semantics), ...compileSingleOp(baseAfterRemove, addOp, opIndex, semantics)];
+		}
+		const out = compileSingleOp(baseJson, {
+			op: "add",
+			path: op.path,
+			value: val
+		}, opIndex, semantics);
+		if (op.op === "move") out.push(...compileSingleOp(baseJson, {
+			op: "remove",
+			path: op.from
+		}, opIndex, semantics));
+		return out;
+	}
+	const path = parsePointerOrThrow(op.path, op.path, opIndex);
+	if (path.length === 0) {
+		if (op.op === "replace" || op.op === "add") return [{
+			t: "ObjSet",
+			path: [],
+			key: ROOT_KEY,
+			value: op.value
+		}];
+		throw compileError("INVALID_TARGET", "remove at root path is not supported in RFC-compliant mode", op.path, opIndex);
+	}
+	const parent = path.slice(0, -1);
+	const token = path[path.length - 1];
+	const parentPath = stringifyJsonPointer(parent);
+	const parentValue = getParentValue(baseJson, parent, opIndex);
+	if (Array.isArray(parentValue)) {
+		const index = parseArrayIndexToken(token, op.op, parentValue.length, op.path, opIndex);
+		if (op.op === "add") return [{
+			t: "ArrInsert",
+			path: parent,
+			index,
+			value: op.value
+		}];
+		if (op.op === "remove") return [{
+			t: "ArrDelete",
+			path: parent,
+			index
+		}];
+		if (op.op === "replace") return [{
+			t: "ArrReplace",
+			path: parent,
+			index,
+			value: op.value
+		}];
+		return assertNever$1(op, "Unsupported op at array path");
+	}
+	if (!isPlainObject(parentValue)) throw compileError("INVALID_TARGET", `expected object or array parent at ${parentPath}`, parentPath, opIndex);
+	if ((op.op === "replace" || op.op === "remove") && !hasOwn(parentValue, token)) throw compileError("MISSING_TARGET", `missing key ${token} at ${parentPath}`, op.path, opIndex);
+	if (op.op === "add") return [{
+		t: "ObjSet",
+		path: parent,
+		key: token,
+		value: op.value,
+		mode: "add"
+	}];
+	if (op.op === "replace") return [{
+		t: "ObjSet",
+		path: parent,
+		key: token,
+		value: op.value,
+		mode: "replace"
+	}];
+	if (op.op === "remove") return [{
+		t: "ObjRemove",
+		path: parent,
+		key: token
+	}];
+	return assertNever$1(op, "Unsupported op");
+}
+function applyPatchOpToJson(baseJson, op, opIndex) {
+	let doc = structuredClone(baseJson);
+	if (op.op === "test") return doc;
+	if (op.op === "copy" || op.op === "move") {
+		const fromPath = parsePointerOrThrow(op.from, op.from, opIndex);
+		const value = structuredClone(lookupValueOrThrow(doc, fromPath, op.from, opIndex));
+		if (op.op === "move") doc = applyPatchOpToJson(doc, {
+			op: "remove",
+			path: op.from
+		}, opIndex);
+		return applyPatchOpToJson(doc, {
+			op: "add",
+			path: op.path,
+			value
+		}, opIndex);
+	}
+	const path = parsePointerOrThrow(op.path, op.path, opIndex);
+	if (path.length === 0) {
+		if (op.op === "add" || op.op === "replace") return structuredClone(op.value);
+		throw compileError("INVALID_TARGET", "remove at root path is not supported in RFC-compliant mode", op.path, opIndex);
+	}
+	const parentPath = path.slice(0, -1);
+	const token = path[path.length - 1];
+	let parent;
+	if (parentPath.length === 0) parent = doc;
+	else parent = lookupValueOrThrow(doc, parentPath, op.path, opIndex);
+	if (Array.isArray(parent)) {
+		const index = parseArrayIndexToken(token, op.op, parent.length, op.path, opIndex);
+		if (op.op === "add") {
+			const insertAt = index === Number.POSITIVE_INFINITY ? parent.length : index;
+			parent.splice(insertAt, 0, structuredClone(op.value));
+			return doc;
+		}
+		if (op.op === "replace") {
+			parent[index] = structuredClone(op.value);
+			return doc;
+		}
+		parent.splice(index, 1);
+		return doc;
+	}
+	if (!isPlainObject(parent)) throw compileError("INVALID_TARGET", `expected object or array parent at ${stringifyJsonPointer(parentPath)}`, op.path, opIndex);
+	if (op.op === "add" || op.op === "replace") {
+		parent[token] = structuredClone(op.value);
+		return doc;
+	}
+	delete parent[token];
+	return doc;
+}
+function parsePointerOrThrow(ptr, path, opIndex) {
+	try {
+		return parseJsonPointer(ptr);
+	} catch (error) {
+		throw compileError("INVALID_POINTER", error instanceof Error ? error.message : "invalid pointer", path, opIndex);
+	}
+}
+function lookupValueOrThrow(baseJson, path, pointer, opIndex) {
+	try {
+		return getAtJson(baseJson, path);
+	} catch (error) {
+		throw compileErrorFromLookup(error, pointer, opIndex);
+	}
+}
+function getParentValue(baseJson, parent, opIndex) {
+	if (parent.length === 0) return baseJson;
+	try {
+		return pathValueAt(baseJson, parent);
+	} catch (error) {
+		throw compileErrorFromLookup(error, stringifyJsonPointer(parent), opIndex);
+	}
+}
+function parseArrayIndexToken(token, op, arrLength, path, opIndex) {
+	if (token === "-") {
+		if (op !== "add") throw compileError("INVALID_POINTER", `'-' index is only valid for add at ${path}`, path, opIndex);
+		return Number.POSITIVE_INFINITY;
+	}
+	if (!ARRAY_INDEX_TOKEN_PATTERN.test(token)) throw compileError("INVALID_POINTER", `expected array index at ${path}`, path, opIndex);
+	const index = Number(token);
+	if (!Number.isSafeInteger(index)) throw compileError("OUT_OF_BOUNDS", `array index is too large at ${path}`, path, opIndex);
+	if (op === "add") {
+		if (index > arrLength) throw compileError("OUT_OF_BOUNDS", `index out of bounds at ${path}; expected 0..${arrLength}`, path, opIndex);
+	} else if (index >= arrLength) throw compileError("OUT_OF_BOUNDS", `index out of bounds at ${path}; expected 0..${Math.max(arrLength - 1, 0)}`, path, opIndex);
+	return index;
+}
+function compileErrorFromLookup(error, path, opIndex) {
+	const mapped = mapLookupErrorToPatchReason(error);
+	return compileError(mapped.reason, mapped.message, path, opIndex);
+}
+function mapLookupErrorToPatchReason(error) {
+	const message = error instanceof Error ? error.message : "invalid path";
+	if (message.includes("Expected array index")) return {
+		reason: "INVALID_POINTER",
+		message
+	};
+	if (message.includes("Index out of bounds")) return {
+		reason: "OUT_OF_BOUNDS",
+		message
+	};
+	if (message.includes("Missing key")) return {
+		reason: "MISSING_PARENT",
+		message
+	};
+	if (message.includes("Cannot traverse into non-container")) return {
+		reason: "INVALID_TARGET",
+		message
+	};
+	return {
+		reason: "INVALID_PATCH",
+		message
+	};
+}
+function compileError(reason, message, path, opIndex) {
+	return new PatchCompileError(reason, message, path, opIndex);
+}
+function isStrictDescendantPath(from, to) {
+	if (to.length <= from.length) return false;
+	for (let i = 0; i < from.length; i++) if (from[i] !== to[i]) return false;
+	return true;
+}
+function isSamePath(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
 
 //#endregion
 //#region src/doc.ts
@@ -673,13 +849,17 @@ function applyTest(base, head, it, evalTestAgainst) {
 		return {
 			ok: false,
 			code: 409,
-			message: `test path missing at /${it.path.join("/")}`
+			reason: "MISSING_TARGET",
+			message: `test path missing at /${it.path.join("/")}`,
+			path: `/${it.path.join("/")}`
 		};
 	}
 	if (!jsonEquals(got, it.value)) return {
 		ok: false,
 		code: 409,
-		message: `test failed at /${it.path.join("/")}`
+		reason: "TEST_FAILED",
+		message: `test failed at /${it.path.join("/")}`,
+		path: `/${it.path.join("/")}`
 	};
 	return null;
 }
@@ -692,12 +872,16 @@ function applyObjSet(head, it, newDot) {
 	if (!parentRes.ok) return {
 		ok: false,
 		code: 409,
-		message: parentRes.message
+		reason: "MISSING_PARENT",
+		message: parentRes.message,
+		path: `/${it.path.join("/")}`
 	};
 	if (it.mode === "replace" && !parentRes.obj.entries.has(it.key)) return {
 		ok: false,
 		code: 409,
-		message: `no value at /${[...it.path, it.key].join("/")}`
+		reason: "MISSING_TARGET",
+		message: `no value at /${[...it.path, it.key].join("/")}`,
+		path: `/${[...it.path, it.key].join("/")}`
 	};
 	const d = newDot();
 	const parentObj = parentRes.obj;
@@ -709,12 +893,16 @@ function applyObjRemove(head, it, newDot) {
 	if (!parentRes.ok) return {
 		ok: false,
 		code: 409,
-		message: parentRes.message
+		reason: "MISSING_PARENT",
+		message: parentRes.message,
+		path: `/${it.path.join("/")}`
 	};
 	if (!parentRes.obj.entries.has(it.key)) return {
 		ok: false,
 		code: 409,
-		message: `no value at /${[...it.path, it.key].join("/")}`
+		reason: "MISSING_TARGET",
+		message: `no value at /${[...it.path, it.key].join("/")}`,
+		path: `/${[...it.path, it.key].join("/")}`
 	};
 	const d = newDot();
 	const parentObj = parentRes.obj;
@@ -734,7 +922,9 @@ function applyArrInsert(base, head, it, newDot, bumpCounterAbove) {
 		return {
 			ok: false,
 			code: 409,
-			message: `base array missing at /${it.path.join("/")}`
+			reason: "MISSING_PARENT",
+			message: `base array missing at /${it.path.join("/")}`,
+			path: `/${it.path.join("/")}`
 		};
 	}
 	const headSeq = ensureSeqAtPath(head, it.path, newDot());
@@ -743,7 +933,9 @@ function applyArrInsert(base, head, it, newDot, bumpCounterAbove) {
 	if (idx < 0 || idx > baseLen) return {
 		ok: false,
 		code: 409,
-		message: `index out of bounds at /${it.path.join("/")}/${it.index}`
+		reason: "OUT_OF_BOUNDS",
+		message: `index out of bounds at /${it.path.join("/")}/${it.index}`,
+		path: `/${it.path.join("/")}/${it.index}`
 	};
 	const prev = idx === 0 ? HEAD : rgaIdAtIndex(baseSeq, idx - 1) ?? HEAD;
 	const d = nextInsertDotForPrev(headSeq, prev, newDot, bumpCounterAbove);
@@ -767,14 +959,18 @@ function applyArrDelete(base, head, it, newDot) {
 	if (!baseSeq) return {
 		ok: false,
 		code: 409,
-		message: `base array missing at /${it.path.join("/")}`
+		reason: "MISSING_PARENT",
+		message: `base array missing at /${it.path.join("/")}`,
+		path: `/${it.path.join("/")}`
 	};
 	const headSeq = ensureSeqAtPath(head, it.path, d);
 	const baseId = rgaIdAtIndex(baseSeq, it.index);
 	if (!baseId) return {
 		ok: false,
 		code: 409,
-		message: `no base element at index ${it.index}`
+		reason: "MISSING_TARGET",
+		message: `no base element at index ${it.index}`,
+		path: `/${it.path.join("/")}/${it.index}`
 	};
 	rgaDelete(headSeq, baseId);
 	return null;
@@ -785,20 +981,26 @@ function applyArrReplace(base, head, it, newDot) {
 	if (!baseSeq) return {
 		ok: false,
 		code: 409,
-		message: `base array missing at /${it.path.join("/")}`
+		reason: "MISSING_PARENT",
+		message: `base array missing at /${it.path.join("/")}`,
+		path: `/${it.path.join("/")}`
 	};
 	const headSeq = ensureSeqAtPath(head, it.path, d);
 	const baseId = rgaIdAtIndex(baseSeq, it.index);
 	if (!baseId) return {
 		ok: false,
 		code: 409,
-		message: `no base element at index ${it.index}`
+		reason: "MISSING_TARGET",
+		message: `no base element at index ${it.index}`,
+		path: `/${it.path.join("/")}/${it.index}`
 	};
 	const e = headSeq.elems.get(baseId);
 	if (!e || e.tombstone) return {
 		ok: false,
 		code: 409,
-		message: `element already deleted at index ${it.index}`
+		reason: "MISSING_TARGET",
+		message: `element already deleted at index ${it.index}`,
+		path: `/${it.path.join("/")}/${it.index}`
 	};
 	e.value = nodeFromJson(it.value, newDot);
 	return null;
@@ -842,34 +1044,39 @@ function applyIntentsToCrdt(base, head, intents, newDot, evalTestAgainst = "head
 	}
 	return { ok: true };
 }
-/**
-* Convenience wrapper: compile a JSON Patch and apply it to a CRDT document.
-* @param base - The base document for index resolution.
-* @param head - The target document to mutate.
-* @param patch - Array of RFC 6902 JSON Patch operations.
-* @param newDot - A function that generates a unique `Dot` per mutation.
-* @param evalTestAgainst - Whether `test` ops evaluate against `"head"` or `"base"`.
-* @param bumpCounterAbove - Optional hook that can fast-forward the underlying counter before inserts.
-* @returns `{ ok: true }` on success, or `{ ok: false, code: 409, message }` on conflict.
-*/
-function jsonPatchToCrdt(base, head, patch, newDot, evalTestAgainst = "head", bumpCounterAbove) {
-	return applyIntentsToCrdt(base, head, compileJsonPatchToIntent(materialize(base.root), patch), newDot, evalTestAgainst, bumpCounterAbove);
+function jsonPatchToCrdt(baseOrOptions, head, patch, newDot, evalTestAgainst = "head", bumpCounterAbove) {
+	if (isJsonPatchToCrdtOptions(baseOrOptions)) return jsonPatchToCrdtInternal(baseOrOptions);
+	if (!head || !patch || !newDot) return {
+		ok: false,
+		code: 409,
+		reason: "INVALID_PATCH",
+		message: "invalid jsonPatchToCrdt call signature"
+	};
+	return jsonPatchToCrdtInternal({
+		base: baseOrOptions,
+		head,
+		patch,
+		newDot,
+		evalTestAgainst,
+		bumpCounterAbove
+	});
 }
-/**
-* Safe wrapper around `jsonPatchToCrdt` that converts compile-time errors into `409` results.
-* This function never throws for malformed/invalid patch paths.
-*/
-function jsonPatchToCrdtSafe(base, head, patch, newDot, evalTestAgainst = "head", bumpCounterAbove) {
+function jsonPatchToCrdtSafe(baseOrOptions, head, patch, newDot, evalTestAgainst = "head", bumpCounterAbove) {
 	try {
-		return jsonPatchToCrdt(base, head, patch, newDot, evalTestAgainst, bumpCounterAbove);
-	} catch (error) {
-		return {
+		if (isJsonPatchToCrdtOptions(baseOrOptions)) return jsonPatchToCrdt(baseOrOptions);
+		if (!head || !patch || !newDot) return {
 			ok: false,
 			code: 409,
-			message: error instanceof Error ? error.message : "failed to compile patch"
+			reason: "INVALID_PATCH",
+			message: "invalid jsonPatchToCrdtSafe call signature"
 		};
+		return jsonPatchToCrdt(baseOrOptions, head, patch, newDot, evalTestAgainst, bumpCounterAbove);
+	} catch (error) {
+		return toApplyError$1(error);
 	}
 }
+/** Alias for codebases that prefer `try*` naming for non-throwing APIs. */
+const tryJsonPatchToCrdt = jsonPatchToCrdtSafe;
 /**
 * Generate a JSON Patch delta between two CRDT documents.
 * @param base - The base document snapshot.
@@ -891,19 +1098,130 @@ function crdtToFullReplace(doc) {
 		value: materialize(doc.root)
 	}];
 }
+function jsonPatchToCrdtInternal(options) {
+	const evalTestAgainst = options.evalTestAgainst ?? "head";
+	if ((options.semantics ?? "sequential") === "base") {
+		const baseJson = materialize(options.base.root);
+		let intents;
+		try {
+			intents = compileJsonPatchToIntent(baseJson, options.patch, { semantics: "base" });
+		} catch (error) {
+			return toApplyError$1(error);
+		}
+		return applyIntentsToCrdt(options.base, options.head, intents, options.newDot, evalTestAgainst, options.bumpCounterAbove);
+	}
+	let shadowBase = cloneDoc(evalTestAgainst === "base" ? options.base : options.head);
+	let shadowCtr = 0;
+	const shadowDot = () => ({
+		actor: "__shadow__",
+		ctr: ++shadowCtr
+	});
+	const shadowBump = (ctr) => {
+		if (shadowCtr < ctr) shadowCtr = ctr;
+	};
+	const applySequentialOp = (op, opIndex) => {
+		const baseJson = materialize(shadowBase.root);
+		let intents;
+		try {
+			intents = compileJsonPatchToIntent(baseJson, [op], { semantics: "sequential" });
+		} catch (error) {
+			return withOpIndex(toApplyError$1(error), opIndex);
+		}
+		const headStep = applyIntentsToCrdt(shadowBase, options.head, intents, options.newDot, evalTestAgainst, options.bumpCounterAbove);
+		if (!headStep.ok) return withOpIndex(headStep, opIndex);
+		if (evalTestAgainst === "base") {
+			const shadowStep = applyIntentsToCrdt(shadowBase, shadowBase, intents, shadowDot, "base", shadowBump);
+			if (!shadowStep.ok) return withOpIndex(shadowStep, opIndex);
+		} else shadowBase = cloneDoc(options.head);
+		return { ok: true };
+	};
+	for (let opIndex = 0; opIndex < options.patch.length; opIndex++) {
+		const op = options.patch[opIndex];
+		if (op.op === "move") {
+			const baseJson = materialize(shadowBase.root);
+			let fromValue;
+			try {
+				fromValue = structuredClone(getAtJson(baseJson, parseJsonPointer(op.from)));
+			} catch {
+				try {
+					compileJsonPatchToIntent(baseJson, [{
+						op: "remove",
+						path: op.from
+					}], { semantics: "sequential" });
+				} catch (error) {
+					return withOpIndex(toApplyError$1(error), opIndex);
+				}
+				return withOpIndex(toApplyError$1(/* @__PURE__ */ new Error(`failed to resolve move source at ${op.from}`)), opIndex);
+			}
+			if (op.from === op.path) continue;
+			const removeStep = applySequentialOp({
+				op: "remove",
+				path: op.from
+			}, opIndex);
+			if (!removeStep.ok) return removeStep;
+			const addStep = applySequentialOp({
+				op: "add",
+				path: op.path,
+				value: fromValue
+			}, opIndex);
+			if (!addStep.ok) return addStep;
+			continue;
+		}
+		const step = applySequentialOp(op, opIndex);
+		if (!step.ok) return step;
+	}
+	return { ok: true };
+}
+function withOpIndex(error, opIndex) {
+	if (error.opIndex !== void 0) return error;
+	return {
+		...error,
+		opIndex
+	};
+}
+function isJsonPatchToCrdtOptions(value) {
+	return typeof value === "object" && value !== null && "base" in value && "head" in value && "patch" in value && "newDot" in value;
+}
+function toApplyError$1(error) {
+	if (error instanceof PatchCompileError) return {
+		ok: false,
+		code: 409,
+		reason: error.reason,
+		message: error.message,
+		path: error.path,
+		opIndex: error.opIndex
+	};
+	return {
+		ok: false,
+		code: 409,
+		reason: "INVALID_PATCH",
+		message: error instanceof Error ? error.message : "failed to compile/apply patch"
+	};
+}
 function assertNever(_value, message) {
 	throw new Error(message);
 }
 
 //#endregion
 //#region src/state.ts
-/** Error thrown when a JSON Patch cannot be applied. Includes a numeric `.code` (409 for conflicts). */
+/** Error thrown when a JSON Patch cannot be applied. Includes structured conflict metadata. */
 var PatchError = class extends Error {
 	code;
-	constructor(message, code = 409) {
-		super(message);
+	reason;
+	path;
+	opIndex;
+	constructor(errorOrMessage, code = 409, reason = "INVALID_PATCH") {
+		super(typeof errorOrMessage === "string" ? errorOrMessage : errorOrMessage.message);
 		this.name = "PatchError";
-		this.code = code;
+		if (typeof errorOrMessage === "string") {
+			this.code = code;
+			this.reason = reason;
+			return;
+		}
+		this.code = errorOrMessage.code;
+		this.reason = errorOrMessage.reason;
+		this.path = errorOrMessage.path;
+		this.opIndex = errorOrMessage.opIndex;
 	}
 };
 /**
@@ -920,6 +1238,18 @@ function createState(initial, options) {
 	};
 }
 /**
+* Fork a replica from a shared origin state while assigning a new local actor ID.
+* The forked state has an independent document clone and clock.
+* By default this rejects actor reuse to prevent duplicate-dot collisions across peers.
+*/
+function forkState(origin, actor, options = {}) {
+	if (actor === origin.clock.actor && !options.allowActorReuse) throw new Error(`forkState actor must be unique; refusing to reuse origin actor '${actor}'`);
+	return {
+		doc: cloneDoc(origin.doc),
+		clock: createClock(actor, origin.clock.ctr)
+	};
+}
+/**
 * Materialize a CRDT document or state back to a plain JSON value.
 * @param target - A `Doc` or `CrdtState` to materialize.
 * @returns The JSON representation of the current document.
@@ -933,34 +1263,69 @@ function toJson(target) {
 * Throws `PatchError` on conflict (e.g. out-of-bounds index, failed test op).
 * @param state - The current CRDT state.
 * @param patch - Array of RFC 6902 JSON Patch operations.
-* @param options - Optional base document and test evaluation mode.
+* @param options - Optional base state snapshot and patch semantics.
 * @returns A new `CrdtState` with the patch applied.
 */
 function applyPatch(state, patch, options = {}) {
-	const nextState = {
-		doc: cloneDoc(state.doc),
-		clock: cloneClock(state.clock)
-	};
-	const result = applyPatchInternal(nextState, patch, options);
-	if (!result.ok) throw new PatchError(result.message, result.code);
-	return nextState;
+	const result = tryApplyPatch(state, patch, options);
+	if (!result.ok) throw new PatchError(result.error);
+	return result.state;
 }
 /**
 * Apply a JSON Patch to the state in place, mutating the existing state.
 * Throws `PatchError` on conflict.
 * @param state - The CRDT state to mutate.
 * @param patch - Array of RFC 6902 JSON Patch operations.
-* @param options - Optional base document and test evaluation mode.
+* @param options - Optional base state snapshot, patch semantics, and atomicity.
 */
 function applyPatchInPlace(state, patch, options = {}) {
-	if (options.atomic ?? true) {
-		const next = applyPatch(state, patch, options);
-		state.doc = next.doc;
-		state.clock = next.clock;
-		return;
+	const result = tryApplyPatchInPlace(state, patch, options);
+	if (!result.ok) throw new PatchError(result.error);
+}
+/** Non-throwing immutable patch application variant. */
+function tryApplyPatch(state, patch, options = {}) {
+	const nextState = {
+		doc: cloneDoc(state.doc),
+		clock: cloneClock(state.clock)
+	};
+	const result = applyPatchInternal(nextState, patch, options);
+	if (!result.ok) return {
+		ok: false,
+		error: result
+	};
+	return {
+		ok: true,
+		state: nextState
+	};
+}
+/** Non-throwing in-place patch application variant. */
+function tryApplyPatchInPlace(state, patch, options = {}) {
+	const { atomic = true, ...applyOptions } = options;
+	if (atomic) {
+		const next = tryApplyPatch(state, patch, applyOptions);
+		if (!next.ok) return next;
+		state.doc = next.state.doc;
+		state.clock = next.state.clock;
+		return { ok: true };
 	}
-	const result = applyPatchInternal(state, patch, options);
-	if (!result.ok) throw new PatchError(result.message, result.code);
+	const result = applyPatchInternal(state, patch, applyOptions);
+	if (!result.ok) return {
+		ok: false,
+		error: result
+	};
+	return { ok: true };
+}
+/**
+* Validate whether a patch is applicable against a JSON base value under the chosen options.
+* Does not mutate caller-provided values.
+*/
+function validateJsonPatch(base, patch, options = {}) {
+	const result = tryApplyPatch(createState(base, { actor: "__validate__" }), patch, options);
+	if (!result.ok) return {
+		ok: false,
+		error: result.error
+	};
+	return { ok: true };
 }
 /**
 * Apply a JSON Patch as a specific actor while maintaining an external version vector.
@@ -971,7 +1336,7 @@ function applyPatchAsActor(doc, vv, actor, patch, options = {}) {
 	const state = applyPatch({
 		doc,
 		clock: createClock(actor, Math.max(vv[actor] ?? 0, observedCtr))
-	}, patch, options);
+	}, patch, toApplyPatchOptionsForActor(options));
 	return {
 		state,
 		vv: {
@@ -980,34 +1345,46 @@ function applyPatchAsActor(doc, vv, actor, patch, options = {}) {
 		}
 	};
 }
+function toApplyPatchOptionsForActor(options) {
+	return {
+		semantics: options.semantics,
+		testAgainst: options.testAgainst,
+		base: options.base ? {
+			doc: options.base,
+			clock: createClock("__base__", 0)
+		} : void 0
+	};
+}
 function applyPatchInternal(state, patch, options) {
-	if ((options.semantics ?? "base") === "sequential") {
+	if ((options.semantics ?? "sequential") === "sequential") {
 		const explicitBaseState = options.base ? {
-			doc: cloneDoc(options.base),
+			doc: cloneDoc(options.base.doc),
 			clock: createClock("__base__", 0)
 		} : null;
-		for (const op of patch) {
-			const step = applyPatchOpSequential(state, op, options, explicitBaseState ? explicitBaseState.doc : cloneDoc(state.doc));
+		for (const [opIndex, op] of patch.entries()) {
+			const step = applyPatchOpSequential(state, op, options, explicitBaseState ? explicitBaseState.doc : cloneDoc(state.doc), opIndex);
 			if (!step.ok) return step;
-			if (explicitBaseState) {
+			if (explicitBaseState && op.op !== "test") {
 				const baseStep = applyPatchInternal(explicitBaseState, [op], {
 					semantics: "sequential",
-					testAgainst: options.testAgainst
+					testAgainst: "base"
 				});
 				if (!baseStep.ok) return baseStep;
 			}
 		}
 		return { ok: true };
 	}
-	const baseDoc = options.base ? options.base : cloneDoc(state.doc);
-	const compiled = compileIntents(materialize(baseDoc.root), patch);
+	const baseDoc = options.base ? options.base.doc : cloneDoc(state.doc);
+	const compiled = compileIntents(materialize(baseDoc.root), patch, "base");
 	if (!compiled.ok) return compiled;
 	return applyIntentsToCrdt(baseDoc, state.doc, compiled.intents, () => state.clock.next(), options.testAgainst ?? "head", (ctr) => bumpClockCounter(state, ctr));
 }
-function applyPatchOpSequential(state, op, options, baseDoc) {
+function applyPatchOpSequential(state, op, options, baseDoc, opIndex) {
 	const baseJson = materialize(baseDoc.root);
 	if (op.op === "move") {
-		const fromValue = getAtJson(baseJson, parseJsonPointer(op.from));
+		const fromResolved = resolveValueAtPointer(baseJson, op.from, opIndex);
+		if (!fromResolved.ok) return fromResolved;
+		const fromValue = fromResolved.value;
 		const removeRes = applySinglePatchOp(state, baseDoc, {
 			op: "remove",
 			path: op.from
@@ -1020,7 +1397,9 @@ function applyPatchOpSequential(state, op, options, baseDoc) {
 		}, options);
 	}
 	if (op.op === "copy") {
-		const fromValue = getAtJson(baseJson, parseJsonPointer(op.from));
+		const fromResolved = resolveValueAtPointer(baseJson, op.from, opIndex);
+		if (!fromResolved.ok) return fromResolved;
+		const fromValue = fromResolved.value;
 		return applySinglePatchOp(state, baseDoc, {
 			op: "add",
 			path: op.path,
@@ -1029,26 +1408,38 @@ function applyPatchOpSequential(state, op, options, baseDoc) {
 	}
 	return applySinglePatchOp(state, baseDoc, op, options);
 }
+function resolveValueAtPointer(baseJson, pointer, opIndex) {
+	let path;
+	try {
+		path = parseJsonPointer(pointer);
+	} catch (error) {
+		return toPointerParseApplyError(error, pointer, opIndex);
+	}
+	try {
+		return {
+			ok: true,
+			value: getAtJson(baseJson, path)
+		};
+	} catch (error) {
+		return toPointerLookupApplyError(error, pointer, opIndex);
+	}
+}
 function applySinglePatchOp(state, baseDoc, op, options) {
-	const compiled = compileIntents(materialize(baseDoc.root), [op]);
+	const compiled = compileIntents(materialize(baseDoc.root), [op], "sequential");
 	if (!compiled.ok) return compiled;
 	return applyIntentsToCrdt(baseDoc, state.doc, compiled.intents, () => state.clock.next(), options.testAgainst ?? "head", (ctr) => bumpClockCounter(state, ctr));
 }
 function bumpClockCounter(state, ctr) {
 	if (state.clock.ctr < ctr) state.clock.ctr = ctr;
 }
-function compileIntents(baseJson, patch) {
+function compileIntents(baseJson, patch, semantics = "sequential") {
 	try {
 		return {
 			ok: true,
-			intents: compileJsonPatchToIntent(baseJson, patch)
+			intents: compileJsonPatchToIntent(baseJson, patch, { semantics })
 		};
 	} catch (error) {
-		return {
-			ok: false,
-			code: 409,
-			message: error instanceof Error ? error.message : "failed to compile patch"
-		};
+		return toApplyError(error);
 	}
 }
 function maxCtrInNodeForActor$1(node, actor) {
@@ -1075,6 +1466,43 @@ function maxCtrInNodeForActor$1(node, actor) {
 		}
 	}
 }
+function toApplyError(error) {
+	if (error instanceof PatchCompileError) return {
+		ok: false,
+		code: 409,
+		reason: error.reason,
+		message: error.message,
+		path: error.path,
+		opIndex: error.opIndex
+	};
+	return {
+		ok: false,
+		code: 409,
+		reason: "INVALID_PATCH",
+		message: error instanceof Error ? error.message : "failed to compile patch"
+	};
+}
+function toPointerParseApplyError(error, pointer, opIndex) {
+	return {
+		ok: false,
+		code: 409,
+		reason: "INVALID_POINTER",
+		message: error instanceof Error ? error.message : "invalid pointer",
+		path: pointer,
+		opIndex
+	};
+}
+function toPointerLookupApplyError(error, pointer, opIndex) {
+	const mapped = mapLookupErrorToPatchReason(error);
+	return {
+		ok: false,
+		code: 409,
+		reason: mapped.reason,
+		message: mapped.message,
+		path: pointer,
+		opIndex
+	};
+}
 
 //#endregion
 //#region src/serialize.ts
@@ -1197,6 +1625,19 @@ function deserializeNode(node) {
 
 //#endregion
 //#region src/merge.ts
+/** Error thrown by throwing merge helpers (`mergeDoc` / `mergeState`). */
+var MergeError = class extends Error {
+	code;
+	reason;
+	path;
+	constructor(error) {
+		super(error.message);
+		this.name = "MergeError";
+		this.code = error.code;
+		this.reason = "LINEAGE_MISMATCH";
+		this.path = error.path;
+	}
+};
 /**
 * Merge two CRDT documents from different peers into one.
 * By default this requires shared array lineage for non-empty sequences.
@@ -1211,9 +1652,27 @@ function deserializeNode(node) {
 * - **Kind mismatch**: the node with the higher "representative dot" wins and replaces the other entirely.
 */
 function mergeDoc(a, b, options = {}) {
+	const result = tryMergeDoc(a, b, options);
+	if (!result.ok) throw new MergeError(result.error);
+	return result.doc;
+}
+/** Non-throwing `mergeDoc` variant with structured conflict details. */
+function tryMergeDoc(a, b, options = {}) {
 	const mismatchPath = options.requireSharedOrigin ?? true ? findSeqLineageMismatch(a.root, b.root, []) : null;
-	if (mismatchPath) throw new Error(`merge requires shared array origin at ${mismatchPath}`);
-	return { root: mergeNode(a.root, b.root) };
+	if (mismatchPath) return {
+		ok: false,
+		error: {
+			ok: false,
+			code: 409,
+			reason: "LINEAGE_MISMATCH",
+			message: `merge requires shared array origin at ${mismatchPath}`,
+			path: mismatchPath
+		}
+	};
+	return {
+		ok: true,
+		doc: { root: mergeNode(a.root, b.root) }
+	};
 }
 /**
 * Merge two CRDT states.
@@ -1227,11 +1686,22 @@ function mergeDoc(a, b, options = {}) {
 * that actor across both input clocks and the merged document dots.
 */
 function mergeState(a, b, options = {}) {
-	const doc = mergeDoc(a.doc, b.doc, { requireSharedOrigin: options.requireSharedOrigin });
+	const result = tryMergeState(a, b, options);
+	if (!result.ok) throw new MergeError(result.error);
+	return result.state;
+}
+/** Non-throwing `mergeState` variant with structured conflict details. */
+function tryMergeState(a, b, options = {}) {
+	const mergedDoc = tryMergeDoc(a.doc, b.doc, { requireSharedOrigin: options.requireSharedOrigin });
+	if (!mergedDoc.ok) return mergedDoc;
+	const doc = mergedDoc.doc;
 	const actor = options.actor ?? a.clock.actor;
 	return {
-		doc,
-		clock: createClock(actor, maxObservedCtrForActor(doc, actor, a, b))
+		ok: true,
+		state: {
+			doc,
+			clock: createClock(actor, maxObservedCtrForActor(doc, actor, a, b))
+		}
 	};
 }
 function findSeqLineageMismatch(a, b, path) {
@@ -1432,4 +1902,4 @@ function cloneNodeShallow(node) {
 }
 
 //#endregion
-export { newReg as A, rgaPrevForInsertAtIndex as B, getAtJson as C, ROOT_KEY as D, stringifyJsonPointer as E, HEAD as F, cloneClock as G, dotToElemId as H, rgaDelete as I, observeDot as J, createClock as K, rgaIdAtIndex as L, objRemove as M, objSet as N, lwwSet as O, materialize as P, rgaInsertAfter as R, diffJsonPatch as S, parseJsonPointer as T, vvHasDot as U, compareDot as V, vvMerge as W, docFromJson as _, serializeDoc as a, jsonPatchToCrdtSafe as b, applyPatch as c, createState as d, toJson as f, crdtToJsonPatch as g, crdtToFullReplace as h, deserializeState as i, newSeq as j, newObj as k, applyPatchAsActor as l, cloneDoc as m, mergeState as n, serializeState as o, applyIntentsToCrdt as p, nextDotForActor as q, deserializeDoc as r, PatchError as s, mergeDoc as t, applyPatchInPlace as u, docFromJsonWithDot as v, jsonEquals as w, compileJsonPatchToIntent as x, jsonPatchToCrdt as y, rgaLinearizeIds as z };
+export { vvMerge as $, compileJsonPatchToIntent as A, newSeq as B, crdtToJsonPatch as C, jsonPatchToCrdtSafe as D, jsonPatchToCrdt as E, stringifyJsonPointer as F, rgaDelete as G, objSet as H, ROOT_KEY as I, rgaLinearizeIds as J, rgaIdAtIndex as K, lwwSet as L, getAtJson as M, jsonEquals as N, tryJsonPatchToCrdt as O, parseJsonPointer as P, vvHasDot as Q, newObj as R, crdtToFullReplace as S, docFromJsonWithDot as T, materialize as U, objRemove as V, HEAD as W, compareDot as X, rgaPrevForInsertAtIndex as Y, dotToElemId as Z, tryApplyPatch as _, tryMergeState as a, applyIntentsToCrdt as b, serializeDoc as c, applyPatch as d, cloneClock as et, applyPatchAsActor as f, toJson as g, forkState as h, tryMergeDoc as i, diffJsonPatch as j, PatchCompileError as k, serializeState as l, createState as m, mergeDoc as n, nextDotForActor as nt, deserializeDoc as o, applyPatchInPlace as p, rgaInsertAfter as q, mergeState as r, observeDot as rt, deserializeState as s, MergeError as t, createClock as tt, PatchError as u, tryApplyPatchInPlace as v, docFromJson as w, cloneDoc as x, validateJsonPatch as y, newReg as z };