@lmzhen/dsh-evolution-curator 0.3.82 → 0.4.0

package/README.md

@@ -1,32 +1,19 @@
-# @deepseek-ai/dsh-evolution-curator
+# @lmzhen/dsh-evolution-curator
 
 Deterministic skill lifecycle and recovery
 
-## Model Experience
+## Model surface
 
-### Indirect model surface
-
-#### 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.
-
-#### Token effect
-
-Zero direct token effect from this package; consumers add any model-visible tokens.
-
-#### KV Cache effect
-
-Independent of request-prefix construction. This package does not alter the assembled prompt or tool list.
-
-## Known Limitations and Deferred Work
+- **Model-visible:** nothing of its own: it registers no prompt section and no tool schema; the packages that consume this service own the model-visible effects.
+- **Prompt prefix / KV cache:** independent of request-prefix construction — it does not alter the assembled prompt or tool list; family-level rules: `packages/README.md` §"Model-visible prompt prefix and the KV cache".
+- **Mount it?** yes — the `evolution-curator` row, carried by the `evolution-host`, `evolution-all` and one-click `evolution-preset` bundles; it provides the `evolutionCurator` service the `/evolution curator …` commands and doctor read.
 
+## Known limitations
 
 - LLM nomination pass is advisory and disabled by default; deterministic lifecycle remains authoritative.
 - Consolidation is a REAL merger path: the LLM nomination (when enabled / via `recommend()`) proposes
-  merge groups, the control plane gates them and applies the mutation — merged source bodies are appended
-  verbatim rather than rewritten into a synthesized skill. The one-click `/evolution consolidate
-  <target> <source...>` remains the direct manual path (P2-8, v11: the earlier "no LLM pass proposes
-  merge groups" wording contradicted the tested nomination chain).
+ merge groups, the control plane gates them and applies the mutation — merged source bodies are appended
+ verbatim rather than rewritten into a synthesized skill.
 
 ## Recovery and consolidation
 
@@ -35,9 +22,12 @@ Independent of request-prefix construction. This package does not alter the asse
 - `consolidate(target, sources)` (service) / `/evolution consolidate` merges source bodies into the target, archives the sources with an absorbed-into marker, and folds their usage records into `archived` state. Both operations snapshot the full state first (`pre-consolidate` / `pre-restore`).
 - `restoreSnapshot` (service) / `/evolution restore` rolls the state back to the latest snapshot: active tree, usage/suppression sidecars, `.archive/` and the curator state carried in the snapshot (`curator-state.json`), so the interval gate does not immediately re-fire after a rollback. Skills that were skipped at snapshot time (a live writer held their lock; recorded in the manifest's `skipped` list) are NOT restored — the restore result names them, and `.backups` may hold a copy. The restore itself is undoable — the pre-rollback safety snapshot preserves the current tree plus its state.
 
-## Automatic scheduling
+## Configuration
 
-- `autoStart` (default true) arms an hourly interval check plus a deferred catch-up check `bootGraceSeconds` (default 10) after host boot. Both decide due-ness from the **persisted** `lastRunAt`, so a restart with an overdue schedule runs the first pass within the boot grace instead of waiting a full interval. `bootGraceSeconds: 0` disables the deferral (not recommended: the check may run against a half-mounted host). All scheduling gates — interval, idle, first-run deferral, and the reentrancy guard — remain inside `run()`.
+- `autoStart` (default true) arms an HOURLY tick that only asks whether the due-ness interval (`intervalHours`, default 168 h) has elapsed — the tick is not the interval — plus a deferred catch-up check `bootGraceSeconds` (default 10) after host boot. Both decide due-ness from the **persisted** `lastRunAt`, so a restart with an overdue schedule runs the first pass within the boot grace instead of waiting a full interval. `bootGraceSeconds: 0` disables the deferral (not recommended: the check may run against a half-mounted host). All scheduling gates — interval, idle, first-run deferral, and the reentrancy guard — remain inside `run()`.
 - `autoStart: false` disables both automatic checks; `/evolution curator run` (manual, gate-skipping) still works.
 
 **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).
+## Notes and history
+
+- The one-click `/evolution consolidate <target> <source...>` remains the direct manual path (P2-8, v11: the earlier "no LLM pass proposes merge groups" wording contradicted the tested nomination chain).

package/lib/index.js

@@ -355,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();
@@ -468,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();
@@ -498,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)}`);
 			}
@@ -547,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,
@@ -1111,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();
@@ -1155,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();

package/lib/types/index.d.ts

@@ -243,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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-curator",
   "description": "Deterministic skill lifecycle and recovery (community build)",
-  "version": "0.3.82",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,20 +27,20 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.82"
+    "@lmzhen/dsh-evolution-core": "^0.4.0"
   },
   "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.82",
-    "@lmzhen/dsh-evolution-state": "^0.3.82"
+    "@lmzhen/dsh-evolution-io": "^0.4.0",
+    "@lmzhen/dsh-evolution-state": "^0.4.0"
   },
   "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.82",
-    "@lmzhen/dsh-evolution-io": "^0.3.82",
-    "@lmzhen/dsh-evolution-state": "^0.3.82"
+    "@lmzhen/dsh-evolution-core": "^0.4.0",
+    "@lmzhen/dsh-evolution-io": "^0.4.0",
+    "@lmzhen/dsh-evolution-state": "^0.4.0"
   }
 }