@lmzhen/dsh-evolution-core 0.1.0-rc.61 → 0.1.0-rc.62

package/lib/index.js

@@ -935,7 +935,13 @@ Quality bar:
 - Prefer verbatim flags, paths, and APIs from the source. Never invent them.
 - Keep it tight: ~100 lines simple, ~200 complex.
 - No router/index/hub skills that only point at other skills.
-- References go in \`references/\`, templates in \`templates/\`.`;
+- References go in \`references/\`, templates in \`templates/\`.
+
+Learn workflow (when the user asks you to learn a reusable skill, or you decide to turn a source/request into one):
+1. Gather every source named (files, URLs, "what we just did", pasted notes) with the tools you already have — and treat prose after a source as authoring requirements, not noise.
+2. Apply every requirement and constraint from the request to the SKILL.md you author.
+3. Author exactly ONE SKILL.md and save it with \`skill_manage\` (action=create); non-trivial scripts go under \`scripts/\`.
+4. When done, tell the user the skill name, its category, and a one-line summary of what it captured.`;
 //#endregion
 //#region lib/types/learn-prompt.js
 /**
@@ -1372,59 +1378,103 @@ var MemoryStore = class {
 		};
 	}
 	async add(target, facts) {
-		const refusal = await this.oversizedRefusal(target);
-		if (refusal) return refusal;
-		if (await this.detectDrift(target)) {
-			const backup = await this.backupFile(target);
-			return {
-				ok: false,
-				message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
-				entries: [],
-				chars: 0,
-				limit: this.limitFor(target)
-			};
-		}
-		const content = facts.trim();
-		if (!content) return {
+		if (!facts.trim()) return {
 			ok: false,
 			message: "Content cannot be empty.",
 			entries: [],
 			chars: 0,
 			limit: this.limitFor(target)
 		};
+		const path = fileFor(this.root, target);
+		let outcome;
+		await transactIo(this.io, path, async (current) => {
+			const core = await this.addCore(target, facts, current ?? "");
+			outcome = core.result;
+			return core.write ?? current ?? "";
+		});
+		return outcome;
+	}
+	/**
+	* Single-entry add inside the transaction: shared checks (oversized,
+	* drift, threat) and the content computation. `raw` is the locked view
+	* (`current`) — never a second IO read. `write: null` means "no change".
+	*/
+	async addCore(target, facts, raw) {
+		const content = facts.trim();
+		if (!content) return {
+			result: this.failure(target, "Content cannot be empty.", []),
+			write: null
+		};
+		const refusal = await this.oversizedRefusal(target);
+		if (refusal) return {
+			result: refusal,
+			write: null
+		};
+		if (this.driftFromRaw(target, raw)) {
+			const backup = await this.backupFile(target);
+			return {
+				result: {
+					ok: false,
+					message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
+					entries: [],
+					chars: 0,
+					limit: this.limitFor(target)
+				},
+				write: null
+			};
+		}
 		const threat = scanMemoryThreats(content);
 		if (threat) return {
-			ok: false,
-			message: threat,
-			entries: [],
-			chars: 0,
-			limit: this.limitFor(target)
+			result: {
+				ok: false,
+				message: threat,
+				entries: [],
+				chars: 0,
+				limit: this.limitFor(target)
+			},
+			write: null
 		};
-		const entries = await this.read(target);
+		const entries = [...new Set(normalizeEntries(raw))];
 		if (entries.some((entry) => stripDatePrefix(entry) === content)) {
 			this.resetFailures();
 			return {
-				ok: true,
-				message: `Entry already exists (no duplicate added).${this.storageHint(target, entries.join(ENTRY_DELIMITER).length)}`,
-				entries,
-				chars: entries.join(ENTRY_DELIMITER).length,
-				limit: this.limitFor(target)
+				result: {
+					ok: true,
+					message: `Entry already exists (no duplicate added).${this.storageHint(target, entries.join(ENTRY_DELIMITER).length)}`,
+					entries,
+					chars: entries.join(ENTRY_DELIMITER).length,
+					limit: this.limitFor(target)
+				},
+				write: null
 			};
 		}
 		const next = [...entries, this.addDatePrefix ? `## ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}\n${content}` : content];
 		const total = next.join(ENTRY_DELIMITER).length;
 		const addLimit = this.limitFor(target);
-		if (addLimit > 0 && total > addLimit) return this.failure(target, `Adding this entry would exceed the ${addLimit} char limit. Consolidate or remove stale entries, then retry.`, entries);
-		await this.write(target, next);
+		if (addLimit > 0 && total > addLimit) return {
+			result: this.failure(target, `Adding this entry would exceed the ${addLimit} char limit. Consolidate or remove stale entries, then retry.`, entries),
+			write: null
+		};
 		this.resetFailures();
 		return {
-			ok: true,
-			message: `Entry added.${this.storageHint(target, total)}`,
-			entries: next,
-			chars: total,
-			limit: this.limitFor(target)
+			result: {
+				ok: true,
+				message: `Entry added.${this.storageHint(target, total)}`,
+				entries: next,
+				chars: total,
+				limit: this.limitFor(target)
+			},
+			write: render(next)
 		};
 	}
