@lmzhen/dsh-evolution-core 0.1.0-rc.49 → 0.1.0-rc.50

package/lib/index.js

@@ -1,5 +1,5 @@
 import { basename, dirname, join } from "node:path";
-import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createHash, randomBytes } from "node:crypto";
 import { homedir } from "node:os";
 import { readFileSync } from "node:fs";
@@ -11,6 +11,20 @@ import { readFileSync } from "node:fs";
 * Native DSH packages pass `ctx.evolutionIo.provider()`; standalone consumers
 * (and the facade's own tests) can use `nodeEvolutionIo`.
 */
+/**
+* Run `task` inside `io.transact` when the backend provides it; otherwise fall
+* back to a plain read → task → write/remove sequence (no cross-process lock —
+* callers keep their single-process serialize chain as the second layer).
+*/
+async function transactIo(io, path, task) {
+	if (io.transact) {
+		await io.transact(path, task);
+		return;
+	}
+	const next = await task(await io.readText(path));
+	if (next === null) await io.remove(path);
+	else await io.writeText(path, next);
+}
 /** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
 function evolutionIoAdapter(provider) {
 	return {
@@ -24,6 +38,14 @@ function evolutionIoAdapter(provider) {
 		size: (path) => {
 			const io = provider();
 			return io.size ? io.size(path) : Promise.resolve(null);
+		},
+		transact: (path, task) => {
+			const io = provider();
+			return io.transact ? io.transact(path, task) : transactIo(io, path, task);
+		},
+		isSymlink: (path) => {
+			const io = provider();
+			return io.isSymlink ? io.isSymlink(path) : Promise.resolve(null);
 		}
 	};
 }
@@ -82,6 +104,26 @@ function nodeEvolutionIo() {
 				await rename(tmp, path);
 			});
 		},
+		async transact(path, task) {
+			await mkdir(dirname(path), { recursive: true });
+			await withWriteLock(path, async () => {
+				let current;
+				try {
+					current = await readFile(path, "utf8");
+				} catch (error) {
+					if (isMissing(error)) current = null;
+					else throw error;
+				}
+				const next = await task(current);
+				if (next === null) {
+					await rm(path, { force: true });
+					return;
+				}
+				const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+				await writeFile(tmp, next, "utf8");
+				await rename(tmp, path);
+			});
+		},
 		async remove(path) {
 			await rm(path, {
 				recursive: true,
@@ -91,8 +133,9 @@ function nodeEvolutionIo() {
 		async list(path) {
 			try {
 				return await readdir(path);
-			} catch {
-				return [];
+			} catch (error) {
+				if (isMissing(error)) return [];
+				throw error;
 			}
 		},
 		async exists(path) {
@@ -122,6 +165,13 @@ function nodeEvolutionIo() {
 				if (isMissing(error)) return null;
 				throw error;
 			}
+		},
+		async isSymlink(path) {
+			try {
+				return (await lstat(path)).isSymbolicLink();
+			} catch {
+				return null;
+			}
 		}
 	};
 }
@@ -181,15 +231,33 @@ function normalizeUsageRecord(record) {
 		quality_warn: typeof raw.quality_warn === "boolean" ? raw.quality_warn : void 0
 	};
 }
-async function loadUsage(root, io = nodeEvolutionIo()) {
+/** Parse a raw usage sidecar; malformed content reads as empty (best-effort telemetry). */
+function parseUsage(raw) {
 	const map = /* @__PURE__ */ new Map();
-	const raw = await io.readText(usageFile(root));
-	if (raw !== null) try {
+	if (raw === null) return map;
+	try {
 		const parsed = JSON.parse(raw);
 		for (const [name, record] of Object.entries(parsed)) map.set(name, normalizeUsageRecord(record));
 	} catch {}
 	return map;
 }
+async function loadUsage(root, io = nodeEvolutionIo()) {
+	return parseUsage(await io.readText(usageFile(root)));
+}
+/**
+* Atomic read-modify-write on the usage sidecar (rc.50 P2-2): `task` receives
+* the map parsed from the current on-disk state and may mutate it; the result
+* is persisted inside the same transact so a second process sharing DSH_HOME
+* cannot interleave its RMW and lose a counter update. Callers keep their own
+* single-process serialize chain as the second layer.
+*/
+async function mutateUsage(root, io, task) {
+	await transactIo(io, usageFile(root), async (current) => {
+		const map = parseUsage(current);
+		await task(map);
+		return JSON.stringify(Object.fromEntries(map.entries()), null, 2);
+	});
+}
 async function saveUsage(root, map, io = nodeEvolutionIo()) {
 	const obj = Object.fromEntries(map.entries());
 	await io.writeText(usageFile(root), JSON.stringify(obj, null, 2));
@@ -240,7 +308,9 @@ function suppressedFile(root) {
 	return join(root, ".curator-suppressed.json");
 }
 async function loadSuppressedNames(root, io = nodeEvolutionIo()) {
-	const raw = await io.readText(suppressedFile(root));
+	return parseSuppressed(await io.readText(suppressedFile(root)));
+}
+function parseSuppressed(raw) {
 	if (raw === null) return /* @__PURE__ */ new Set();
 	try {
 		const parsed = JSON.parse(raw);
@@ -256,6 +326,22 @@ async function saveSuppressedNames(root, names, io = nodeEvolutionIo()) {
 		names: [...names].sort()
 	}, null, 2));
 }
+/**
+* Atomic read-modify-write on the suppression sidecar (rc.50 P2-2): `task`
+* receives the set parsed from the current on-disk state and may mutate it;
+* the result is persisted inside the same transact so a second process
+* sharing DSH_HOME cannot interleave its RMW. Best-effort posture unchanged.
+*/
+async function updateSuppressedNames(root, io, task) {
+	await transactIo(io, suppressedFile(root), async (current) => {
+		const names = parseSuppressed(current);
+		await task(names);
+		return JSON.stringify({
+			version: 1,
+			names: [...names].sort()
+		}, null, 2);
+	});
+}
 //#endregion
 //#region lib/types/constants.js
 /**
@@ -1487,8 +1573,13 @@ function mutationsFile(root) {
 function contentHash(content) {
 	return createHash("sha256").update(content).digest("hex");
 }
-async function loadMutations(root, io = nodeEvolutionIo()) {
-	const raw = await io.readText(mutationsFile(root));
+/**
+* Parse a raw mutations sidecar; malformed content reads as empty (auditing is
+* best-effort). Versioned shape ({ version, records }) with legacy
+* plain-array compat, plus a field-level guard for records without the
+* required identity/timestamp fields (rc.42 audit P2-3).
+*/
+function parseMutationRecords(raw) {
 	if (raw === null) return [];
 	try {
 		const parsed = JSON.parse(raw);
@@ -1497,15 +1588,20 @@ async function loadMutations(root, io = nodeEvolutionIo()) {
 		return [];
 	}
 }
+async function loadMutations(root, io = nodeEvolutionIo()) {
+	return parseMutationRecords(await io.readText(mutationsFile(root)));
+}
 /** Append one record, trim to `cap`, and write atomically (versioned shape). */
 async function recordMutation(root, io, record, cap = 500) {
-	const existing = await loadMutations(root, io);
-	existing.push(record);
-	const trimmed = existing.length > cap ? existing.slice(existing.length - cap) : existing;
-	await io.writeText(mutationsFile(root), JSON.stringify({
-		version: 1,
-		records: trimmed
-	}, null, 2));
+	await transactIo(io, mutationsFile(root), (current) => {
+		const existing = parseMutationRecords(current);
+		existing.push(record);
+		const trimmed = existing.length > cap ? existing.slice(existing.length - cap) : existing;
+		return Promise.resolve(JSON.stringify({
+			version: 1,
+			records: trimmed
+		}, null, 2));
+	});
 }
 //#endregion
 //#region lib/types/quality.js
@@ -2286,6 +2382,12 @@ var SkillLibrary = class {
 			const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/g, "").slice(0, 14);
 			dest = join(archiveRoot, `${name.trim()}-${stamp}`);
 		}
+		if (this.io.isSymlink) {
+			if (await this.io.isSymlink(dir) === true) return {
+				ok: false,
+				message: `Skill "${name}" is a symlink; refusing to archive it.`
+			};
+		}
 		try {
 			await this.io.rename(dir, dest);
 		} catch {
@@ -2422,6 +2524,12 @@ var SkillLibrary = class {
 		};
 		const source = join(archiveRoot, chosen);
 		const dest = this.dirOf(name);
+		if (this.io.isSymlink) {
+			if (await this.io.isSymlink(source) === true) return {
+				ok: false,
+				message: `Archived entry "${chosen}" is a symlink; refusing to restore it.`
+			};
+		}
 		try {
 			await this.io.rename(source, dest);
 		} catch {
@@ -2648,7 +2756,16 @@ var SkillLibrary = class {
 			message: "No skill snapshot available."
 		};
 		await this.snapshotAll("pre-rollback", extras);
-		for (const name of await listNames(this.root, this.io)) await this.io.remove(this.dirOf(name));
+		let rootEntries;
+		try {
+			rootEntries = await this.io.list(this.root);
+		} catch {
+			rootEntries = [];
+		}
+		for (const entry of rootEntries) {
+			if (entry.startsWith(".")) continue;
+			await this.io.remove(join(this.root, entry));
+		}
 		const manifest = await this.readSnapshotManifest(latest.path);
 		if (manifest === null) for (const entry of await this.io.list(latest.path)) {
 			if (entry === "manifest.json" || entry === "extras") continue;
@@ -2742,4 +2859,4 @@ var JsonState = class JsonState {
 	}
 };
 //#endregion
-export { 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_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, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EvolutionGateSet, JsonState, LOW_QUALITY_THRESHOLD, MAX_DESCRIPTION_LENGTH, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computeQualityScores, computeScopeView, contentHash, createGateSet, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, lifecycleCandidate, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, mutationsFile, nodeEvolutionIo, normalizeUsageRecord, observeEvent, parseCuratorNominations, parseFrontmatter, recordMutation, relatedSkillNames, renderCuratorReportMarkdown, resolveOrigins, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, usageFile, validateFrontmatter, verifyPromptBundle };
+export { 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_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, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EvolutionGateSet, JsonState, LOW_QUALITY_THRESHOLD, MAX_DESCRIPTION_LENGTH, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computeQualityScores, computeScopeView, contentHash, createGateSet, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, lifecycleCandidate, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, mutateUsage, mutationsFile, nodeEvolutionIo, normalizeUsageRecord, observeEvent, parseCuratorNominations, parseFrontmatter, recordMutation, relatedSkillNames, renderCuratorReportMarkdown, resolveOrigins, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, validateFrontmatter, verifyPromptBundle };

package/lib/types/io.d.ts

@@ -20,7 +20,28 @@ export interface EvolutionIoLike {
      * consumers treat an unknown size as "guard not applicable".
      */
     size?(path: string): Promise<number | null>;
+    /**
+     * Optional atomic read-modify-write on one file: the read and the write run
+     * inside a single cross-process lock, so two processes that share DSH_HOME
+     * cannot interleave their RMW sequences. `task` receives the current content
+     * (`null` when missing) and returns the next content; returning `null`
+     * deletes the file. A backend without it falls back to plain read+write and
+     * the caller keeps its single-process chain as the second layer.
+     */
+    transact?(this: void, path: string, task: (current: string | null) => Promise<string | null>): Promise<void>;
+    /**
+     * Optional symlink probe (G7). `true` = the path is a symlink, `false` = a
+     * real entry, `null` = guard not applicable (backend without the probe or
+     * the path does not exist). Consumers treat `null` as "let it through".
+     */
+    isSymlink?(this: void, path: string): Promise<boolean | null>;
 }
+/**
+ * Run `task` inside `io.transact` when the backend provides it; otherwise fall
+ * back to a plain read → task → write/remove sequence (no cross-process lock —
+ * callers keep their single-process serialize chain as the second layer).
+ */
+export declare function transactIo(io: EvolutionIoLike, path: string, task: (current: string | null) => Promise<string | null>): Promise<void>;
 /** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
 export declare function evolutionIoAdapter(provider: () => EvolutionIoLike): EvolutionIoLike;
 export declare function nodeEvolutionIo(): EvolutionIoLike;

package/lib/types/usage.d.ts

@@ -33,6 +33,14 @@ export declare function emptyRecord(): UsageRecord;
  */
 export declare function normalizeUsageRecord(record: unknown): UsageRecord;
 export declare function loadUsage(root: string, io?: EvolutionIoLike): Promise<UsageMap>;
+/**
+ * Atomic read-modify-write on the usage sidecar (rc.50 P2-2): `task` receives
+ * the map parsed from the current on-disk state and may mutate it; the result
+ * is persisted inside the same transact so a second process sharing DSH_HOME
+ * cannot interleave its RMW and lose a counter update. Callers keep their own
+ * single-process serialize chain as the second layer.
+ */
+export declare function mutateUsage(root: string, io: EvolutionIoLike, task: (map: UsageMap) => void | Promise<void>): Promise<void>;
 export declare function saveUsage(root: string, map: UsageMap, io?: EvolutionIoLike): Promise<void>;
 export declare function getRecord(map: UsageMap, name: string): UsageRecord;
 export declare function bumpView(map: UsageMap, name: string, when?: Date): void;
@@ -50,4 +58,11 @@ export declare const SUPPRESSED_FILE_VERSION = 1;
 export declare function suppressedFile(root: string): string;
 export declare function loadSuppressedNames(root: string, io?: EvolutionIoLike): Promise<ReadonlySet<string>>;
 export declare function saveSuppressedNames(root: string, names: ReadonlySet<string>, io?: EvolutionIoLike): Promise<void>;
+/**
+ * Atomic read-modify-write on the suppression sidecar (rc.50 P2-2): `task`
+ * receives the set parsed from the current on-disk state and may mutate it;
+ * the result is persisted inside the same transact so a second process
+ * sharing DSH_HOME cannot interleave its RMW. Best-effort posture unchanged.
+ */
+export declare function updateSuppressedNames(root: string, io: EvolutionIoLike, task: (names: Set<string>) => void | Promise<void>): Promise<void>;
 //# sourceMappingURL=usage.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.1.0-rc.49",
+  "version": "0.1.0-rc.50",
   "publishConfig": {
     "access": "public"
   },