@lmzhen/dsh-evolution-curator 0.3.61 → 0.3.63

package/lib/index.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
 import z from "@deepseek-ai/schemastery";
-import { CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MIN_IDLE_HOURS, DEFAULT_STALE_AFTER_DAYS, EvolutionGateSet, SKILL_NAME_RE, SkillLibrary, buildCuratorRunReport, clampedNumber, computeDedupGroups, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, emptyRecord, evolutionHome, evolutionIoAdapter, foldCuratorFields, loadSuppressedNames, loadUsage, markerEntryName, mutateUsage, parseCuratorNominations, parseFrontmatter, relatedSkillNames, renderCuratorReportMarkdown, resolveSkillsRoot, updateSuppressedNames, usageObserved } from "@lmzhen/dsh-evolution-core";
+import { CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MIN_IDLE_HOURS, DEFAULT_STALE_AFTER_DAYS, EvolutionGateSet, SKILL_NAME_RE, SkillLibrary, buildCuratorRunReport, clampedNumber, computeDedupGroups, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, emptyRecord, evolutionHome, evolutionIoAdapter, foldCuratorFields, loadSuppressedNames, loadUsage, markerEntryName, mutateUsage, parseCuratorNominations, parseFrontmatter, relatedSkillNames, renderCuratorReportMarkdown, resolveSkillsRoot, updateSuppressedNames, usageObserved } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Deterministic skill lifecycle curator with interval gate and archive.
@@ -39,8 +39,8 @@ var EvolutionCurator = class extends Service {
 		pruneBuiltins: z.boolean().default(false),
 		referencedSkillNames: z.array(z.string()).default([]),
 		autoStart: z.boolean().default(true),
-		bootGraceSeconds: z.number().min(0).default(10),
-		curatorReviewMaxTokens: z.number().min(1).default(2048),
+		bootGraceSeconds: z.number().min(0).default(DEFAULT_CURATOR_BOOT_GRACE_SECONDS),
+		curatorReviewMaxTokens: z.number().min(1).default(DEFAULT_CURATOR_REVIEW_MAX_TOKENS),
 		healthSoftBodyChars: z.number().min(1).default(DEFAULT_HEALTH_THRESHOLDS.softBodyChars),
 		healthStampDensityPerKb: z.number().min(1).default(DEFAULT_HEALTH_THRESHOLDS.stampDensityPerKb),
 		healthChurnMinPatches: z.number().min(1).default(DEFAULT_HEALTH_THRESHOLDS.churnMinPatches)
@@ -68,11 +68,12 @@ var EvolutionCurator = class extends Service {
 	lastRun = 0;
 	timer;
 	bootCheck;
-	running = false;
 	/** 0.3.18 (E-18): stateless first-run defer fires ONCE per process — the
 	* in-memory clock is seeded and later due runs must proceed, or the
 	* persisted===null defer repeats forever (no state service to persist). */
 	statelessFirstRunDeferred = false;
+	/** P2-5 (v14): one-shot warning that the interval baseline is process-only. */
+	statelessStateWarned = false;
 	constructor(ctx, config = {}) {
 		super(ctx, "evolutionCurator");
 		this.io = evolutionIoAdapter(() => ctx.evolutionIo.provider());
@@ -81,8 +82,11 @@ var EvolutionCurator = class extends Service {
 		});
 		this.enabled = config.enabled ?? true;
 		const clamped = [];
-		const field = (name, value, fallback, min) => {
-			const result = clampedNumber(value, fallback, { min });
+		const field = (name, value, fallback, min, max) => {
+			const result = clampedNumber(value, fallback, max === void 0 ? { min } : {
+				min,
+				max
+			});
 			if (value !== void 0 && result !== value) clamped.push(name);
 			return result;
 		};
@@ -98,8 +102,8 @@ var EvolutionCurator = class extends Service {
 		this.manageUnmanaged = config.manageUnmanaged ?? false;
 		this.pruneBuiltins = config.pruneBuiltins ?? false;
 		this.referencedSkillNames = new Set(config.referencedSkillNames ?? []);
-		this.bootGraceSeconds = field("bootGraceSeconds", config.bootGraceSeconds, 10, 0);
-		this.curatorReviewMaxTokens = field("curatorReviewMaxTokens", config.curatorReviewMaxTokens, 2048, 1);
+		this.bootGraceSeconds = field("bootGraceSeconds", config.bootGraceSeconds, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, 0, 3600);
+		this.curatorReviewMaxTokens = field("curatorReviewMaxTokens", config.curatorReviewMaxTokens, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, 1);
 		this.healthSoftBodyChars = field("healthSoftBodyChars", config.healthSoftBodyChars, DEFAULT_HEALTH_THRESHOLDS.softBodyChars, 1);
 		this.healthStampDensityPerKb = field("healthStampDensityPerKb", config.healthStampDensityPerKb, DEFAULT_HEALTH_THRESHOLDS.stampDensityPerKb, 1);
 		this.healthChurnMinPatches = field("healthChurnMinPatches", config.healthChurnMinPatches, DEFAULT_HEALTH_THRESHOLDS.churnMinPatches, 1);
@@ -171,10 +175,21 @@ var EvolutionCurator = class extends Service {
 	* HERE as a cheap pre-check (persisted or in-memory clock) AND again inside
 	* run() as the authoritative gate — the docstring no longer claims the two
 	* never duplicate; a future interval change must update both.
+	*
+	* P2-5 (v14): without the `evolution-state` service there is no durable
+	* `lastRunAt`, so the baseline degrades to this process's lifetime. That is
+	* a supported-but-degraded composition (every shipped bundle mounts the
+	* state rows), so the schedule is left as-is and the degradation is
+	* surfaced once instead of silently meaning "never runs".
 	*/
 	async autoCheck() {
 		try {
-			const last = (await this.curatorStateService()?.loadCuratorState())?.lastRunAt ?? this.lastRun;
+			const stateService = this.curatorStateService();
+			if (stateService === void 0 && !this.statelessStateWarned) {
+				this.statelessStateWarned = true;
+				this.ctx.logger.warn(`evolution-curator: evolution-state is not mounted — the curation interval baseline is this process's lifetime only (default interval ${DEFAULT_CURATOR_INTERVAL_HOURS}h), so automatic curation will not fire again until the process has been alive that long. Mount evolution-state (evolution-host/all bundle) for a durable schedule.`);
+			}
+			const last = (await stateService?.loadCuratorState())?.lastRunAt ?? this.lastRun;
 			if (Date.now() - last >= this.lifecycle().intervalHours * 36e5) await this.run();
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
@@ -319,18 +334,18 @@ var EvolutionCurator = class extends Service {
 	* skipped with an explicit `already-running` outcome.
 	*/
 	async run(options = {}) {
-		if (this.running) return {
+		if (this.mutexDepth > 0) return {
 			stale: [],
 			archived: [],
 			errors: [],
 			report: this.skippedReport("already-running", (/* @__PURE__ */ new Date()).toISOString()),
 			skipped: "already-running"
 		};
-		this.running = true;
+		const release = await this.acquireMutex();
 		try {
 			return await this.runCore(options);
 		} finally {
-			this.running = false;
+			release();
 			try {
 				await this.retainReports();
 			} catch (error) {
@@ -338,6 +353,36 @@ var EvolutionCurator = class extends Service {
 			}
 		}
 	}
+	/**
+	* P1 (v16): the control-plane mutex — ONE promise chain serializing run(),
+	* restore() and consolidate(). Replaces the v15 draft (`running` flag +
+	* `runSettled` polling), which could (a) spin forever on an
+	* already-resolved promise while a control-plane mutator held the flag
+	* (micro-task starvation: the flag's reset lives behind IO the spun loop
+	* never lets run) and (b) let two queued waiters wake into the same idle
+	* window and mutate concurrently. Here the chain IS the mutex: an entrant
+	* increments `mutexDepth` synchronously (so run()'s skip check sees queued
+	* work), awaits the previous tail, and the returned release resolves the
+	* tail for the next entrant. Double-release is a no-op.
+	*/
+	mutexDepth = 0;
+	mutexTail = Promise.resolve();
+	acquireMutex() {
+		this.mutexDepth += 1;
+		const prev = this.mutexTail;
+		let releaseMutex;
+		this.mutexTail = new Promise((resolve) => {
+			releaseMutex = resolve;
+		});
+		let released = false;
+		const release = () => {
+			if (released) return;
+			released = true;
+			this.mutexDepth -= 1;
+			releaseMutex();
+		};
+		return prev.then(() => release);
+	}
 	async runCore(options = {}) {
 		const { ignoreGates = false, dryRun = false } = options;
 		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -472,16 +517,20 @@ var EvolutionCurator = class extends Service {
 		}
 		const llmHint = !this.llmReview && result.markStale.length > 0 ? " (llmReview: off - deterministic archive only; set llmReview: true for the LLM merge channel)" : "";
 		const summary = `${dryRun ? "dry-run" : "auto"}: stale:${result.markStale.length} archived:${archivedSkills.length} consolidated:${gatedNominations.consolidations.length}${llmHint}`;
-		await stateService?.transactCuratorState((current) => {
-			const pausedNow = current?.paused ?? false;
-			return {
-				schemaVersion: 1,
-				lastRunAt: dryRun ? persisted?.lastRunAt ?? this.lastRun : Date.now(),
-				runCount: dryRun ? persisted?.runCount ?? 0 : (current?.runCount ?? 0) + 1,
-				lastSummary: summary,
-				paused: pausedNow
-			};
-		});
+		try {
+			await stateService?.transactCuratorState((current) => {
+				const pausedNow = current?.paused ?? false;
+				return {
+					schemaVersion: 1,
+					lastRunAt: dryRun ? persisted?.lastRunAt ?? this.lastRun : Date.now(),
+					runCount: dryRun ? persisted?.runCount ?? 0 : (current?.runCount ?? 0) + 1,
+					lastSummary: summary,
+					paused: pausedNow
+				};
+			});
+		} catch (error) {
+			this.ctx.logger.warn(`evolution-curator: failed to persist run bookkeeping: ${error instanceof Error ? error.message : String(error)}`);
+		}
 		return {
 			stale: result.markStale,
 			archived: archivedSkills.map((item) => item.name),
@@ -513,6 +562,11 @@ var EvolutionCurator = class extends Service {
 	}
 	/**
 	* F13 six-factor quality scoring, persisted onto the usage records.
+	* P1-1 (v15): these are the CURATOR-owned fields (`quality_score`/
+	* `quality_warn`) — this method must never touch the feedback-owned
+	* `feedback_*` pair (the lifecycle engine reads the union of both warn
+	* flags, so overwriting feedback here is what used to make negative
+	* feedback decision-irrelevant; field ownership on `UsageRecord`).
 	*/
 	async scoreTree(usage, treeNames) {
 		const supportDirs = /* @__PURE__ */ new Map();
@@ -846,6 +900,14 @@ var EvolutionCurator = class extends Service {
 	* records into `archived` state. Snapshot-then-mutate, never a hard delete.
 	*/
 	async consolidate(target, sources) {
+		const release = await this.acquireMutex();
+		try {
+			return await this.consolidateMutate(target, sources);
+		} finally {
+			release();
+		}
+	}
+	async consolidateMutate(target, sources) {
 		const suppressedNames = new Set(await loadSuppressedNames(this.skills.root, this.io));
 		const gates = new EvolutionGateSet({
 			exclude: this.excludeSkillNames,
@@ -876,6 +938,14 @@ var EvolutionCurator = class extends Service {
 	* and reset its usage state, keeping the recoverable-archive invariant.
 	*/
 	async restore(name) {
+		const release = await this.acquireMutex();
+		try {
+			return await this.restoreMutate(name);
+		} finally {
+			release();
+		}
+	}
+	async restoreMutate(name) {
 		await this.snapshotFull("pre-restore");
 		const result = await this.skills.restoreFromArchive(name);
 		if (!result.ok) return result;

package/lib/types/index.d.ts

@@ -110,11 +110,12 @@ export declare class EvolutionCurator extends Service {
     private lastRun;
     private timer;
     private bootCheck;
-    private running;
     /** 0.3.18 (E-18): stateless first-run defer fires ONCE per process — the
      * in-memory clock is seeded and later due runs must proceed, or the
      * persisted===null defer repeats forever (no state service to persist). */
     private statelessFirstRunDeferred;
+    /** P2-5 (v14): one-shot warning that the interval baseline is process-only. */
+    private statelessStateWarned;
     constructor(ctx: Context, config?: Config);
     private lifecycle;
     start(): void;
@@ -139,6 +140,12 @@ export declare class EvolutionCurator extends Service {
      * HERE as a cheap pre-check (persisted or in-memory clock) AND again inside
      * run() as the authoritative gate — the docstring no longer claims the two
      * never duplicate; a future interval change must update both.
+     *
+     * P2-5 (v14): without the `evolution-state` service there is no durable
+     * `lastRunAt`, so the baseline degrades to this process's lifetime. That is
+     * a supported-but-degraded composition (every shipped bundle mounts the
+     * state rows), so the schedule is left as-is and the degradation is
+     * surfaced once instead of silently meaning "never runs".
      */
     private autoCheck;
     /**
@@ -184,6 +191,21 @@ export declare class EvolutionCurator extends Service {
         ignoreGates?: boolean;
         dryRun?: boolean;
     }): Promise<CuratorRunOutcome>;
+    /**
+     * P1 (v16): the control-plane mutex — ONE promise chain serializing run(),
+     * restore() and consolidate(). Replaces the v15 draft (`running` flag +
+     * `runSettled` polling), which could (a) spin forever on an
+     * already-resolved promise while a control-plane mutator held the flag
+     * (micro-task starvation: the flag's reset lives behind IO the spun loop
+     * never lets run) and (b) let two queued waiters wake into the same idle
+     * window and mutate concurrently. Here the chain IS the mutex: an entrant
+     * increments `mutexDepth` synchronously (so run()'s skip check sees queued
+     * work), awaits the previous tail, and the returned release resolves the
+     * tail for the next entrant. Double-release is a no-op.
+     */
+    private mutexDepth;
+    private mutexTail;
+    private acquireMutex;
     private runCore;
     /**
      * Seed baseline records for tree skills the sidecar has not seen yet, so
@@ -194,6 +216,11 @@ export declare class EvolutionCurator extends Service {
     private seedBaseline;
     /**
      * F13 six-factor quality scoring, persisted onto the usage records.
+     * P1-1 (v15): these are the CURATOR-owned fields (`quality_score`/
+     * `quality_warn`) — this method must never touch the feedback-owned
+     * `feedback_*` pair (the lifecycle engine reads the union of both warn
+     * flags, so overwriting feedback here is what used to make negative
+     * feedback decision-irrelevant; field ownership on `UsageRecord`).
      */
     private scoreTree;
     /**
@@ -254,11 +281,13 @@ export declare class EvolutionCurator extends Service {
      * records into `archived` state. Snapshot-then-mutate, never a hard delete.
      */
     consolidate(target: string, sources: string[]): Promise<SkillActionResult>;
+    private consolidateMutate;
     /**
      * Control-plane restore: bring one archived skill back to the active root
      * and reset its usage state, keeping the recoverable-archive invariant.
      */
     restore(name: string): Promise<SkillActionResult>;
+    private restoreMutate;
 }
 export default EvolutionCurator;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-curator",
   "description": "Deterministic skill lifecycle and recovery (community build)",
-  "version": "0.3.61",
+  "version": "0.3.63",
   "publishConfig": {
     "access": "public"
   },
@@ -31,20 +31,20 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.61"
+    "@lmzhen/dsh-evolution-core": "^0.3.63"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.3.61",
-    "@lmzhen/dsh-evolution-state": "^0.3.61"
+    "@lmzhen/dsh-evolution-io": "^0.3.63",
+    "@lmzhen/dsh-evolution-state": "^0.3.63"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-core": "^0.3.61",
-    "@lmzhen/dsh-evolution-io": "^0.3.61",
-    "@lmzhen/dsh-evolution-state": "^0.3.61"
+    "@lmzhen/dsh-evolution-core": "^0.3.63",
+    "@lmzhen/dsh-evolution-io": "^0.3.63",
+    "@lmzhen/dsh-evolution-state": "^0.3.63"
   }
 }