@lmzhen/dsh-evolution-core 0.3.21 → 0.3.22

package/README.md

@@ -18,6 +18,26 @@ Zero direct token effect from this package; consumers add any model-visible toke
 
 Independent of request-prefix construction. This package does not alter the assembled prompt or tool list.
 
+## SkillLibrary concurrency model
+
+Skill-library mutations are read-modify-write on one file, so `SkillLibrary`
+serializes them in-process with a `makeSerialQueue` chain: `update`, `patch`,
+`restructure` and `writeSupportFile` run their whole read→validate→write under
+one serial task, so two concurrent mutators on one skill never interleave in
+this process. Single-file writes (`update`, `patch`, `writeSupportFile`)
+additionally run the read and the write inside `transactIo` when a caller
+injects a `transact` into the constructor — that is the cross-process lock, so
+two processes sharing `DSH_HOME` cannot interleave their RMW on one file.
+`create` writes a new file and `archive`/`consolidate` already own a two-phase
+commit, so they deliberately stay outside the serial chain.
+
+When no `transact` is injected (the current default callers), only the
+in-process serial chain protects the RMW; same-skill concurrent writes from
+different surfaces (foreground `skill_manage`, the review pipeline, the
+curator, `/evolution restructure`) still resolve **last writer wins**. Wire a
+`transact` at every SkillLibrary instantiation point to extend that guarantee
+across processes.
+
 ## Known Limitations and Deferred Work
 
 - This package is a library, not a Cordis row; do not mount it as a plugin.

package/lib/index.js

@@ -942,6 +942,13 @@ function isEventRecord(event) {
 * rebuildable, NOT malformed) or a corrupt one reads as empty; corrupt content
 * is still refused on append, never overwritten.
 *