+	/** Canonical-form drift check derived from the locked view (same formula as `detectDrift`, no second read). */
+	driftFromRaw(target, raw) {
+		if (raw.trim() === "") return false;
+		const entries = normalizeEntries(raw);
+		const limit = this.limitFor(target);
+		if (limit > 0 && entries.some((entry) => entry.length > limit)) return true;
+		return render(entries) !== raw;
+	}
 	async applyBatch(target, operations) {
 		if (operations.length === 0) return {
 			ok: false,
@@ -1433,95 +1483,138 @@ var MemoryStore = class {
 			chars: 0,
 			limit: this.limitFor(target)
 		};
+		const path = fileFor(this.root, target);
+		let outcome;
+		await transactIo(this.io, path, async (current) => {
+			const core = await this.applyBatchCore(target, operations, current ?? "");
+			outcome = core.result;
+			return core.write ?? current ?? "";
+		});
+		return outcome;
+	}
+	/** Batch RMW inside the transaction. `write: null` = failure/no-op, disk untouched. */
+	async applyBatchCore(target, operations, raw) {
 		const refusal = await this.oversizedRefusal(target);
-		if (refusal) return refusal;
-		if (await this.detectDrift(target)) {
+		if (refusal) return {
+			result: refusal,
+			write: null
+		};
+		if (this.driftFromRaw(target, raw)) {
 			const backup = await this.backupFile(target);
 			return {
-				ok: false,
-				message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
-				entries: [],
-				chars: 0,
-				limit: this.limitFor(target)
+				result: {
+					ok: false,
+					message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
+					entries: [],
+					chars: 0,
+					limit: this.limitFor(target)
+				},
+				write: null
 			};
 		}
-		const entries = await this.read(target);
+		const entries = [...new Set(normalizeEntries(raw))];
 		const working = [...entries];
 		for (const [index, op] of operations.entries()) {
 			const position = index + 1;
 			if (op.action === "add") {
 				const body = (op.facts ?? "").trim();
 				if (!body) return {
-					ok: false,
-					message: `Operation ${position} (add): facts is required. No operations were applied.${previewEntries(entries)}`,
-					entries,
-					chars: entries.join(ENTRY_DELIMITER).length,
-					limit: this.limitFor(target)
+					result: {
+						ok: false,
+						message: `Operation ${position} (add): facts is required. No operations were applied.${previewEntries(entries)}`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
 				};
 				const threat = scanMemoryThreats(body);
 				if (threat) return {
-					ok: false,
-					message: `Operation ${position}: ${threat}`,
-					entries,
-					chars: entries.join(ENTRY_DELIMITER).length,
-					limit: this.limitFor(target)
+					result: {
+						ok: false,
+						message: `Operation ${position}: ${threat}`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
 				};
 				if (!working.some((entry) => stripDatePrefix(entry) === body)) working.push(this.addDatePrefix ? `## ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}\n${body}` : body);
 				continue;
 			}
 			const needle = (op.old_text ?? "").trim();
 			if (!needle) return {
-				ok: false,
-				message: `Operation ${position} (${op.action}): old_text is required. No operations were applied.${previewEntries(entries)}`,
-				entries,
-				chars: entries.join(ENTRY_DELIMITER).length,
-				limit: this.limitFor(target)
+				result: {
+					ok: false,
+					message: `Operation ${position} (${op.action}): old_text is required. No operations were applied.${previewEntries(entries)}`,
+					entries,
+					chars: entries.join(ENTRY_DELIMITER).length,
+					limit: this.limitFor(target)
+				},
+				write: null
 			};
 			const matches = working.map((entry, matchIndex) => ({
 				entry,
 				matchIndex
 			})).filter(({ entry }) => entry.includes(needle));
-			if (matches.length === 0) return this.failure(target, `Operation ${position}: no entry matching "${needle}" found. No operations were applied.`, entries);
+			if (matches.length === 0) return {
+				result: this.failure(target, `Operation ${position}: no entry matching "${needle}" found. No operations were applied.`, entries),
+				write: null
+			};
 			if (new Set(matches.map((m) => m.entry)).size > 1) return {
-				ok: false,
-				message: `Operation ${position}: "${needle}" matched multiple distinct entries. No operations were applied.${previewEntries(entries)}`,
-				entries,
-				chars: entries.join(ENTRY_DELIMITER).length,
-				limit: this.limitFor(target)
+				result: {
+					ok: false,
+					message: `Operation ${position}: "${needle}" matched multiple distinct entries. No operations were applied.${previewEntries(entries)}`,
+					entries,
+					chars: entries.join(ENTRY_DELIMITER).length,
+					limit: this.limitFor(target)
+				},
+				write: null
 			};
 			const matchIndex = matches[0]?.matchIndex ?? -1;
 			if (op.action === "remove") working.splice(matchIndex, 1);
 			else {
 				const body = (op.facts ?? "").trim();
 				if (!body) return {
-					ok: false,
-					message: `Operation ${position} (replace): facts is required.${previewEntries(entries)}`,
-					entries,
-					chars: entries.join(ENTRY_DELIMITER).length,
-					limit: this.limitFor(target)
+					result: {
+						ok: false,
+						message: `Operation ${position} (replace): facts is required.${previewEntries(entries)}`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
 				};
 				const threat = scanMemoryThreats(body);
 				if (threat) return {
-					ok: false,
-					message: `Operation ${position}: ${threat}`,
-					entries,
-					chars: entries.join(ENTRY_DELIMITER).length,
-					limit: this.limitFor(target)
+					result: {
+						ok: false,
+						message: `Operation ${position}: ${threat}`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
 				};
 				working[matchIndex] = body;
 			}
 		}
 		const total = working.join(ENTRY_DELIMITER).length;
 		const batchLimit = this.limitFor(target);
-		if (batchLimit > 0 && total > batchLimit) return this.failure(target, `Batch result (${total} chars) exceeds the ${batchLimit} limit. Remove or shorten more entries in the same batch.`, entries);
-		await this.write(target, working);
+		if (batchLimit > 0 && total > batchLimit) return {
+			result: this.failure(target, `Batch result (${total} chars) exceeds the ${batchLimit} limit. Remove or shorten more entries in the same batch.`, entries),
+			write: null
+		};
 		this.resetFailures();
 		return {
-			ok: true,
-			message: `Applied ${operations.length} operation(s).${this.storageHint(target, total)}`,
-			entries: working,
-			chars: total,
-			limit: this.limitFor(target)
+			result: {
+				ok: true,
+				message: `Applied ${operations.length} operation(s).${this.storageHint(target, total)}`,
+				entries: working,
+				chars: total,
+				limit: this.limitFor(target)
+			},
+			write: render(working)
 		};
 	}
 	async renderContext() {

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

@@ -72,7 +72,17 @@ export declare class MemoryStore {
      */
     private oversizedRefusal;
     add(target: MemoryTarget, facts: string): Promise<MemoryApplyResult>;
+    /**
+     * Single-entry add inside the transaction: shared checks (oversized,
+     * drift, threat) and the content computation. `raw` is the locked view
+     * (`current`) — never a second IO read. `write: null` means "no change".
+     */
+    private addCore;
+    /** Canonical-form drift check derived from the locked view (same formula as `detectDrift`, no second read). */
+    private driftFromRaw;
     applyBatch(target: MemoryTarget, operations: MemoryOperation[]): Promise<MemoryApplyResult>;
+    /** Batch RMW inside the transaction. `write: null` = failure/no-op, disk untouched. */
+    private applyBatchCore;
     renderContext(): Promise<string>;
     /**
      * Detect on-disk drift: true when the file is not in the canonical

package/lib/types/prompts.d.ts

@@ -28,5 +28,5 @@ export interface PromptBundle {
 }
 export declare const PROMPT_BUNDLE: PromptBundle;
 export declare function verifyPromptBundle(bundle?: PromptBundle): boolean;
-export declare const DSH_AUTHORING_STANDARDS = "Follow the Hermes skill-authoring standards, translated to DSH tools.\n\nFrontmatter:\n- name: lowercase-hyphenated, <=64 chars, no spaces.\n- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving. If the description contains a colon, wrap the whole value in double quotes.\n- version: 0.1.0\n- author: always the literal value \"Hermes\". NEVER fill it from the environment, git config, or any identity you can probe \u2014 an environment-derived name is a privacy leak the user never opted into (skills get shared and published), and the skill names itself as Hermes.\n- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound (osascript/apt/systemctl => the matching OS; /proc, signal.SIGKILL => linux; fcntl/termios => POSIX). Prefer fixing it cross-platform first (tempdir, pathlib, pure-Node); omit the field for portable skills.\n- metadata.hermes.tags: a few Capitalized, Relevant, Tags.\n- metadata.hermes.related_skills: [a, b] \u2014 name sibling skills this one builds on or is referenced by (optional; feeds the quality references factor).\n\nBody section order (omit only when empty):\n1. \"# <Human Title>\" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.\n2. \"## When to Use\" \u2014 concrete trigger phrases.\n3. \"## Prerequisites\" \u2014 exact env vars, install steps, credentials.\n4. \"## How to Run\" \u2014 canonical invocation framed through DSH tools.\n5. \"## Quick Reference\" \u2014 flat command/endpoint list.\n6. \"## Procedure\" \u2014 numbered steps with copy-paste-exact commands.\n7. \"## Pitfalls\" \u2014 known limits and rate limits.\n8. \"## Verification\" \u2014 one check proving the skill worked.\n\nDSH-tool framing:\n- Reference DSH tools by name in backticks: `bash`, `str_replace_editor`, `write`, `skill`, `skill_manage`, `memory`.\n- Do not name wrapped shell utilities when a DSH tool already covers them.\n- Larger scripts belong under `scripts/` (written with `skill_manage write_file`) and are referenced from SKILL.md by relative path.\n\nQuality bar:\n- Prefer verbatim flags, paths, and APIs from the source. Never invent them.\n- Keep it tight: ~100 lines simple, ~200 complex.\n- No router/index/hub skills that only point at other skills.\n- References go in `references/`, templates in `templates/`.";
+export declare const DSH_AUTHORING_STANDARDS = "Follow the Hermes skill-authoring standards, translated to DSH tools.\n\nFrontmatter:\n- name: lowercase-hyphenated, <=64 chars, no spaces.\n- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving. If the description contains a colon, wrap the whole value in double quotes.\n- version: 0.1.0\n- author: always the literal value \"Hermes\". NEVER fill it from the environment, git config, or any identity you can probe \u2014 an environment-derived name is a privacy leak the user never opted into (skills get shared and published), and the skill names itself as Hermes.\n- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound (osascript/apt/systemctl => the matching OS; /proc, signal.SIGKILL => linux; fcntl/termios => POSIX). Prefer fixing it cross-platform first (tempdir, pathlib, pure-Node); omit the field for portable skills.\n- metadata.hermes.tags: a few Capitalized, Relevant, Tags.\n- metadata.hermes.related_skills: [a, b] \u2014 name sibling skills this one builds on or is referenced by (optional; feeds the quality references factor).\n\nBody section order (omit only when empty):\n1. \"# <Human Title>\" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.\n2. \"## When to Use\" \u2014 concrete trigger phrases.\n3. \"## Prerequisites\" \u2014 exact env vars, install steps, credentials.\n4. \"## How to Run\" \u2014 canonical invocation framed through DSH tools.\n5. \"## Quick Reference\" \u2014 flat command/endpoint list.\n6. \"## Procedure\" \u2014 numbered steps with copy-paste-exact commands.\n7. \"## Pitfalls\" \u2014 known limits and rate limits.\n8. \"## Verification\" \u2014 one check proving the skill worked.\n\nDSH-tool framing:\n- Reference DSH tools by name in backticks: `bash`, `str_replace_editor`, `write`, `skill`, `skill_manage`, `memory`.\n- Do not name wrapped shell utilities when a DSH tool already covers them.\n- Larger scripts belong under `scripts/` (written with `skill_manage write_file`) and are referenced from SKILL.md by relative path.\n\nQuality bar:\n- Prefer verbatim flags, paths, and APIs from the source. Never invent them.\n- Keep it tight: ~100 lines simple, ~200 complex.\n- No router/index/hub skills that only point at other skills.\n- References go in `references/`, templates in `templates/`.\n\nLearn workflow (when the user asks you to learn a reusable skill, or you decide to turn a source/request into one):\n1. Gather every source named (files, URLs, \"what we just did\", pasted notes) with the tools you already have \u2014 and treat prose after a source as authoring requirements, not noise.\n2. Apply every requirement and constraint from the request to the SKILL.md you author.\n3. Author exactly ONE SKILL.md and save it with `skill_manage` (action=create); non-trivial scripts go under `scripts/`.\n4. When done, tell the user the skill name, its category, and a one-line summary of what it captured.";
 //# sourceMappingURL=prompts.d.ts.map

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.1.0-rc.61",
+  "version": "0.1.0-rc.62",
   "publishConfig": {
     "access": "public"
   },