@lmzhen/dsh-evolution-state-json 0.17.0 → 0.18.0

package/lib/index.js

@@ -1,5 +1,5 @@
 import z from "@deepseek-ai/schemastery";
-import { evolutionHome, makeSerialQueue, transactIo, transactTaskGuard } from "@lmzhen/dsh-evolution-core";
+import { evolutionHome, isAbsent, isPresent, isUnknown, makeSerialQueue, probeText, transactIo, transactTaskGuard } from "@lmzhen/dsh-evolution-core";
 import { CURATOR_STATE_FILE, CURATOR_STATE_KEY, CURATOR_STATE_TABLE, PENDING_ARCHIVE_BAK_FILE, PENDING_ARCHIVE_FILE, PENDING_LEGACY_FILE, PENDING_RESOLVED_CAP, PENDING_STATE_FILE, PENDING_TABLE, PROVIDER_JSON, REVIEW_STATE_FILE, REVIEW_STATE_SESSION_CAP, REVIEW_STATE_TABLE, assertCloneable, canClaimPending, canResolvePending, cloneRecord, recordIssue, releasedStatus, selectPendingOverflow, selectSessionOverflow } from "@lmzhen/dsh-evolution-state-storage";
 import { basename, dirname, isAbsolute, join } from "node:path";
 //#region lib/types/index.js