+* This reader is **v1-only** (F-338): a body carrying a `version` other than
+* `EVENT_LOG_VERSION` is a future-format log this reader cannot interpret, so
+* it reads as an EMPTY timeline rather than being mis-parsed as v1. The read
+* side never overwrites it on its own — `appendEvolutionEvent` rejects a
+* version mismatch up front and preserves the original bytes, so a newer log
+* is never silently downgraded here.
+*
 * Per-entry normalization (rc.70 F-1): entries without a numeric `seq` are
 * skipped here and dropped at the next append — valid entries survive, the
 * damaged record is the only loss (self-heal semantics, matching the usage
@@ -951,6 +958,7 @@ function parseEvolutionEvents(raw) {
 	if (raw === null || raw.trim() === "") return [];
 	try {
 		const parsed = JSON.parse(raw);
+		if (parsed.version !== void 0 && parsed.version !== 1) return [];
 		if (!Array.isArray(parsed.events)) return [];
 		return parsed.events.filter(isEventRecord);
 	} catch {
@@ -989,11 +997,19 @@ async function listEventArchives(io, path) {
 */
 async function appendEvolutionEvent(io, path, event, rotateAt = EVENT_LOG_ROTATE_AT) {
 	let assigned = 0;
+	let refuseMessage = "";
 	await transactIo(io, path, async (current) => {
-		if (current !== null && current.trim() !== "") try {
-			JSON.parse(current);
-		} catch {
-			return current;
+		if (current !== null && current.trim() !== "") {
+			let shape;
+			try {
+				shape = JSON.parse(current);
+			} catch {
+				return current;
+			}
+			if (shape.version !== void 0 && shape.version !== 1) {
+				refuseMessage = `evolution event log version mismatch (found ${typeof shape.version === "number" || typeof shape.version === "string" ? String(shape.version) : "unknown"}, expected 1) and was not touched`;
+				return current;
+			}
 		}
 		const nextEvents = await rotateIfDue(io, path, parseEvolutionEvents(current), rotateAt);
 		let maxSeq = nextEvents.reduce((max, entry) => Math.max(max, entry.seq), 0);
@@ -1009,7 +1025,7 @@ async function appendEvolutionEvent(io, path, event, rotateAt = EVENT_LOG_ROTATE
 			events: [...nextEvents, record]
 		}, null, 2);
 	});
-	if (assigned === 0) throw new Error(`evolution event log is malformed and was not touched: ${path}`);
+	if (assigned === 0) throw new Error(`${refuseMessage || "evolution event log is malformed and was not touched"}: ${path}`);
 	return assigned;
 }
 /**
@@ -1049,7 +1065,10 @@ async function retainEventArchives(io, path) {
 	for (const name of excess) await io.remove(join(dir, name)).catch(() => {});
 }
 /** Read the event log; a missing/whitespace-only file reads as empty,
-* corrupt content is flagged (and refused on append). */
+* corrupt content is flagged (and refused on append). A well-formed future-
+* version body is v1-incompatible and reads as empty, NOT malformed (F-338:
+* the reader must never mis-shape a newer format; the append path refuses it
+* up front so the original bytes survive). */
 async function readEvolutionEvents(io, path) {
 	let raw;
 	try {
@@ -1066,6 +1085,10 @@ async function readEvolutionEvents(io, path) {
 	};
 	try {
 		const parsed = JSON.parse(raw);
+		if (parsed.version !== void 0 && parsed.version !== 1) return {
+			events: [],
+			malformed: false
+		};
 		if (!Array.isArray(parsed.events)) return {
 			events: [],
 			malformed: false
@@ -1810,6 +1833,14 @@ function render(entries) {
 function stripDatePrefix(entry) {
 	return entry.replace(/^## \d{4}-\d{2}-\d{2}\n/, "");
 }
+/** F-201: does `content` carry the on-disk entry delimiter or a trailing
+* `\n§` fragment that would combine with the render terminator into a real
+* delimiter boundary? Both split the fact into multiple entries on read-back
+* (and a delimiter-ending fact is permanent drift — `render(entries)!==raw`
+* bricks every later write). A leading/plain `§` is safe and round-trips. */
+function hasEntryDelimiter(content) {
+	return content.includes("\n§\n") || content.endsWith("\n§");
+}
 var MemoryStore = class {
 	memoryLimit;
 	userLimit;
@@ -1976,6 +2007,16 @@ var MemoryStore = class {
 			},
 			write: null
 		};
+		if (hasEntryDelimiter(content)) return {
+			result: {
+				ok: false,
+				message: "Operation 1 (add): Fact contains the entry delimiter (§) and would split into multiple entries; rewrite it as separate facts.",
+				entries: [],
+				chars: 0,
+				limit: this.limitFor(target)
+			},
+			write: null
+		};
 		const entries = [...new Set(normalizeEntries(raw))];
 		if (entries.some((entry) => stripDatePrefix(entry) === content)) {
 			this.resetFailures();
@@ -2078,6 +2119,16 @@ var MemoryStore = class {
 					},
 					write: null
 				};
+				if (hasEntryDelimiter(body)) return {
+					result: {
+						ok: false,
+						message: `Operation ${position} (add): Fact contains the entry delimiter (§) and would split into multiple entries; rewrite it as separate facts.`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
+				};
 				if (!working.some((entry) => stripDatePrefix(entry) === body)) working.push(this.addDatePrefix ? `## ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}\n${body}` : body);
 				continue;
 			}
@@ -2135,6 +2186,16 @@ var MemoryStore = class {
 					},
 					write: null
 				};
+				if (hasEntryDelimiter(body)) return {
+					result: {
+						ok: false,
+						message: `Operation ${position} (replace): Fact contains the entry delimiter (§) and would split into multiple entries; rewrite it as separate facts.`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
+				};
 				working[matchIndex] = body;
 			}
 		}
@@ -2829,7 +2890,9 @@ function skillsRoot(env = process.env) {
 * the skills tree — tool-skill-manage / evolution-skill-catalog / skill-usage
 * / evolution-learning-graph used to each resolve `config.root || skillsRoot()`
 * (and the graph ignored config entirely). Empty/whitespace config falls
-* through to the default; callers pass their raw Config. */
+* through to the default; callers pass their raw Config. The optional field is
+* declared `| undefined` so a config object whose root field is explicitly
+* `string | undefined` still assignable under exactOptionalPropertyTypes. */
 function resolveSkillsRoot(config = {}) {
 	return (config.root ?? "").trim() || skillsRoot();
 }
@@ -3176,15 +3239,9 @@ function fuzzyPatch(content, oldString, newString, replaceAll = false) {
 	const boundary = trimPatternBoundaries(oldString);
 	if (boundary === "") return null;
 	if (boundary !== oldString) {
-		if (fuzzyIndexOf(content, boundary) !== null) {
-			const patched = fuzzyReplace(content, boundary, newString, replaceAll);
-			return patched === content ? null : patched;
-		}
-	}
-	if (fuzzyIndexOf(content, oldString) !== null) {
-		const patched = fuzzyReplace(content, oldString, newString, replaceAll);
-		return patched === content ? null : patched;
+		if (fuzzyIndexOf(content, boundary) !== null) return fuzzyReplace(content, boundary, newString, replaceAll);
 	}
+	if (fuzzyIndexOf(content, oldString) !== null) return fuzzyReplace(content, oldString, newString, replaceAll);
 	return null;
 }
 /**
@@ -3255,11 +3312,47 @@ var SkillLibrary = class {
 	limits;
 	io;
 	onMutation;
-	constructor(root = skillsRoot(), io = nodeEvolutionIo(), limits = DEFAULT_SKILL_LIMITS, onMutation) {
+	/** 0.3.21 (F-208): optional cross-process RMW transactor injected by callers.
+	* When unset each single-file write falls back to read→task→write. */
+	transact;
+	/** 0.3.21 (F-208): in-process serialize queue so two concurrent mutators on
+	* one skill never interleave their read-modify-write (the cross-process layer
+	* is the IO backend's transact lock; this chain is the second layer). */
+	serial;
+	constructor(root = skillsRoot(), io = nodeEvolutionIo(), limits = DEFAULT_SKILL_LIMITS, onMutation, transact) {
 		this.root = root;
 		this.io = io;
 		this.limits = limits;
 		this.onMutation = onMutation;
+		this.transact = transact;
+		this.serial = makeSerialQueue();
+	}
+	/**
+	* Run one single-file read-modify-write for a mutator. When `transact` was
+	* injected the read and the write run inside it (cross-process atomicity);
+	* otherwise a plain read → task → write sequence runs (the process-level
+	* `serial` chain is the second layer). `task` receives the current content
+	* (null when missing) and returns a {@link SingleWriteOutcome}. Audit and the
+	* mutation event are issued ONLY when a write actually lands, so a no-op
+	* never inflates the mutation-maturity counter.
+	*/
+	async runSingleWrite(path, task) {
+		let outcome;
+		const run = async (current) => {
+			const o = await task(current ?? null);
+			outcome = o;
+			return o.write ?? current ?? null;
+		};
+		if (this.transact) await this.transact(this.io, path, run);
+		else {
+			const current = await this.io.readText(path);
+			const next = await run(current);
+			if (next !== null && next !== current) await this.io.writeText(path, next);
+		}
+		const o = outcome;
+		if (o.write !== null && o.audit) await this.audit(o.audit.skillName, o.audit.action, o.audit.before, o.audit.after, o.audit.summary);
+		if (o.write !== null && o.event) this.notifyMutation(o.event);
+		return o.result;
 	}
 	/** Notify the mutation observer after a successful write; observers must never fail the mutation. */
 	notifyMutation(event) {
@@ -3516,9 +3609,10 @@ var SkillLibrary = class {
 			ok: false,
 			message: `Skill "${normalized}" already exists.`
 		};
-		await this.io.writeText(join(dir, "SKILL.md"), finalContent.trimEnd() + "\n");
+		const onDisk = finalContent.trimEnd() + "\n";
+		await this.io.writeText(join(dir, "SKILL.md"), onDisk);
 		if (origin !== "foreground") await this.io.writeText(markerPath(dir, "hermes-managed"), "");
-		await this.audit(normalized, "create", null, finalContent, "created");
+		await this.audit(normalized, "create", null, onDisk, "created");
 		this.notifyMutation({
 			action: "create",
 			name: normalized,
@@ -3533,17 +3627,16 @@ var SkillLibrary = class {
 	}
 	async update(rawName, content, origin = "foreground") {
 		const name = rawName.trim();
+		return await this.serial(() => this.updateCore(name, content, origin));
+	}
+	async updateCore(name, content, origin) {
+		const dir = this.dirOf(name);
+		const path = join(dir, "SKILL.md");
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
 			message: badName
 		};
-		const dir = this.dirOf(name);
-		const md = await this.io.readText(join(dir, "SKILL.md"));
-		if (!md) return {
-			ok: false,
-			message: `Skill "${name}" not found.`
-		};
 		const protection = await this.writeProtection(name, origin);
 		if (protection) return {
 			ok: false,
@@ -3572,27 +3665,52 @@ var SkillLibrary = class {
 			ok: false,
 			message: threat
 		};
-		await this.io.writeText(join(dir, "SKILL.md"), finalContent.trimEnd() + "\n");
-		await this.audit(name, "update", md, finalContent, "updated");
-		this.notifyMutation({
-			action: "update",
-			name,
-			skillDir: dir
+		return await this.runSingleWrite(path, (current) => {
+			if (current === null) return {
+				result: {
+					ok: false,
+					message: `Skill "${name}" not found.`
+				},
+				write: null
+			};
+			if (finalContent.trimEnd() === current.trimEnd()) return {
+				result: {
+					ok: true,
+					message: `Skill "${name}" unchanged: the supplied content already matches the current file; nothing written.`,
+					noop: true,
+					path: dir
+				},
+				write: null
+			};
+			const onDisk = finalContent.trimEnd() + "\n";
+			return {
+				result: {
+					ok: true,
+					message: `Skill "${name}" updated.`,
+					path: dir,
+					...norm.changed ? { normalizedFrontmatterFields: norm.fields } : {}
+				},
+				write: onDisk,
+				audit: {
+					skillName: name,
+					action: "update",
+					before: current,
+					after: onDisk,
+					summary: "updated"
+				},
+				event: {
+					action: "update",
+					name,
+					skillDir: dir
+				}
+			};
 		});
-		return {
-			ok: true,
-			message: `Skill "${name}" updated.`,
-			path: dir,
-			...norm.changed ? { normalizedFrontmatterFields: norm.fields } : {}
-		};
 	}
 	async patch(rawName, oldString, newString, filePath = "", replaceAll = false, origin = "foreground") {
 		const name = rawName.trim();
-		const badName = this.badName(name);
-		if (badName) return {
-			ok: false,
-			message: badName
-		};
+		return await this.serial(() => this.patchCore(name, oldString, newString, filePath, replaceAll, origin));
+	}
+	async patchCore(name, oldString, newString, filePath, replaceAll, origin) {
 		const dir = this.dirOf(name);
 		const skillMd = join(dir, "SKILL.md");
 		if (!await this.io.exists(skillMd)) return {
@@ -3615,71 +3733,109 @@ var SkillLibrary = class {
 			target = join(dir, ...filePath.replace(/\\/g, "/").split("/").filter(Boolean));
 			patchLabel = filePath;
 		}
-		const md = await this.io.readText(target);
-		if (!md) return {
-			ok: false,
-			message: `File not found: ${patchLabel}`
-		};
-		const patched = fuzzyPatch(md, oldString, newString, replaceAll);
-		if (patched === null) return {
-			ok: false,
-			message: `Could not find old_string in "${name}/${patchLabel}". Use update for a full rewrite.`
-		};
-		let writeContent = patched;
-		let normalizedFields;
-		if (target === skillMd) {
-			const validation = validateFrontmatter(patched, name, this.limits);
-			if (validation) return {
-				ok: false,
-				message: `Patch rejected: ${validation}`
-			};
-			const norm = normalizeFrontmatter(patched);
-			if (norm.issues.length > 0) return {
-				ok: false,
-				message: `Patch rejected: frontmatter cannot be auto-fixed (${norm.issues[0]}).`
+		return await this.runSingleWrite(target, (current) => {
+			const md = current;
+			if (md === null) return {
+				result: {
+					ok: false,
+					message: `File not found: ${patchLabel}`
+				},
+				write: null
 			};
-			if (norm.changed) {
-				writeContent = norm.content;
-				normalizedFields = norm.fields;
-				const revalidated = validateFrontmatter(writeContent, name, this.limits);
-				if (revalidated) return {
+			const patched = fuzzyPatch(md, oldString, newString, replaceAll);
+			if (patched === null) return {
+				result: {
 					ok: false,
-					message: `Patch rejected: ${revalidated}`
+					message: `Could not find old_string in "${name}/${patchLabel}". Use update for a full rewrite.`
+				},
+				write: null
+			};
+			let writeContent = patched;
+			let normalizedFields;
+			if (target === skillMd) {
+				const validation = validateFrontmatter(patched, name, this.limits);
+				if (validation) return {
+					result: {
+						ok: false,
+						message: `Patch rejected: ${validation}`
+					},
+					write: null
 				};
+				const norm = normalizeFrontmatter(patched);
+				if (norm.issues.length > 0) return {
+					result: {
+						ok: false,
+						message: `Patch rejected: frontmatter cannot be auto-fixed (${norm.issues[0]}).`
+					},
+					write: null
+				};
+				if (norm.changed) {
+					writeContent = norm.content;
+					normalizedFields = norm.fields;
+					const revalidated = validateFrontmatter(writeContent, name, this.limits);
+					if (revalidated) return {
+						result: {
+							ok: false,
+							message: `Patch rejected: ${revalidated}`
+						},
+						write: null
+					};
+				}
 			}
-		}
-		if (Buffer.byteLength(writeContent, "utf8") > this.limits.maxSkillFileBytes && target !== skillMd) return {
-			ok: false,
-			message: `Patched file exceeds ${this.limits.maxSkillFileBytes} bytes.`
-		};
-		if (writeContent.length > this.limits.maxSkillContentChars && target === skillMd) return {
-			ok: false,
-			message: `Patched content exceeds ${this.limits.maxSkillContentChars} characters. Consider splitting into a smaller SKILL.md with supporting files.`
-		};
-		const threat = scanContentThreats(writeContent);
-		if (threat) return {
-			ok: false,
-			message: threat
-		};
-		if (writeContent.trimEnd() + "\n" === md) return {
-			ok: true,
-			message: `Skill "${name}" unchanged: old_string already equals the replacement (${patchLabel}); nothing written.`,
-			noop: true,
-			path: dir
-		};
-		await this.io.writeText(target, writeContent.trimEnd() + "\n");
-		await this.audit(name, "patch", md, writeContent, `patched ${patchLabel}`);
-		this.notifyMutation({
-			action: "patch",
-			name,
-			skillDir: dir
+			if (Buffer.byteLength(writeContent, "utf8") > this.limits.maxSkillFileBytes && target !== skillMd) return {
+				result: {
+					ok: false,
+					message: `Patched file exceeds ${this.limits.maxSkillFileBytes} bytes.`
+				},
+				write: null
+			};
+			if (writeContent.length > this.limits.maxSkillContentChars && target === skillMd) return {
+				result: {
+					ok: false,
+					message: `Patched content exceeds ${this.limits.maxSkillContentChars} characters. Consider splitting into a smaller SKILL.md with supporting files.`
+				},
+				write: null
+			};
+			const threat = scanContentThreats(writeContent);
+			if (threat) return {
+				result: {
+					ok: false,
+					message: threat
+				},
+				write: null
+			};
+			if (writeContent.trimEnd() === md.trimEnd()) return {
+				result: {
+					ok: true,
+					message: `Skill "${name}" unchanged: old_string already equals the replacement (${patchLabel}); nothing written.`,
+					noop: true,
+					path: dir
+				},
+				write: null
+			};
+			const onDisk = writeContent.trimEnd() + "\n";
+			return {
+				result: {
+					ok: true,
+					message: `Skill "${name}" patched (${patchLabel}).`,
+					path: dir,
+					...normalizedFields ? { normalizedFrontmatterFields: normalizedFields } : {}
+				},
+				write: onDisk,
+				audit: {
+					skillName: name,
+					action: "patch",
+					before: md,
+					after: onDisk,
+					summary: `patched ${patchLabel}`
+				},
+				event: {
+					action: "patch",
+					name,
+					skillDir: dir
+				}
+			};
 		});
-		return {
-			ok: true,
-			message: `Skill "${name}" patched (${patchLabel}).`,
-			path: dir,
-			...normalizedFields ? { normalizedFrontmatterFields: normalizedFields } : {}
-		};
 	}
 	async archive(rawName, options = {}) {
 		const name = rawName.trim();
@@ -3933,6 +4089,9 @@ var SkillLibrary = class {
 	*/
 	async restructure(rawName, moves, origin = "foreground") {
 		const name = rawName.trim();
+		return await this.serial(() => this.restructureCore(name, moves, origin));
+	}
+	async restructureCore(name, moves, origin) {
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
@@ -4181,12 +4340,15 @@ var SkillLibrary = class {
 	}
 	async writeSupportFile(rawName, filePath, content, origin = "foreground") {
 		const name = rawName.trim();
+		return await this.serial(() => this.writeSupportFileCore(name, filePath, content, origin));
+	}
+	async writeSupportFileCore(name, filePath, content, origin) {
+		const dir = this.dirOf(name);
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
 			message: badName
 		};
-		const dir = this.dirOf(name);
 		if (!await this.io.exists(join(dir, "SKILL.md"))) return {
 			ok: false,
 			message: `Skill "${name}" not found.`
@@ -4211,20 +4373,29 @@ var SkillLibrary = class {
 			message: threat
 		};
 		const target = join(dir, ...filePath.replace(/\\/g, "/").split("/").filter(Boolean));
-		const existing = await this.io.readText(target).catch(() => null);
-		await this.io.writeText(target, content);
-		await this.audit(name, "write_file", existing, content, `wrote ${filePath}`);
-		this.notifyMutation({
-			action: "write_file",
-			name,
-			skillDir: dir,
-			file: target
+		return await this.runSingleWrite(target, (current) => {
+			return {
+				result: {
+					ok: true,
+					message: `Support file "${filePath}" written to "${name}".`,
+					path: target
+				},
+				write: content,
+				audit: {
+					skillName: name,
+					action: "write_file",
+					before: current,
+					after: content,
+					summary: `wrote ${filePath}`
+				},
+				event: {
+					action: "write_file",
+					name,
+					skillDir: dir,
+					file: target
+				}
+			};
 		});
-		return {
-			ok: true,
-			message: `Support file "${filePath}" written to "${name}".`,
-			path: target
-		};
 	}
 	async removeSupportFile(rawName, filePath, origin = "foreground") {
 		const name = rawName.trim();
@@ -4457,8 +4628,18 @@ var SkillLibrary = class {
 * Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
 * state (reports, activity store, feedback file, state-domain data).
 */
+/**
+* DSH home root: `$DSH_HOME` or `~/.dsh`. Single source of the empty-string
+* fallback (`||`, not `??`) — an EMPTY DSH_HOME resolves to the default home,
+* never to a CWD-relative path (0.3.19 W1.3, 0.3.22 F-207).
+*/
+function evolutionRoot(env = process.env) {
+	return env.DSH_HOME || join(homedir(), ".dsh");
+}
+/** Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
+* state (reports, activity store, feedback file, state-domain data). */
 function evolutionHome(env = process.env) {
-	return join(env.DSH_HOME || join(homedir(), ".dsh"), "evolution");
+	return join(evolutionRoot(env), "evolution");
 }
 //#endregion
-export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, LOW_QUALITY_THRESHOLD, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, appendEvolutionEvent, applyCuratorFields, applyCuratorLifecycleFields, applyCuratorMetaFields, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionHome, evolutionIoAdapter, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterYamlUnsafeValues, getRecord, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, markAgentCreated, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, verifyPromptBundle, yamlPlainScalarNeedsQuotes };
+export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, LOW_QUALITY_THRESHOLD, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, appendEvolutionEvent, applyCuratorFields, applyCuratorLifecycleFields, applyCuratorMetaFields, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterYamlUnsafeValues, getRecord, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, markAgentCreated, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, verifyPromptBundle, yamlPlainScalarNeedsQuotes };

package/lib/types/evolution-events.d.ts

@@ -73,6 +73,13 @@ export declare function eventsFile(home: string): string;
  * rebuildable, NOT malformed) or a corrupt one reads as empty; corrupt content
  * is still refused on append, never overwritten.
  *
+ * This reader is **v1-only** (F-338): a body carrying a `version` other than
+ * `EVENT_LOG_VERSION` is a future-format log this reader cannot interpret, so
+ * it reads as an EMPTY timeline rather than being mis-parsed as v1. The read
+ * side never overwrites it on its own — `appendEvolutionEvent` rejects a
+ * version mismatch up front and preserves the original bytes, so a newer log
+ * is never silently downgraded here.
+ *
  * Per-entry normalization (rc.70 F-1): entries without a numeric `seq` are
  * skipped here and dropped at the next append — valid entries survive, the
  * damaged record is the only loss (self-heal semantics, matching the usage
@@ -124,7 +131,10 @@ export interface EventLogRead {
     malformed: boolean;
 }
 /** Read the event log; a missing/whitespace-only file reads as empty,
- * corrupt content is flagged (and refused on append). */
+ * corrupt content is flagged (and refused on append). A well-formed future-
+ * version body is v1-incompatible and reads as empty, NOT malformed (F-338:
+ * the reader must never mis-shape a newer format; the append path refuses it
+ * up front so the original bytes survive). */
 export declare function readEvolutionEvents(io: EvolutionIoLike, path: string): Promise<EventLogRead>;
 /**
  * Read the full timeline (rc.71): active log + all archives, merged by seq

package/lib/types/skill-store.d.ts

@@ -6,7 +6,7 @@
  * it created unless a `.hermes-managed` marker opts a skill in. Archival is a
  * move to `.archive/` — never a hard delete.
  */
-import { type EvolutionIoLike } from './io.ts';
+import { transactIo, type EvolutionIoLike } from './io.ts';
 import { type MutationRecord } from './mutations.ts';
 import { type SkillHealthAssessment, type SkillHealthThresholds } from './skill-health.ts';
 import type { EvolutionSkillMutatedEvent } from './events.ts';
@@ -88,9 +88,11 @@ export declare function skillsRoot(env?: NodeJS.ProcessEnv): string;
  * the skills tree — tool-skill-manage / evolution-skill-catalog / skill-usage
  * / evolution-learning-graph used to each resolve `config.root || skillsRoot()`
  * (and the graph ignored config entirely). Empty/whitespace config falls
- * through to the default; callers pass their raw Config. */
+ * through to the default; callers pass their raw Config. The optional field is
+ * declared `| undefined` so a config object whose root field is explicitly
+ * `string | undefined` still assignable under exactOptionalPropertyTypes. */
 export declare function resolveSkillsRoot(config?: {
-    root?: string;
+    root?: string | undefined;
 }): string;
 /**
  * Map a requesting session onto the two origin surfaces (rc.44 plan M2-2.3):
@@ -212,7 +214,24 @@ export declare class SkillLibrary {
     readonly limits: SkillLimits;
     private readonly io;
     private readonly onMutation;
-    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void);
+    /** 0.3.21 (F-208): optional cross-process RMW transactor injected by callers.
+     * When unset each single-file write falls back to read→task→write. */
+    private readonly transact;
+    /** 0.3.21 (F-208): in-process serialize queue so two concurrent mutators on
+     * one skill never interleave their read-modify-write (the cross-process layer
+     * is the IO backend's transact lock; this chain is the second layer). */
+    private readonly serial;
+    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void, transact?: typeof transactIo);
+    /**
+     * Run one single-file read-modify-write for a mutator. When `transact` was
+     * injected the read and the write run inside it (cross-process atomicity);
+     * otherwise a plain read → task → write sequence runs (the process-level
+     * `serial` chain is the second layer). `task` receives the current content
+     * (null when missing) and returns a {@link SingleWriteOutcome}. Audit and the
+     * mutation event are issued ONLY when a write actually lands, so a no-op
+     * never inflates the mutation-maturity counter.
+     */
+    private runSingleWrite;
     /** Notify the mutation observer after a successful write; observers must never fail the mutation. */
     private notifyMutation;
     list(): Promise<SkillSummary[]>;
@@ -271,7 +290,9 @@ export declare class SkillLibrary {
     setPinned(name: string, pinned: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
     create(name: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     update(rawName: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    private updateCore;
     patch(rawName: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
+    private patchCore;
     archive(rawName: string, options?: ArchiveOptions): Promise<SkillActionResult>;
     /**
      * Merge the bodies of `sources` into `target` and archive the sources with
@@ -307,6 +328,7 @@ export declare class SkillLibrary {
      * same package; the moved text belongs in references/ beside them).
      */
     restructure(rawName: string, moves: SkillRestructureMove[], origin?: WriteOrigin): Promise<SkillActionResult>;
+    private restructureCore;
     /**
      * Unified tree-change commit point (009 kernel): owns validation order,
      * pre-read rollback bytes, two-phase write with byte-level rollback, audit
@@ -322,6 +344,7 @@ export declare class SkillLibrary {
      */
     restoreFromArchive(rawName: string): Promise<SkillActionResult>;
     writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    private writeSupportFileCore;
     removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     /**
      * Snapshot the recoverable skills state: active tree, usage/suppression

package/lib/types/state-store.d.ts

@@ -2,5 +2,13 @@
  * Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
  * state (reports, activity store, feedback file, state-domain data).
  */
+/**
+ * DSH home root: `$DSH_HOME` or `~/.dsh`. Single source of the empty-string
+ * fallback (`||`, not `??`) — an EMPTY DSH_HOME resolves to the default home,
+ * never to a CWD-relative path (0.3.19 W1.3, 0.3.22 F-207).
+ */
+export declare function evolutionRoot(env?: NodeJS.ProcessEnv): string;
+/** Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
+ * state (reports, activity store, feedback file, state-domain data). */
 export declare function evolutionHome(env?: NodeJS.ProcessEnv): string;
 //# sourceMappingURL=state-store.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.3.21",
+  "version": "0.3.22",
   "publishConfig": {
     "access": "public"
   },