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

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,33 +88,11 @@ 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));
-				}
-				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}`);
-			}
-			const next = await task(parsed);
-			return next === null ? null : JSON.stringify(next, null, 2);
-		});
-	}
 	const mutate = makeSerialQueue();
 	async function loadPendingMap() {
 		const [current, legacy] = await Promise.all([readJson("pending-state.json"), readJson("pending.json")]);
@@ -160,7 +164,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 +177,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 +185,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,7 +203,7 @@ 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") ?? {},
 						...current ?? {},
@@ -211,7 +215,7 @@ 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") ?? {},
 						...current ?? {}
@@ -233,7 +237,7 @@ 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") ?? {},
 						...current ?? {}
@@ -254,7 +258,7 @@ 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") ?? {},
 						...current ?? {}
@@ -289,4 +293,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.28",
   "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.28"
   },
   "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.28",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.28"
   },
   "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.28",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.28"
   }
 }