@lmzhen/dsh-evolution-curator 0.25.7 → 0.25.9

package/README.md

@@ -37,3 +37,12 @@ Deterministic skill lifecycle and recovery
 ## 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).
+
+## 单元与撤销（对外契约摘要）
+
+- 一个单元 = 一次树改动（一个 unitId）。索引里只有一条记录带 unitHead，两形态互斥：代表片 { moves, sources }（全量清单 + 它写过哪些技能）／路标 { skill }（记录在别的技能里）；判别式固定为 moves !== undefined。
+- undoUnit(name, unitId?)：逐路径回该单元铸的基线；没有基线才回退到最早那条的 beforeHash；单元前不存在的路径删除并锚定（盘上字节被别人改过就拒绝，不覆盖）。决策在纯函数 src/unit-undo-plan.ts，IO 与主机不进决策层。
+- 跨技能单元：成员只按 sources[] 的已知 key 解析（禁止目录扫描）；缺片／外来片／重复片一律拒绝并点名对象 —— 不得用剩下的片段拼一个撤销。
+- 路标的 undoable 是 undefined（wire 上不出现该键），绝不为 false；聚合时跳过路标，避免它的 hash 污染同单元兄弟片。
+- 剪枝按单元 all-or-nothing；保留窗口今天仍按条目计（切换条件见仓库文档）。
+- 完整说明（含回退与验证命令）见仓库 docs/units-and-undo.md；该目录不随 npm 发布，故在此摘要。

package/lib/index.js

@@ -4,7 +4,79 @@ import { join } from "node:path";
 import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
 import z from "@deepseek-ai/schemastery";
 import { preferProvider } from "@lmzhen/dsh-evolution-io";
