@lmzhen/dsh-evolution-state-json 0.3.51 → 0.3.53

package/README.md

@@ -22,5 +22,5 @@ Independent of request-prefix construction. This package does not alter the asse
 ## Known Limitations and Deferred Work
 
 
-- JSON provider serializes writers inside one process AND through the IO backend's cross-process transact lock (`jsonTransact` wraps every mutation, 0.3.20/0.3.27) — this provider is NOT limited to single-process safety. The caveat below is about the DSH storage-domain providers (`storage-json` documents no cross-process write locking) when the DOMAIN provider is used instead; multi-process deployments should route the evolution domain to a backend with cross-process semantics such as SQLite or remote storage.
+- JSON provider serializes writers inside one process AND through the IO backend's cross-process transact lock (an internal transact wrapper — not public API, audit v10 S-03 — wraps every mutation, 0.3.20/0.3.27) — this provider is NOT limited to single-process safety. The caveat below is about the DSH storage-domain providers (`storage-json` documents no cross-process write locking) when the DOMAIN provider is used instead; multi-process deployments should route the evolution domain to a backend with cross-process semantics such as SQLite or remote storage.
 

package/lib/index.js

@@ -1,7 +1,7 @@
 import z from "@deepseek-ai/schemastery";
 import { evolutionHome, makeSerialQueue, transactIo } from "@lmzhen/dsh-evolution-core";
-import { canClaimPending, canResolvePending, releasedStatus } from "@lmzhen/dsh-evolution-state-storage";
-import { join } from "node:path";
+import { CURATOR_STATE_FILE, CURATOR_STATE_KEY, PENDING_ARCHIVE_BAK_FILE, PENDING_ARCHIVE_FILE, PENDING_LEGACY_FILE, PENDING_STATE_FILE, PROVIDER_JSON, REVIEW_STATE_FILE, canClaimPending, canResolvePending, releasedStatus } from "@lmzhen/dsh-evolution-state-storage";
+import { isAbsolute, join } from "node:path";
 //#region lib/types/index.js
 /**
 * JSON-file evolution state provider over the IO seam.
@@ -35,22 +35,62 @@ const pendingArchiveKey = (record) => `${record.id}\u0000${record.status}\u0000$
 * is a top-level ARRAY and must NOT be gated by this predicate. */
 const isPlainRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const RECORD_MAP_FILES = new Set([
-	"review-state.json",
-	"curator-state.json",
-	"pending-state.json",
-	"pending.json"
+	REVIEW_STATE_FILE,
+	CURATOR_STATE_FILE,
+	PENDING_STATE_FILE,
+	PENDING_LEGACY_FILE
 ]);
+/** V10-05 (P2-5): discriminant stamped on every quarantine error so
+* best-effort wrappers (retireLegacyOnce) can tell "corrupt state — fail
+* loud" from a transient IO failure and let the quarantine propagate. */
+const QUARANTINE_ERROR_NAME = "EvolutionStateCorruptFile";
 /** 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". */
+* corruption is never accepted as "empty".
+* V10-05 (P2-5): the copy is the FIXED name `<file>.corrupt`, written through
+* the IO seam's atomic write (tmp+rename under the node backend), so it
+* overwrite-commits — at most ONE preserved copy per file can ever
+* accumulate. The old `.corrupt-<stamp>-<rand>` name minted a fresh file on
+* EVERY read of a corrupt file: unbounded growth with no sweep. The fixed
+* copy is swept after 7 days by the node backend's sweepStaleTmps (S-10). */
 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)}`;
+	const dest = `${join(root, file)}.corrupt`;
 	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.`);
+	throw Object.assign(/* @__PURE__ */ new Error(`evolution state file "${file}" is not valid JSON (${reason}); original preserved at ${dest} — inspect and fix it, then retry.`), { name: QUARANTINE_ERROR_NAME });
 }
