@lmzhen/dsh-evolution-merge 0.40.1 → 0.42.0

package/lib/index.js

@@ -1,14 +1,15 @@
 import { dirname, isAbsolute, join } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { pairKeyOf, screen, selectCandidates } from "@lmzhen/dsh-evolution-merge-engine";
-import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { DEFAULT_SKILL_LIMITS, LeaseStore, SkillLibrary, UnitTransactions, authorityFrom, contentHash, createSubagentChannel, errorText, evolutionHome, evolutionIoAdapter, executeUnitUndo, isPresent, isProcessAlive, newRunRegistry, newSkillLibrary, parseFrontmatter, planUnitUndoAcross, policyStageLimits, probeAbsent, probeList, probePresent, probeText, probeUnknown, readTreeLock, readUnitEvidence, readUnitJournal, registerOwnerSettings, reportsSweepLockTarget, revisionAnchorOf, revisionFingerprint, revisionSupportDigest, runsFile, scanContentThreats, skillLibraryUnitBackend, supportRefs, sweepReports, transactIo, validateFrontmatter, validateSupportPath } from "@lmzhen/dsh-evolution-core";
+import { createUserMessage, defineTool } from "@lmzhen/dsh-evolution-core/platform";
+import { DEFAULT_SKILL_LIMITS, LeaseStore, acquireTreeWriteLock, authorityFrom, contentHash, createSubagentChannel, errorText, evolutionHome, evolutionIoAdapter, isPresent, isProcessAlive, newRunRegistry, policyStageLimits, probeAbsent, probeList, probePresent, probeText, probeUnknown, readTreeLock, registerOwnerSettings, reportsSweepLockTarget, runsFile, scanContentThreats, supportRefs, sweepReports, transactIo } from "@lmzhen/dsh-evolution-core";
+import { SkillLibrary, newSkillLibrary, parseFrontmatter, revisionAnchorOf, revisionFingerprint, revisionSupportDigest, validateFrontmatter, validateSupportPath } from "@lmzhen/dsh-evolution-core/skills";
 import { HOST_ROUTES, json, methodNotAllowed, registerHostRoutes } from "@lmzhen/dsh-evolution-core/http-routes";
 import { createHash, randomUUID } from "node:crypto";
 import { chmod, mkdir, open, readFile, stat, unlink } from "node:fs/promises";
+import { executeUnitUndo, planUnitUndoAcross, readUnitEvidence, readUnitIndex, readUnitJournal, readUnitReceipt, readUnitSnapshot, unitStorageKey, writeUnitEvidence, writeUnitJournal, writeUnitReceipt, writeUnitSnapshot } from "@lmzhen/dsh-evolution-core/write";
 import { aliasRegistration, buildSurface, parseCommand } from "@lmzhen/dsh-evolution-commands";
 import { readFileSync } from "node:fs";
