json-patch-to-crdt 0.0.0 → 0.1.0

package/dist/{merge-DikOFBWc.mjs → merge-BqROEw61.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 `""`).
@@ -234,94 +247,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));
+		if (semantics === "sequential") workingBase = applyPatchOpToJson(workingBase, op, opIndex);
 	}
 	return intents;
 }
@@ -473,6 +407,185 @@ function pathValueAt(base, path) {
 function assertNever$1(_value, message) {
 	throw new Error(message);
 }
+function compileSingleOp(baseJson, op, opIndex) {
+	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);
+		const out = compileSingleOp(baseJson, {
+			op: "add",
+			path: op.path,
+			value: val
+		}, opIndex);
+		if (op.op === "move") out.push(...compileSingleOp(baseJson, {
+			op: "remove",
+			path: op.from
+		}, opIndex));
+		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 (!/^[0-9]+$/.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 message = error instanceof Error ? error.message : "invalid path";
+	if (message.includes("Expected array index")) return compileError("INVALID_POINTER", message, path, opIndex);
+	if (message.includes("Index out of bounds")) return compileError("OUT_OF_BOUNDS", message, path, opIndex);
+	if (message.includes("Missing key")) return compileError("MISSING_PARENT", message, path, opIndex);
+	if (message.includes("Cannot traverse into non-container")) return compileError("INVALID_TARGET", message, path, opIndex);
+	return compileError("INVALID_PATCH", message, path, opIndex);
+}
+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;
+}
 
 //#endregion
 //#region src/doc.ts
@@ -673,13 +786,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 +809,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 +830,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 +859,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 +870,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 +896,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 +918,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 +981,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 +1035,95 @@ 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;
+	};
+	for (let opIndex = 0; opIndex < options.patch.length; opIndex++) {
+		const op = options.patch[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 };
+}
+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 +1140,16 @@ 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.
+*/
+function forkState(origin, 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 +1163,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 +1236,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,27 +1245,37 @@ 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));
 			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));
 }
@@ -1030,25 +1305,21 @@ function applyPatchOpSequential(state, op, options, baseDoc) {
 	return applySinglePatchOp(state, baseDoc, op, options);
 }
 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 +1346,22 @@ 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"
+	};
+}
 
 //#endregion
 //#region src/serialize.ts
@@ -1197,6 +1484,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 +1511,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 +1545,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 +1761,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 };