@lmzhen/dsh-evolution-state-json 0.3.27 → 0.3.29

package/lib/index.js

@@ -40,21 +40,47 @@ const RECORD_MAP_FILES = new Set([
 	"pending-state.json",
 	"pending.json"
 ]);
+/** 0.3.17 (E-9): a malformed state file used to parse to `null` and was then
+* OVERWRITTEN by the next save — every other session's review state / the
+* whole pending table vanished silently. Fail loud instead: preserve the
+* original bytes beside it and throw, so the operator can rescue and the
+* corruption is never accepted as "empty". */
+async function quarantine(io, root, file, raw, reason) {
+	const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+	const dest = `${join(root, file)}.corrupt-${stamp}-${Math.random().toString(36).slice(2, 6)}`;
+	await io().writeText(dest, raw).catch(() => {});
+	throw new Error(`evolution state file "${file}" is not valid JSON (${reason}); original preserved at ${dest} — inspect and fix it, then retry.`);
+}
+/**
+* Cross-process JSON-file RMW (v3-audit M-8): every read-modify-write state
+* mutation runs inside the IO backend's transact lock (via transactIo) so a
+* second process sharing DSH_HOME cannot interleave its claim/resolve.
+* `task` returns the next value (null = keep); for a record-map file the
+* return must be null or a plain object map of records, and an array/scalar
+* would be persisted as a corrupt map — so it fails loud before any write
+* (0.3.28, V4-08). The legacy `pending.json` merge stays inside the task via
+* `readJson` where relevant.
+*/
+async function jsonTransact(io, root, file, task) {
+	await transactIo(io(), join(root, file), async (current) => {
+		let parsed = null;
+		if (current !== null) {
+			try {
+				parsed = JSON.parse(current);
+			} catch (error) {
+				return await quarantine(io, root, file, current, error instanceof Error ? error.message : String(error));
+			}
+			if (RECORD_MAP_FILES.has(file) && !isPlainRecord(parsed)) return await quarantine(io, root, file, current, `expected a plain JSON object (map of records), got ${Array.isArray(parsed) ? "an array" : parsed === null ? "null" : typeof parsed}`);
+		}
+		const next = await task(parsed);
+		if (next !== null && RECORD_MAP_FILES.has(file) && !isPlainRecord(next)) throw new Error(`evolution state file "${file}" task returned ${Array.isArray(next) ? "an array" : typeof next} (expected null or a plain JSON object map of records); not written.`);
+		return next === null ? null : JSON.stringify(next, null, 2);
+	});
+}
 function apply(ctx, rawConfig) {
 	const root = (rawConfig.root ?? "").trim() || evolutionHome();
 	const io = () => ctx.evolutionIo.provider();
 	const pathOf = (file) => join(root, file);
-	/** 0.3.17 (E-9): a malformed state file used to parse to `null` and was then
-	* OVERWRITTEN by the next save — every other session's review state / the
-	* whole pending table vanished silently. Fail loud instead: preserve the
-	* original bytes beside it and throw, so the operator can rescue and the
-	* corruption is never accepted as "empty". */
-	async function quarantine(file, raw, reason) {
-		const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-		const dest = `${pathOf(file)}.corrupt-${stamp}-${Math.random().toString(36).slice(2, 6)}`;
-		await io().writeText(dest, raw).catch(() => {});
-		throw new Error(`evolution state file "${file}" is not valid JSON (${reason}); original preserved at ${dest} — inspect and fix it, then retry.`);
-	}
 	async function readJson(file) {
 		const raw = await io().readText(pathOf(file));
 		if (raw === null) return null;
@@ -62,40 +88,47 @@ function apply(ctx, rawConfig) {
 		try {
 			parsed = JSON.parse(raw);
 		} catch (error) {
-			return await quarantine(file, raw, error instanceof Error ? error.message : String(error));
+			return await quarantine(io, root, file, raw, error instanceof Error ? error.message : String(error));
 		}
-		if (RECORD_MAP_FILES.has(file) && !isPlainRecord(parsed)) return await quarantine(file, raw, `expected a plain JSON object (map of records), got ${Array.isArray(parsed) ? "an array" : parsed === null ? "null" : typeof parsed}`);
+		if (RECORD_MAP_FILES.has(file) && !isPlainRecord(parsed)) return await quarantine(io, root, file, raw, `expected a plain JSON object (map of records), got ${Array.isArray(parsed) ? "an array" : parsed === null ? "null" : typeof parsed}`);
 		return parsed;
 	}
-	/**
-	* Cross-process JSON-file RMW (v3-audit M-8): every read-modify-write state
-	* mutation runs inside the IO backend's transact lock (via transactIo) so a
-	* second process sharing DSH_HOME cannot interleave its claim/resolve.
-	* `task` returns the next value (null = delete); the legacy `pending.json`
-	* merge stays inside the task via `readJson` where relevant.
-	*/
-	async function jsonTransact(file, task) {
-		await transactIo(ctx.evolutionIo.provider(), pathOf(file), async (current) => {
-			let parsed = null;
-			if (current !== null) {
-				try {
-					parsed = JSON.parse(current);
-				} catch (error) {
-					return await quarantine(file, current, error instanceof Error ? error.message : String(error));
+	const mutate = makeSerialQueue();
+	let legacyMigrated = false;
+	async function retireLegacyOnce(legacy, current) {
+		if (legacyMigrated) return {};
+		try {
+			const archivedIds = /* @__PURE__ */ new Set();
+			try {
+				const rawArchive = await readJson("pending-state-archive.json");
+				if (Array.isArray(rawArchive)) {
+					for (const entry of rawArchive) if (entry && typeof entry.id === "string") archivedIds.add(entry.id);
 				}
-				if (RECORD_MAP_FILES.has(file) && !isPlainRecord(parsed)) return await quarantine(file, current, `expected a plain JSON object (map of records), got ${Array.isArray(parsed) ? "an array" : parsed === null ? "null" : typeof parsed}`);
+			} catch {}
+			const retired = {};
+			for (const [id, record] of Object.entries(legacy)) {
+				if (id in (current ?? {})) continue;
+				if (archivedIds.has(id)) continue;
+				retired[id] = record;
 			}
-			const next = await task(parsed);
-			return next === null ? null : JSON.stringify(next, null, 2);
-		});
+			await jsonTransact(io, root, "pending-state.json", () => ({
+				...retired,
+				...current ?? {}
+			}));
+			await io().rename(pathOf("pending.json"), pathOf("pending.json.migrated"));
+			legacyMigrated = true;
+			return retired;
+		} catch {
+			return legacy;
+		}
 	}
-	const mutate = makeSerialQueue();
 	async function loadPendingMap() {
 		const [current, legacy] = await Promise.all([readJson("pending-state.json"), readJson("pending.json")]);
-		return {
-			...legacy ?? {},
+		if (legacy !== null) return {
+			...await retireLegacyOnce(legacy, current),
 			...current ?? {}
 		};
+		return { ...current ?? {} };
 	}
 	/** 0.3.22 (F-336): when the live pending map holds more than
 	* `PENDING_RESOLVED_CAP` resolved records, drop the oldest (by resolvedAt,
@@ -110,12 +143,15 @@ function apply(ctx, rawConfig) {
 			evicted: []
 		};
 		const overflow = resolved.length - PENDING_RESOLVED_CAP;
-		const oldest = resolved.sort((a, b) => {
-			return (a.resolvedAt ? Date.parse(a.resolvedAt) : Number.MAX_SAFE_INTEGER) - (b.resolvedAt ? Date.parse(b.resolvedAt) : Number.MAX_SAFE_INTEGER);
-		}).slice(0, overflow);
+		const entryTime = (record) => {
+			if (!record.resolvedAt) return Number.MAX_SAFE_INTEGER;
+			const parsed = Date.parse(record.resolvedAt);
+			return Number.isNaN(parsed) ? Number.MAX_SAFE_INTEGER : parsed;
+		};
+		const oldest = resolved.sort((a, b) => entryTime(a) - entryTime(b)).slice(0, overflow);
 		const evictIds = new Set(oldest.map((record) => record.id));
 		const kept = {};
-		for (const [key, value] of Object.entries(map)) if (!evictIds.has(key)) kept[key] = value;
+		for (const [key, value] of Object.entries(map)) if (!evictIds.has(value.id)) kept[key] = value;
 		return {
 			map: kept,
 			evicted: oldest
@@ -144,8 +180,8 @@ function apply(ctx, rawConfig) {
 				if (fresh.length === 0) return current;
 				const next = [...archive, ...fresh];
 				if (next.length > ARCHIVE_RESOLVED_CAP) {
-					await io().writeText(pathOf("pending-state-archive.json.bak"), JSON.stringify(archive, null, 2)).catch(() => {});
-					return JSON.stringify(fresh, null, 2);
+					if (archive.length > 0) await io().writeText(pathOf("pending-state-archive.json.bak"), JSON.stringify(archive, null, 2)).catch(() => {});
+					return JSON.stringify(fresh.slice(-5e3), null, 2);
 				}
 				return JSON.stringify(next, null, 2);
 			});
@@ -160,7 +196,7 @@ function apply(ctx, rawConfig) {
 		},
 		async saveReviewState(sessionId, record) {
 			await mutate(async () => {
-				await jsonTransact("review-state.json", (current) => ({
+				await jsonTransact(io, root, "review-state.json", (current) => ({
 					...current ?? {},
 					[sessionId]: record
 				}));
@@ -173,7 +209,7 @@ function apply(ctx, rawConfig) {
 		},
 		async saveCuratorState(record) {
 			await mutate(async () => {
-				await jsonTransact("curator-state.json", (current) => ({
+				await jsonTransact(io, root, "curator-state.json", (current) => ({
 					...current ?? {},
 					primary: record
 				}));
@@ -181,7 +217,7 @@ function apply(ctx, rawConfig) {
 		},
 		async transactCuratorState(task) {
 			await mutate(async () => {
-				await jsonTransact("curator-state.json", (current) => {
+				await jsonTransact(io, root, "curator-state.json", (current) => {
 					const next = task(current?.primary ?? null);
 					if (next === null) return current;
 					return {
@@ -199,9 +235,9 @@ function apply(ctx, rawConfig) {
 		},
 		async savePending(record) {
 			await mutate(async () => {
-				await jsonTransact("pending-state.json", async (current) => {
+				await jsonTransact(io, root, "pending-state.json", async (current) => {
 					return {
-						...await readJson("pending.json") ?? {},
+						...(legacyMigrated ? null : await readJson("pending.json")) ?? {},
 						...current ?? {},
 						[record.id]: record
 					};
@@ -211,9 +247,9 @@ function apply(ctx, rawConfig) {
 		async claimPending(id, claimId) {
 			return await mutate(async () => {
 				const slot = { claimed: null };
-				await jsonTransact("pending-state.json", async (current) => {
+				await jsonTransact(io, root, "pending-state.json", async (current) => {
 					const map = {
-						...await readJson("pending.json") ?? {},
+						...(legacyMigrated ? null : await readJson("pending.json")) ?? {},
 						...current ?? {}
 					};
 					const record = map[id] ?? null;
@@ -233,9 +269,9 @@ function apply(ctx, rawConfig) {
 		},
 		async releasePendingClaim(id, claimId) {
 			await mutate(async () => {
-				await jsonTransact("pending-state.json", async (current) => {
+				await jsonTransact(io, root, "pending-state.json", async (current) => {
 					const map = {
-						...await readJson("pending.json") ?? {},
+						...(legacyMigrated ? null : await readJson("pending.json")) ?? {},
 						...current ?? {}
 					};
 					const record = map[id];
@@ -254,9 +290,9 @@ function apply(ctx, rawConfig) {
 					applied: false
 				};
 				let evicted = [];
-				await jsonTransact("pending-state.json", async (current) => {
+				await jsonTransact(io, root, "pending-state.json", async (current) => {
 					const map = {
-						...await readJson("pending.json") ?? {},
+						...(legacyMigrated ? null : await readJson("pending.json")) ?? {},
 						...current ?? {}
 					};
 					const record = map[id] ?? null;
@@ -289,4 +325,4 @@ function apply(ctx, rawConfig) {
 	ctx.effect(() => ctx.evolutionStateStorage.registerProvider(provider), "evolution-state-json.provider");
 }
 //#endregion
-export { Config, apply, inject, name };
+export { Config, apply, inject, jsonTransact, name };

package/lib/types/index.d.ts

@@ -7,11 +7,23 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 export declare const name = "evolution-state-json";
 export declare const inject: string[];
 export interface Config {
     root?: string;
 }
 export declare const Config: z<Config>;
+/**
+ * Cross-process JSON-file RMW (v3-audit M-8): every read-modify-write state
+ * mutation runs inside the IO backend's transact lock (via transactIo) so a
+ * second process sharing DSH_HOME cannot interleave its claim/resolve.
+ * `task` returns the next value (null = keep); for a record-map file the
+ * return must be null or a plain object map of records, and an array/scalar
+ * would be persisted as a corrupt map — so it fails loud before any write
+ * (0.3.28, V4-08). The legacy `pending.json` merge stays inside the task via
+ * `readJson` where relevant.
+ */
+export declare function jsonTransact<T>(io: () => EvolutionIoLike, root: string, file: string, task: (current: T | null) => T | null | Promise<T | null>): Promise<void>;
 export declare function apply(ctx: Context, rawConfig: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-state-json",
   "description": "JSON-file evolution state provider over the IO seam (community build)",
-  "version": "0.3.27",
+  "version": "0.3.29",
   "publishConfig": {
     "access": "public"
   },
@@ -31,17 +31,17 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.27"
+    "@lmzhen/dsh-evolution-core": "^0.3.29"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.3.27",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.27"
+    "@lmzhen/dsh-evolution-io": "^0.3.29",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.29"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.3.27",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.27"
+    "@lmzhen/dsh-evolution-io": "^0.3.29",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.29"
   }
 }