-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_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_LIMITS, DEFAULT_STALE_AFTER_DAYS, EvolutionGateSet, INSTANCE_KEYS, MAX_TIMER_DELAY_MS, PROMPT_BUNDLE, SKILL_NAME_RE, buildCuratorRunReport, claimInstance, clampOnce, clampedNumber, computeDedupGroups, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, emptyRecord, entryTarget, evolutionHome, evolutionIoAdapter, foldCuratorFields, isPresent, isUnknown, lintSkill, liveBool, loadSuppressedNames, loadUsage, markerEntryName, mutateUsage, newSkillLibrary, paramRowId, parseCuratorNominations, parseFrontmatter, pickWithPolicy, policyStageLimits, probeList, probeText, readNumberParam, relatedSkillNames, releaseInstance, renderCuratorReportMarkdown, reportTime, reportsSweepLockTarget, sessionLastEventTime, sweepReports, transactIo, unwrapLive, updateSuppressedNames, usageObserved, userSetKeys, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
+import { BASELINE_ACTION, 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_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_LIMITS, DEFAULT_STALE_AFTER_DAYS, EvolutionGateSet, INSTANCE_KEYS, MAX_TIMER_DELAY_MS, PROMPT_BUNDLE, SKILL_NAME_RE, blobPath, buildCuratorRunReport, claimInstance, clampOnce, clampedNumber, computeDedupGroups, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, emptyRecord, entryTarget, evolutionHome, evolutionIoAdapter, foldCuratorFields, historyIndexFile, isPresent, isUnknown, lintSkill, liveBool, loadSuppressedNames, loadUsage, markerEntryName, mutateUsage, newSkillLibrary, paramRowId, parseCuratorNominations, parseFrontmatter, parseHistoryIndex, pickWithPolicy, policyStageLimits, probeList, probeText, readNumberParam, relatedSkillNames, releaseInstance, renderCuratorReportMarkdown, reportTime, reportsSweepLockTarget, resolveUnitMembers, sessionLastEventTime, staleRouteStubs, sweepReports, transactIo, unitMembersAreComplete, unwrapLive, updateSuppressedNames, usageObserved, userSetKeys, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
+//#region lib/types/unit-undo-plan.js
+/**
+* G3a: the pure half of `undoUnit` — deciding WHAT to write back, with no io and no host.
+*
+* Kept apart from the curator so it can be tested in isolation (the curator module needs a cordis
+* host; this file needs nothing but the version records). The rules are the storage seat’s:
+*
+* - one path is described by the triple (baseline, oldest after, newest after): the bytes to write
+*   back are the BASELINE this unit minted for that path, and only when there is no baseline do we
+*   fall back to the OLDEST after’s `beforeHash`. Using the NEWEST one’s `beforeHash` would roll the
+*   file back to a state from the middle of the unit — the half-split file this contract exists to
+*   avoid;
+* - a path with no baseline at all did not exist before the unit ⇒ it is REMOVED, and the removal is
+*   anchored on the newest after-entry’s hash so a hand edit refuses instead of being deleted;
+* - anything the plan cannot resolve is a refusal, and the caller writes nothing (pre-flight).
+*/
+/** The newest unit the index carries, or undefined when no entry has a unit id yet. */
+function newestUnitId(versions) {
+	for (let i = versions.length - 1; i >= 0; i -= 1) {
+		const unit = versions[i]?.unitId;
+		if (unit !== void 0) return unit;
+	}
+}
+/**
+* Decide the whole unit rollback. Pure: the caller resolves the hashes to bytes afterwards.
+* @param members - the unit’s entries (any order from the index; oldest first is what it emits).
+* @param versions - the whole index, so `entryTarget` can classify an entry the way the faces do.
+* @returns the operations and the refusals.
+*/
+function planUnitUndo(members, versions) {
+	const slots = /* @__PURE__ */ new Map();
+	const refusals = [];
+	const body = {};
+	for (const entry of members) {
+		const path = entry.path;
+		if (!(path !== void 0 && entryTarget(entry, versions) === "support")) {
+			if (entry.action === BASELINE_ACTION) body.baseline ??= entry;
+			else {
+				body.oldest ??= entry;
+				body.newest = entry;
+			}
+			continue;
+		}
+		const slot = slots.get(path) ?? {};
+		slots.set(path, slot);
+		if (entry.action === BASELINE_ACTION) slot.baseline ??= entry;
+		else {
+			slot.oldest ??= entry;
+			slot.newest = entry;
+		}
+	}
+	const ops = [];
+	for (const [path, slot] of slots) {
+		if (slot.newest === void 0) {
+			refusals.push(`${path}（单元里没有该路径的 after 条目）`);
+			continue;
+		}
+		const preUnitHash = slot.baseline !== void 0 ? slot.baseline.hash : slot.oldest?.beforeHash;
+		ops.push({
+			remove: preUnitHash === void 0,
+			path,
+			preUnitHash,
+			expectedHash: slot.newest.hash
+		});
+	}
+	return {
+		ops,
+		bodyPreUnitHash: body.baseline !== void 0 ? body.baseline.hash : body.oldest?.beforeHash,
+		refusals
+	};
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Deterministic skill lifecycle curator with interval gate and archive.
@@ -821,6 +893,41 @@ var EvolutionCurator = class extends Service {
 			llmReviewEnabled: settings.llmReview,
 			...gatedNominations.warnings.length > 0 ? { nominationsWarnings: gatedNominations.warnings } : {}
 		});
+		report.routeStubs = await (async () => {
+			const history = join(this.skills.root, ".history", "skills");
+			const listed = await probeList(this.io, history);
+			if (!isPresent(listed)) return {
+				skills: 0,
+				stubs: 0,
+				reason: "index-root-absent",
+				detail: []
+			};
+			const indexes = /* @__PURE__ */ new Map();
+			for (const name of listed.value) {
+				const probe = await probeText(this.io, join(history, name, "index.json"));
+				if (!isPresent(probe)) {
+					indexes.set(name, null);
+					continue;
+				}
+				try {
+					indexes.set(name, JSON.parse(probe.value).versions ?? null);
+				} catch {
+					indexes.set(name, null);
+				}
+			}
+			const detail = staleRouteStubs(indexes).map((stub) => ({
+				skill: stub.skill,
+				v: stub.v,
+				owner: stub.owner,
+				reason: stub.reason
+			}));
+			return {
+				skills: indexes.size,
+				stubs: detail.length,
+				reason: "ok",
+				detail
+			};
+		})();
 		const reportsRoot = join(evolutionHome(), "reports");
 		try {
 			await this.io.writeText(join(reportsRoot, `curator-${runId}.json`), JSON.stringify(report, null, 2));
@@ -1458,6 +1565,117 @@ var EvolutionCurator = class extends Service {
 			message: `${result.message} （已撤销到 v${target} —— 仅内容：标记、使用计数与策展状态不变，且这次撤销本身就是一个新版本。）`
 		};
 	}
+	/**
+	* G3a: undo ONE unit — every path that unit wrote goes back together, or nothing does.
+	*
+	* Phase A is a ZERO-WRITE preflight (the body and each support file still hold the unit’s
+	* after-bytes, and every before-blob is readable); Phase B applies support files first and the
+	* body last, passing the anchors Phase A computed so a concurrent change is refused, not
+	* overwritten. Blobs are read BY HASH — entries are pruned by `keep`, blobs are never reclaimed.
+	* @param name - the skill.
+	* @param unitId - the unit to undo; omitted takes the newest unit the index carries.
+	* @returns the outcome; the message names what was reverted, or why nothing was written.
+	*/
+	async undoUnit(name, unitId) {
+		const versions = await this.skills.listVersions(name);
+		if (versions.length === 0) return {
+			ok: false,
+			message: `技能「${name}」还没有记录内容版本 —— 没有可撤销的。`
+		};
+		const live = await this.skills.read(name);
+		if (live === null) return {
+			ok: false,
+			message: `「${name}」不在活动目录树里 —— 撤销恢复的是存活技能；若它已归档，请先 restore。`
+		};
+		const unit = unitId ?? newestUnitId(versions);
+		if (unit === void 0) return {
+			ok: false,
+			message: `技能「${name}」还没有记录任何单元 —— 没有可整体撤销的。`
+		};
+		const members = versions.filter((entry) => entry.unitId === unit);
+		if (members.length === 0) return {
+			ok: false,
+			message: `单元 ${unit} 不在「${name}」已记录的历史里 —— 拒绝瞎猜、不做写入。`
+		};
+		const head = members[0];
+		const headLike = head !== void 0 && head.unitHead !== void 0 ? head.unitHead : void 0;
+		const sources = headLike?.sources;
+		if (sources !== void 0 && sources.length > 0) {
+			const resolved = await resolveUnitMembers(this.skills.root, this.io, {
+				skill: name,
+				unitId: unit,
+				sources,
+				...headLike === void 0 ? {} : { unitHead: headLike }
+			}, historyIndexFile, parseHistoryIndex);
+			if (!unitMembersAreComplete(resolved)) {
+				const missing = resolved.missing.map((m) => m.skill + (m.reason === "index-absent" ? "（索引文件不在）" : "（索引里没有这个单元）")).join("、");
+				const conflicts = resolved.conflicts.map((c) => c.path + "（" + c.kind + "）").join("、");
+				return {
+					ok: false,
+					message: "单元 " + unit + " 的成员没解析齐：" + missing + (conflicts === "" ? "" : "；冲突：" + conflicts) + " —— 拒绝用剩余片段拼一个撤销。"
+				};
+			}
+			if (resolved.members.length > 1) return {
+				ok: false,
+				message: "单元 " + unit + " 跨 " + String(resolved.members.length) + " 个技能（" + resolved.members.map((m) => m.skill).join("、") + "）—— 跨技能整体撤销尚未接线，拒绝只撤销其中一片。"
+			};
+		}
+		const blobOf = async (hash) => {
+			if (hash === void 0) return null;
+			const probe = await probeText(this.io, blobPath(this.skills.root, hash));
+			return isPresent(probe) ? probe.value : null;
+		};
+		const plan = planUnitUndo(members, versions);
+		const refused = [...plan.refusals];
+		const ops = [];
+		for (const op of plan.ops) {
+			const back = await blobOf(op.preUnitHash);
+			if (op.preUnitHash !== void 0 && back === null) {
+				refused.push(`${op.path}（before 字节读不到：blob ${op.preUnitHash}）`);
+				continue;
+			}
+			const liveProbe = await probeText(this.io, join(this.skills.root, name, ...op.path.split("/")));
+			if (isPresent(liveProbe) && contentHash(liveProbe.value) !== op.expectedHash) {
+				refused.push(`${op.path}（盘上字节已变，回退会覆盖别人的改动）`);
+				continue;
+			}
+			ops.push({
+				remove: op.remove,
+				path: op.path,
+				bytes: back ?? "",
+				anchor: { sha256: op.expectedHash }
+			});
+		}
+		const bodyBytes = await blobOf(plan.bodyPreUnitHash);
+		if (plan.bodyPreUnitHash !== void 0 && bodyBytes === null) refused.push("SKILL.md（正文 before 字节读不到）");
+		if (refused.length > 0) return {
+			ok: false,
+			message: `整单元撤销未开始（零写）—— 预检未通过：${refused.join("；")}。修好后可重试。`
+		};
+		const undoUnitId = `u-undo-${Date.now().toString(36)}`;
+		const reverted = [];
+		const done = () => reverted.length === 0 ? "无" : reverted.join(", ");
+		for (const op of ops) {
+			const result = op.remove ? await this.skills.removeSupportFile(name, op.path, "foreground", op.anchor, undoUnitId) : await this.skills.writeSupportFile(name, op.path, op.bytes, "foreground", op.anchor);
+			if (!result.ok) return {
+				ok: false,
+				message: `「${op.path}」：${result.message} —— 撤销未完成（已回退：${done()}）。`
+			};
+			reverted.push(op.path);
+		}
+		if (plan.bodyPreUnitHash !== void 0 && bodyBytes !== null) {
+			const result = await this.skills.update(name, bodyBytes, "foreground", { sha256: contentHash(live) });
+			if (!result.ok) return {
+				ok: false,
+				message: `正文：${result.message} —— 撤销未完成（已回退：${done()}）。`
+			};
+			reverted.push("SKILL.md");
+		}
+		return {
+			ok: true,
+			message: `已按单元撤销「${name}」：${reverted.join(", ")}（撤销单元 ${undoUnitId}，被撤单元 ${unit}）。`
+		};
+	}
 	/** 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

package/lib/types/index.d.ts

@@ -562,6 +562,18 @@ export declare class EvolutionCurator extends Service {
      */
     undo(name: string, v?: number): Promise<SkillActionResult>;
     private undoMutate;
+    /**
+     * G3a: undo ONE unit — every path that unit wrote goes back together, or nothing does.
+     *
+     * Phase A is a ZERO-WRITE preflight (the body and each support file still hold the unit’s
+     * after-bytes, and every before-blob is readable); Phase B applies support files first and the
+     * body last, passing the anchors Phase A computed so a concurrent change is refused, not
+     * overwritten. Blobs are read BY HASH — entries are pruned by `keep`, blobs are never reclaimed.
+     * @param name - the skill.
+     * @param unitId - the unit to undo; omitted takes the newest unit the index carries.
+     * @returns the outcome; the message names what was reverted, or why nothing was written.
+     */
+    undoUnit(name: string, unitId?: string): Promise<SkillActionResult>;
     /** 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

package/lib/types/unit-undo-plan.d.ts

@@ -0,0 +1,45 @@
+/**
+ * G3a: the pure half of `undoUnit` — deciding WHAT to write back, with no io and no host.
+ *
+ * Kept apart from the curator so it can be tested in isolation (the curator module needs a cordis
+ * host; this file needs nothing but the version records). The rules are the storage seat’s:
+ *
+ * - one path is described by the triple (baseline, oldest after, newest after): the bytes to write
+ *   back are the BASELINE this unit minted for that path, and only when there is no baseline do we
+ *   fall back to the OLDEST after’s `beforeHash`. Using the NEWEST one’s `beforeHash` would roll the
+ *   file back to a state from the middle of the unit — the half-split file this contract exists to
+ *   avoid;
+ * - a path with no baseline at all did not exist before the unit ⇒ it is REMOVED, and the removal is
+ *   anchored on the newest after-entry’s hash so a hand edit refuses instead of being deleted;
+ * - anything the plan cannot resolve is a refusal, and the caller writes nothing (pre-flight).
+ */
+import { type SkillVersion } from '@lmzhen/dsh-evolution-core';
+/** One path’s action inside a unit undo. */
+export interface UnitUndoOp {
+    /** True when the unit created the file (no pre-unit bytes) ⇒ remove it, anchored. */
+    remove: boolean;
+    /** The support file, relative to the skill directory. */
+    path: string;
+    /** The blob to write back (hash), or undefined when the unit created the path. */
+    preUnitHash: string | undefined;
+    /** The bytes the unit left on disk — the CAS anchor for either action. */
+    expectedHash: string;
+}
+/** What the undo would do, plus why it refuses to do anything. */
+export interface UnitUndoPlan {
+    ops: UnitUndoOp[];
+    /** The body’s pre-unit bytes (hash), or undefined when the unit did not rewrite the body. */
+    bodyPreUnitHash: string | undefined;
+    /** Non-empty ⇒ the caller must NOT write anything (pre-flight). */
+    refusals: string[];
+}
+/** The newest unit the index carries, or undefined when no entry has a unit id yet. */
+export declare function newestUnitId(versions: SkillVersion[]): string | undefined;
+/**
+ * Decide the whole unit rollback. Pure: the caller resolves the hashes to bytes afterwards.
+ * @param members - the unit’s entries (any order from the index; oldest first is what it emits).
+ * @param versions - the whole index, so `entryTarget` can classify an entry the way the faces do.
+ * @returns the operations and the refusals.
+ */
+export declare function planUnitUndo(members: SkillVersion[], versions: SkillVersion[]): UnitUndoPlan;
+//# sourceMappingURL=unit-undo-plan.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.25.7",
+  "version": "0.25.9",
   "publishConfig": {
     "access": "public"
   },
@@ -27,20 +27,20 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
-    "@lmzhen/dsh-evolution-core": "^0.25.7"
+    "@lmzhen/dsh-evolution-core": "^0.25.9"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
     "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
-    "@lmzhen/dsh-evolution-io": "^0.25.7",
-    "@lmzhen/dsh-evolution-state": "^0.25.7"
+    "@lmzhen/dsh-evolution-io": "^0.25.9",
+    "@lmzhen/dsh-evolution-state": "^0.25.9"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
     "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
-    "@lmzhen/dsh-evolution-core": "^0.25.7",
-    "@lmzhen/dsh-evolution-io": "^0.25.7",
-    "@lmzhen/dsh-evolution-state": "^0.25.7"
+    "@lmzhen/dsh-evolution-core": "^0.25.9",
+    "@lmzhen/dsh-evolution-io": "^0.25.9",
+    "@lmzhen/dsh-evolution-state": "^0.25.9"
   }
 }