@lmzhen/dsh-evolution-core 0.3.16 → 0.3.17

package/lib/index.js

@@ -64,45 +64,81 @@ function nodeEvolutionIo() {
 	};
 	/**
 	* Cross-process write lock (claw `withFileLock` parity): an O_EXCL lock file
-	* guards the atomic write. A >5s-old lock is taken over ONLY after probing
+	* guards the atomic write. A >1s-old lock is taken over ONLY after probing
 	* the holder pid it carries (rc.66): a LIVE holder is never stolen, so a
-	* slow writer no longer loses its lock to a peer at the 5s mark (the
+	* slow writer no longer loses its lock to a peer at the threshold (the
 	* takeover is the only best-effort surface; the retry budget fails loud —
 	* rc.65 — instead of ever proceeding unlocked). Budget = 40 * 50ms (~2s,
 	* rc.69): 8-writer contention bursts on a loaded CI runner exceed 10
 	* attempts (500ms), and a fail-loud throw was observed instead of a clean
 	* serialization.
+	* 0.3.17 (E-8): acquisition and the task are now SEPARATE try blocks — a
+	* task error (win32 rename/EBUSY surfaces as EPERM) used to be mistaken for
+	* lock contention, retried up to 40x and finally reported as
+	* "could not acquire write lock" while the real cause was hidden.
+	* 0.3.17 (E-8a): the takeover threshold (1000ms) now fits INSIDE the ~2s
+	* retry budget (budget >= 2 x threshold), so a dead holder's lock is
+	* actually recoverable within one budget instead of being arithmetically
+	* unreachable.
 	*/
 	const withWriteLock = async (path, task) => {
 		const lock = `${path}.lock`;
-		for (let attempt = 0; attempt < 40; attempt += 1) try {
-			await writeFile(lock, String(process.pid), { flag: "wx" });
+		for (let attempt = 0; attempt < 40; attempt += 1) {
 			try {
-				return await task();
-			} finally {
-				await rm(lock, { force: true }).catch(() => {});
-			}
-		} catch (error) {
-			const code = error?.code;
-			if (code !== "EEXIST" && code !== "EPERM") throw error;
-			try {
-				const st = await stat(lock);
-				if (Date.now() - st.mtimeMs > 5e3) {
-					const holder = Number(await readFile(lock, "utf8").catch(() => ""));
-					if (!(Number.isInteger(holder) && holder > 0 && isAlive(holder))) {
-						try {
-							await rm(lock, { force: true });
-						} catch {}
-						continue;
+				await writeFile(lock, String(process.pid), { flag: "wx" });
+			} catch (error) {
+				const code = error?.code;
+				if (code !== "EEXIST" && code !== "EPERM") throw error;
+				try {
+					const st = await stat(lock);
+					if (Date.now() - st.mtimeMs > 1e3) {
+						const holder = Number(await readFile(lock, "utf8").catch(() => ""));
+						if (!(Number.isInteger(holder) && holder > 0 && isAlive(holder))) {
+							try {
+								await rm(lock, { force: true });
+							} catch {}
+							continue;
+						}
 					}
+				} catch {
+					continue;
 				}
-			} catch {
+				await new Promise((resolve) => setTimeout(resolve, 50));
 				continue;
 			}
-			await new Promise((resolve) => setTimeout(resolve, 50));
+			try {
+				return await task();
+			} finally {
+				await rm(lock, { force: true }).catch(() => {});
+			}
 		}
 		throw new Error(`could not acquire write lock for ${path} after 40 attempts`);
 	};
+	/** 0.3.17 (E-8b): sweep tmp files a crashed writer left behind — same
+	* `<target>.<pid>.<rand>.tmp` shape, older than 1h AND held by a dead pid.
+	* Lazy: only the directory a write is about to touch gets swept, once per
+	* write, inside the write lock. */
+	const sweepStaleTmps = async (path) => {
+		const dir = dirname(path);
+		const base = basename(path);
+		let entries;
+		try {
+			entries = await readdir(dir);
+		} catch {
+			return;
+		}
+		const prefix = `${base}.`;
+		for (const name of entries) {
+			if (!name.startsWith(prefix) || !name.endsWith(".tmp")) continue;
+			const tmpPath = join(dir, name);
+			const holder = Number(name.slice(prefix.length, name.length - 4).split(".")[0] ?? "");
+			try {
+				const st = await stat(tmpPath);
+				const deadHolder = !Number.isInteger(holder) || holder <= 0 || !isAlive(holder);
+				if (Date.now() - st.mtimeMs > 36e5 && deadHolder) await rm(tmpPath, { force: true });
+			} catch {}
+		}
+	};
 	return {
 		async readText(path) {
 			try {
@@ -115,6 +151,7 @@ function nodeEvolutionIo() {
 		async writeText(path, content) {
 			await mkdir(dirname(path), { recursive: true });
 			await withWriteLock(path, async () => {
+				await sweepStaleTmps(path);
 				const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
 				await writeFile(tmp, content, "utf8");
 				await rename(tmp, path);
@@ -123,6 +160,7 @@ function nodeEvolutionIo() {
 		async transact(path, task) {
 			await mkdir(dirname(path), { recursive: true });
 			await withWriteLock(path, async () => {
+				await sweepStaleTmps(path);
 				let current;
 				try {
 					current = await readFile(path, "utf8");
@@ -494,6 +532,19 @@ const DEFAULT_USER_CHAR_LIMIT = 1375;
 /** Consolidation-failure backoff cap, shared by MemoryStore and memory-files' Config default. */
 const DEFAULT_CONSOLIDATION_FAILURES = 3;
 const DEFAULT_SKILL_CONTENT_CHARS = 1e5;
+/** 0.3.17 (S3.10, T-1): control-plane fields a model-facing write call may
+* never carry — single source for plan-validator, evolution-policy and the
+* threat scanner (they used to each hardcode the list). */
+const FORBIDDEN_CONTROL_KEYS = [
+	"policy",
+	"threshold",
+	"prompt_hash",
+	"model_route",
+	"evolution_config"
+];
+/** 0.3.17 (S3.10): the model-facing write tools the policy guard and threat
+* scanner cover. */
+const EVOLUTION_WRITE_TOOLS = ["memory", "skill_manage"];
 /** Hermes authoring quality bar for descriptions (the 60-char Rule). The
 * platform's own index limit stays in validateFrontmatter; this bar is the
 * target the authoring standard names, enforced as ADVISORY feedback.
@@ -2362,6 +2413,24 @@ function redactSecrets(text) {
 	return out;
 }
 //#endregion
+//#region lib/types/serial.js
+/**
+* A process-local serial task queue: each task starts only after the previous
+* one settles (success or failure), so read-modify-write sequences that share
+* one file never interleave inside this process. The durable cross-process
+* serialization layer is the IO backend's transact lock; this chain is the
+* second layer (0.3.17 S2.8, T-1: the shape was duplicated in state-json and
+* memory-files — one factory now).
+*/
+function makeSerialQueue() {
+	let chain = Promise.resolve();
+	return (task) => {
+		const run = chain.then(task, task);
+		chain = run.then(() => void 0, () => void 0);
+		return run;
+	};
+}
+//#endregion
 //#region lib/types/skill-health.js
 /**
 * Skill structure-health domain (rc.73 A1, 008 design): a SECOND assessment
@@ -4301,4 +4370,4 @@ function evolutionHome(env = process.env) {
 	return join(env.DSH_HOME || join(homedir(), ".dsh"), "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, EvolutionGateSet, 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, 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, markAgentCreated, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renderCuratorReportMarkdown, resolveOrigins, 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, 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, renderCuratorReportMarkdown, resolveOrigins, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, verifyPromptBundle, yamlPlainScalarNeedsQuotes };

package/lib/types/constants.d.ts

@@ -50,6 +50,13 @@ export declare const DEFAULT_USER_CHAR_LIMIT = 1375;
 /** Consolidation-failure backoff cap, shared by MemoryStore and memory-files' Config default. */
 export declare const DEFAULT_CONSOLIDATION_FAILURES = 3;
 export declare const DEFAULT_SKILL_CONTENT_CHARS = 100000;
+/** 0.3.17 (S3.10, T-1): control-plane fields a model-facing write call may
+ * never carry — single source for plan-validator, evolution-policy and the
+ * threat scanner (they used to each hardcode the list). */
+export declare const FORBIDDEN_CONTROL_KEYS: readonly ["policy", "threshold", "prompt_hash", "model_route", "evolution_config"];
+/** 0.3.17 (S3.10): the model-facing write tools the policy guard and threat
+ * scanner cover. */
+export declare const EVOLUTION_WRITE_TOOLS: readonly ["memory", "skill_manage"];
 /** Hermes authoring quality bar for descriptions (the 60-char Rule). The
  * platform's own index limit stays in validateFrontmatter; this bar is the
  * target the authoring standard names, enforced as ADVISORY feedback.

package/lib/types/index.d.ts

@@ -19,6 +19,7 @@ export * from './preset-composition.ts';
 export * from './prompts.ts';
 export * from './quality.ts';
 export * from './redact.ts';
+export * from './serial.ts';
 export * from './skill-health.ts';
 export * from './signals.ts';
 export * from './drift-signals.ts';

package/lib/types/serial.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A process-local serial task queue: each task starts only after the previous
+ * one settles (success or failure), so read-modify-write sequences that share
+ * one file never interleave inside this process. The durable cross-process
+ * serialization layer is the IO backend's transact lock; this chain is the
+ * second layer (0.3.17 S2.8, T-1: the shape was duplicated in state-json and
+ * memory-files — one factory now).
+ */
+export declare function makeSerialQueue(): <T>(task: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=serial.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.16",
+  "version": "0.3.17",
   "publishConfig": {
     "access": "public"
   },