+/** S-05: the V8-16 record-shape gate existed as two verbatim ~15-line
+* copies (jsonTransact + readJson); this private helper is the single owner.
+* Returns the quarantine reason for the first non-plain-object record value,
+* or null when every value of the map is a plain object. */
+function firstNonRecordValue(parsed) {
+	if (!isPlainRecord(parsed)) return null;
+	for (const [recordId, record] of Object.entries(parsed)) if (!isPlainRecord(record)) return `expected a plain object for record "${recordId}", got ${record === null ? "null" : Array.isArray(record) ? "an array" : typeof record}`;
+	return null;
+}
+const isNonNegInt = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+const optionalString = (value) => value === void 0 || typeof value === "string";
+const PENDING_KINDS = new Set([
+	"memory",
+	"skill",
+	"capability"
+]);
+const PENDING_STATUSES = new Set([
+	"pending",
+	"executing",
+	"approved",
+	"rejected"
+]);
+const gateReviewRecord = (record) => isNonNegInt(record.turnsSinceMemory) && isNonNegInt(record.turnsSinceSkill) && isNonNegInt(record.lastTurn);
+const gateCuratorRecord = (record) => typeof record.lastRunAt === "number" && Number.isFinite(record.lastRunAt) && record.lastRunAt >= 0 && isNonNegInt(record.runCount) && typeof record.lastSummary === "string" && typeof record.paused === "boolean";
+const gatePendingRecord = (record) => typeof record.id === "string" && typeof record.kind === "string" && PENDING_KINDS.has(record.kind) && typeof record.summary === "string" && typeof record.createdAt === "string" && typeof record.status === "string" && PENDING_STATUSES.has(record.status) && optionalString(record.resolvedAt) && optionalString(record.claimedBy) && optionalString(record.claimedAt) && optionalString(record.origin) && optionalString(record.sessionId);
+const RECORD_FIELD_GATES = {
+	[REVIEW_STATE_FILE]: gateReviewRecord,
+	[CURATOR_STATE_FILE]: gateCuratorRecord,
+	[PENDING_STATE_FILE]: gatePendingRecord,
+	[PENDING_LEGACY_FILE]: gatePendingRecord
+};
 /**
 * 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
@@ -61,6 +101,8 @@ async function quarantine(io, root, file, raw, reason) {
 * 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.
+* @internal Exported only for this package's own tests — not public API
+* surface (audit v10 S-03); other packages must go through the provider seam.
 */
 async function jsonTransact(io, root, file, task) {
 	await transactIo(io(), join(root, file), async (current) => {
@@ -72,9 +114,8 @@ async function jsonTransact(io, root, file, task) {
 				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}`);
-			if (RECORD_MAP_FILES.has(file) && isPlainRecord(parsed)) {
-				for (const [recordId, record] of Object.entries(parsed)) if (!isPlainRecord(record)) return await quarantine(io, root, file, current, `expected a plain object for record "${recordId}", got ${record === null ? "null" : Array.isArray(record) ? "an array" : typeof record}`);
-			}
+			const malformed = firstNonRecordValue(parsed);
+			if (malformed !== null) return await quarantine(io, root, file, current, malformed);
 		}
 		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.`);
@@ -83,8 +124,10 @@ async function jsonTransact(io, root, file, task) {
 }
 function apply(ctx, rawConfig) {
 	const root = (rawConfig.root ?? "").trim() || evolutionHome();
+	if (rawConfig.root !== void 0 && rawConfig.root.trim() !== "" && !isAbsolute(rawConfig.root)) ctx.logger.warn(`evolution-state-json: config.root "${rawConfig.root}" is a relative path and resolves against the process CWD ("${root}") — pass an absolute path to make the store location launch-independent`);
 	const io = () => ctx.evolutionIo.provider();
 	const pathOf = (file) => join(root, file);
+	const recordGateWarned = /* @__PURE__ */ new Set();
 	async function readJson(file) {
 		const raw = await io().readText(pathOf(file));
 		if (raw === null) return null;
@@ -95,8 +138,24 @@ function apply(ctx, rawConfig) {
 			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(io, root, 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)) {
-			for (const [recordId, record] of Object.entries(parsed)) if (!isPlainRecord(record)) return await quarantine(io, root, file, raw, `expected a plain object for record "${recordId}", got ${record === null ? "null" : Array.isArray(record) ? "an array" : typeof record}`);
+		const malformed = firstNonRecordValue(parsed);
+		if (malformed !== null) return await quarantine(io, root, file, raw, malformed);
+		const gate = RECORD_FIELD_GATES[file];
+		if (gate !== void 0 && isPlainRecord(parsed)) {
+			const entries = Object.entries(parsed);
+			const failing = entries.filter(([, record]) => !isPlainRecord(record) || !gate(record)).map(([id]) => id);
+			if (failing.length > 0) {
+				const bad = {};
+				const good = {};
+				for (const [id, record] of entries) if (failing.includes(id)) bad[id] = record;
+				else good[id] = record;
+				await io().writeText(`${pathOf(file)}.corrupt`, JSON.stringify(bad, null, 2)).catch(() => {});
+				if (!recordGateWarned.has(file)) {
+					recordGateWarned.add(file);
+					ctx.logger.warn(`evolution-state-json: ${failing.length} record(s) in "${file}" failed the record schema gate and were quarantined to "${file}.corrupt": ${failing.join(", ")}`);
+				}
+				return good;
+			}
 		}
 		return parsed;
 	}
@@ -107,12 +166,12 @@ function apply(ctx, rawConfig) {
 		if (archivedIdsCache !== null) return archivedIdsCache;
 		const ids = /* @__PURE__ */ new Set();
 		try {
-			const rawArchive = await readJson("pending-state-archive.json");
+			const rawArchive = await readJson(PENDING_ARCHIVE_FILE);
 			if (Array.isArray(rawArchive)) {
 				for (const entry of rawArchive) if (entry && typeof entry.id === "string") ids.add(entry.id);
 			}
 			try {
-				const rawBak = await readJson("pending-state-archive.json.bak");
+				const rawBak = await readJson(PENDING_ARCHIVE_BAK_FILE);
 				if (Array.isArray(rawBak)) {
 					for (const entry of rawBak) if (entry && typeof entry.id === "string") ids.add(entry.id);
 				}
@@ -134,19 +193,21 @@ function apply(ctx, rawConfig) {
 		if (legacyMigrated) return {};
 		try {
 			const retired = filterLegacy(legacy, current, await readArchivedIds());
-			await jsonTransact(io, root, "pending-state.json", (fresh) => ({
+			await jsonTransact(io, root, PENDING_STATE_FILE, (fresh) => ({
 				...retired,
 				...fresh ?? {}
 			}));
-			await io().rename(pathOf("pending.json"), pathOf("pending.json.migrated"));
+			await io().rename(pathOf(PENDING_LEGACY_FILE), `${pathOf(PENDING_LEGACY_FILE)}.migrated`);
 			legacyMigrated = true;
 			return retired;
-		} catch {
+		} catch (error) {
+			if (error instanceof Error && error.name === QUARANTINE_ERROR_NAME) throw error;
+			ctx.logger.warn(`evolution-state-json: legacy pending retirement deferred: ${error instanceof Error ? error.message : String(error)}`);
 			return legacy;
 		}
 	}
 	async function loadPendingMap() {
-		const [current, legacy] = await Promise.all([readJson("pending-state.json"), readJson("pending.json")]);
+		const [current, legacy] = await Promise.all([readJson(PENDING_STATE_FILE), readJson(PENDING_LEGACY_FILE)]);
 		if (legacy !== null) return {
 			...await retireLegacyOnce(legacy, current),
 			...current ?? {}
@@ -204,7 +265,7 @@ function apply(ctx, rawConfig) {
 	* bound. */
 	async function appendArchive(records) {
 		try {
-			await transactIo(io(), pathOf("pending-state-archive.json"), async (current) => {
+			await transactIo(io(), pathOf(PENDING_ARCHIVE_FILE), async (current) => {
 				let archive = [];
 				if (current !== null) try {
 					const parsed = JSON.parse(current);
@@ -224,7 +285,7 @@ function apply(ctx, rawConfig) {
 				if (fresh.length === 0 && !hadDuplicates) return current;
 				const next = [...archive, ...fresh];
 				if (next.length > ARCHIVE_RESOLVED_CAP) {
-					if (archive.length > 0) await io().writeText(pathOf("pending-state-archive.json.bak"), JSON.stringify(archive, null, 2)).catch(() => {});
+					if (archive.length > 0) await io().writeText(pathOf(PENDING_ARCHIVE_BAK_FILE), JSON.stringify(archive, null, 2)).catch(() => {});
 					archivedIdsCache = null;
 					return JSON.stringify((fresh.length > 0 ? fresh : next).slice(-5e3), null, 2);
 				}
@@ -234,15 +295,15 @@ function apply(ctx, rawConfig) {
 		} catch {}
 	}
 	const provider = {
-		name: "json",
+		name: PROVIDER_JSON,
 		async loadReviewState(sessionId) {
 			return await mutate(async () => {
-				return (await readJson("review-state.json"))?.[sessionId] ?? null;
+				return (await readJson(REVIEW_STATE_FILE))?.[sessionId] ?? null;
 			});
 		},
 		async saveReviewState(sessionId, record) {
 			await mutate(async () => {
-				await jsonTransact(io, root, "review-state.json", (current) => ({
+				await jsonTransact(io, root, REVIEW_STATE_FILE, (current) => ({
 					...current ?? {},
 					[sessionId]: record
 				}));
@@ -250,25 +311,25 @@ function apply(ctx, rawConfig) {
 		},
 		async loadCuratorState() {
 			return await mutate(async () => {
-				return (await readJson("curator-state.json"))?.primary ?? null;
+				return (await readJson(CURATOR_STATE_FILE))?.[CURATOR_STATE_KEY] ?? null;
 			});
 		},
 		async saveCuratorState(record) {
 			await mutate(async () => {
-				await jsonTransact(io, root, "curator-state.json", (current) => ({
+				await jsonTransact(io, root, CURATOR_STATE_FILE, (current) => ({
 					...current ?? {},
-					primary: record
+					[CURATOR_STATE_KEY]: record
 				}));
 			});
 		},
 		async transactCuratorState(task) {
 			await mutate(async () => {
-				await jsonTransact(io, root, "curator-state.json", (current) => {
-					const next = task(current?.primary ?? null);
+				await jsonTransact(io, root, CURATOR_STATE_FILE, (current) => {
+					const next = task(current?.[CURATOR_STATE_KEY] ?? null);
 					if (next === null) return current;
 					return {
 						...current ?? {},
-						primary: next
+						[CURATOR_STATE_KEY]: next
 					};
 				});
 			});
@@ -281,9 +342,9 @@ function apply(ctx, rawConfig) {
 		},
 		async savePending(record) {
 			await mutate(async () => {
-				await jsonTransact(io, root, "pending-state.json", async (current) => {
+				await jsonTransact(io, root, PENDING_STATE_FILE, async (current) => {
 					return {
-						...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson("pending.json"), current ?? {}),
+						...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson(PENDING_LEGACY_FILE), current ?? {}),
 						[record.id]: record
 					};
 				});
@@ -292,8 +353,8 @@ function apply(ctx, rawConfig) {
 		async claimPending(id, claimId) {
 			return await mutate(async () => {
 				const slot = { claimed: null };
-				await jsonTransact(io, root, "pending-state.json", async (current) => {
-					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson("pending.json"), current ?? {}) };
+				await jsonTransact(io, root, PENDING_STATE_FILE, async (current) => {
+					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson(PENDING_LEGACY_FILE), current ?? {}) };
 					const record = map[id] ?? null;
 					if (record === null || !canClaimPending(record.status)) return map;
 					const now = Date.now();
@@ -311,8 +372,8 @@ function apply(ctx, rawConfig) {
 		},
 		async releasePendingClaim(id, claimId) {
 			await mutate(async () => {
-				await jsonTransact(io, root, "pending-state.json", async (current) => {
-					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson("pending.json"), current ?? {}) };
+				await jsonTransact(io, root, PENDING_STATE_FILE, async (current) => {
+					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson(PENDING_LEGACY_FILE), current ?? {}) };
 					const record = map[id];
 					if (!record || record.claimedBy !== claimId) return map;
 					if (record.status !== "pending" && record.status !== "executing") return map;
@@ -330,8 +391,8 @@ function apply(ctx, rawConfig) {
 					applied: false
 				};
 				let evicted = [];
-				await jsonTransact(io, root, "pending-state.json", async (current) => {
-					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson("pending.json"), current ?? {}) };
+				await jsonTransact(io, root, PENDING_STATE_FILE, async (current) => {
+					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson(PENDING_LEGACY_FILE), current ?? {}) };
 					const record = map[id] ?? null;
 					if (record === null || !canResolvePending(record.status)) {
 						result = {

package/lib/types/index.d.ts

@@ -24,6 +24,8 @@ export declare const Config: z<Config>;
  * 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.
+ * @internal Exported only for this package's own tests — not public API
+ * surface (audit v10 S-03); other packages must go through the provider seam.
  */
 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;

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@lmzhen/dsh-evolution-state-json",
   "description": "JSON-file evolution state provider over the IO seam (community build)",
-  "version": "0.3.51",
+  "version": "0.3.53",
   "publishConfig": {
     "access": "public"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lmzhen/dsh-evolution.git",
-    "directory": "packages/dsh-evolution-state-json"
+    "directory": "packages/evolution-state-json"
   },
   "type": "module",
   "main": "lib/index.js",
@@ -31,18 +31,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.51"
+    "@lmzhen/dsh-evolution-core": "^0.3.53"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.3.51",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.51"
+    "@lmzhen/dsh-evolution-io": "^0.3.53",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.53"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.3.51",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.51",
-    "@lmzhen/dsh-evolution-io-node": "^0.3.51"
+    "@lmzhen/dsh-evolution-io": "^0.3.53",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.53",
+    "@lmzhen/dsh-evolution-io-node": "^0.3.53"
   }
 }