json-patch-to-crdt 0.0.0 → 0.1.1

package/dist/{merge-B1BFMhJJ.js → merge-BAfuC6bf.js}

@@ -195,6 +195,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 `""`).
@@ -203,13 +216,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.
@@ -217,8 +254,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") {
@@ -235,94 +272,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;
 }
@@ -464,6 +422,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);
 }
@@ -474,6 +433,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
@@ -674,13 +850,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;
 }
@@ -693,12 +873,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;
@@ -710,12 +894,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;
@@ -735,7 +923,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());
@@ -744,7 +934,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);
@@ -768,14 +960,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;
@@ -786,20 +982,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;
@@ -843,34 +1045,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.
@@ -892,19 +1099,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;
 	}
 };
 /**
@@ -921,6 +1239,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.
@@ -934,34 +1264,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.
@@ -972,7 +1337,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: {
@@ -981,34 +1346,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
@@ -1021,7 +1398,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,
@@ -1030,26 +1409,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) {
@@ -1076,6 +1467,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
@@ -1198,6 +1626,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.
@@ -1212,9 +1653,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.
@@ -1228,11 +1687,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) {
@@ -1439,6 +1909,18 @@ Object.defineProperty(exports, 'HEAD', {
     return HEAD;
   }
 });
+Object.defineProperty(exports, 'MergeError', {
+  enumerable: true,
+  get: function () {
+    return MergeError;
+  }
+});
+Object.defineProperty(exports, 'PatchCompileError', {
+  enumerable: true,
+  get: function () {
+    return PatchCompileError;
+  }
+});
 Object.defineProperty(exports, 'PatchError', {
   enumerable: true,
   get: function () {
@@ -1559,6 +2041,12 @@ Object.defineProperty(exports, 'dotToElemId', {
     return dotToElemId;
   }
 });
+Object.defineProperty(exports, 'forkState', {
+  enumerable: true,
+  get: function () {
+    return forkState;
+  }
+});
 Object.defineProperty(exports, 'getAtJson', {
   enumerable: true,
   get: function () {
@@ -1709,6 +2197,42 @@ Object.defineProperty(exports, 'toJson', {
     return toJson;
   }
 });
+Object.defineProperty(exports, 'tryApplyPatch', {
+  enumerable: true,
+  get: function () {
+    return tryApplyPatch;
+  }
+});
+Object.defineProperty(exports, 'tryApplyPatchInPlace', {
+  enumerable: true,
+  get: function () {
+    return tryApplyPatchInPlace;
+  }
+});
+Object.defineProperty(exports, 'tryJsonPatchToCrdt', {
+  enumerable: true,
+  get: function () {
+    return tryJsonPatchToCrdt;
+  }
+});
+Object.defineProperty(exports, 'tryMergeDoc', {
+  enumerable: true,
+  get: function () {
+    return tryMergeDoc;
+  }
+});
+Object.defineProperty(exports, 'tryMergeState', {
+  enumerable: true,
+  get: function () {
+    return tryMergeState;
+  }
+});
+Object.defineProperty(exports, 'validateJsonPatch', {
+  enumerable: true,
+  get: function () {
+    return validateJsonPatch;
+  }
+});
 Object.defineProperty(exports, 'vvHasDot', {
   enumerable: true,
   get: function () {