@lmzhen/dsh-evolution-feedback 0.1.0-rc.67 → 0.1.0-rc.69

package/lib/index.js

@@ -41,6 +41,82 @@ 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";
+}
+/**
+* Parse an event log body. A missing file, a whitespace-only file (rc.69:
+* rebuildable, NOT malformed) or a corrupt one reads as empty; corrupt content
+* is still refused on append, never overwritten.
+*/
+function parseEvolutionEvents(raw) {
+	if (raw === null || raw.trim() === "") 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 && current.trim() !== "") try {
+			JSON.parse(current);
+		} catch {
+			return Promise.resolve(current);
+		}
+		const events = parseEvolutionEvents(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/whitespace-only file reads as empty,
+* corrupt content is flagged (and refused on append). */
+async function readEvolutionEvents(io, path) {
+	const raw = await io.readText(path);
+	if (raw === null || raw.trim() === "") 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
 /**
@@ -276,8 +352,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: {},
@@ -285,9 +368,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) {
@@ -297,26 +384,40 @@ 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
-					}
-				};
+			const rawEvents = await io.readText(eventsPath);
+			if (rawEvents === null || rawEvents.trim() === "") {
+				const aggregate = parseAggregate(await io.readText(path));
+				if (aggregate) try {
+					await migrateFeedbackEvents(io, eventsPath, aggregate);
+				} 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] ?? {
@@ -326,28 +427,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) {}
 		});
@@ -369,26 +459,175 @@ 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: {}
-	};
+/** True when `existing` contains the legacy sequence as a contiguous run on
+* its semantic fields (skip case). `seq` and `at` are excluded: after a merge
+* the legacy events carry shifted seqs, and a re-synthesis stamps a different
+* `at` — the semantic identity is type/kind/target/rating/note. A coincidental
+* semantic match of an already-appended user sequence yields the identical
+* aggregation, so the skip is harmless for counts and notes. */
+function containsLegacySequence(existing, expected) {
+	if (expected.length === 0) return true;
+	for (let start = 0; start <= existing.length - expected.length; start += 1) {
+		let match = true;
+		for (let offset = 0; offset < expected.length; offset += 1) {
+			const a = expected[offset];
+			const b = existing[start + offset];
+			if (!a || !b || a.type !== b.type || a.kind !== b.kind || a.target !== b.target || a.rating !== b.rating || a.note !== b.note) {
+				match = false;
+				break;
+			}
+		}
+		if (match) return true;
+	}
+	return false;
+}
+/**
+* Merge a legacy aggregate into the event log (rc.69): the expected synthetic
+* sequence is APPENDED (seq-shifted) when the log does not already contain it
+* — so a concurrent first writer's events AND the legacy history both
+* survive; when the sequence is already present the migration was completed
+* (by a first writer or by this path) and nothing is re-appended. Idempotent
+* and race-safe (the search runs inside the same transact). Exported for the
+* migration-race regression test.
+*/
+async function migrateFeedbackEvents(io, eventsPath, aggregate) {
+	const expected = synthesizeFeedbackEvents(aggregate);
+	await transactIo(io, eventsPath, (current) => {
+		const existing = parseEvolutionEvents(current);
+		if (containsLegacySequence(existing, expected)) return Promise.resolve(current ?? "");
+		const maxSeq = existing.reduce((max, event) => Math.max(max, event.seq), 0);
+		const merged = [...existing, ...expected.map((event, index) => ({
+			...event,
+			seq: maxSeq + index + 1
+		}))];
+		return Promise.resolve(JSON.stringify({
+			version: 1,
+			events: merged
+		}, null, 2));
+	});
+}
+/** 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),
@@ -405,8 +644,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);
@@ -417,8 +656,8 @@ function apply(ctx, rawConfig = {}) {
 		};
 	}
 	ctx.effect(() => () => {
-		return feedback.waitIdle();
+		return Promise.all([feedback.persistCache(), feedback.waitIdle()]);
 	}, "evolution-feedback.records");
 }
 //#endregion
-export { Config, EvolutionFeedback, apply, name };
+export { Config, EvolutionFeedback, apply, migrateFeedbackEvents, name };

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,36 @@ 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>;
 }
+/**
+ * Merge a legacy aggregate into the event log (rc.69): the expected synthetic
+ * sequence is APPENDED (seq-shifted) when the log does not already contain it
+ * — so a concurrent first writer's events AND the legacy history both
+ * survive; when the sequence is already present the migration was completed
+ * (by a first writer or by this path) and nothing is re-appended. Idempotent
+ * and race-safe (the search runs inside the same transact). Exported for the
+ * migration-race regression test.
+ */
+export declare function migrateFeedbackEvents(io: IoLike, eventsPath: string, aggregate: FeedbackState): 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 always stays at $DSH_HOME/evolution/events.json (derived from
+     * home, never from this override). */
     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.67",
+  "version": "0.1.0-rc.69",
   "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.67",
-    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.67"
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.69",
+    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.69"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.67",
-    "@lmzhen/dsh-evolution-io-node": "^0.1.0-rc.67",
-    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.67"
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.69",
+    "@lmzhen/dsh-evolution-io-node": "^0.1.0-rc.69",
+    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.69"
   }
 }