@lmzhen/dsh-evolution-core 0.3.70 → 0.3.71

package/lib/index.js

@@ -1647,11 +1647,11 @@ async function readEvolutionEvents(io, path) {
 * malformed (or unreadable) ARCHIVE is skipped — it never bricks the boot and
 * it is still flagged.
 */
-async function readEvolutionTimeline(io, path) {
+async function readEvolutionTimeline(io, path, archives) {
 	const dir = dirname(path);
 	let malformed = false;
 	const bySeq = /* @__PURE__ */ new Map();
-	for (const name of await listEventArchives(io, path)) {
+	for (const name of archives ?? await listEventArchives(io, path)) {
 		const read = await readEvolutionEvents(io, join(dir, name));
 		if (read.malformed) malformed = true;
 		for (const event of read.events) bySeq.set(event.seq, event);
@@ -3888,6 +3888,65 @@ const DEFAULT_SKILL_LIMITS = {
 	maxSkillContentChars: MAX_SKILL_CONTENT_CHARS,
 	maxSkillFileBytes: MAX_SKILL_FILE_BYTES
 };
+/**
+* Evaluate a stage-time anchor against the bytes a locked read observed.
+* @param anchor - the caller's anchor, or `undefined` for an unanchored write.
+* @param current - the bytes the write lock read (`null` = the target is absent).
+* @returns `match` when the write may proceed, otherwise the refusal verdict.
+*/
+function anchorVerdict(anchor, current) {
+	if (anchor === void 0) return "match";
+	if ("absent" in anchor) return current === null ? "match" : "drift";
+	if (current === null) return "missing";
+	return contentHash(current) === anchor.sha256 ? "match" : "drift";
+}
+/**
+* Build the refusal for a skill write whose anchor did not hold. The wording is
+* the library's own; a caller with staged-replay wording (the skill tool, the
+* review plan) re-words it from {@link SkillActionResult.anchor}.
+* @param name - the skill name the refusal names.
+* @param verdict - the non-matching verdict.
+* @returns the refusal result (nothing was written).
+*/
+function anchorRefusal(name, verdict) {
+	return {
+		ok: false,
+		stale: true,
+		anchor: verdict,
+		message: verdict === "missing" ? `Skill "${name}" not found.` : `Skill "${name}" changed since it was read; the write was refused to avoid overwriting newer content.`
+	};
+}
+/**
+* Build the refusal for a support-file write/remove whose anchor did not hold.
+* @param name - the owning skill name.
+* @param filePath - the support-file path inside the skill.
+* @param verdict - the non-matching verdict.
+* @returns the refusal result (nothing was written or removed).
+*/
+/**
+* Refusal for a target the locked read could not verify at all (EISDIR, an
+* unreadable file). A staged replay reports "could not be verified" instead of
+* propagating an exception: nothing was read, so nothing can have been written.
+* @param name - the owning skill name.
+* @param filePath - the support-file path, or `null` for the skill body.
+* @returns the refusal result.
+*/
+function anchorUnverifiable(name, filePath) {
+	return {
+		ok: false,
+		stale: true,
+		anchor: "drift",
+		message: filePath === null ? `Skill "${name}" could not be read to verify the staged content.` : `Support file "${filePath}" of "${name}" could not be read to verify the staged content.`
+	};
+}
+function anchorRefusalFile(name, filePath, verdict) {
+	return {
+		ok: false,
+		stale: true,
+		anchor: verdict,
+		message: verdict === "missing" ? `File "${filePath}" not found in skill "${name}".` : `Support file "${filePath}" of "${name}" changed since it was read; the write was refused to avoid overwriting newer content.`
+	};
+}
 /** Upper bound of moves per restructure proposal (validator and core agree). */
 const MAX_RESTRUCTURE_MOVES = 5;
 /** Restructure targets are plain markdown files under references/ — no
@@ -4647,9 +4706,11 @@ var SkillLibrary = class {
 	* mutation event are issued ONLY when a write actually lands, so a no-op
 	* never inflates the mutation-maturity counter.
 	*/
-	async runSingleWrite(path, task) {
+	async runSingleWrite(path, task, readFailure) {
 		let outcome;
+		const progress = { entered: false };
 		const run = async (current) => {
+			progress.entered = true;
 			const o = await task(current ?? null);
 			outcome = {
 				...o,
@@ -4662,11 +4723,18 @@ var SkillLibrary = class {
 		if (this.transact) try {
 			await this.transact(this.io, path, run);
 		} catch (error) {
+			if (!progress.entered && readFailure !== void 0) return readFailure;
 			if (!committedOnly(error)) throw error;
 			durabilityWarning = error instanceof Error ? error.message : String(error);
 		}
 		else {
-			const current = await this.io.readText(path);
+			let current;
+			try {
+				current = await this.io.readText(path);
+			} catch (error) {
+				if (readFailure !== void 0) return readFailure;
+				throw error;
+			}
 			const next = await run(current);
 			if (next !== null && next !== current) try {
 				await this.io.writeText(path, next);
@@ -4745,7 +4813,14 @@ var SkillLibrary = class {
 			throw error;
 		}
 	}
-	async list() {
+	/**
+	* Summarize the skill tree.
+	* @param options - `withContent` attaches each skill's whole SKILL.md body to
+	* its summary (v35 C11): the read this listing already performs is the one the
+	* body would cost again, so a content-consuming caller pays no second pass.
+	* @returns one summary per readable skill directory.
+	*/
+	async list(options = {}) {
 		const summaries = [];
 		for (const name of await listNames(this.root, this.io)) {
 			const dir = this.dirOf(name);
@@ -4793,7 +4868,8 @@ var SkillLibrary = class {
 					hermesManaged
 				].some((value) => value === null),
 				managed: hermesManaged === true,
-				...typeof parsedWhenToUse === "string" && parsedWhenToUse.trim() !== "" ? { whenToUse: parsedWhenToUse } : {}
+				...typeof parsedWhenToUse === "string" && parsedWhenToUse.trim() !== "" ? { whenToUse: parsedWhenToUse } : {},
+				...options.withContent === true ? { content: md } : {}
 			});
 		}
 		return summaries;
@@ -5145,11 +5221,11 @@ var SkillLibrary = class {
 			...norm.changed ? { normalizedFrontmatterFields: norm.fields } : {}
 		};
 	}
-	async update(rawName, content, origin = "foreground") {
+	async update(rawName, content, origin = "foreground", anchor) {
 		const name = rawName.trim();
-		return await this.serial(() => this.updateCore(name, content, origin));
+		return await this.serial(() => this.updateCore(name, content, origin, anchor));
 	}
-	async updateCore(name, content, origin) {
+	async updateCore(name, content, origin, anchor) {
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
@@ -5186,6 +5262,11 @@ var SkillLibrary = class {
 			message: threat
 		};
 		return await this.runSingleWrite(path, (current) => {
+			const verdict = anchorVerdict(anchor, current);
+			if (verdict !== "match") return {
+				result: anchorRefusal(name, verdict),
+				write: null
+			};
 			if (current === null) return {
 				result: {
 					ok: false,
@@ -5224,7 +5305,7 @@ var SkillLibrary = class {
 					skillDir: dir
 				}
 			};
-		});
+		}, anchor !== void 0 ? anchorRefusal(name, "missing") : void 0);
 	}
 	async patch(rawName, oldString, newString, filePath = "", replaceAll = false, origin = "foreground") {
 		const name = rawName.trim();
@@ -6081,11 +6162,11 @@ var SkillLibrary = class {
 			path: dest
 		};
 	}
-	async writeSupportFile(rawName, filePath, content, origin = "foreground") {
+	async writeSupportFile(rawName, filePath, content, origin = "foreground", anchor) {
 		const name = rawName.trim();
-		return await this.serial(() => this.writeSupportFileCore(name, filePath, content, origin));
+		return await this.serial(() => this.writeSupportFileCore(name, filePath, content, origin, anchor));
 	}
-	async writeSupportFileCore(name, filePath, content, origin) {
+	async writeSupportFileCore(name, filePath, content, origin, anchor) {
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
@@ -6117,6 +6198,11 @@ var SkillLibrary = class {
 		};
 		const target = join(dir, ...filePath.replace(/\\/g, "/").split("/").filter(Boolean));
 		return await this.runSingleWrite(target, (current) => {
+			const verdict = anchorVerdict(anchor, current);
+			if (verdict !== "match") return {
+				result: anchorRefusalFile(name, filePath, verdict),
+				write: null
+			};
 			if (current !== null && content.trimEnd() === current.trimEnd()) return {
 				result: {
 					ok: true,
@@ -6147,13 +6233,13 @@ var SkillLibrary = class {
 					file: target
 				}
 			};
-		});
+		}, anchor !== void 0 ? anchorUnverifiable(name, filePath) : void 0);
 	}
-	async removeSupportFile(rawName, filePath, origin = "foreground") {
+	async removeSupportFile(rawName, filePath, origin = "foreground", anchor) {
 		const name = rawName.trim();
-		return await this.serial(() => this.removeSupportFileCore(name, filePath, origin));
+		return await this.serial(() => this.removeSupportFileCore(name, filePath, origin, anchor));
 	}
-	async removeSupportFileCore(name, filePath, origin) {
+	async removeSupportFileCore(name, filePath, origin, anchor) {
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
@@ -6175,17 +6261,25 @@ var SkillLibrary = class {
 			message: validation
 		};
 		const target = join(dir, ...filePath.replace(/\\/g, "/").split("/").filter(Boolean));
-		if (!await this.io.exists(target)) return {
-			ok: false,
-			message: `File "${filePath}" not found in skill "${name}".`
-		};
+		if (!await this.io.exists(target)) {
+			if (anchor !== void 0) return anchorRefusalFile(name, filePath, "missing");
+			return {
+				ok: false,
+				message: `File "${filePath}" not found in skill "${name}".`
+			};
+		}
 		const before = await this.io.readText(target).catch(() => null);
 		if (before === null) return {
 			ok: false,
 			message: `"${filePath}" is not a readable regular file — remove the files inside it one by one.`
 		};
-		if (this.transact) await this.transact(this.io, target, () => null);
-		else await this.io.remove(target);
+		let verdict = anchorVerdict(anchor, before);
+		if (verdict === "match" && this.transact) await this.transact(this.io, target, (current) => {
+			verdict = anchorVerdict(anchor, current);
+			return verdict === "match" ? null : current;
+		});
+		else if (verdict === "match") await this.io.remove(target);
+		if (verdict !== "match") return anchorRefusalFile(name, filePath, verdict);
 		await this.audit(name, "remove_file", before, null, `removed ${filePath}`);
 		this.notifyMutation({
 			action: "remove_file",

package/lib/types/evolution-events.d.ts

@@ -140,5 +140,5 @@ export declare function readEvolutionEvents(io: EvolutionIoLike, path: string):
  * malformed (or unreadable) ARCHIVE is skipped — it never bricks the boot and
  * it is still flagged.
  */
-export declare function readEvolutionTimeline(io: EvolutionIoLike, path: string): Promise<EventLogRead>;
+export declare function readEvolutionTimeline(io: EvolutionIoLike, path: string, archives?: readonly string[]): Promise<EventLogRead>;
 //# sourceMappingURL=evolution-events.d.ts.map

package/lib/types/skill-store.d.ts

@@ -31,7 +31,32 @@ export interface SkillSummary {
      * platform catalog keeps it while this provider shadows the upstream
      * filesystem provider. Absent when the frontmatter has none. */
     whenToUse?: string;
+    /** v35 C11: the whole SKILL.md body, present only for
+     * {@link SkillLibrary.list} calls that pass `{ withContent: true }`. A consumer
+     * that needs both the summary fields and the body (tree hashing, enrichment,
+     * drift scans) saves the second per-skill read; the default stays body-free so
+     * the common listing does not hold a whole tree in memory. */
+    content?: string;
 }
+/**
+ * Stage-time anchor for a full-content write (v35 C9): the sha256 the caller read
+ * when it staged the plan, or `absent` when the target did not exist then. The
+ * library compares it against the bytes it reads INSIDE the write's own lock — the
+ * same read the write commits — so a concurrent writer landing between staging and
+ * commit is refused instead of silently overwritten.
+ */
+export type WriteAnchor = {
+    readonly sha256: string;
+} | {
+    readonly absent: true;
+};
+/**
+ * What the write lock observed about an anchor target.
+ * - `match`: the anchor holds; the write proceeds.
+ * - `drift`: the target exists with different bytes.
+ * - `missing`: the target does not exist (an `absent` anchor `match`es this).
+ */
+export type AnchorVerdict = 'match' | 'drift' | 'missing';
 export interface SkillActionResult {
     ok: boolean;
     message: string;
@@ -42,6 +67,12 @@ export interface SkillActionResult {
     /** 0.3.18 (E-68): patch produced byte-identical content (old===new) — no
      * write, no audit, no mutation event; callers must not count a patch. */
     noop?: boolean;
+    /** Set when the caller passed a {@link WriteAnchor} that the locked read did
+     * not satisfy: nothing was written. Carries {@link SkillActionResult.anchor}
+     * so a caller with staged-replay wording can translate it (v35 C9). */
+    stale?: true;
+    /** The locked read's verdict for the caller's anchor. */
+    anchor?: AnchorVerdict;
 }
 /**
  * One section move of a restructure proposal (008 batch B): a body section
@@ -369,7 +400,16 @@ export declare class SkillLibrary {
      * last-writer-wins.
      */
     readSupportFile(name: string, filePath: string): Promise<string | null>;
-    list(): Promise<SkillSummary[]>;
+    /**
+     * Summarize the skill tree.
+     * @param options - `withContent` attaches each skill's whole SKILL.md body to
+     * its summary (v35 C11): the read this listing already performs is the one the
+     * body would cost again, so a content-consuming caller pays no second pass.
+     * @returns one summary per readable skill directory.
+     */
+    list(options?: {
+        withContent?: boolean;
+    }): Promise<SkillSummary[]>;
     read(rawName: string): Promise<string | null>;
     /**
   
@@ -439,7 +479,7 @@ export declare class SkillLibrary {
     private setPinnedCore;
     create(name: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     private createCore;
-    update(rawName: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    update(rawName: string, content: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
     private updateCore;
     patch(rawName: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
     private patchCore;
@@ -546,9 +586,9 @@ export declare class SkillLibrary {
      * path back. The `.archive-reason` marker is dropped on restore.
      */
     restoreFromArchive(rawName: string): Promise<SkillActionResult>;
-    writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
     private writeSupportFileCore;
-    removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
     private removeSupportFileCore;
     /**
      * v23 (ML-1): `.archive` retention. Archived skills are recoverable history,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.3.70",
+  "version": "0.3.71",
   "publishConfig": {
     "access": "public"
   },