@lmzhen/dsh-evolution-curator 0.3.81 → 0.3.83

package/README.md

@@ -1,4 +1,4 @@
-# @deepseek-ai/dsh-evolution-curator
+# @lmzhen/dsh-evolution-curator
 
 Deterministic skill lifecycle and recovery
 
@@ -8,7 +8,7 @@ Deterministic skill lifecycle and recovery
 
 #### What the model sees
 
-`@deepseek-ai/dsh-evolution-curator` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
+`@lmzhen/dsh-evolution-curator` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
 
 #### Token effect
 

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_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_MODEL, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MIN_IDLE_HOURS, DEFAULT_STALE_AFTER_DAYS, EvolutionGateSet, INSTANCE_KEYS, MAX_TIMER_DELAY_MS, SKILL_NAME_RE, buildCuratorRunReport, claimInstance, clampedNumber, computeDedupGroups, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, emptyRecord, evolutionHome, evolutionIoAdapter, foldCuratorFields, isPresent, isUnknown, loadSuppressedNames, loadUsage, markerEntryName, mutateUsage, newSkillLibrary, parseCuratorNominations, parseFrontmatter, probeList, probeMtime, relatedSkillNames, releaseInstance, renderCuratorReportMarkdown, 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_MODEL, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MIN_IDLE_HOURS, DEFAULT_STALE_AFTER_DAYS, EvolutionGateSet, INSTANCE_KEYS, MAX_TIMER_DELAY_MS, SKILL_NAME_RE, buildCuratorRunReport, claimInstance, clampedNumber, computeDedupGroups, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, emptyRecord, evolutionHome, evolutionIoAdapter, foldCuratorFields, isPresent, isUnknown, loadSuppressedNames, loadUsage, markerEntryName, mutateUsage, newSkillLibrary, parseCuratorNominations, parseFrontmatter, probeList, probeMtime, relatedSkillNames, releaseInstance, renderCuratorReportMarkdown, transactIo, updateSuppressedNames, usageObserved } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Deterministic skill lifecycle curator with interval gate and archive.
@@ -96,7 +96,9 @@ var EvolutionCurator = class extends Service {
 	/** P2-5 (v14): one-shot warning that the interval baseline is process-only. */
 	statelessStateWarned = false;
 	/** B3 / G4: the home this instance claimed, plus whether the claim was
-	* granted. A non-owning instance schedules nothing and runs nothing. */
+	* granted. A non-owning instance schedules nothing and runs nothing. The
+	* claim is PER PROCESS (v43 FLOW2-1): another process's holder is invisible
+	* here, so `holdsInstance` never proves this instance is alone on the home. */
 	instanceHome = "";
 	holdsInstance = false;
 	/** B3 / G4: this instance's identity in the claim — pid + short token, so the
@@ -114,7 +116,7 @@ var EvolutionCurator = class extends Service {
 		this.instanceHome = evolutionHome();
 		const claim = claimInstance(this.instanceHome, INSTANCE_KEYS.curator, this.instanceOwner);
 		this.holdsInstance = claim.granted;
-		if (!claim.granted) this.ctx.logger.warn(`evolution-curator: this instance YIELDS — ${claim.key} is already held by ${claim.holder}; a second curator over one home would race the report retention sweep. It schedules nothing and every run() returns skipped "instance-held".`);
+		if (!claim.granted) this.ctx.logger.warn(`evolution-curator: this instance YIELDS — ${claim.key} is already held by ${claim.holder} IN THIS PROCESS (the claim is a module-scope Map, so it does not exclude another process); a second curator ROW over one home would run a second gate set and a second lifecycle pass over the same tree. It schedules nothing and every run() returns skipped "instance-held"; the report sweep itself is cross-process locked (v43 FLOW2-1).`);
 		const clamped = [];
 		const field = (name, value, fallback, min, max) => {
 			const result = clampedNumber(value, fallback, max === void 0 ? { min } : {
@@ -353,6 +355,7 @@ var EvolutionCurator = class extends Service {
 	async restoreSnapshot() {
 		const release = await this.acquireMutex();
 		try {
+			if (!this.holdsInstance) return this.instanceHeldRefusal("restoreSnapshot");
 			return await this.restoreSnapshotCore();
 		} finally {
 			release();
@@ -466,6 +469,27 @@ var EvolutionCurator = class extends Service {
 		};
 		return prev.then(() => release);
 	}
+	/**
+	* PLAN S4.5 (2026-09-16) (audit P2-16): the manual control-plane entries
+	* (restore/consolidate/restoreSnapshot) honor the same per-home instance
+	* claim `run()` checks before every pass. The claim is taken at MOUNT and
+	* released at DISPOSE (core/instance-scope.ts), so `holdsInstance` is
+	* stable for this instance's lifetime: a single-instance deployment always
+	* holds it and every manual entry behaves exactly as before. The refusal
+	* fires only on a YIELDING second row of one process, whose manual mutation
+	* would otherwise race the holder row's in-flight run over the same tree —
+	* this instance's control-plane mutex cannot see the holder's chain. The
+	* shape is the plain `SkillActionResult` failure the command face already
+	* renders through `err(result.message)` — no new error type — and the
+	* leading `instance-held` token names the same outcome run() reports via
+	* its `skipped` field.
+	*/
+	instanceHeldRefusal(operation) {
+		return {
+			ok: false,
+			message: `instance-held: this curator row yielded the per-home claim to another curator row of this process — ${operation} is refused alongside run() so the holder row stays the only control-plane writer (run it on the holder row)`
+		};
+	}
 	async runCore(options = {}) {
 		const { ignoreGates = false, dryRun = false } = options;
 		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -496,13 +520,13 @@ var EvolutionCurator = class extends Service {
 		};
 		if (!ignoreGates && persisted === null && (stateService !== void 0 || !this.statelessFirstRunDeferred)) {
 			if (stateService) try {
-				await stateService.saveCuratorState({
+				await stateService.transactCuratorState((current) => current === null ? {
 					schemaVersion: 1,
 					lastRunAt: Date.now(),
 					runCount: 0,
 					lastSummary: "first-run-deferred",
 					paused: false
-				});
+				} : null);
 			} catch (error) {
 				this.ctx.logger.warn(`evolution-curator: failed to persist the first-run baseline: ${error instanceof Error ? error.message : String(error)}`);
 			}
@@ -545,7 +569,7 @@ var EvolutionCurator = class extends Service {
 			if (text) contents.set(name, text);
 		}
 		const protectedNames = await this.protectedNameMap();
-		const dedupMembers = [...new Set(computeDedupGroups({ contents }).filter((group) => group.length >= 2).flat())].filter((name) => !protectedNames.has(name));
+		const dedupMembers = [...new Set(computeDedupGroups({ contents }).groups.filter((group) => group.length >= 2).flat())].filter((name) => !protectedNames.has(name));
 		await this.scoreTree(usage, treeNames, contents);
 		const result = computeLifecycleTransitions(usage, {
 			staleAfterDays: lifecycle.staleAfterDays,
@@ -934,8 +958,26 @@ var EvolutionCurator = class extends Service {
 	* (`curator-error-*.json`) are BUDGETED INDEPENDENTLY. Before this they shared
 	* one keep-20 window, so after 25 consecutive failures the next successful
 	* run's window held only a few real reports alongside the errors.
+	*
+	* v43 FLOW2-1 (P1): the sweep runs inside the IO backend's cross-process write
+	* lock. The inventory used to declare this site as serialized by the per-home
+	* instance claim, which is a module-scope Map (core/instance-scope.ts): a
+	* second ROW of this process yields, but a second PROCESS over the same home
+	* was never excluded — and "list the directory, then delete beyond the window"
+	* is exactly the multi-step shape that needs a real lock. A backend without
+	* `transact` has no lock at all: the sweep then degrades to the previous
+	* best-effort pass, which is safe because every deletion is idempotent and
+	* each report name is unique per runId.
 	*/
 	async retainReports(keep = 20, errorKeep = 10) {
+		await transactIo(this.io, reportsSweepLockTarget(), async () => {
+			await this.sweepReports(keep, errorKeep);
+			return null;
+		});
+	}
+	/** The sweep `retainReports` holds the per-home lock for. A caller MUST hold
+	* that lock: the listing and the deletions are not atomic on their own. */
+	async sweepReports(keep, errorKeep) {
 		const reportsRoot = join(evolutionHome(), "reports");
 		const listed = await probeList(this.io, reportsRoot);
 		if (isUnknown(listed)) {
@@ -1091,6 +1133,7 @@ var EvolutionCurator = class extends Service {
 	async consolidate(target, sources) {
 		const release = await this.acquireMutex();
 		try {
+			if (!this.holdsInstance) return this.instanceHeldRefusal("consolidate");
 			return await this.consolidateMutate(target, sources);
 		} finally {
 			release();
@@ -1135,6 +1178,7 @@ var EvolutionCurator = class extends Service {
 	async restore(name) {
 		const release = await this.acquireMutex();
 		try {
+			if (!this.holdsInstance) return this.instanceHeldRefusal("restore");
 			return await this.restoreMutate(name);
 		} finally {
 			release();
@@ -1167,5 +1211,17 @@ var EvolutionCurator = class extends Service {
 		return result;
 	}
 };
+/**
+* v43 FLOW2-1: the per-home lock target for the report retention sweep.
+* `transactIo` takes the IO write lock on THIS path (minting `<path>.lock` with
+* the io protocol's `pid:token` body) and holds it for the whole task; nothing
+* ever writes the target, because the sweep's exclusion is the point. It lives
+* inside `<home>/reports` next to the directory it protects: the sweep's own
+* name filter (`curator-*.json`) ignores it, and the lock file is removed on
+* release.
+*/
+function reportsSweepLockTarget() {
+	return join(evolutionHome(), "reports", ".retention");
+}
 //#endregion
 export { EvolutionCurator, EvolutionCurator as default, gateConsolidations };

package/lib/types/index.d.ts

@@ -131,7 +131,9 @@ export declare class EvolutionCurator extends Service {
     /** P2-5 (v14): one-shot warning that the interval baseline is process-only. */
     private statelessStateWarned;
     /** B3 / G4: the home this instance claimed, plus whether the claim was
-     * granted. A non-owning instance schedules nothing and runs nothing. */
+     * granted. A non-owning instance schedules nothing and runs nothing. The
+     * claim is PER PROCESS (v43 FLOW2-1): another process's holder is invisible
+     * here, so `holdsInstance` never proves this instance is alone on the home. */
     private instanceHome;
     private holdsInstance;
     /** B3 / G4: this instance's identity in the claim — pid + short token, so the
@@ -241,6 +243,22 @@ export declare class EvolutionCurator extends Service {
     private mutexDepth;
     private mutexTail;
     private acquireMutex;
+    /**
+     * PLAN S4.5 (2026-09-16) (audit P2-16): the manual control-plane entries
+     * (restore/consolidate/restoreSnapshot) honor the same per-home instance
+     * claim `run()` checks before every pass. The claim is taken at MOUNT and
+     * released at DISPOSE (core/instance-scope.ts), so `holdsInstance` is
+     * stable for this instance's lifetime: a single-instance deployment always
+     * holds it and every manual entry behaves exactly as before. The refusal
+     * fires only on a YIELDING second row of one process, whose manual mutation
+     * would otherwise race the holder row's in-flight run over the same tree —
+     * this instance's control-plane mutex cannot see the holder's chain. The
+     * shape is the plain `SkillActionResult` failure the command face already
+     * renders through `err(result.message)` — no new error type — and the
+     * leading `instance-held` token names the same outcome run() reports via
+     * its `skipped` field.
+     */
+    private instanceHeldRefusal;
     private runCore;
     /**
      * Seed baseline records for tree skills the sidecar has not seen yet, so
@@ -283,8 +301,21 @@ export declare class EvolutionCurator extends Service {
      * (`curator-error-*.json`) are BUDGETED INDEPENDENTLY. Before this they shared
      * one keep-20 window, so after 25 consecutive failures the next successful
      * run's window held only a few real reports alongside the errors.
+     *
+     * v43 FLOW2-1 (P1): the sweep runs inside the IO backend's cross-process write
+     * lock. The inventory used to declare this site as serialized by the per-home
+     * instance claim, which is a module-scope Map (core/instance-scope.ts): a
+     * second ROW of this process yields, but a second PROCESS over the same home
+     * was never excluded — and "list the directory, then delete beyond the window"
+     * is exactly the multi-step shape that needs a real lock. A backend without
+     * `transact` has no lock at all: the sweep then degrades to the previous
+     * best-effort pass, which is safe because every deletion is idempotent and
+     * each report name is unique per runId.
      */
     private retainReports;
+    /** The sweep `retainReports` holds the per-home lock for. A caller MUST hold
+     * that lock: the listing and the deletions are not atomic on their own. */
+    private sweepReports;
     /** Remove the oldest reports beyond `keep` (each with its `.md` digest, best-effort). */
     private pruneReportList;
     latestReport(): Promise<CuratorRunReport | null>;

package/package.json

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