@harbour-enterprises/superdoc 1.17.0-next.12 → 1.17.0-next.13

package/dist/chunks/{src-D6cAnOaK.cjs → src-ByCDwKn7.cjs}

@@ -1,5 +1,5 @@
 const require_rolldown_runtime = require("./rolldown-runtime-Dp2H1eGw.cjs");
-const require_SuperConverter = require("./SuperConverter-BSNvGA-_.cjs");
+const require_SuperConverter = require("./SuperConverter-BgHHB-Z2.cjs");
 const require_jszip = require("./jszip-DCT9QYaK.cjs");
 const require_uuid = require("./uuid-CHj_rjgt.cjs");
 const require_constants = require("./constants-CpniKo9Z.cjs");
@@ -261,7 +261,7 @@ var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 const COMMUNITY_LICENSE_KEY = "community-and-eval-agplv3";
 function getSuperdocVersion() {
 	try {
-		return "1.17.0-next.12";
+		return "1.17.0-next.13";
 	} catch {
 		return "unknown";
 	}
@@ -20734,7 +20734,7 @@ const canUseDOM = () => {
 		return false;
 	}
 };
-var summaryVersion = "1.17.0-next.12";
+var summaryVersion = "1.17.0-next.13";
 var nodeKeys = [
 	"group",
 	"content",
@@ -21211,6 +21211,9 @@ var T_PLAN_ENGINE = [
 	"TARGET_MOVED",
 	"PLAN_CONFLICT_OVERLAP",
 	"INVALID_STEP_COMBINATION",
+	"REVISION_CHANGED_SINCE_COMPILE",
+	"INVALID_INSERTION_CONTEXT",
+	"DOCUMENT_IDENTITY_CONFLICT",
 	"CAPABILITY_UNAVAILABLE"
 ];
 var T_QUERY_MATCH = [
@@ -24308,9 +24311,11 @@ function trackRevisions(editor) {
 function checkRevision(editor, expectedRevision) {
 	if (expectedRevision === void 0) return;
 	const current = getRevision(editor);
-	if (expectedRevision !== current) throw new PlanError("REVISION_MISMATCH", `REVISION_MISMATCH — expected revision "${expectedRevision}" but document is at "${current}"`, void 0, {
+	if (expectedRevision !== current) throw new PlanError("REVISION_MISMATCH", `REVISION_MISMATCH — expected revision "${expectedRevision}" but document is at "${current}". Re-run query.match to obtain a fresh ref.`, void 0, {
 		expectedRevision,
-		currentRevision: current
+		currentRevision: current,
+		refStability: "ephemeral",
+		remediation: "Re-run query.match() to obtain a fresh ref valid for the current revision."
 	});
 }
 function resolveSegmentPosition(targetOffset, segmentStart, segmentLength, docFrom, docTo) {
@@ -24560,7 +24565,9 @@ function captureRunsInRange(editor, blockPos, from$1, to) {
 			return;
 		}
 		if (node.isLeaf) {
+			const start$1 = offset$1;
 			offset$1 += 1;
+			maybePushRun(start$1, offset$1, []);
 			return;
 		}
 		let isFirstChild = true;
@@ -24960,12 +24967,62 @@ function executeBlockSelector(index, query, diagnostics) {
 function isAssertStep(step) {
 	return step.op === "assert";
 }
+function isCreateOp(op) {
+	return op === "create.heading" || op === "create.paragraph";
+}
+var VALID_CREATE_POSITIONS = ["before", "after"];
 function isSelectWhere(where) {
 	return where.by === "select";
 }
 function isRefWhere(where) {
 	return where.by === "ref";
 }
+function validateCreateStepPosition(step) {
+	const args$1 = step.args;
+	if (args$1.position === void 0 || args$1.position === null) {
+		args$1.position = "after";
+		return;
+	}
+	if (!VALID_CREATE_POSITIONS.includes(args$1.position)) throw planError("INVALID_INPUT", `create step requires args.position to be 'before' or 'after'`, step.id, {
+		receivedPosition: args$1.position,
+		allowedValues: [...VALID_CREATE_POSITIONS],
+		default: "after"
+	});
+}
+function resolveCreateAnchorFromTargets(targets, position, stepId) {
+	const target = targets[0];
+	if (!target) throw planError("INVALID_INPUT", "create step has no resolved targets", stepId);
+	if (target.kind === "range") return target.blockId;
+	const segments = target.segments;
+	if (!segments.length) throw planError("INVALID_INPUT", "span target has no segments", stepId);
+	return position === "before" ? segments[0].blockId : segments[segments.length - 1].blockId;
+}
+function validateInsertionContext(editor, index, step, stepIndex, anchorBlockId, position) {
+	const candidate = index.candidates.find((c$3) => c$3.nodeId === anchorBlockId);
+	if (!candidate) return;
+	const paragraphType = editor.state.schema?.nodes?.paragraph;
+	if (!paragraphType) return;
+	const resolvedPos = editor.state.doc.resolve(candidate.pos);
+	const parent = resolvedPos.parent;
+	const anchorIndex = resolvedPos.index();
+	const insertionIndex = position === "before" ? anchorIndex : anchorIndex + 1;
+	if (!(typeof parent.canReplaceWith === "function" ? parent.canReplaceWith(insertionIndex, insertionIndex, paragraphType) : parent.type.contentMatch.matchType(paragraphType))) {
+		const allowedChildTypes = [];
+		const match$1 = parent.type.contentMatch;
+		for (const nodeType of Object.values(editor.state.schema.nodes)) if (match$1.matchType(nodeType)) allowedChildTypes.push(nodeType.name);
+		throw planError("INVALID_INSERTION_CONTEXT", `Cannot create ${step.op} inside ${parent.type.name}`, step.id, {
+			stepIndex,
+			stepId: step.id,
+			operation: step.op,
+			anchorBlockId,
+			parentType: parent.type.name,
+			allowedChildTypes,
+			insertionIndex,
+			requestedChildType: "paragraph",
+			requestedSemanticType: step.op === "create.heading" ? "heading" : "paragraph"
+		});
+	}
+}
 function isV3Ref(payload) {
 	return typeof payload === "object" && payload !== null && "v" in payload && payload.v === 3;
 }
@@ -25178,9 +25235,13 @@ function decodeTextRefPayload(encoded, stepId) {
 }
 function resolveV3TextRef(editor, index, step, refData) {
 	const currentRevision = getRevision(editor);
-	if (refData.rev !== currentRevision) throw planError("REVISION_MISMATCH", `text ref was created at revision "${refData.rev}" but document is at "${currentRevision}"`, step.id, {
+	if (refData.rev !== currentRevision) throw planError("REVISION_MISMATCH", `Text ref is ephemeral and revision-scoped. Re-run query.match to obtain a fresh handle.ref for revision ${currentRevision}.`, step.id, {
 		refRevision: refData.rev,
-		currentRevision
+		currentRevision,
+		refStability: "ephemeral",
+		refScope: refData.scope,
+		blockId: refData.segments?.[0]?.blockId,
+		remediation: `Re-run query.match() to obtain a fresh ref valid for the current revision.`
 	});
 	if (!refData.segments?.length) return [];
 	const segments = refData.segments.map((s) => ({
@@ -25279,7 +25340,11 @@ function resolveStepTargets(editor, index, step) {
 		return t.blockId !== prev.blockId || t.from !== prev.from || t.to !== prev.to;
 	});
 	if (refWhere) {
-		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", `ref "${refWhere.ref}" did not resolve to any targets`, step.id);
+		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", `ref "${refWhere.ref}" did not resolve to any targets`, step.id, {
+			selectorType: "ref",
+			selectorPattern: refWhere.ref,
+			candidateCount: 0
+		});
 		if (targets.length > 1) throw planError("AMBIGUOUS_MATCH", `ref "${refWhere.ref}" resolved to ${targets.length} targets`, step.id, { matchCount: targets.length });
 		return targets;
 	}
@@ -25288,57 +25353,157 @@ function resolveStepTargets(editor, index, step) {
 	if (selectWhere.require === "first" && targets.length > 1) targets = [targets[0]];
 	return targets;
 }
+function buildMatchNotFoundDetails(step) {
+	const where = step.where;
+	const select = "select" in where ? where.select : void 0;
+	const within$1 = "within" in where ? where.within : void 0;
+	return {
+		selectorType: select?.type ?? "unknown",
+		selectorPattern: select?.pattern ?? "",
+		selectorMode: select?.mode ?? "contains",
+		searchScope: within$1?.blockId ?? "document",
+		candidateCount: 0
+	};
+}
 function applyCardinalityCheck(step, targets) {
 	const where = step.where;
 	if (!("require" in where) || where.require === void 0) return;
 	const require$1 = where.require;
 	if (require$1 === "first") {
-		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id);
+		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id, buildMatchNotFoundDetails(step));
 	} else if (require$1 === "exactlyOne") {
-		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id);
+		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id, buildMatchNotFoundDetails(step));
 		if (targets.length > 1) throw planError("AMBIGUOUS_MATCH", `selector matched ${targets.length} ranges, expected exactly one`, step.id, { matchCount: targets.length });
 	} else if (require$1 === "all") {
-		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id);
-	}
-}
-function detectOverlaps(steps) {
-	const rangesByBlock = /* @__PURE__ */ new Map();
-	for (const compiled of steps) for (const target of compiled.targets) if (target.kind === "range") addRange(rangesByBlock, target.blockId, target.stepId, target.from, target.to);
-	else for (const seg of target.segments) addRange(rangesByBlock, seg.blockId, target.stepId, seg.from, seg.to);
-	for (const [blockId, ranges] of rangesByBlock) {
-		ranges.sort((a, b$1) => a.from - b$1.from);
-		for (let i$1 = 1; i$1 < ranges.length; i$1++) {
-			const prev = ranges[i$1 - 1];
-			const curr = ranges[i$1];
-			if (prev.stepId !== curr.stepId && prev.to > curr.from) throw planError("PLAN_CONFLICT_OVERLAP", `steps "${prev.stepId}" and "${curr.stepId}" target overlapping ranges in block "${blockId}"`, curr.stepId, {
+		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id, buildMatchNotFoundDetails(step));
+	}
+}
+const STEP_INTERACTION_MATRIX = new Map([
+	["text.rewrite::format.apply::same_target", "allow"],
+	["text.rewrite::text.rewrite::same_target", "reject"],
+	["text.rewrite::text.delete::overlapping", "reject"],
+	["text.rewrite::create.*::same_block", "allow"],
+	["text.rewrite::text.insert::same_target", "reject"],
+	["format.apply::format.apply::same_target", "allow"],
+	["format.apply::text.rewrite::same_target", "reject"],
+	["format.apply::text.delete::overlapping", "reject"],
+	["format.apply::create.*::same_block", "allow"],
+	["format.apply::text.insert::same_target", "allow"],
+	["text.delete::text.rewrite::overlapping", "reject"],
+	["text.delete::text.delete::overlapping", "reject"],
+	["text.delete::format.apply::overlapping", "reject"],
+	["text.delete::create.*::same_block", "allow"],
+	["text.delete::text.insert::overlapping", "reject"],
+	["create.*::text.rewrite::same_block", "allow"],
+	["create.*::format.apply::same_block", "allow"],
+	["create.*::text.delete::same_block", "allow"],
+	["create.*::create.*::same_block", "allow"],
+	["create.*::text.insert::same_block", "allow"],
+	["text.insert::format.apply::same_target", "allow"],
+	["text.insert::text.rewrite::same_target", "reject"],
+	["text.insert::text.delete::overlapping", "reject"],
+	["text.insert::create.*::same_block", "allow"],
+	["text.insert::text.insert::same_target", "reject"]
+]);
+const MATRIX_EXEMPT_OPS = new Set(["assert"]);
+function normalizeOpForMatrix(op) {
+	return op.startsWith("create.") ? "create.*" : op;
+}
+function classifyOverlap(stepA, stepB) {
+	const rangesA = extractBlockRanges(stepA);
+	const rangesB = extractBlockRanges(stepB);
+	const opA = normalizeOpForMatrix(stepA.step.op);
+	const opB = normalizeOpForMatrix(stepB.step.op);
+	const isCreateA = opA === "create.*";
+	const isCreateB = opB === "create.*";
+	for (const [blockId, aEntries] of rangesA) {
+		const bEntries = rangesB.get(blockId);
+		if (!bEntries) continue;
+		for (const a of aEntries) for (const b$1 of bEntries) {
+			if (isCreateA || isCreateB) return {
+				overlapClass: "same_block",
 				blockId,
-				rangeA: {
-					from: prev.from,
-					to: prev.to
-				},
-				rangeB: {
-					from: curr.from,
-					to: curr.to
-				}
-			});
+				rangeA: a,
+				rangeB: b$1
+			};
+			if (a.to <= b$1.from || b$1.to <= a.from) continue;
+			if (a.from === b$1.from && a.to === b$1.to) return {
+				overlapClass: "same_target",
+				blockId,
+				rangeA: a,
+				rangeB: b$1
+			};
+			return {
+				overlapClass: "overlapping",
+				blockId,
+				rangeA: a,
+				rangeB: b$1
+			};
 		}
 	}
 }
-function addRange(map$2, blockId, stepId, from$1, to) {
-	let blockRanges = map$2.get(blockId);
-	if (!blockRanges) {
-		blockRanges = [];
-		map$2.set(blockId, blockRanges);
+function extractBlockRanges(compiled) {
+	const result = /* @__PURE__ */ new Map();
+	for (const target of compiled.targets) if (target.kind === "range") pushBlockRange(result, target.blockId, target.from, target.to);
+	else for (const seg of target.segments) pushBlockRange(result, seg.blockId, seg.from, seg.to);
+	return result;
+}
+function pushBlockRange(map$2, blockId, from$1, to) {
+	let entries = map$2.get(blockId);
+	if (!entries) {
+		entries = [];
+		map$2.set(blockId, entries);
 	}
-	blockRanges.push({
-		stepId,
+	entries.push({
 		from: from$1,
 		to
 	});
 }
+function validateStepInteractions(steps) {
+	for (let i$1 = 0; i$1 < steps.length; i$1++) for (let j = i$1 + 1; j < steps.length; j++) {
+		const stepA = steps[i$1];
+		const stepB = steps[j];
+		if (MATRIX_EXEMPT_OPS.has(stepA.step.op) || MATRIX_EXEMPT_OPS.has(stepB.step.op)) continue;
+		const overlap = classifyOverlap(stepA, stepB);
+		if (!overlap) continue;
+		const matrixKey = `${normalizeOpForMatrix(stepA.step.op)}::${normalizeOpForMatrix(stepB.step.op)}::${overlap.overlapClass}`;
+		const verdict = STEP_INTERACTION_MATRIX.get(matrixKey) ?? "reject";
+		if (verdict === "reject") throw planError("PLAN_CONFLICT_OVERLAP", `steps "${stepA.step.id}" and "${stepB.step.id}" target overlapping ranges in block "${overlap.blockId}"`, stepB.step.id, {
+			blockId: overlap.blockId,
+			stepIdA: stepA.step.id,
+			stepIdB: stepB.step.id,
+			opKeyA: stepA.step.op,
+			opKeyB: stepB.step.op,
+			rangeA: overlap.rangeA,
+			rangeB: overlap.rangeB,
+			overlapRegion: {
+				from: Math.max(overlap.rangeA.from, overlap.rangeB.from),
+				to: Math.min(overlap.rangeA.to, overlap.rangeB.to)
+			},
+			matrixVerdict: verdict,
+			matrixKey
+		});
+	}
+}
+function assertNoDuplicateBlockIds(index) {
+	const seen = /* @__PURE__ */ new Map();
+	const duplicates = [];
+	for (const candidate of index.candidates) {
+		const count = seen.get(candidate.nodeId) ?? 0;
+		seen.set(candidate.nodeId, count + 1);
+		if (count === 1) duplicates.push(candidate.nodeId);
+	}
+	if (duplicates.length > 0) throw planError("DOCUMENT_IDENTITY_CONFLICT", "Document contains blocks with duplicate identities. This must be resolved before mutations can be applied.", void 0, {
+		duplicateBlockIds: duplicates,
+		blockCount: duplicates.length,
+		remediation: "Re-import the document or call document.repair() to assign unique identities."
+	});
+}
 function compilePlan(editor, steps) {
 	if (steps.length > 200) throw planError("INVALID_INPUT", `plan contains ${steps.length} steps, maximum is 200`);
+	const compiledRevision = getRevision(editor);
 	const index = getBlockIndex(editor);
+	assertNoDuplicateBlockIds(index);
 	const mutationSteps = [];
 	const assertSteps = [];
 	const seenIds = /* @__PURE__ */ new Set();
@@ -25348,26 +25513,41 @@ function compilePlan(editor, steps) {
 		seenIds.add(step.id);
 	}
 	let totalTargets = 0;
+	let stepIndex = 0;
 	for (const step of steps) {
 		if (isAssertStep(step)) {
 			assertSteps.push(step);
+			stepIndex++;
 			continue;
 		}
 		if (!hasStepExecutor(step.op)) throw planError("INVALID_INPUT", `unknown step op "${step.op}"`, step.id);
+		if (isCreateOp(step.op)) validateCreateStepPosition(step);
 		const targets = resolveStepTargets(editor, index, step);
+		if (isCreateOp(step.op) && targets.length > 0) {
+			const position = step.args.position ?? "after";
+			const anchorBlockId = resolveCreateAnchorFromTargets(targets, position, step.id);
+			validateInsertionContext(editor, index, step, stepIndex, anchorBlockId, position);
+		}
 		totalTargets += targets.length;
 		mutationSteps.push({
 			step,
 			targets
 		});
+		stepIndex++;
 	}
 	if (totalTargets > 500) throw planError("INVALID_INPUT", `plan resolved ${totalTargets} total targets, maximum is 500`);
-	detectOverlaps(mutationSteps);
+	validateStepInteractions(mutationSteps);
 	return {
 		mutationSteps,
-		assertSteps
+		assertSteps,
+		compiledRevision
 	};
 }
+function resolveBlockInsertionPos(editor, anchorBlockId, position, stepId) {
+	const candidate = getBlockIndex(editor).candidates.find((c$3) => c$3.nodeId === anchorBlockId);
+	if (!candidate) throw planError("TARGET_NOT_FOUND", `block "${anchorBlockId}" not found`, stepId);
+	return position === "before" ? candidate.pos : candidate.end;
+}
 function applyDirectMutationMeta(tr) {
 	tr.setMeta("inputType", "programmatic");
 	tr.setMeta("skipTrackChanges", true);
@@ -25412,10 +25592,28 @@ function buildMarksFromSetMarks(editor, setMarks) {
 	if (setMarks.strike && schema.marks.strike) marks.push(schema.marks.strike.create());
 	return marks;
 }
-function toAbsoluteBlockInsertPos(editor, blockId, offset$1, stepId) {
-	const candidate = getBlockIndex(editor).candidates.find((c$3) => c$3.nodeId === blockId);
-	if (!candidate) throw planError("TARGET_NOT_FOUND", `block "${blockId}" not found`, stepId);
-	return candidate.pos + offset$1;
+function applyInlineMarkPatches(editor, tr, absFrom, absTo, inline) {
+	const { schema } = editor.state;
+	let changed = false;
+	const markEntries = [
+		[inline.bold, schema.marks.bold],
+		[inline.italic, schema.marks.italic],
+		[inline.underline, schema.marks.underline],
+		[inline.strike, schema.marks.strike]
+	];
+	for (const [value, markType] of markEntries) {
+		if (value === void 0 || !markType) continue;
+		if (value) tr.addMark(absFrom, absTo, markType.create());
+		else tr.removeMark(absFrom, absTo, markType);
+		changed = true;
+	}
+	return changed;
+}
+function resolveCreateAnchorBlockId(target, position, stepId) {
+	if (target.kind === "range") return target.blockId;
+	const segments = target.segments;
+	if (!segments.length) throw planError("INVALID_INPUT", "span target has no segments", stepId);
+	return position === "before" ? segments[0].blockId : segments[segments.length - 1].blockId;
 }
 function executeTextRewrite(editor, tr, target, step, mapping) {
 	const absFrom = mapping.map(target.absFrom);
@@ -25449,39 +25647,7 @@ function executeTextDelete(_editor, tr, target, _step, mapping) {
 	return { changed: true };
 }
 function executeStyleApply(editor, tr, target, step, mapping) {
-	const absFrom = mapping.map(target.absFrom);
-	const absTo = mapping.map(target.absTo);
-	const { schema } = editor.state;
-	let changed = false;
-	const markEntries = [
-		[
-			"bold",
-			step.args.inline.bold,
-			schema.marks.bold
-		],
-		[
-			"italic",
-			step.args.inline.italic,
-			schema.marks.italic
-		],
-		[
-			"underline",
-			step.args.inline.underline,
-			schema.marks.underline
-		],
-		[
-			"strike",
-			step.args.inline.strike,
-			schema.marks.strike
-		]
-	];
-	for (const [, value, markType] of markEntries) {
-		if (value === void 0 || !markType) continue;
-		if (value) tr.addMark(absFrom, absTo, markType.create());
-		else tr.removeMark(absFrom, absTo, markType);
-		changed = true;
-	}
-	return { changed };
+	return { changed: applyInlineMarkPatches(editor, tr, mapping.map(target.absFrom), mapping.map(target.absTo), step.args.inline) };
 }
 function validateMappedSpanContiguity(target, mapping, stepId) {
 	let lastMappedEnd = -1;
@@ -25542,41 +25708,9 @@ function executeSpanTextDelete(_editor, tr, target, step, mapping) {
 }
 function executeSpanStyleApply(editor, tr, target, step, mapping) {
 	validateMappedSpanContiguity(target, mapping, step.id);
-	const { schema } = editor.state;
-	let changed = false;
 	const firstSeg = target.segments[0];
 	const lastSeg = target.segments[target.segments.length - 1];
-	const absFrom = mapping.map(firstSeg.absFrom, 1);
-	const absTo = mapping.map(lastSeg.absTo, -1);
-	const markEntries = [
-		[
-			"bold",
-			step.args.inline.bold,
-			schema.marks.bold
-		],
-		[
-			"italic",
-			step.args.inline.italic,
-			schema.marks.italic
-		],
-		[
-			"underline",
-			step.args.inline.underline,
-			schema.marks.underline
-		],
-		[
-			"strike",
-			step.args.inline.strike,
-			schema.marks.strike
-		]
-	];
-	for (const [, value, markType] of markEntries) {
-		if (value === void 0 || !markType) continue;
-		if (value) tr.addMark(absFrom, absTo, markType.create());
-		else tr.removeMark(absFrom, absTo, markType);
-		changed = true;
-	}
-	return { changed };
+	return { changed: applyInlineMarkPatches(editor, tr, mapping.map(firstSeg.absFrom, 1), mapping.map(lastSeg.absTo, -1), step.args.inline) };
 }
 function getReplacementText(replacement) {
 	if (replacement.blocks !== void 0) return replacement.blocks.map((b$1) => b$1.text).join("\n\n");
@@ -25747,9 +25881,11 @@ function executeAssertStep(_editor, tr, step) {
 }
 function executeCreateStep(editor, tr, step, targets, mapping) {
 	const target = targets[0];
-	if (!target || target.kind !== "range") throw planError("INVALID_INPUT", `${step.op} step requires exactly one range target`, step.id);
+	if (!target) throw planError("INVALID_INPUT", `${step.op} step requires at least one target`, step.id);
 	const args$1 = step.args;
-	const pos = mapping.map(toAbsoluteBlockInsertPos(editor, target.blockId, target.from, step.id));
+	const position = args$1.position ?? "after";
+	const anchorPos = resolveBlockInsertionPos(editor, resolveCreateAnchorBlockId(target, position, step.id), position, step.id);
+	const pos = mapping.map(anchorPos);
 	const paragraphType = editor.state.schema?.nodes?.paragraph;
 	if (!paragraphType) throw planError("INVALID_INPUT", "paragraph node type not in schema", step.id);
 	const sdBlockId = args$1.sdBlockId;
@@ -25766,6 +25902,7 @@ function executeCreateStep(editor, tr, step, targets, mapping) {
 	const node = paragraphType.createAndFill(attrs, textNode ?? void 0) ?? paragraphType.create(attrs, textNode ? [textNode] : void 0);
 	if (!node) throw planError("INVALID_INPUT", `could not create ${step.op} node`, step.id);
 	tr.insert(pos, node);
+	assertNoPostInsertDuplicateIds(tr.doc, step.id);
 	return {
 		stepId: step.id,
 		op: step.op,
@@ -25777,6 +25914,27 @@ function executeCreateStep(editor, tr, step, targets, mapping) {
 		}
 	};
 }
+function assertNoPostInsertDuplicateIds(doc$2, stepId) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicateSet = /* @__PURE__ */ new Set();
+	doc$2.descendants((node) => {
+		if (!node.isTextblock) return true;
+		const attrs = node.attrs ?? {};
+		const id = typeof attrs.paraId === "string" && attrs.paraId || typeof attrs.sdBlockId === "string" && attrs.sdBlockId || typeof attrs.nodeId === "string" && attrs.nodeId;
+		if (!id) return true;
+		if (seen.has(id)) duplicateSet.add(id);
+		else seen.add(id);
+		return true;
+	});
+	if (duplicateSet.size > 0) {
+		const duplicates = [...duplicateSet];
+		throw planError("INTERNAL_ERROR", `create step produced duplicate block identities: [${duplicates.join(", ")}]`, stepId, {
+			source: "executor:checkPostInsertIdentityUniqueness",
+			invariant: "post-insert block IDs must be unique",
+			duplicateBlockIds: duplicates
+		});
+	}
+}
 function runMutationsOnTransaction(editor, tr, compiled, options) {
 	const mapping = tr.mapping;
 	const stepOutcomes = [];
@@ -25832,6 +25990,13 @@ function executeCompiledPlan(editor, compiled, options = {}) {
 	const startTime = performance.now();
 	const revisionBefore = getRevision(editor);
 	checkRevision(editor, options.expectedRevision);
+	if (compiled.compiledRevision !== revisionBefore) throw planError("REVISION_CHANGED_SINCE_COMPILE", `Document revision changed between compile and execute. Compiled at "${compiled.compiledRevision}", now at "${revisionBefore}".`, void 0, {
+		compiledRevision: compiled.compiledRevision,
+		currentRevision: revisionBefore,
+		stepCount: compiled.mutationSteps.length,
+		failedAtStep: "pre-execution",
+		remediation: "Re-compile the plan against the current document state."
+	});
 	const tr = editor.state.tr;
 	if ((options.changeMode ?? "direct") === "tracked") applyTrackedMutationMeta(tr);
 	else applyDirectMutationMeta(tr);
@@ -26040,7 +26205,8 @@ function executeDomainCommand(editor, handler, options) {
 			},
 			targets: []
 		}],
-		assertSteps: []
+		assertSteps: [],
+		compiledRevision: getRevision(editor)
 	}, { expectedRevision: options?.expectedRevision });
 }
 function validateWriteRequest(request, resolved) {
@@ -26127,7 +26293,8 @@ function writeWrapper(editor, request, options) {
 			step: stepDef,
 			targets: [toCompiledTarget(stepId, op, resolved)]
 		}],
-		assertSteps: []
+		assertSteps: [],
+		compiledRevision: getRevision(editor)
 	}, {
 		changeMode: mode,
 		expectedRevision: options?.expectedRevision
@@ -26193,7 +26360,8 @@ function styleApplyWrapper(editor, input, options) {
 				marks: []
 			}]
 		}],
-		assertSteps: []
+		assertSteps: [],
+		compiledRevision: getRevision(editor)
 	}, {
 		changeMode: mode,
 		expectedRevision: options?.expectedRevision
@@ -27127,9 +27295,7 @@ function resolveCreateInsertPosition(editor, at, operationLabel) {
 	const location$1 = at ?? { kind: "documentEnd" };
 	if (location$1.kind === "documentStart") return 0;
 	if (location$1.kind === "documentEnd") return editor.state.doc.content.size;
-	const target = findBlockById(getBlockIndex(editor), location$1.target);
-	if (!target) throw new DocumentApiAdapterError("TARGET_NOT_FOUND", `Create ${operationLabel} target block was not found.`, { target: location$1.target });
-	return location$1.kind === "before" ? target.pos : target.end;
+	return resolveBlockInsertionPos(editor, location$1.target.nodeId, location$1.kind);
 }
 function resolveCreatedBlock(editor, nodeType, blockId) {
 	const index = getBlockIndex(editor);
@@ -27231,7 +27397,9 @@ function createParagraphWrapper(editor, input, options) {
 			try {
 				const paragraph = resolveCreatedBlock(editor, "paragraph", paragraphId);
 				if (mode === "tracked") trackedChangeRefs = collectTrackInsertRefsInRange(editor, paragraph.pos, paragraph.end);
-			} catch {}
+			} catch (e) {
+				if (!(e instanceof DocumentApiAdapterError)) throw e;
+			}
 		}
 		return didApply;
 	}, { expectedRevision: options?.expectedRevision }).steps[0]?.effect !== "changed") return {
@@ -27293,7 +27461,9 @@ function createHeadingWrapper(editor, input, options) {
 			try {
 				const heading = resolveCreatedBlock(editor, "heading", headingId);
 				if (mode === "tracked") trackedChangeRefs = collectTrackInsertRefsInRange(editor, heading.pos, heading.end);
-			} catch {}
+			} catch (e) {
+				if (!(e instanceof DocumentApiAdapterError)) throw e;
+			}
 		}
 		return didApply;
 	}, { expectedRevision: options?.expectedRevision }).steps[0]?.effect !== "changed") return {
@@ -28505,14 +28675,15 @@ function trackChangesRejectAllWrapper(editor, _input, options) {
 	return { success: true };
 }
 function previewPlan(editor, input) {
-	const evaluatedRevision = getRevision(editor);
 	checkRevision(editor, input.expectedRevision);
 	if (!input.steps?.length) throw planError("INVALID_INPUT", "plan must contain at least one step");
 	const failures = [];
 	const stepPreviews = [];
 	let currentPhase = "compile";
+	let evaluatedRevision = getRevision(editor);
 	try {
 		const compiled = compilePlan(editor, input.steps);
+		evaluatedRevision = compiled.compiledRevision;
 		currentPhase = "execute";
 		const tr = editor.state.tr;
 		const { stepOutcomes, assertFailures } = runMutationsOnTransaction(editor, tr, compiled, { throwOnAssertFailure: false });
@@ -29015,14 +29186,24 @@ function queryMatchAdapter(editor, input) {
 	const userOffset = input.offset ?? 0;
 	const paginatedMatches = isTextSelector ? applyPagination(rawMatches, userOffset, input.limit) : rawMatches;
 	if (require$1 === "first" || require$1 === "exactlyOne" || require$1 === "all") {
-		if (totalMatches === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges");
+		if (totalMatches === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", void 0, {
+			selectorType: input.select?.type ?? "unknown",
+			selectorPattern: input.select?.pattern ?? "",
+			selectorMode: input.select?.mode ?? "contains",
+			searchScope: (input.within?.kind === "block" ? input.within.nodeId : void 0) ?? "document",
+			candidateCount: 0
+		});
 	}
 	if (require$1 === "exactlyOne" && totalMatches > 1) throw planError("AMBIGUOUS_MATCH", `selector matched ${totalMatches} ranges, expected exactly one`, void 0, { matchCount: totalMatches });
 	const matchItems = paginatedMatches.map((raw, pageIdx) => {
 		const id = `m:${userOffset + pageIdx}`;
 		if (isTextSelector && raw.textRanges?.length) {
 			const blocks = buildMatchBlocks(editor, raw.textRanges, evaluatedRevision, id);
-			if (blocks.length === 0) throw planError("INTERNAL_ERROR", `text match produced no blocks for ${id}`);
+			if (blocks.length === 0) throw planError("INTERNAL_ERROR", `text match produced no blocks for ${id}`, void 0, {
+				source: "query-match-adapter:buildMatchEntries",
+				invariant: "text match must have at least one block after zero-width filtering",
+				context: { matchId: id }
+			});
 			const snippetResult = buildBlocksSnippet(editor, blocks);
 			return {
 				id,
@@ -30627,7 +30808,7 @@ var Editor = class Editor extends EventEmitter$1 {
 		return migrations.length > 0;
 	}
 	processCollaborationMigrations() {
-		console.debug("[checkVersionMigrations] Current editor version", "1.17.0-next.12");
+		console.debug("[checkVersionMigrations] Current editor version", "1.17.0-next.13");
 		if (!this.options.ydoc) return;
 		let docVersion = this.options.ydoc.getMap("meta").get("version");
 		if (!docVersion) docVersion = "initial";