@lmzhen/dsh-evolution-curator 0.9.0 → 0.11.1

package/README.md

@@ -19,6 +19,8 @@ Deterministic skill lifecycle and recovery
 
 - `archive` never deletes: skills move to `.archive/` with a `.archive-reason` marker.
 - `restore(name)` (service) / `/evolution skill restore <name>` brings one archived skill back to the active root and resets its usage state.
+- `history(name)` (service) / `/evolution skill history <name>` lists one skill's content versions (number, time, action, characters, hash prefix) from the content history every write path maintains (`evolution-core/src/skill-history.ts`). An index that cannot be read, carries a foreign field layout, or was written by a NEWER reader all read as "no versions" (the module's never-guess posture) — the next successful write re-seeds the index with a baseline entry, so the record heals instead of staying invisible.
+- `undo(name, v?)` (service) / `/evolution skill undo <name> [--to v<N>]` restores one version's CONTENT through an ordinary anchored write: an omitted `v` means the newest version whose content differs from the live file, the anchor is the live hash (a concurrent writer is refused rather than overwritten, and a version the index lists but whose blob cannot be read is refused rather than guessed at), and the rollback itself becomes a new version. Content only: the pin marker, usage counters and curation state are not versions and do not move, which the result text says. A skill with no recorded versions, a target that is not in the active tree (use `skill restore` for an archived one), and a session that cannot replay the write each get their own refusal.
 - `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.
 

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_SKILL_LIMITS, 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, installParamSection, isPresent, isUnknown, loadSuppressedNames, loadUsage, markerEntryName, mutateUsage, newSkillLibrary, paramNamespace, parseCuratorNominations, parseFrontmatter, policyStageLimits, probeList, probeMtime, readNumberParam, relatedSkillNames, releaseInstance, renderCuratorReportMarkdown, transactIo, 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_SKILL_LIMITS, DEFAULT_STALE_AFTER_DAYS, EvolutionGateSet, INSTANCE_KEYS, MAX_TIMER_DELAY_MS, SKILL_NAME_RE, buildCuratorRunReport, claimInstance, clampedNumber, computeDedupGroups, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, emptyRecord, evolutionHome, evolutionIoAdapter, foldCuratorFields, installParamSection, isPresent, isUnknown, loadSuppressedNames, loadUsage, markerEntryName, mutateUsage, newSkillLibrary, paramNamespace, parseCuratorNominations, parseFrontmatter, policyStageLimits, probeList, probeMtime, readNumberParam, relatedSkillNames, releaseInstance, renderCuratorReportMarkdown, transactIo, updateSuppressedNames, usageObserved, versionTarget } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Deterministic skill lifecycle curator with interval gate and archive.
@@ -1320,6 +1320,105 @@ var EvolutionCurator = class extends Service {
 		}
 		return result;
 	}
+	/**
+	* One skill's content versions, oldest first (skill-history.ts, batch A).
+	*
+	* READ-ONLY on purpose: no control-plane mutex and no instance claim. A human asking "which
+	* versions exist?" must not be blocked by a running pass, and this cannot change anything.
+	* @param name - the skill's name.
+	* @returns the versions; a skill with no history (or an index that cannot be read) answers [].
+	*/
+	async history(name) {
+		return await this.skills.listVersions(name);
+	}
+	/**
+	* Control-plane undo: put one skill's CONTENT back to a recorded version.
+	*
+	* The undo is an ordinary anchored write (design I5): it goes through `update`, so it earns its
+	* own version, joins the mutation ledger, and is refused if the live content changed since the
+	* caller read it — there is no second write channel to bypass. Only content moves: markers
+	* (`.pinned`/`.hermes-managed`), usage counters and curation state are deliberately untouched,
+	* which the result message says so nobody reads this as a time machine.
+	* @param name - the skill's name.
+	* @param v - the version to restore; omitted means "the newest version that differs from the live
+	*   content", i.e. the state before the latest change.
+	* @returns the write result (`ok:false` with the reason when there is nothing to undo).
+	*/
+	async undo(name, v) {
+		const release = await this.acquireMutex();
+		try {
+			if (!this.holdsInstance) return this.instanceHeldRefusal("undo");
+			return await this.undoMutate(name, v);
+		} finally {
+			release();
+		}
+	}
+	async undoMutate(name, v) {
+		const versions = await this.skills.listVersions(name);
+		if (versions.length === 0) return {
+			ok: false,
+			message: `No content versions are recorded for "${name}" yet — nothing to undo.`
+		};
+		const live = await this.skills.read(name);
+		if (live === null) return {
+			ok: false,
+			message: `"${name}" is not in the active tree — undo restores CONTENT of a live skill; use '/evolution skill restore ${name}' for an archived one.`
+		};
+		const liveHash = contentHash(live);
+		const target = v ?? this.previousVersionOf(versions, liveHash);
+		if (target === void 0) return {
+			ok: false,
+			message: `"${name}" is already at its recorded content — no earlier version to undo to.`
+		};
+		if (!versions.some((candidate) => candidate.v === target)) {
+			const listed = versions.map((candidate) => `v${candidate.v}`).join(", ");
+			return {
+				ok: false,
+				message: `Version v${target} of "${name}" is not in the recorded history (recorded: ${listed === "" ? "none" : listed}).`
+			};
+		}
+		const entry = versions.find((candidate) => candidate.v === target);
+		if (entry !== void 0 && versionTarget(entry.action) === "support") return {
+			ok: false,
+			message: `Version v${target} of "${name}" was written by '${entry.action}' and holds a SUPPORT FILE's bytes, not this skill's SKILL.md — undo restores the body only. The recorded bytes stay in the history store; copy the blob back over that file to restore them.`
+		};
+		const content = await this.skills.readVersion(name, target);
+		if (content === null) return {
+			ok: false,
+			message: `Version v${target} of "${name}" is listed in the index but its stored content could not be read — refusing rather than writing a guess.`
+		};
+		const anchor = { sha256: liveHash };
+		const result = await this.skills.update(name, content, "foreground", anchor);
+		if (!result.ok) return result;
+		if (result.noop === true) return {
+			ok: true,
+			message: `"${name}" already holds the content of v${target} — nothing was written and no new version was recorded.`
+		};
+		return {
+			ok: true,
+			message: `${result.message} (undone to v${target} — content only: markers, usage counts and curation state are unchanged, and this undo is itself a new version.)`
+		};
+	}
+	/** The content the live bytes replaced: the CHAIN first, the recorded order as the fallback.
+	*
+	* Every entry written from 0.10.0 on carries `beforeHash`, read under the content lock, so the link
+	* survives two writers of one skill appending their versions out of order. The tail scan stays for
+	* entries written before the link existed and for a live body no version recorded (a hand-edited
+	* tree): the newest version whose content differs from the live bytes.
+	*
+	* Support-file versions are skipped in both branches: undo restores the skill BODY, and a version
+	* holding a support file's bytes is not a state the body was ever in (0.10.1). */
+	previousVersionOf(versions, liveHash) {
+		const live = [...versions].reverse().find((entry) => entry.hash === liveHash);
+		if (live?.beforeHash !== void 0) {
+			const predecessor = [...versions].reverse().find((entry) => entry.hash === live.beforeHash);
+			if (predecessor !== void 0 && versionTarget(predecessor.action) !== "support") return predecessor.v;
+		}
+		for (let index = versions.length - 1; index >= 0; index -= 1) {
+			const entry = versions[index];
+			if (entry !== void 0 && entry.hash !== liveHash && versionTarget(entry.action) !== "support") return entry.v;
+		}
+	}
 };
 /**
 * v43 FLOW2-1: the per-home lock target for the report retention sweep.

package/lib/types/index.d.ts

@@ -7,6 +7,7 @@ import z from '@deepseek-ai/schemastery';
 import type Schema from '@deepseek-ai/schemastery';
 import { EvolutionGateSet, type SkillLibrary } from '@lmzhen/dsh-evolution-core';
 import { type CuratorConsolidation, type CuratorNominations, type CuratorRunReport, type ScopeView, type SkillActionResult, type SkillHealthVerdict } from '@lmzhen/dsh-evolution-core';
+import type { SkillVersion } from '@lmzhen/dsh-evolution-core';
 import type { CuratorStateRecord } from '@lmzhen/dsh-evolution-state';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -416,6 +417,40 @@ export declare class EvolutionCurator extends Service {
      */
     restore(name: string): Promise<SkillActionResult>;
     private restoreMutate;
+    /**
+     * One skill's content versions, oldest first (skill-history.ts, batch A).
+     *
+     * READ-ONLY on purpose: no control-plane mutex and no instance claim. A human asking "which
+     * versions exist?" must not be blocked by a running pass, and this cannot change anything.
+     * @param name - the skill's name.
+     * @returns the versions; a skill with no history (or an index that cannot be read) answers [].
+     */
+    history(name: string): Promise<SkillVersion[]>;
+    /**
+     * Control-plane undo: put one skill's CONTENT back to a recorded version.
+     *
+     * The undo is an ordinary anchored write (design I5): it goes through `update`, so it earns its
+     * own version, joins the mutation ledger, and is refused if the live content changed since the
+     * caller read it — there is no second write channel to bypass. Only content moves: markers
+     * (`.pinned`/`.hermes-managed`), usage counters and curation state are deliberately untouched,
+     * which the result message says so nobody reads this as a time machine.
+     * @param name - the skill's name.
+     * @param v - the version to restore; omitted means "the newest version that differs from the live
+     *   content", i.e. the state before the latest change.
+     * @returns the write result (`ok:false` with the reason when there is nothing to undo).
+     */
+    undo(name: string, v?: number): Promise<SkillActionResult>;
+    private undoMutate;
+    /** The content the live bytes replaced: the CHAIN first, the recorded order as the fallback.
+     *
+     * Every entry written from 0.10.0 on carries `beforeHash`, read under the content lock, so the link
+     * survives two writers of one skill appending their versions out of order. The tail scan stays for
+     * entries written before the link existed and for a live body no version recorded (a hand-edited
+     * tree): the newest version whose content differs from the live bytes.
+     *
+     * Support-file versions are skipped in both branches: undo restores the skill BODY, and a version
+     * holding a support file's bytes is not a state the body was ever in (0.10.1). */
+    private previousVersionOf;
 }
 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.9.0",
+  "version": "0.11.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,20 +27,20 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.9.0"
+    "@lmzhen/dsh-evolution-core": "^0.11.1"
   },
   "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.9.0",
-    "@lmzhen/dsh-evolution-state": "^0.9.0"
+    "@lmzhen/dsh-evolution-io": "^0.11.1",
+    "@lmzhen/dsh-evolution-state": "^0.11.1"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@lmzhen/dsh-evolution-core": "^0.9.0",
-    "@lmzhen/dsh-evolution-io": "^0.9.0",
-    "@lmzhen/dsh-evolution-state": "^0.9.0"
+    "@lmzhen/dsh-evolution-core": "^0.11.1",
+    "@lmzhen/dsh-evolution-io": "^0.11.1",
+    "@lmzhen/dsh-evolution-state": "^0.11.1"
   }
 }