@lmzhen/dsh-evolution-feedback 0.1.0-rc.66 → 0.1.0-rc.68

package/lib/index.js

@@ -41,6 +41,76 @@ function evolutionIoAdapter(provider) {
 		}
 	};
 }
+function eventsFile(home) {
+	return join(home, "evolution", "events.json");
+}
+function isEventRecord(event) {
+	return typeof event === "object" && event !== null && typeof event.seq === "number";
+}
+function parseEventList(raw) {
+	if (raw === null) return [];
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed.events)) return [];
+		return parsed.events.filter(isEventRecord);
+	} catch {
+		return [];
+	}
+}
+/**
+* Append one event under the write lock (rc.68): `seq` = current max + 1
+* computed inside the transact, so two processes appending concurrently never
+* collide. A malformed log is refused (bytes preserved) and the append fails.
+* Returns the assigned seq.
+*/
+async function appendEvolutionEvent(io, path, event) {
+	let assigned = 0;
+	await transactIo(io, path, (current) => {
+		if (current !== null) try {
+			JSON.parse(current);
+		} catch {
+			return Promise.resolve(current);
+		}
+		const events = parseEventList(current);
+		const maxSeq = events.reduce((max, entry) => Math.max(max, entry.seq), 0);
+		const record = {
+			...event,
+			seq: maxSeq + 1,
+			at: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		assigned = record.seq;
+		return Promise.resolve(JSON.stringify({
+			version: 1,
+			events: [...events, record]
+		}, null, 2));
+	});
+	if (assigned === 0) throw new Error(`evolution event log is malformed and was not touched: ${path}`);
+	return assigned;
+}
+/** Read the event log; a missing file reads as empty, malformed is flagged. */
+async function readEvolutionEvents(io, path) {
+	const raw = await io.readText(path);
+	if (raw === null) return {
+		events: [],
+		malformed: false
+	};
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed.events)) return {
+			events: [],
+			malformed: true
+		};
+		return {
+			events: parsed.events.filter(isEventRecord),
+			malformed: false
+		};
+	} catch {
+		return {
+			events: [],
+			malformed: true
+		};
+	}
+}
 //#endregion
 //#region ../evolution-core/src/prompts.ts
 /**
@@ -65,7 +135,7 @@ function evolutionIoAdapter(provider) {
 * changes semantically: the bundle digest is the fail-closed signal for
 * review workers, so a stale id across deployments must be distinguishable.
 */
-const PROMPT_BUNDLE_ID = "dsh-evolution@6";
+const PROMPT_BUNDLE_ID = "dsh-evolution@7";
 const MEMORY_REVIEW_PROMPT = `[Auto-review — Memory]
 Review the conversation above and consider saving to memory if appropriate.
 
@@ -86,6 +156,8 @@ Signals to look for (any one of these warrants action):
   • Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.
   • A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.
 
+Read-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session — ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.
+
 Preference order — prefer the earliest action that fits, but do pick one when a signal above fired:
   1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the conversation for skills the user loaded or you read. If any of them covers the territory of the new learning, PATCH that one first. It is the skill that was in play, so it's the right one to extend.
   2. UPDATE AN EXISTING UMBRELLA. If no loaded skill fits but an existing class-level skill does, patch it. Add a subsection, a pitfall, or broaden a trigger.
@@ -133,6 +205,8 @@ Signals that warrant a skill update (any one is enough):
   • Non-trivial technique, fix, workaround, or debugging path emerged.
   • A skill that was loaded or consulted turned out wrong, missing, or outdated — patch it now.
 
+Read-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session — ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.
+
 Preference order for skills — pick the earliest that fits:
   1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were loaded or read in the conversation. If one of them covers the learning, PATCH it first. It was in play; it's the right place.
   2. UPDATE AN EXISTING UMBRELLA. Patch it.
@@ -240,12 +314,12 @@ function sha256(text) {
 function createPromptBundle(prompts) {
 	const canonical = JSON.stringify({
 		id: PROMPT_BUNDLE_ID,
-		version: 6,
+		version: 7,
 		prompts: Object.fromEntries(Object.entries(prompts).sort())
 	});
 	return Object.freeze({
 		id: PROMPT_BUNDLE_ID,
-		version: 6,
+		version: 7,
 		prompts: Object.freeze({ ...prompts }),
 		sha256: sha256(canonical)
 	});
@@ -272,8 +346,15 @@ new RegExp(String.raw`ignore\s+${FILLER}(?:previous|above|prior|all)\s+${FILLER}
 * Feedback is durable through `ctx.evolutionIo` (when mounted) and skill
 * feedback feeds `quality_score` / `quality_warn` on the usage record, so
 * curator decisions can consume it deterministically.