-import { defineTool } from "@lmzhen/dsh-evolution-core/platform";
 //#region lib/types/adapters/select.js
 /** Host selector correction: engine selector does not route judge errors to candidates. */
 function selectWithErrors(report) {
@@ -2678,7 +2679,7 @@ function isReport(value) {
 	const report = value;
 	return report.schemaVersion === 2 && report.kind === "merge" && typeof report.runId === "string" && typeof report.command === "string" && typeof report.startedAt === "number" && typeof report.endedAt === "number" && Array.isArray(report.pairs) && typeof report.totals === "object" && Array.isArray(report.notes);
 }
-function digest$2(report) {
+function digest$3(report) {
 	const lines = [];
 	lines.push("# merge " + report.runId);
 	lines.push("");
@@ -2697,7 +2698,7 @@ function digest$2(report) {
 async function writeMergeReport(io, home, report) {
 	const path = mergeReportPath(home, report.runId);
 	await io.writeText(path, JSON.stringify(report, null, 2) + "\n");
-	await io.writeText(mergeReportDigestPath(home, report.runId), digest$2(report));
+	await io.writeText(mergeReportDigestPath(home, report.runId), digest$3(report));
 	return path;
 }
 async function readMergeReport(io, home, runId) {
@@ -3124,6 +3125,754 @@ async function readHistory(io, home) {
 	}));
 }
 //#endregion
+//#region lib/types/unit-protocol.js
+/** G2 opaque UnitTransaction. Core owns prepare/commit/verify/rollback lifecycle. */
+function canonicalJson(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return "[" + value.map(canonicalJson).join(",") + "]";
+	const object = value;
+	return "{" + Object.keys(object).sort().map((key) => JSON.stringify(key) + ":" + canonicalJson(object[key])).join(",") + "}";
+}
+function sameTarget(a, b) {
+	return (a ?? "").trimEnd() === (b ?? "").trimEnd();
+}
+function digest$2(plan) {
+	return createHash("sha256").update(canonicalJson(plan)).digest("hex");
+}
+function unitEvidenceDigest(evidence) {
+	return createHash("sha256").update(canonicalJson({
+		...evidence,
+		at: 0,
+		mutations: 0
+	})).digest("hex");
+}
+var MergeUnitTransactions = class {
+	options;
+	prepared = /* @__PURE__ */ new Map();
+	commits = /* @__PURE__ */ new Map();
+	now;
+	constructor(options) {
+		this.options = options;
+		this.now = options.now ?? (() => Date.now());
+	}
+	unitId(plan) {
+		return plan.unitId ?? plan.runId + ":" + createHash("sha256").update(plan.pairKey).digest("hex").slice(0, 16);
+	}
+	async snapshot(plan, unitId, planDigest) {
+		const targetBefore = await this.options.backend.readSkill(plan.target);
+		const supportBefore = await Promise.all(plan.supportFiles.map(async (file) => ({
+			path: file.path,
+			content: await this.options.backend.readSupportFile(plan.target, file.path)
+		})));
+		const sourceBefore = await Promise.all(plan.sources.filter((source) => source !== plan.target).map(async (name) => ({
+			name,
+			body: await this.options.backend.readSkill(name) ?? ""
+		})));
+		return {
+			schemaVersion: 1,
+			unitId,
+			planDigest,
+			runId: plan.runId,
+			target: plan.target,
+			targetExists: plan.targetExists,
+			targetBefore,
+			targetAfter: plan.body,
+			supportBefore,
+			supportAfter: plan.supportFiles,
+			sourceBefore,
+			origin: plan.origin,
+			summary: plan.summary,
+			...plan.validationPlan === void 0 ? {} : { validationPlan: plan.validationPlan },
+			createdAt: this.now()
+		};
+	}
+	async prepare(plan) {
+		const unitId = this.unitId(plan);
+		const planDigest = digest$2(plan);
+		const existing = this.prepared.get(unitId);
+		if (existing !== void 0) return existing.digest === planDigest ? {
+			ok: true,
+			prepared: {
+				unitId,
+				planDigest
+			}
+		} : {
+			ok: false,
+			code: "unit-conflict",
+			message: "unitId already prepared with a different plan"
+		};
+		const snapshot = await this.snapshot(plan, unitId, planDigest);
+		await writeUnitSnapshot(this.options.io, this.options.home, snapshot);
+		const journal = {
+			schemaVersion: 1,
+			unitId,
+			runId: plan.runId,
+			planDigest,
+			target: plan.target,
+			sources: plan.sources,
+			phase: "prepared",
+			storageKey: unitStorageKey(unitId),
+			snapshotSha256: createHash("sha256").update(JSON.stringify(snapshot, null, 2) + "\n").digest("hex"),
+			updatedAt: this.now()
+		};
+		await writeUnitJournal(this.options.io, this.options.home, journal);
+		await this.options.onPhase?.("prepared");
+		this.prepared.set(unitId, {
+			plan,
+			digest: planDigest,
+			at: this.now(),
+			snapshotSha256: createHash("sha256").update(JSON.stringify(snapshot, null, 2) + "\n").digest("hex")
+		});
+		return {
+			ok: true,
+			prepared: {
+				unitId,
+				planDigest
+			}
+		};
+	}
+	async commit(prepared, options) {
+		const running = this.commits.get(prepared.unitId);
+		if (running !== void 0) return await running;
+		const run = () => this.commitOnce(prepared, options);
+		const task = this.options.serial === void 0 ? run() : this.options.serial(run);
+		this.commits.set(prepared.unitId, task);
+		try {
+			return await task;
+		} finally {
+			this.commits.delete(prepared.unitId);
+		}
+	}
+	async commitOnce(prepared, options) {
+		const existing = await readUnitEvidence(this.options.io, this.options.home, prepared.unitId);
+		if (existing !== null) return existing.planDigest === prepared.planDigest ? {
+			ok: true,
+			evidence: existing
+		} : {
+			ok: false,
+			code: "unit-conflict",
+			message: "unit already committed with a different digest"
+		};
+		const stored = this.prepared.get(prepared.unitId);
+		if (stored === void 0 || stored.digest !== prepared.planDigest) return {
+			ok: false,
+			code: "unit-plan-missing",
+			message: "prepared plan is not in this process; manual recovery required"
+		};
+		if (options?.signal?.aborted === true) return {
+			ok: false,
+			code: "unit-commit-failed",
+			message: "cancelled before commit"
+		};
+		if (this.options.isActive !== void 0 && !await this.options.isActive(stored.plan.runId)) return {
+			ok: false,
+			code: "unit-run-inactive",
+			message: "run is no longer active; refusing to commit"
+		};
+		const journalBase = {
+			schemaVersion: 1,
+			unitId: prepared.unitId,
+			runId: stored.plan.runId,
+			planDigest: stored.digest,
+			target: stored.plan.target,
+			sources: stored.plan.sources,
+			storageKey: unitStorageKey(prepared.unitId),
+			snapshotSha256: stored.snapshotSha256,
+			updatedAt: this.now()
+		};
+		let lock;
+		let fenceLease;
+		let claim;
+		let stage = "fence";
+		const checkpoints = [];
+		const writePhase = async (phase, checkpointsNext = checkpoints) => {
+			if (lock !== void 0 && !await lock.assertHeld()) throw new Error("unit-fence-lost");
+			await writeUnitJournal(this.options.io, this.options.home, {
+				...journalBase,
+				phase,
+				checkpoints: checkpointsNext
+			});
+			await this.options.onPhase?.(phase);
+		};
+		try {
+			if (this.options.fence !== void 0) {
+				fenceLease = await this.options.fence.acquire();
+				lock = fenceLease.lock;
+				this.options.onLock?.("tree");
+			} else {
+				const acquired = await acquireTreeWriteLock({
+					io: this.options.io,
+					home: this.options.home,
+					waitMs: this.options.waitMs ?? 5e3
+				});
+				if (!acquired.ok) return {
+					ok: false,
+					code: "unit-fence-failed",
+					message: acquired.message ?? acquired.reason
+				};
+				lock = acquired.lock;
+				this.options.onLock?.("tree");
+			}
+			if (!await lock.assertHeld()) return {
+				ok: false,
+				code: "unit-fence-failed",
+				message: "tree fence lost"
+			};
+			stage = "claim";
+			claim = await this.options.claim.acquire(stored.plan.target, stored.plan.runId);
+			this.options.onLock?.("claim");
+			const committedWhileWaiting = await readUnitEvidence(this.options.io, this.options.home, prepared.unitId);
+			if (committedWhileWaiting !== null) return committedWhileWaiting.planDigest === prepared.planDigest ? {
+				ok: true,
+				evidence: committedWhileWaiting
+			} : {
+				ok: false,
+				code: "unit-conflict",
+				message: "unit already committed with a different digest"
+			};
+			stage = "commit";
+			await writeUnitJournal(this.options.io, this.options.home, {
+				...journalBase,
+				phase: "target-pending"
+			});
+			const result = await this.options.backend.commit({
+				...stored.plan,
+				unitId: prepared.unitId
+			}, async (phase, detail) => {
+				if (phase === "support-pending") {
+					await writePhase("support-pending");
+					await this.options.onPhase?.("support-pending");
+					return;
+				}
+				if (phase === "target-applied") {
+					await this.options.onPhase?.("target-applied");
+					return;
+				}
+				if (phase === "unit-written") {
+					if (lock !== void 0 && !await lock.assertHeld()) throw new Error("unit-fence-lost");
+					await writeUnitReceipt(this.options.io, this.options.home, {
+						schemaVersion: 1,
+						unitId: prepared.unitId,
+						runId: stored.plan.runId,
+						planDigest: stored.digest,
+						target: stored.plan.target,
+						archived: stored.plan.sources.filter((source) => source !== stored.plan.target),
+						at: this.now()
+					});
+					await writePhase("unit-written");
+					return;
+				}
+				if (phase === "source-archiving" && detail?.source !== void 0) checkpoints.push({
+					source: detail.source,
+					phase: "archived",
+					hash: createHash("sha256").update(stored.plan.expectedSourceBodies.find((item) => item.name === detail.source)?.body ?? "").digest("hex"),
+					at: this.now()
+				});
+				await writePhase(phase, checkpoints);
+			}, options?.signal, async () => lock !== void 0 && await lock.assertHeld(), this.options.serial === void 0 ? void 0 : { serialized: true });
+			if (!result.ok) {
+				await writePhase("failed");
+				return {
+					ok: false,
+					code: result.code ?? "unit-commit-failed",
+					message: result.message
+				};
+			}
+			const targetAfter = await this.options.backend.readSkill(stored.plan.target) ?? "";
+			const evidence = {
+				schemaVersion: 1,
+				unitId: prepared.unitId,
+				runId: stored.plan.runId,
+				planDigest: stored.digest,
+				state: "complete",
+				target: {
+					before: stored.plan.expectedTargetBody,
+					after: targetAfter,
+					supportDigest: createHash("sha256").update(JSON.stringify(stored.plan.supportFiles)).digest("hex"),
+					created: !stored.plan.targetExists
+				},
+				sources: stored.plan.sources.filter((source) => source !== stored.plan.target).map((name) => ({
+					name,
+					before: stored.plan.expectedSourceBodies.find((item) => item.name === name)?.body ?? "",
+					after: null,
+					archived: (result.archived ?? []).includes(name),
+					absorbedInto: stored.plan.target
+				})),
+				mutations: result.mutations ?? 0,
+				...stored.plan.validationPlan === void 0 ? {} : { validationPlan: stored.plan.validationPlan },
+				at: this.now()
+			};
+			if (!await lock.assertHeld()) throw new Error("unit-fence-lost");
+			const evidenceSha256 = unitEvidenceDigest(evidence);
+			await writeUnitEvidence(this.options.io, this.options.home, evidence);
+			await writeUnitReceipt(this.options.io, this.options.home, {
+				schemaVersion: 1,
+				unitId: prepared.unitId,
+				runId: stored.plan.runId,
+				planDigest: stored.digest,
+				target: stored.plan.target,
+				archived: stored.plan.sources.filter((source) => source !== stored.plan.target),
+				at: this.now(),
+				evidenceSha256
+			});
+			await writePhase("committed", checkpoints);
+			this.prepared.delete(prepared.unitId);
+			return {
+				ok: true,
+				evidence
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				ok: false,
+				code: message === "unit-fence-lost" ? "unit-fence-failed" : stage === "claim" ? "unit-claim-failed" : stage === "fence" ? "unit-fence-failed" : "unit-commit-failed",
+				message
+			};
+		} finally {
+			try {
+				await claim?.release();
+			} finally {
+				if (fenceLease !== void 0) await fenceLease.release();
+				else await lock?.release();
+			}
+		}
+	}
+	async verify(ref) {
+		if ("unitId" in ref) return await readUnitEvidence(this.options.io, this.options.home, ref.unitId);
+		const entries = (await readUnitIndex(this.options.io, this.options.home)).filter((entry) => entry.runId === ref.runId);
+		const found = (await Promise.all(entries.map(async (entry) => readUnitEvidence(this.options.io, this.options.home, entry.unitId)))).filter((item) => item !== null && item.runId === ref.runId);
+		const only = found[0];
+		return found.length === 0 ? null : found.length === 1 ? only ?? null : found;
+	}
+	async withRecoveryFence(task) {
+		if (this.options.fence === void 0) return await task();
+		const lease = await this.options.fence.acquire();
+		try {
+			return await task();
+		} finally {
+			await lease.release();
+		}
+	}
+	async finalize(unitId) {
+		return await this.withRecoveryFence(async () => this.finalizeUnlocked(unitId));
+	}
+	async finalizeUnlocked(unitId) {
+		const existing = await readUnitEvidence(this.options.io, this.options.home, unitId);
+		if (existing !== null) return {
+			ok: true,
+			evidence: existing
+		};
+		const snapshot = await readUnitSnapshot(this.options.io, this.options.home, unitId);
+		const journal = await readUnitJournal(this.options.io, this.options.home, unitId);
+		const receipt = await readUnitReceipt(this.options.io, this.options.home, unitId);
+		if (snapshot === null || journal === null || journal.phase !== "committed" && receipt === null) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "unit is not committed; manual recovery required"
+		};
+		if (receipt !== null && (receipt.unitId !== unitId || receipt.runId !== snapshot.runId || receipt.planDigest !== snapshot.planDigest || receipt.target !== snapshot.target)) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "unit receipt does not match snapshot; manual recovery required"
+		};
+		const checkpoints = journal.checkpoints ?? [];
+		const missing = snapshot.sourceBefore.filter((source) => !checkpoints.some((item) => item.source === source.name));
+		if (missing.length > 0) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "source checkpoint missing: " + missing.map((item) => item.name).join(",")
+		};
+		const liveTarget = await this.options.backend.readSkill(snapshot.target);
+		if (liveTarget === null || !sameTarget(liveTarget, snapshot.targetAfter)) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "target live hash does not match the prepared target; manual recovery required"
+		};
+		const liveSource = (await Promise.all(snapshot.sourceBefore.map(async (source) => ({
+			name: source.name,
+			body: await this.options.backend.readSkill(source.name)
+		})))).find((source) => source.body !== null);
+		if (liveSource !== void 0) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "source is still live: " + liveSource.name
+		};
+		let liveSupport = await Promise.all(snapshot.supportAfter.map(async (file) => ({
+			path: file.path,
+			content: await this.options.backend.readSupportFile(snapshot.target, file.path)
+		})));
+		const supportMatches = () => liveSupport.every((file) => file.content === (snapshot.supportAfter.find((item) => item.path === file.path)?.content ?? null));
+		if (!supportMatches()) {
+			if (![
+				"support-pending",
+				"sources-archived",
+				"unit-written"
+			].includes(journal.phase) || this.options.backend.restoreSupportFile === void 0) return {
+				ok: false,
+				code: "unit-rollback-blocked",
+				message: "support file live hash does not match the prepared support; manual recovery required"
+			};
+			for (const file of snapshot.supportAfter) await this.options.backend.restoreSupportFile(snapshot.target, file.path, file.content);
+			liveSupport = await Promise.all(snapshot.supportAfter.map(async (file) => ({
+				path: file.path,
+				content: await this.options.backend.readSupportFile(snapshot.target, file.path)
+			})));
+			if (!supportMatches()) return {
+				ok: false,
+				code: "unit-rollback-blocked",
+				message: "support file could not be completed from the prepared snapshot"
+			};
+		}
+		const evidence = {
+			schemaVersion: 1,
+			unitId,
+			runId: snapshot.runId,
+			planDigest: snapshot.planDigest,
+			state: "complete",
+			target: {
+				before: snapshot.targetBefore,
+				after: await this.options.backend.readSkill(snapshot.target) ?? "",
+				supportDigest: createHash("sha256").update(JSON.stringify(snapshot.supportAfter)).digest("hex"),
+				created: !snapshot.targetExists
+			},
+			sources: snapshot.sourceBefore.map((source) => ({
+				name: source.name,
+				before: source.body,
+				after: null,
+				archived: checkpoints.some((item) => item.source === source.name),
+				absorbedInto: snapshot.target
+			})),
+			mutations: 0,
+			...snapshot.validationPlan === void 0 ? {} : { validationPlan: snapshot.validationPlan },
+			at: this.now()
+		};
+		if (receipt?.evidenceSha256 !== void 0 && unitEvidenceDigest(evidence) !== receipt.evidenceSha256) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "receipt evidence hash does not match rebuilt evidence"
+		};
+		await writeUnitEvidence(this.options.io, this.options.home, evidence);
+		if (journal.phase !== "committed") await writeUnitJournal(this.options.io, this.options.home, {
+			...journal,
+			phase: "committed",
+			checkpoints,
+			updatedAt: this.now()
+		});
+		return {
+			ok: true,
+			evidence
+		};
+	}
+	async rollForward(unitId) {
+		return await this.withRecoveryFence(async () => this.rollForwardUnlocked(unitId));
+	}
+	async rollForwardUnlocked(unitId) {
+		const existing = await readUnitEvidence(this.options.io, this.options.home, unitId);
+		if (existing !== null) return {
+			ok: true,
+			evidence: existing
+		};
+		const snapshot = await readUnitSnapshot(this.options.io, this.options.home, unitId);
+		const journal = await readUnitJournal(this.options.io, this.options.home, unitId);
+		if (snapshot === null || journal === null || ![
+			"target-written",
+			"support-pending",
+			"source-archiving",
+			"sources-archived",
+			"unit-written"
+		].includes(journal.phase)) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "unit is not roll-forwardable; manual recovery required"
+		};
+		const checkpoints = journal.checkpoints ?? [];
+		const missing = snapshot.sourceBefore.filter((source) => !checkpoints.some((item) => item.source === source.name));
+		if (missing.length > 0) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "source checkpoint missing: " + missing.map((item) => item.name).join(",")
+		};
+		const targetAfter = await this.options.backend.readSkill(snapshot.target);
+		if (targetAfter === null || !sameTarget(targetAfter, snapshot.targetAfter)) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "target missing or drifted; manual recovery required"
+		};
+		const liveSource = (await Promise.all(snapshot.sourceBefore.map(async (source) => ({
+			name: source.name,
+			body: await this.options.backend.readSkill(source.name)
+		})))).find((source) => source.body !== null);
+		if (liveSource !== void 0) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "source is still live: " + liveSource.name
+		};
+		let liveSupport = await Promise.all(snapshot.supportAfter.map(async (file) => ({
+			path: file.path,
+			content: await this.options.backend.readSupportFile(snapshot.target, file.path)
+		})));
+		const supportMatches = () => liveSupport.every((file) => file.content === (snapshot.supportAfter.find((item) => item.path === file.path)?.content ?? null));
+		if (!supportMatches()) {
+			if (![
+				"support-pending",
+				"sources-archived",
+				"unit-written"
+			].includes(journal.phase) || this.options.backend.restoreSupportFile === void 0) return {
+				ok: false,
+				code: "unit-rollback-blocked",
+				message: "support file live hash does not match the prepared support; manual recovery required"
+			};
+			for (const file of snapshot.supportAfter) await this.options.backend.restoreSupportFile(snapshot.target, file.path, file.content);
+			liveSupport = await Promise.all(snapshot.supportAfter.map(async (file) => ({
+				path: file.path,
+				content: await this.options.backend.readSupportFile(snapshot.target, file.path)
+			})));
+			if (!supportMatches()) return {
+				ok: false,
+				code: "unit-rollback-blocked",
+				message: "support file could not be completed from the prepared snapshot"
+			};
+		}
+		const evidence = {
+			schemaVersion: 1,
+			unitId,
+			runId: snapshot.runId,
+			planDigest: snapshot.planDigest,
+			state: "complete",
+			target: {
+				before: snapshot.targetBefore,
+				after: targetAfter,
+				supportDigest: createHash("sha256").update(JSON.stringify(snapshot.supportAfter)).digest("hex"),
+				created: !snapshot.targetExists
+			},
+			sources: snapshot.sourceBefore.map((source) => ({
+				name: source.name,
+				before: source.body,
+				after: null,
+				archived: checkpoints.some((item) => item.source === source.name),
+				absorbedInto: snapshot.target
+			})),
+			mutations: 0,
+			...snapshot.validationPlan === void 0 ? {} : { validationPlan: snapshot.validationPlan },
+			at: this.now()
+		};
+		await writeUnitEvidence(this.options.io, this.options.home, evidence);
+		await writeUnitJournal(this.options.io, this.options.home, {
+			...journal,
+			phase: "committed",
+			checkpoints,
+			updatedAt: this.now()
+		});
+		return {
+			ok: true,
+			evidence
+		};
+	}
+	async rollback(ref) {
+		const evidence = await readUnitEvidence(this.options.io, this.options.home, ref.unitId);
+		const receipt = await readUnitReceipt(this.options.io, this.options.home, ref.unitId);
+		if (evidence !== null || receipt !== null) return {
+			ok: false,
+			code: "unit-committed",
+			message: "committed unit cannot roll back"
+		};
+		const snapshot = await readUnitSnapshot(this.options.io, this.options.home, ref.unitId);
+		if (snapshot === null) return {
+			ok: false,
+			code: "unit-rollback-blocked",
+			message: "snapshot missing"
+		};
+		const journal = await readUnitJournal(this.options.io, this.options.home, ref.unitId);
+		let fenceLease;
+		let lock;
+		let claim;
+		try {
+			if (this.options.fence !== void 0) {
+				fenceLease = await this.options.fence.acquire();
+				lock = fenceLease.lock;
+			} else {
+				const acquired = await acquireTreeWriteLock({
+					io: this.options.io,
+					home: this.options.home,
+					waitMs: this.options.waitMs ?? 5e3
+				});
+				if (!acquired.ok) return {
+					ok: false,
+					code: "unit-fence-failed",
+					message: acquired.message ?? acquired.reason
+				};
+				lock = acquired.lock;
+			}
+			this.options.onLock?.("tree");
+			if (!await lock.assertHeld()) return {
+				ok: false,
+				code: "unit-fence-failed",
+				message: "tree fence lost"
+			};
+			claim = await this.options.claim.acquire(snapshot.target, snapshot.runId);
+			this.options.onLock?.("claim");
+			const currentTarget = await this.options.backend.readSkill(snapshot.target);
+			if (currentTarget !== snapshot.targetBefore && !sameTarget(currentTarget, snapshot.targetAfter)) return {
+				ok: false,
+				code: "unit-rollback-blocked",
+				message: "target drifted since snapshot; manual recovery required"
+			};
+			for (const source of snapshot.sourceBefore) {
+				const current = await this.options.backend.readSkill(source.name);
+				if (current !== null && current !== source.body) return {
+					ok: false,
+					code: "unit-rollback-blocked",
+					message: "source drifted since snapshot: " + source.name
+				};
+			}
+			if (!await lock.assertHeld()) return {
+				ok: false,
+				code: "unit-fence-failed",
+				message: "tree fence lost before target restore"
+			};
+			await this.options.backend.restoreTarget(snapshot.target, snapshot.targetBefore);
+			for (const file of snapshot.supportBefore) {
+				if (!await lock.assertHeld()) return {
+					ok: false,
+					code: "unit-fence-failed",
+					message: "tree fence lost before support restore"
+				};
+				await this.options.backend.restoreSupportFile?.(snapshot.target, file.path, file.content);
+			}
+			for (const source of snapshot.sourceBefore) {
+				if (!await lock.assertHeld()) return {
+					ok: false,
+					code: "unit-fence-failed",
+					message: "tree fence lost before source restore"
+				};
+				await this.options.backend.restoreSource(source.name, source.body);
+			}
+			if (journal !== null) await writeUnitJournal(this.options.io, this.options.home, {
+				...journal,
+				phase: "rolled-back",
+				updatedAt: this.now()
+			});
+			return {
+				ok: true,
+				evidence: {
+					schemaVersion: 1,
+					unitId: ref.unitId,
+					runId: snapshot.runId,
+					planDigest: snapshot.planDigest,
+					state: "target-only",
+					target: {
+						before: snapshot.targetBefore,
+						after: snapshot.targetBefore ?? "",
+						supportDigest: "",
+						created: false
+					},
+					sources: snapshot.sourceBefore.map((source) => ({
+						name: source.name,
+						before: source.body,
+						after: null,
+						archived: false,
+						absorbedInto: snapshot.target
+					})),
+					mutations: 0,
+					at: this.now()
+				}
+			};
+		} finally {
+			try {
+				await claim?.release();
+			} finally {
+				if (fenceLease !== void 0) await fenceLease.release();
+				else await lock?.release();
+			}
+		}
+	}
+	async cancel(unitId, reason) {
+		const journal = await readUnitJournal(this.options.io, this.options.home, unitId);
+		if (journal === null) return {
+			ok: false,
+			phase: "none"
+		};
+		if (journal.phase === "prepared" && this.prepared.has(unitId)) {
+			this.prepared.delete(unitId);
+			return {
+				ok: true,
+				phase: "prepared"
+			};
+		}
+		if (journal.phase === "target-pending" || journal.phase === "target-written" || journal.phase === "source-archiving" || journal.phase === "support-pending" || journal.phase === "sources-archived") return {
+			ok: (await this.rollback({
+				unitId,
+				reason
+			})).ok,
+			phase: journal.phase
+		};
+		return {
+			ok: false,
+			phase: journal.phase
+		};
+	}
+};
+//#endregion
+//#region lib/types/skill-library-unit-backend.js
+function skillLibraryUnitBackend(skills) {
+	return {
+		async readSkill(name) {
+			return await skills.read(name);
+		},
+		async readSupportFile(name, path) {
+			const probe = skills.readSupportFile;
+			return typeof probe === "function" ? await probe.call(skills, name, path) : null;
+		},
+		async commit(plan, onPhase, signal, assertFence, options) {
+			const result = await skills.commitMerge({
+				...plan.runId === void 0 ? {} : { runId: plan.runId },
+				...plan.unitId === void 0 ? {} : { unitId: plan.unitId },
+				target: plan.target,
+				nested: true,
+				targetExists: plan.targetExists,
+				sources: plan.sources,
+				body: plan.body,
+				supportFiles: plan.supportFiles,
+				expectedTargetBody: plan.expectedTargetBody,
+				expectedSourceBodies: plan.expectedSourceBodies,
+				origin: plan.origin,
+				summary: plan.summary,
+				...plan.skillLimits === void 0 ? {} : { limits: plan.skillLimits },
+				...plan.targetRevision === void 0 ? {} : { targetRevision: plan.targetRevision },
+				...plan.sourceRevisions === void 0 ? {} : { sourceRevisions: plan.sourceRevisions },
+				...plan.supportDigest === void 0 ? {} : { supportDigest: plan.supportDigest },
+				...onPhase === void 0 ? {} : { onPhase },
+				...signal === void 0 ? {} : { signal },
+				...assertFence === void 0 ? {} : { assertFence }
+			}, { ...options?.serialized === void 0 ? {} : { serialized: options.serialized } });
+			return {
+				ok: result.ok,
+				message: result.message,
+				...result.code === void 0 ? {} : { code: result.code },
+				...result.archived === void 0 ? {} : { archived: result.archived },
+				...result.mutations === void 0 ? {} : { mutations: result.mutations }
+			};
+		},
+		async restoreTarget(name, body) {
+			if (body === null) {
+				await skills.archive(name, { reason: "unit-rollback" });
+				return;
+			}
+			const result = await skills.update(name, body);
+			if (!result.ok) throw new Error(result.message);
+		},
+		async restoreSupportFile(name, path, content) {
+			const result = content === null ? await skills.removeSupportFile(name, path) : await skills.writeSupportFile(name, path, content);
+			if (!result.ok) throw new Error(result.message);
+		},
+		async restoreSource(name, body) {
+			if ((await skills.restoreFromArchive(name)).ok) return;
+			const result = await skills.update(name, body);
+			if (!result.ok) throw new Error(result.message);
+		}
+	};
+}
+//#endregion
 //#region lib/types/domain/claim.js
 function acquireClaim(current, now, leaseMs, token, pid, startedAt) {
 	if (current !== void 0 && current.expiresAt > now) return void 0;
@@ -8136,7 +8885,7 @@ async function commitStagedRun(io, home, runId, port, options) {
 	let result;
 	let evidenceSha256$1;
 	let warning;
-	const transaction = options.unit ?? port.unit ?? legacyUnitAdapter(port, assembled.plan, options, runId);
+	const transaction = options.unit ?? port.unit;
 	if (transaction === void 0) return {
 		ok: false,
 		message: "commit port missing: UnitTransaction or commitMerge required",
@@ -8267,98 +9016,6 @@ async function commitStagedRun(io, home, runId, port, options) {
 		};
 	}
 }
-function legacyUnitAdapter(port, plan, options, runId) {
-	if (port.commitMerge === void 0) return void 0;
-	let evidence;
-	const unitId = "legacy:" + plan.target + ":" + String(options.now());
-	return {
-		async prepare() {
-			return {
-				ok: true,
-				prepared: {
-					unitId,
-					planDigest: unitId
-				}
-			};
-		},
-		async commit() {
-			if (port.commitMerge === void 0) return {
-				ok: false,
-				code: "unit-commit-failed",
-				message: "commitMerge missing"
-			};
-			const result = await port.commitMerge(plan);
-			if (!result.ok) return {
-				ok: false,
-				code: result.code ?? "unit-commit-failed",
-				message: result.message
-			};
-			const actualUnitId = result.unitId ?? unitId;
-			evidence = {
-				schemaVersion: 1,
-				unitId: actualUnitId,
-				runId,
-				planDigest: actualUnitId,
-				state: "complete",
-				target: {
-					before: plan.expectedTargetBody,
-					after: plan.body,
-					supportDigest: "",
-					created: !plan.targetExists
-				},
-				sources: plan.expectedSourceBodies.map((source) => ({
-					name: source.name,
-					before: source.body,
-					after: null,
-					archived: (result.archived ?? []).includes(source.name),
-					absorbedInto: plan.target
-				})),
-				mutations: result.mutations ?? 0,
-				at: options.now()
-			};
-			return {
-				ok: true,
-				evidence
-			};
-		},
-		async verify() {
-			return evidence ?? null;
-		},
-		async rollback() {
-			return {
-				ok: false,
-				code: "unit-committed",
-				message: "legacy commit cannot roll back"
-			};
-		},
-		async finalize() {
-			return evidence === void 0 ? {
-				ok: false,
-				code: "unit-plan-missing",
-				message: "legacy unit has no evidence"
-			} : {
-				ok: true,
-				evidence
-			};
-		},
-		async rollForward() {
-			return evidence === void 0 ? {
-				ok: false,
-				code: "unit-plan-missing",
-				message: "legacy unit has no evidence"
-			} : {
-				ok: true,
-				evidence
-			};
-		},
-		async cancel() {
-			return {
-				ok: false,
-				phase: "none"
-			};
-		}
-	};
-}
 //#endregion
 //#region lib/types/domain/validation-plan.js
 /** Immutable post-stage validation plan: Q09/support/threat/revision facts. */
@@ -9367,12 +10024,13 @@ async function removeRuntimeRow(io, home, id, event, unitId, fence) {
 function unitFor(deps) {
 	if (deps.unit !== void 0) return deps.unit;
 	if (!(deps.skills instanceof SkillLibrary)) return void 0;
-	return new UnitTransactions({
+	return new MergeUnitTransactions({
 		io: deps.io,
 		home: deps.home,
 		backend: skillLibraryUnitBackend(deps.skills),
 		claim: targetClaimUnitPort(deps.io, deps.home, deps.now),
-		now: deps.now
+		now: deps.now,
+		serial: async (task) => await deps.skills.runSerial(task)
 	});
 }
 function createMergeRuntime(deps) {
@@ -10778,13 +11436,14 @@ function apply(ctx, rawConfig = {}) {
 				ctx.logger.warn("merge state is not ready: " + value.code + ": " + value.message);
 				return;
 			}
-			const unit = new UnitTransactions({
+			const unit = new MergeUnitTransactions({
 				io,
 				home,
 				backend: skillLibraryUnitBackend(skills),
 				claim: targetClaimUnitPort(io, home, () => Date.now()),
 				now: () => Date.now(),
 				isActive: async (runId) => await runs.hasOwner(runId),
+				serial: async (task) => await skills.runSerial(task),
 				...mutationAuthority?.homeFence === void 0 ? {} : { fence: mutationAuthority.homeFence }
 			});
 			const cards = async () => await readSkillCards(skills);