@lmzhen/dsh-evolution-learning-graph 0.3.16 → 0.3.18

package/README.md

@@ -2,12 +2,20 @@
 
 Learning graph over skills and memory
 
+## Graph surface
+
+`/graph` renders the learning graph. A skill node is its name; a memory node is `memory:<source>:<index>`, where `<source>` is `memory`|`user` and `<index>` is the position in that file's entries.
+
+Memory node ids carry a trailing snapshot token (`memory:<source>:<index>:<snapshot>` — an 8-hex digest of the node label's first line). It exists so `graph edit`/`graph delete` can detect index drift: any memory write between the last render and the command shifts indices, and a stale id is rejected (requiring a re-run of `/graph`) instead of mutating a different entry.
+
+Memory→skill edges are word-level, not substring: the entry is tokenized on non-letter/digit/hyphen runs and a skill name links only when it is a whole token. This prevents a skill named `run` from linking the words `running`/`grunt`.
+
+`graph edit`/`graph delete` of a skill node route through the evolution approval seam when it is mounted (soft-probed; the write executes directly when it is absent). Each approved/executed edit bumps the skill's patch counter and a delete archives it, matching `skill_manage`.
+
 ## Model Experience
 
 ### Indirect model surface
 
-#### What the model sees
-
 `@deepseek-ai/dsh-evolution-learning-graph` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
 
 #### Token effect
@@ -20,5 +28,5 @@ Independent of request-prefix construction. This package does not alter the asse
 
 ## Known Limitations and Deferred Work
 
-
-- No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.
+- The memory drift snapshot covers only the node label (first line, first 80 chars): a change confined to a later line of the same entry is not detected, because the rendered node label is the comparison anchor.
+- A hand-typed bare `memory:<source>:<index>` id has no snapshot and skips the drift check (legacy path; the rendered ids always carry the snapshot).

package/lib/index.js

@@ -1,11 +1,12 @@
-import { SKILL_NAME_RE, SkillLibrary, evolutionIoAdapter, relatedSkillNames } from "@lmzhen/dsh-evolution-core";
+import { SKILL_NAME_RE, SkillLibrary, evolutionIoAdapter, relatedSkillNames, resolveOrigins, resolveSkillsRoot } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Learning graph over skills and memory, plus node-level commands
 * (`/evolution graph [detail|edit|delete] <nodeId>`) aligned with the Hermes
 * journey surface: a skill node is its name, a memory node is
 * `memory:<source>:<index>` (source = memory|user, index = position in that
-* file's entries).
+* file's entries). Memory node ids carry a trailing snapshot token so
+* edit/delete can reject a stale index (E-21).
 * @module @lmzhen/dsh-evolution-learning-graph
 */
 function graphDensity(graph) {
@@ -64,14 +65,15 @@ function buildLearningGraph(usage, memoryEntries, userEntries = [], related) {
 	}
 	const appendMemory = (source, entries) => {
 		entries.forEach((entry, index) => {
-			const id = `memory:${source}:${index}`;
+			const label = (entry.split("\n")[0] ?? "").slice(0, 80);
+			const id = `memory:${source}:${index}:${memorySnapshotOf(label)}`;
 			nodes.push({
 				id,
 				kind: "memory",
-				label: entry.split("\n")[0]?.slice(0, 80) ?? id
+				label
 			});
-			const token = entry.toLowerCase();
-			for (const name of sorted) if (name && token.includes(name.toLowerCase())) edges.push({
+			const words = new Set(entry.toLowerCase().split(/[^a-z0-9-]+/).filter(Boolean));
+			for (const name of sorted) if (name && words.has(name.toLowerCase())) edges.push({
 				from: id,
 				to: name,
 				type: "memory_skill"
@@ -85,13 +87,61 @@ function buildLearningGraph(usage, memoryEntries, userEntries = [], related) {
 		edges
 	};
 }
-/** Parse a graph node id: skill names pass through; `memory:<source>:<index>` becomes a memory node. */
+/**
+* E-21 snapshot token: a deterministic 8-hex-char digest of a memory entry's
+* rendered label (first line, first 80 chars). The graph builder embeds it in
+* the memory node id so a later edit/delete can detect index drift — any
+* memory write between the last render and the command shifts `memory:<source>:<index>`
+* positions, and the token lets the command reject a stale index instead of
+* mutating the wrong entry. FNV-1a (no imports, cross-platform).
+*/
+function memorySnapshotOf(entry) {
+	const label = (entry.split("\n")[0] ?? "").slice(0, 80);
+	let hash = 2166136261;
+	for (let i = 0; i < label.length; i += 1) {
+		hash ^= label.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0").slice(-8);
+}
+/**
+* E-21 TOCTOU guard for a memory node operation. Re-reads the entry at
+* `parsed.index` and, when the id carries a snapshot token, verifies the
+* current entry's label still matches it. A mismatch means a memory write
+* shifted the index between the last `/graph` render and this command, so the
+* operation is refused (the caller surfaces "re-run /graph"). A missing
+* snapshot (a hand-typed bare `memory:<source>:<index>` id) skips the check
+* and falls back to operating on whatever currently sits at the index.
+*/
+function readMemoryIndex(parsed, entries) {
+	const entry = entries[parsed.index];
+	if (entry === void 0) return {
+		ok: false,
+		message: `Memory ${parsed.source}[${parsed.index}] does not exist (${entries.length} entries).`
+	};
+	if (parsed.snapshot !== void 0 && memorySnapshotOf(entry) !== parsed.snapshot) return {
+		ok: false,
+		message: `Memory ${parsed.source}[${parsed.index}] changed since the graph was rendered; run /graph again and retry.`
+	};
+	return {
+		ok: true,
+		entry
+	};
+}
+/**
+* Parse a graph node id: skill names pass through; `memory:<source>:<index>`
+* becomes a memory node. An optional trailing `:<snapshot>` (the E-21
+* `memorySnapshotOf` token the builder embeds) is carried so edit/delete can
+* detect index drift; a bare index id (hand-typed) still parses with no
+* snapshot and skips the drift check.
+*/
 function parseGraphNodeId(id) {
-	const memory = /^memory:(memory|user):(\d+)$/.exec(id);
+	const memory = /^memory:(memory|user):(\d+)(?::([0-9a-f]{8}))?$/.exec(id);
 	if (memory) return {
 		kind: "memory",
 		source: memory[1],
-		index: Number(memory[2])
+		index: Number(memory[2]),
+		...memory[3] !== void 0 ? { snapshot: memory[3] } : {}
 	};
 	if (SKILL_NAME_RE.test(id)) return {
 		kind: "skill",
@@ -175,7 +225,7 @@ function apply(ctx) {
 					return lines.join("\n") + "\n\n" + edges.join("\n") + densityLine;
 				}
 				function withSkills() {
-					return new SkillLibrary(void 0, evolutionIoAdapter(() => io.provider()), void 0, (event) => {
+					return new SkillLibrary(resolveSkillsRoot(), evolutionIoAdapter(() => io.provider()), void 0, (event) => {
 						ctx.emit("evolution/skill-mutated", event);
 					});
 				}
@@ -192,15 +242,34 @@ function apply(ctx) {
 					const parsed = parseGraphNodeId(id);
 					if (parsed === null) return err(`Invalid node id "${id}". Skill names or memory:<source>:<index> expected.`);
 					if (parsed.kind === "skill") {
+						const approval = ctx.get("evolutionApproval");
+						if (approval) {
+							const origins = resolveOrigins(void 0);
+							const decision = await approval.request({
+								kind: "skill",
+								summary: `graph edit ${parsed.name}`,
+								args: {
+									operation: {
+										action: "update",
+										name: parsed.name,
+										content
+									},
+									origin: origins.approval,
+									libraryOrigin: origins.library
+								},
+								origin: origins.approval
+							});
+							if (decision.action === "staged") return ok(decision.message);
+						}
 						const result = await withSkills().update(parsed.name, content, "foreground");
+						if (result.ok) await usageService.record?.(parsed.name, "patch");
 						return result.ok ? ok(result.message) : err(result.message);
 					}
-					const entries = await memory.read(parsed.source);
-					const entry = entries[parsed.index];
-					if (entry === void 0) return err(`Memory ${parsed.source}[${parsed.index}] does not exist (${entries.length} entries).`);
+					const check = readMemoryIndex(parsed, await memory.read(parsed.source));
+					if (!check.ok) return err(check.message ?? "Memory index check failed.");
 					const result = await memory.applyBatch(parsed.source, [{
 						action: "replace",
-						old_text: entry,
+						old_text: check.entry ?? "",
 						facts: content
 					}]);
 					return result.ok ? ok(result.message) : err(result.message);
@@ -209,16 +278,33 @@ function apply(ctx) {
 					const parsed = parseGraphNodeId(id);
 					if (parsed === null) return err(`Invalid node id "${id}". Skill names or memory:<source>:<index> expected.`);
 					if (parsed.kind === "skill") {
+						const approval = ctx.get("evolutionApproval");
+						if (approval) {
+							const origins = resolveOrigins(void 0);
+							const decision = await approval.request({
+								kind: "skill",
+								summary: `graph delete ${parsed.name}`,
+								args: {
+									operation: {
+										action: "delete",
+										name: parsed.name
+									},
+									origin: origins.approval,
+									libraryOrigin: origins.library
+								},
+								origin: origins.approval
+							});
+							if (decision.action === "staged") return ok(decision.message);
+						}
 						const result = await withSkills().archive(parsed.name);
 						if (result.ok) await usageService?.markArchived?.(parsed.name);
 						return result.ok ? ok(result.message) : err(result.message);
 					}
-					const entries = await memory.read(parsed.source);
-					const entry = entries[parsed.index];
-					if (entry === void 0) return err(`Memory ${parsed.source}[${parsed.index}] does not exist (${entries.length} entries).`);
+					const check = readMemoryIndex(parsed, await memory.read(parsed.source));
+					if (!check.ok) return err(check.message ?? "Memory index check failed.");
 					const result = await memory.applyBatch(parsed.source, [{
 						action: "remove",
-						old_text: entry
+						old_text: check.entry ?? ""
 					}]);
 					return result.ok ? ok(result.message) : err(result.message);
 				}
@@ -227,4 +313,4 @@ function apply(ctx) {
 	});
 }
 //#endregion
-export { apply, buildLearningGraph, graphDensity, name, parseGraphNodeId, resolveGraphNode };
+export { apply, buildLearningGraph, graphDensity, memorySnapshotOf, name, parseGraphNodeId, readMemoryIndex, resolveGraphNode };

package/lib/types/index.d.ts

@@ -3,7 +3,8 @@
  * (`/evolution graph [detail|edit|delete] <nodeId>`) aligned with the Hermes
  * journey surface: a skill node is its name, a memory node is
  * `memory:<source>:<index>` (source = memory|user, index = position in that
- * file's entries).
+ * file's entries). Memory node ids carry a trailing snapshot token so
+ * edit/delete can reject a stale index (E-21).
  * @module @deepseek-ai/dsh-evolution-learning-graph
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -47,10 +48,7 @@ export declare function graphDensity(graph: LearningGraph): GraphDensity;
  * omitted `related` yields no skill-skill edges — the former alphabet-order
  * chain was a placeholder that connected unrelated neighbors.
  */
-export declare function buildLearningGraph(usage: ReadonlyMap<string, {
-    use_count?: number;
-    pinned?: boolean;
-}>, memoryEntries: readonly string[], userEntries?: readonly string[], related?: ReadonlyMap<string, readonly string[]>): LearningGraph;
+export declare function buildLearningGraph(usage: ReadonlyMap<string, unknown>, memoryEntries: readonly string[], userEntries?: readonly string[], related?: ReadonlyMap<string, readonly string[]>): LearningGraph;
 export type GraphNodeId = {
     kind: 'skill';
     name: string;
@@ -58,8 +56,42 @@ export type GraphNodeId = {
     kind: 'memory';
     source: 'memory' | 'user';
     index: number;
+    snapshot?: string;
 };
-/** Parse a graph node id: skill names pass through; `memory:<source>:<index>` becomes a memory node. */
+/**
+ * E-21 snapshot token: a deterministic 8-hex-char digest of a memory entry's
+ * rendered label (first line, first 80 chars). The graph builder embeds it in
+ * the memory node id so a later edit/delete can detect index drift — any
+ * memory write between the last render and the command shifts `memory:<source>:<index>`
+ * positions, and the token lets the command reject a stale index instead of
+ * mutating the wrong entry. FNV-1a (no imports, cross-platform).
+ */
+export declare function memorySnapshotOf(entry: string): string;
+export interface MemoryIndexCheck {
+    ok: boolean;
+    /** The current entry at the index, present when ok. */
+    entry?: string;
+    message?: string;
+}
+/**
+ * E-21 TOCTOU guard for a memory node operation. Re-reads the entry at
+ * `parsed.index` and, when the id carries a snapshot token, verifies the
+ * current entry's label still matches it. A mismatch means a memory write
+ * shifted the index between the last `/graph` render and this command, so the
+ * operation is refused (the caller surfaces "re-run /graph"). A missing
+ * snapshot (a hand-typed bare `memory:<source>:<index>` id) skips the check
+ * and falls back to operating on whatever currently sits at the index.
+ */
+export declare function readMemoryIndex(parsed: Extract<GraphNodeId, {
+    kind: 'memory';
+}>, entries: readonly string[]): MemoryIndexCheck;
+/**
+ * Parse a graph node id: skill names pass through; `memory:<source>:<index>`
+ * becomes a memory node. An optional trailing `:<snapshot>` (the E-21
+ * `memorySnapshotOf` token the builder embeds) is carried so edit/delete can
+ * detect index drift; a bare index id (hand-typed) still parses with no
+ * snapshot and skips the drift check.
+ */
 export declare function parseGraphNodeId(id: string): GraphNodeId | null;
 /** Resolve a parsed node to its current content (read-only). */
 export declare function resolveGraphNode(parsed: GraphNodeId, repository: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-learning-graph",
   "description": "Learning graph over skills and memory (community build)",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "publishConfig": {
     "access": "public"
   },
@@ -33,7 +33,7 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.16"
+    "@lmzhen/dsh-evolution-core": "^0.3.18"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",