+*
+* Persistence (rc.68): the EVENTS LOG (`evolution/events.json`, via
+* `evolution-core/evolution-events.ts`) is the single source of truth —
+* every increment appends one event under the write lock. `feedback.json` is
+* a rebuildable BOOT CACHE (`{ version: 2, lastSeq, skills, sessions }`),
+* never the truth; the in-memory state is the optimistic aggregate.
 * @module @lmzhen/dsh-evolution-feedback
 */
+const CACHE_VERSION = 2;
 var EvolutionFeedback = class {
 	state = {
 		skills: {},
@@ -281,9 +362,13 @@ var EvolutionFeedback = class {
 	};
 	chain = Promise.resolve();
 	path;
+	eventsPath;
 	io;
 	constructor(io, home = process.env.DSH_HOME ?? join(homedir(), ".dsh"), pathOverride) {
-		if (io) this.path = pathOverride ?? join(home, "evolution", "feedback.json");
+		if (io) {
+			this.path = pathOverride ?? join(home, "evolution", "feedback.json");
+			this.eventsPath = eventsFile(home);
+		}
 		this.io = io;
 	}
 	mutate(task) {
@@ -293,26 +378,45 @@ var EvolutionFeedback = class {
 	}
 	async restore(io) {
 		const path = this.path;
-		if (!path) return;
+		const eventsPath = this.eventsPath;
+		if (!path || !eventsPath) return;
 		await this.mutate(async () => {
-			const raw = await io.readText(path);
-			if (raw === null) return;
-			try {
-				const parsed = JSON.parse(raw);
-				this.state = {
-					skills: {
-						...parsed.skills,
-						...this.state.skills
-					},
-					sessions: {
-						...parsed.sessions,
-						...this.state.sessions
-					}
-				};
+			if (await io.readText(eventsPath) === null) {
+				const aggregate = parseAggregate(await io.readText(path));
+				if (aggregate) try {
+					await transactIo(io, eventsPath, (current) => {
+						if (current !== null) return Promise.resolve(current);
+						return Promise.resolve(JSON.stringify({
+							version: 1,
+							events: synthesizeFeedbackEvents(aggregate)
+						}, null, 2));
+					});
+				} catch {}
+			}
+			const { events } = await readEvolutionEvents(io, eventsPath);
+			const cache = parseCache(await io.readText(path));
+			const maxSeq = events.reduce((max, event) => Math.max(max, event.seq), 0);
+			const truth = cache ? foldWithDelta(cache, events) : foldFeedbackState(events);
+			this.state = {
+				skills: {
+					...truth.skills,
+					...this.state.skills
+				},
+				sessions: {
+					...truth.sessions,
+					...this.state.sessions
+				}
+			};
+			if (maxSeq > 0 && (!cache || cache.lastSeq < maxSeq)) try {
+				await io.writeText(path, JSON.stringify({
+					version: CACHE_VERSION,
+					lastSeq: maxSeq,
+					...truth
+				}, null, 2));
 			} catch {}
 		});
 	}
-	record(target, rating, note, kind = "session", io) {
+	record(target, rating, note, kind = "session") {
 		const mode = kind === "skill" ? "skills" : "sessions";
 		const table = this.state[mode];
 		const current = table[target] ?? {
@@ -322,28 +426,17 @@ var EvolutionFeedback = class {
 		current[rating] += 1;
 		if (note !== void 0) current.lastNote = note;
 		table[target] = current;
-		const recordIo = io ?? this.io;
-		const path = this.path;
-		if (!recordIo || !path) return;
+		const recordIo = this.io;
+		const eventsPath = this.eventsPath;
+		if (!recordIo || !eventsPath) return;
 		this.mutate(async () => {
 			try {
-				await transactIo(recordIo, path, (raw) => {
-					if (raw !== null) try {
-						JSON.parse(raw);
-					} catch {
-						return Promise.resolve(raw);
-					}
-					const diskState = parseState(raw);
-					const diskTable = diskState[mode];
-					const diskRec = diskTable[target] ?? {
-						positive: 0,
-						negative: 0
-					};
-					diskRec[rating] += 1;
-					if (note !== void 0) diskRec.lastNote = note;
-					diskTable[target] = diskRec;
-					this.state = diskState;
-					return Promise.resolve(JSON.stringify(diskState, null, 2));
+				await appendEvolutionEvent(recordIo, eventsPath, {
+					type: "feedback",
+					target,
+					kind,
+					rating,
+					note
 				});
 			} catch (error) {}
 		});
@@ -365,26 +458,128 @@ var EvolutionFeedback = class {
 	waitIdle() {
 		return this.chain;
 	}
+	/** Rebuild the boot cache from the log truth (rc.68); best-effort. */
+	persistCache() {
+		const path = this.path;
+		const eventsPath = this.eventsPath;
+		const recordIo = this.io;
+		if (!path || !eventsPath || !recordIo) return Promise.resolve();
+		return this.mutate(async () => {
+			try {
+				const { events } = await readEvolutionEvents(recordIo, eventsPath);
+				const maxSeq = events.reduce((max, event) => Math.max(max, event.seq), 0);
+				if (maxSeq === 0) return;
+				await recordIo.writeText(path, JSON.stringify({
+					version: CACHE_VERSION,
+					lastSeq: maxSeq,
+					...foldFeedbackState(events)
+				}, null, 2));
+			} catch {}
+		});
+	}
 };
-/** Parse a raw feedback sidecar; malformed reads as empty (best-effort). */
-function parseState(raw) {
-	if (raw === null) return {
-		skills: {},
-		sessions: {}
-	};
+/** Parse a legacy aggregate (v1) or a v2 cache into a plain aggregate state. */
+function parseAggregate(raw) {
+	if (raw === null) return null;
 	try {
 		const parsed = JSON.parse(raw);
+		const skills = isRecord(parsed.skills) ? parsed.skills : void 0;
+		const sessions = isRecord(parsed.sessions) ? parsed.sessions : void 0;
+		if (!skills && !sessions) return null;
 		return {
-			skills: typeof parsed.skills === "object" && !Array.isArray(parsed.skills) ? parsed.skills : {},
-			sessions: typeof parsed.sessions === "object" && !Array.isArray(parsed.sessions) ? parsed.sessions : {}
+			skills: skills ?? {},
+			sessions: sessions ?? {}
 		};
 	} catch {
+		return null;
+	}
+}
+function parseCache(raw) {
+	if (raw === null) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed.version !== CACHE_VERSION || typeof parsed.lastSeq !== "number") return null;
+		if (!isRecord(parsed.skills) || !isRecord(parsed.sessions)) return null;
 		return {
-			skills: {},
-			sessions: {}
+			lastSeq: parsed.lastSeq,
+			state: {
+				skills: parsed.skills,
+				sessions: parsed.sessions
+			}
 		};
+	} catch {
+		return null;
 	}
 }
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Fold all feedback events from zero (the truth view). */
+function foldFeedbackState(events) {
+	const state = {
+		skills: {},
+		sessions: {}
+	};
+	for (const event of events) applyFeedbackEvent(state, event);
+	return state;
+}
+/** Fold events after the cache's lastSeq onto the cached aggregates. */
+function foldWithDelta(cache, events) {
+	const state = {
+		skills: { ...cache.state.skills },
+		sessions: { ...cache.state.sessions }
+	};
+	for (const event of events) if (event.seq > cache.lastSeq) applyFeedbackEvent(state, event);
+	return state;
+}
+function applyFeedbackEvent(state, event) {
+	if (event.type !== "feedback") return;
+	const target = event.target;
+	if (target === void 0 || event.rating === void 0) return;
+	const table = event.kind === "skill" ? state.skills : state.sessions;
+	const record = table[target] ?? {
+		positive: 0,
+		negative: 0
+	};
+	record[event.rating] += 1;
+	if (event.note !== void 0) record.lastNote = event.note;
+	table[target] = record;
+}
+/** Synthesize one event per aggregate count unit, lastNote on the final event (migration). */
+function synthesizeFeedbackEvents(aggregate) {
+	const events = [];
+	const at = (/* @__PURE__ */ new Date()).toISOString();
+	const emitTarget = (kind, target, record) => {
+		const first = events.length + 1;
+		for (let index = 0; index < record.positive; index += 1) events.push({
+			seq: events.length + 1,
+			at,
+			type: "feedback",
+			kind,
+			target,
+			rating: "positive"
+		});
+		for (let index = 0; index < record.negative; index += 1) events.push({
+			seq: events.length + 1,
+			at,
+			type: "feedback",
+			kind,
+			target,
+			rating: "negative"
+		});
+		if (record.lastNote !== void 0 && events.length >= first) {
+			const last = events.length - 1;
+			const final = events[last];
+			if (final) events[last] = {
+				...final,
+				note: record.lastNote
+			};
+		}
+	};
+	for (const [target, record] of Object.entries(aggregate.skills)) emitTarget("skill", target, record);
+	for (const [target, record] of Object.entries(aggregate.sessions)) emitTarget("session", target, record);
+	return events;
+}
 const name = "evolution-feedback";
 const Config = z.object({
 	qualityWarnThreshold: z.number().default(-.25),
@@ -401,8 +596,8 @@ function apply(ctx, rawConfig = {}) {
 	const skillUsage = ctx.get("skillUsage");
 	if (skillUsage) {
 		const original = feedback.record.bind(feedback);
-		feedback.record = (target, rating, note, kind, recordIo) => {
-			original(target, rating, note, kind ?? "session", recordIo ?? io);
+		feedback.record = (target, rating, note, kind) => {
+			original(target, rating, note, kind ?? "session");
 			if (kind === "skill") {
 				const score = feedback.score(target, "skill");
 				const warn = score < (rawConfig.qualityWarnThreshold ?? -.25);
@@ -413,7 +608,7 @@ function apply(ctx, rawConfig = {}) {
 		};
 	}
 	ctx.effect(() => () => {
-		return feedback.waitIdle();
+		return Promise.all([feedback.persistCache(), feedback.waitIdle()]);
 	}, "evolution-feedback.records");
 }
 //#endregion

package/lib/types/index.d.ts

@@ -4,6 +4,12 @@
  * Feedback is durable through `ctx.evolutionIo` (when mounted) and skill
  * feedback feeds `quality_score` / `quality_warn` on the usage record, so
  * curator decisions can consume it deterministically.
+ *
+ * Persistence (rc.68): the EVENTS LOG (`evolution/events.json`, via
+ * `evolution-core/evolution-events.ts`) is the single source of truth —
+ * every increment appends one event under the write lock. `feedback.json` is
+ * a rebuildable BOOT CACHE (`{ version: 2, lastSeq, skills, sessions }`),
+ * never the truth; the in-memory state is the optimistic aggregate.
  * @module @deepseek-ai/dsh-evolution-feedback
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -28,21 +34,25 @@ export declare class EvolutionFeedback {
     private state;
     private chain;
     private readonly path?;
+    private readonly eventsPath?;
     private readonly io;
     constructor(io?: IoLike, home?: string, pathOverride?: string);
     private mutate;
     restore(io: IoLike): Promise<void>;
-    record(target: string, rating: 'positive' | 'negative', note?: string, kind?: 'skill' | 'session', io?: IoLike): void;
+    record(target: string, rating: 'positive' | 'negative', note?: string, kind?: 'skill' | 'session'): void;
     score(target: string, kind?: 'skill' | 'session'): number;
     snapshot(): FeedbackState;
     /** Await the pending record-task chain (unload safety; rc.66). */
     waitIdle(): Promise<unknown>;
+    /** Rebuild the boot cache from the log truth (rc.68); best-effort. */
+    persistCache(): Promise<void>;
 }
 export declare const name = "evolution-feedback";
 export interface Config {
     /** Score below which curator receives quality_warn for a skill. */
     qualityWarnThreshold?: number;
-    /** Explicit feedback file path; empty derives $DSH_HOME/evolution/feedback.json. */
+    /** Explicit boot-cache file path; empty derives $DSH_HOME/evolution/feedback.json
+     * (the event log is its sibling `events.json`). */
     path?: string;
 }
 export declare const Config: z<Config>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-feedback",
   "description": "Feedback-to-quality scoring for self-evolution (community build)",
-  "version": "0.1.0-rc.66",
+  "version": "0.1.0-rc.68",
   "publishConfig": {
     "access": "public"
   },
@@ -37,13 +37,13 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.66",
-    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.66"
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.68",
+    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.68"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.66",
-    "@lmzhen/dsh-evolution-io-node": "^0.1.0-rc.66",
-    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.66"
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.68",
+    "@lmzhen/dsh-evolution-io-node": "^0.1.0-rc.68",
+    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.68"
   }
 }