@@ -68,11 +68,16 @@ const QUARANTINE_ERROR_NAME = "EvolutionStateCorruptFile";
 * DIFFERENT payload gets a stamped sibling so the earlier rescue copy is never
 * overwritten. The node backend's 7-day `.corrupt` sweep bounds the set. */
 async function quarantineTarget(io, base, content) {
-	if (!await io().exists(base).catch(() => false)) return {
+	const baseProbe = await probeText(io(), base);
+	if (isUnknown(baseProbe)) return {
+		dest: `${base}.${Date.now()}`,
+		needsWrite: true
+	};
+	if (isAbsent(baseProbe)) return {
 		dest: base,
 		needsWrite: true
 	};
-	if (await io().readText(base).catch(() => null) === content) return {
+	if (baseProbe.value === content) return {
 		dest: base,
 		needsWrite: false
 	};
@@ -83,7 +88,8 @@ async function quarantineTarget(io, base, content) {
 			if (!name.startsWith(stem)) continue;
 			if (!/^\d+$/.test(name.slice(stem.length))) continue;
 			const sibling = join(dir, name);
-			if (await io().readText(sibling).catch(() => null) === content) return {
+			const siblingProbe = await probeText(io(), sibling);
+			if (isPresent(siblingProbe) && siblingProbe.value === content) return {
 				dest: sibling,
 				needsWrite: false
 			};
@@ -94,16 +100,16 @@ async function quarantineTarget(io, base, content) {
 		needsWrite: true
 	};
 }
-async function quarantine(io, root, file, raw, reason) {
+async function quarantine(io, root, file, raw, reason, memory) {
 	const { dest, needsWrite } = await quarantineTarget(io, `${join(root, file)}.corrupt`, raw);
 	let preservedNote = `; original preserved at ${dest} — inspect and fix it, then retry.`;
 	if (needsWrite) try {
 		await io().writeText(dest, raw);
-		corruptWritten.delete(file);
+		memory.written.delete(file);
 	} catch (writeError) {
 		preservedNote = `; the quarantine copy at ${dest} FAILED to write (${writeError instanceof Error ? writeError.message : String(writeError)}) — the original file is left in place.`;
 	}
-	else corruptWritten.delete(file);
+	else memory.written.delete(file);
 	throw Object.assign(/* @__PURE__ */ new Error(`evolution state file "${file}" is not valid JSON (${reason})${preservedNote}`), { name: QUARANTINE_ERROR_NAME });
 }
 /** S-05: the V8-16 record-shape gate existed as two verbatim ~15-line
@@ -132,22 +138,14 @@ function gateScan(file, parsed) {
 	if (gate === void 0 || !isPlainRecord(parsed)) return [];
 	return Object.entries(parsed).filter(([, record]) => !isPlainRecord(record) || !gate(record));
 }
-/**
-* 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 = ENSURE-ABSENT (the file is deleted
-* when it exists — the parity of the transact seam, V6-32). 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.
-* @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.
-*/
-const recordGateWarned = /* @__PURE__ */ new Set();
-const corruptWritten = /* @__PURE__ */ new Map();
-const corruptWriteWarned = /* @__PURE__ */ new Set();
+/** One provider instance's quarantine memory. */
+function newQuarantineMemory() {
+	return {
+		warned: /* @__PURE__ */ new Set(),
+		written: /* @__PURE__ */ new Map(),
+		writeWarned: /* @__PURE__ */ new Set()
+	};
+}
 /** P3 (v15): name carried by the two fail-loud write gates in `jsonTransact`
 * (task-return shape, write-back field gate) so best-effort wrappers —
 * `retireLegacyOnce` is the one that matters — rethrow instead of deferring. */
@@ -157,26 +155,26 @@ function writeGateError(message) {
 	error.name = WRITE_GATE_ERROR_NAME;
 	return error;
 }
-function reportGateViolation(ctx, file, failing) {
-	if (recordGateWarned.has(file)) return;
-	recordGateWarned.add(file);
+function reportGateViolation(ctx, file, failing, memory) {
+	if (memory.warned.has(file)) return;
+	memory.warned.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.map(([id]) => id).join(", ")}`);
 }
-async function ensureCorruptCopy(ctx, io, root, file, bad) {
+async function ensureCorruptCopy(ctx, io, root, file, bad, memory) {
 	const base = `${join(root, file)}.corrupt`;
 	const corruptKey = JSON.stringify(Object.entries(bad).map(([id, record]) => ({
 		id,
 		fields: typeof record === "object" && record !== null ? Object.entries(record).map(([field, value]) => `${field}:${Array.isArray(value) ? "array" : typeof value}`).sort() : [typeof record]
 	})).sort((a, b) => a.id.localeCompare(b.id)));
-	if (corruptWritten.get(file) === corruptKey && await io().exists(base)) return true;
+	if (memory.written.get(file) === corruptKey && await io().exists(base)) return true;
 	const payload = JSON.stringify(bad, null, 2);
 	const { dest, needsWrite } = await quarantineTarget(io, base, payload);
 	const wrote = needsWrite ? await io().writeText(dest, payload).then(() => true).catch(() => false) : true;
 	if (wrote) {
-		corruptWritten.set(file, corruptKey);
-		corruptWriteWarned.delete(file);
-	} else if (!corruptWriteWarned.has(file)) {
-		corruptWriteWarned.add(file);
+		memory.written.set(file, corruptKey);
+		memory.writeWarned.delete(file);
+	} else if (!memory.writeWarned.has(file)) {
+		memory.writeWarned.add(file);
 		ctx.logger.warn(`evolution-state-json: could not write quarantine copy "${dest}" for ${Object.keys(bad).length} failed record(s) — the main file keeps them; the copy is retried on the next access`);
 	}
 	return wrote;
@@ -188,26 +186,26 @@ async function jsonTransact(ctx, io, root, file, task, options) {
 			try {
 				parsed = JSON.parse(current);
 			} catch (error) {
-				return await quarantine(io, root, file, current, error instanceof Error ? error.message : String(error));
+				return await quarantine(io, root, file, current, error instanceof Error ? error.message : String(error), options.memory);
 			}
-			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)) 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}`, options.memory);
 			const malformed = firstNonRecordValue(parsed);
-			if (malformed !== null) return await quarantine(io, root, file, current, malformed);
+			if (malformed !== null) return await quarantine(io, root, file, current, malformed, options.memory);
 			const failing = gateScan(file, parsed);
 			if (failing.length > 0) {
 				const bad = {};
 				const good = {};
 				for (const [id, record] of Object.entries(parsed)) if (failing.some(([failedId]) => failedId === id)) bad[id] = record;
 				else good[id] = record;
-				reportGateViolation(ctx, file, failing);
-				if (await ensureCorruptCopy(ctx, io, root, file, bad)) {
+				reportGateViolation(ctx, file, failing, options.memory);
+				if (await ensureCorruptCopy(ctx, io, root, file, bad, options.memory)) {
 					parsed = good;
-					options?.onGateDrop?.(file, failing.map(([id]) => id));
+					options.onGateDrop?.(file, failing.map(([id]) => id));
 				} else {
-					options?.onGateDrop?.(file, []);
+					options.onGateDrop?.(file, []);
 					ctx.logger.warn(`evolution-state-json: keeping ${failing.length} malformed record(s) in ${file} — the quarantine copy could not be written, so rewriting the file without them would destroy the only copy`);
 				}
-			} else options?.onGateDrop?.(file, []);
+			} else options.onGateDrop?.(file, []);
 		}
 		const next = await task(parsed);
 		if (next !== null && RECORD_MAP_FILES.has(file) && !isPlainRecord(next)) throw writeGateError(`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.`);
@@ -223,6 +221,7 @@ function apply(ctx, rawConfig = {}) {
 	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 quarantineMemory = newQuarantineMemory();
 	const gateDroppedCurrent = /* @__PURE__ */ new Set();
 	const noteGateDrop = (file, ids) => {
 		if (file !== PENDING_STATE_FILE) return;
@@ -242,7 +241,16 @@ function apply(ctx, rawConfig = {}) {
 	* @param task - the read-modify-write body, exactly as jsonTransact takes it.
 	* @returns jsonTransact's own result.
 	*/
-	const pendingTransact = (task) => jsonTransact(ctx, io, root, PENDING_STATE_FILE, task, { onGateDrop: noteGateDrop });
+	const pendingTransact = (task, what = "the pending table") => {
+		const guard = transactTaskGuard(`pending table write for ${what}`);
+		const pendingWrite = {
+			onGateDrop: noteGateDrop,
+			memory: quarantineMemory
+		};
+		return jsonTransact(ctx, io, root, PENDING_STATE_FILE, guard.wrap(task), pendingWrite).then(() => {
+			guard.assertInvoked();
+		});
+	};
 	let warnedPendingCapacity = false;
 	let warnedPendingArgsBytes = false;
 	async function readJson(file) {
@@ -252,19 +260,19 @@ function apply(ctx, rawConfig = {}) {
 		try {
 			parsed = JSON.parse(raw);
 		} catch (error) {
-			return await quarantine(io, root, file, raw, error instanceof Error ? error.message : String(error));
+			return await quarantine(io, root, file, raw, error instanceof Error ? error.message : String(error), quarantineMemory);
 		}
-		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)) 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}`, quarantineMemory);
 		const malformed = firstNonRecordValue(parsed);
-		if (malformed !== null) return await quarantine(io, root, file, raw, malformed);
+		if (malformed !== null) return await quarantine(io, root, file, raw, malformed, quarantineMemory);
 		const failing = gateScan(file, parsed);
 		if (failing.length > 0) {
 			const bad = {};
 			const good = {};
 			for (const [id, record] of Object.entries(parsed)) if (failing.some(([failedId]) => failedId === id)) bad[id] = record;
 			else good[id] = record;
-			reportGateViolation(ctx, file, failing);
-			await ensureCorruptCopy(ctx, io, root, file, bad);
+			reportGateViolation(ctx, file, failing, quarantineMemory);
+			await ensureCorruptCopy(ctx, io, root, file, bad, quarantineMemory);
 			if (file === PENDING_STATE_FILE) {
 				gateDroppedCurrent.clear();
 				for (const id of Object.keys(bad)) gateDroppedCurrent.add(id);
@@ -362,6 +370,7 @@ function apply(ctx, rawConfig = {}) {
 	async function retireLegacyOnce(legacy) {
 		if (legacyMigrated) return {};
 		const keyedLegacy = keyPendingById(legacy);
+		let committed = null;
 		try {
 			const retired = {};
 			await jsonTransact(ctx, io, root, PENDING_STATE_FILE, async (fresh) => {
@@ -374,15 +383,20 @@ function apply(ctx, rawConfig = {}) {
 					merged[id] = record;
 					retired[id] = record;
 				}
+				committed = merged;
 				return merged;
-			}, { onGateDrop: noteGateDrop });
+			}, {
+				onGateDrop: noteGateDrop,
+				memory: quarantineMemory
+			});
 			await io().rename(pathOf(PENDING_LEGACY_FILE), `${pathOf(PENDING_LEGACY_FILE)}.migrated`);
 			legacyMigrated = true;
 			return retired;
 		} catch (error) {
 			if (error instanceof Error && (error.name === QUARANTINE_ERROR_NAME || error.name === WRITE_GATE_ERROR_NAME)) throw error;
 			ctx.logger.warn(`evolution-state-json: legacy pending retirement deferred: ${error instanceof Error ? error.message : String(error)}`);
-			return {};
+			if (committed === null) return {};
+			return committed;
 		}
 	}
 	async function loadPendingMap() {
@@ -449,9 +463,10 @@ function apply(ctx, rawConfig = {}) {
 	* revive a ghost twin. A dedupe no-op counts as success — the records are
 	* already in the archive. */
 	async function appendArchive(records) {
+		const guard = transactTaskGuard(`pending archive (${PENDING_ARCHIVE_FILE})`);
 		let landed = true;
 		try {
-			await transactIo(io(), pathOf(PENDING_ARCHIVE_FILE), async (current) => {
+			await transactIo(io(), pathOf(PENDING_ARCHIVE_FILE), guard.wrap(async (current) => {
 				let archive = [];
 				if (current !== null) {
 					let parsed;
@@ -488,7 +503,8 @@ function apply(ctx, rawConfig = {}) {
 					return JSON.stringify((fresh.length > 0 ? fresh : next).slice(-5e3));
 				}
 				return JSON.stringify(next);
-			});
+			}));
+			if (!guard.invoked()) landed = false;
 			return landed;
 		} catch (error) {
 			ctx.logger.warn(`evolution-state-json: archive append deferred: ${error instanceof Error ? error.message : String(error)}`);
@@ -549,7 +565,7 @@ function apply(ctx, rawConfig = {}) {
 					const pruned = {};
 					for (const [id, row] of Object.entries(stamped)) if (!evict.has(id)) pruned[id] = row;
 					return pruned;
-				}));
+				}), { memory: quarantineMemory });
 				guard.assertInvoked();
 			});
 		},
@@ -564,7 +580,7 @@ function apply(ctx, rawConfig = {}) {
 				await jsonTransact(ctx, io, root, CURATOR_STATE_FILE, guard.wrap((current) => ({
 					...current ?? {},
 					[CURATOR_STATE_KEY]: record
-				})));
+				})), { memory: quarantineMemory });
 				guard.assertInvoked();
 			});
 		},
@@ -579,7 +595,7 @@ function apply(ctx, rawConfig = {}) {
 						...current ?? {},
 						[CURATOR_STATE_KEY]: next
 					};
-				}));
+				}), { memory: quarantineMemory });
 				guard.assertInvoked();
 			});
 		},
@@ -591,16 +607,14 @@ function apply(ctx, rawConfig = {}) {
 		},
 		async savePending(record) {
 			await mutate(async () => {
-				const guard = transactTaskGuard(`pending record "${record.id}" (${PENDING_STATE_FILE})`);
-				await pendingTransact(guard.wrap(async (current) => {
+				await pendingTransact(async (current) => {
 					const map = {
 						...await mergedWithFilteredLegacy(legacyMigrated ? null : await readLegacyPending(), current ?? {}),
 						[record.id]: record
 					};
 					warnPendingGrowth(map, "save");
 					return map;
-				}));
-				guard.assertInvoked();
+				}, `record "${record.id}" (${PENDING_STATE_FILE})`);
 			});
 		},
 		async claimPending(id, claimId) {
@@ -692,4 +706,4 @@ function apply(ctx, rawConfig = {}) {
 	ctx.effect(() => ctx.evolutionStateStorage.registerProvider(provider), "evolution-state-json.provider");
 }
 //#endregion
-export { Config, apply, inject, jsonTransact, name };
+export { Config, apply, inject, jsonTransact, name, newQuarantineMemory };

package/lib/types/index.d.ts

@@ -14,8 +14,47 @@ export interface Config {
     root?: string;
 }
 export declare const Config: z<Config>;
-export declare function jsonTransact<T>(ctx: Context, io: () => EvolutionIoLike, root: string, file: string, task: (current: T | null) => T | null | Promise<T | null>, options?: {
+/**
+ * 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 = ENSURE-ABSENT (the file is deleted
+ * when it exists — the parity of the transact seam, V6-32). 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.
+ * @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.
+ */
+/**
+ * The quarantine bookkeeping ONE provider instance owns (N12/O-6, S4.4).
+ *
+ * These three used to be module-scope ("`jsonTransact` is a module function that cannot reach the
+ * apply-scoped closure"), which made warn/rewrite dedup span instances AND roots keyed by file NAME
+ * only: two providers on different roots deduped each other's quarantine writes. Threading the memory
+ * through the one module function that needs it removes that limit — the dedup is now exactly "this
+ * instance, this file", which is what the three fields always described.
+ */
+export interface QuarantineMemory {
+    /** V10-04 (P2-19): the record-gate warn fires once per file per instance — a permanently bad
+     * record would otherwise warn on every turn's read. */
+    readonly warned: Set<string>;
+    /** P2-24 (v11): the last `.corrupt` rewrite key per file (sorted failing id set) — skip
+     * rewriting when nothing changed, so a permanently bad record never re-atomic-writes the copy on
+     * every read. */
+    readonly written: Map<string, string>;
+    /** P3-12 (v14): the "could not write the quarantine copy" warn fires once per file; the key is set
+     * ONLY after a successful write (a failed write is retried, not marked done). */
+    readonly writeWarned: Set<string>;
+}
+/** One provider instance's quarantine memory. */
+export declare function newQuarantineMemory(): QuarantineMemory;
+export declare function jsonTransact<T>(ctx: Context, io: () => EvolutionIoLike, root: string, file: string, task: (current: T | null) => T | null | Promise<T | null>, options: {
     onGateDrop?: (file: string, ids: string[]) => void;
+    /** N12/O-6 (S4.4): the calling INSTANCE's quarantine memory — one per provider, never module
+     * scope (that keyed the dedup by bare file name across every root in the process). */
+    memory: QuarantineMemory;
 }): 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.17.0",
+  "version": "0.18.0",
   "publishConfig": {
     "access": "public"
   },
@@ -26,17 +26,17 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.17.0"
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "@lmzhen/dsh-evolution-core": "^0.18.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.17.0",
-    "@lmzhen/dsh-evolution-state-storage": "^0.17.0"
+    "@lmzhen/dsh-evolution-io": "^0.18.0",
+    "@lmzhen/dsh-evolution-state-storage": "^0.18.0"
   },
   "devDependencies": {
-    "@lmzhen/dsh-evolution-io": "^0.17.0",
-    "@lmzhen/dsh-evolution-state-storage": "^0.17.0",
-    "@lmzhen/dsh-evolution-io-node": "^0.17.0"
+    "@lmzhen/dsh-evolution-io": "^0.18.0",
+    "@lmzhen/dsh-evolution-state-storage": "^0.18.0",
+    "@lmzhen/dsh-evolution-io-node": "^0.18.0"
   }
 }