@lmzhen/dsh-evolution-state-json 0.3.81 → 0.3.83

package/README.md

@@ -1,4 +1,4 @@
-# @deepseek-ai/dsh-evolution-state-json
+# @lmzhen/dsh-evolution-state-json
 
 JSON-file evolution state provider over the IO seam
 
@@ -9,7 +9,7 @@ JSON-file evolution state provider over the IO seam
 
 #### What the model sees
 
-`@deepseek-ai/dsh-evolution-state-json` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
+`@lmzhen/dsh-evolution-state-json` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
 
 #### Token effect
 

package/lib/index.js

@@ -1,6 +1,6 @@
 import z from "@deepseek-ai/schemastery";
-import { evolutionHome, makeSerialQueue, transactIo } 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, recordIssue, releasedStatus, selectPendingOverflow, selectSessionOverflow } from "@lmzhen/dsh-evolution-state-storage";
+import { evolutionHome, makeSerialQueue, 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
 /**
@@ -24,6 +24,12 @@ const PENDING_RESOLVED_CAP$1 = PENDING_RESOLVED_CAP;
 * `.bak` sidecar, so the file — and the full-array rewrite on every append —
 * never grows without bound. */
 const ARCHIVE_RESOLVED_CAP = 5e3;
+/** S2-12 (FLOW5-3): the staged table's byte budget for the args it carries.
+* Lives here rather than on the seam because it bounds THIS medium: json
+* rewrites the whole state file per pending mutation, so bytes — not just row
+* count — decide the cost. The domain provider writes rows individually and
+* needs no equivalent (declared asymmetry, not an oversight). */
+const PENDING_ARGS_BYTES_WARN = 1e6;
 /** 0.3.27 (V4-01): an archive entry's dedupe identity. The same audit record
 * (id + status + resolvedAt) must never appear twice; the read-only legacy
 * `pending.json` merge used to re-introduce an evicted record on the next
@@ -223,7 +229,22 @@ function apply(ctx, rawConfig = {}) {
 		gateDroppedCurrent.clear();
 		for (const id of ids) gateDroppedCurrent.add(id);
 	};
+	/**
+	* v43 audit (S1-9, F-2's deeper half): every pending-state mutation goes
+	* through jsonTransact, and only the RETIREMENT path used to hand the
+	* gate-drop reporter over. The other paths read `current` with their own
+	* field-gate pass, so a record dropped there stayed invisible to
+	* `gateDroppedCurrent` — and `mergedWithFilteredLegacy` then resurrected the
+	* legacy pending twin of a record whose fields went bad (an approve replays an
+	* already-landed write). Binding the reporter to the FILE here means no call
+	* site can forget it; jsonTransact reports the drops before the task runs, so
+	* the merged basis inside the task sees them.
+	* @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 });
 	let warnedPendingCapacity = false;
+	let warnedPendingArgsBytes = false;
 	async function readJson(file) {
 		const raw = await io().readText(pathOf(file));
 		if (raw === null) return null;
@@ -444,6 +465,32 @@ function apply(ctx, rawConfig = {}) {
 			return false;
 		}
 	}
+	/**
+	* S2-12 (FLOW5-3/5-4): the staged table's two growth signals, evaluated on
+	* EVERY write path that can move it. Before this, only `savePending` warned
+	* about the record count, so a deployment whose approvals arrive through
+	* claim/resolve grew silently; and nothing measured the staged ARGS at all.
+	* Both warns flip once and re-arm when the table comes back under the bound.
+	*
+	* @param map - the post-write pending map.
+	* @param where - the path that wrote it, named in the warning.
+	*/
+	const warnPendingGrowth = (map, where) => {
+		const live = Object.values(map).filter((entry) => entry.status === "pending" || entry.status === "executing");
+		if (live.length > PENDING_RESOLVED_CAP$1) {
+			if (!warnedPendingCapacity) {
+				warnedPendingCapacity = true;
+				ctx.logger.warn(`evolution-state-json: ${live.length} pending/executing staged records exceed the resolved cap (${PENDING_RESOLVED_CAP$1}) after ${where} — they are never trimmed by design; resolve or reject them (/evolution pending) or the file keeps growing`);
+			}
+		} else warnedPendingCapacity = false;
+		const argsBytes = live.reduce((total, entry) => total + Buffer.byteLength(JSON.stringify(entry.args ?? null), "utf8"), 0);
+		if (argsBytes > PENDING_ARGS_BYTES_WARN) {
+			if (!warnedPendingArgsBytes) {
+				warnedPendingArgsBytes = true;
+				ctx.logger.warn(`evolution-state-json: ${argsBytes} bytes of staged args across ${live.length} pending/executing record(s) exceed ${PENDING_ARGS_BYTES_WARN} after ${where} — every pending mutation rewrites this file in full; resolve or drop the oversized records (/evolution pending)`);
+			}
+		} else warnedPendingArgsBytes = false;
+	};
 	const provider = {
 		name: PROVIDER_JSON,
 		async loadReviewState(sessionId) {
@@ -456,7 +503,8 @@ function apply(ctx, rawConfig = {}) {
 		},
 		async saveReviewState(sessionId, record) {
 			await mutate(async () => {
-				await jsonTransact(ctx, io, root, REVIEW_STATE_FILE, (current) => {
+				const guard = transactTaskGuard(`review state for session "${sessionId}" (${REVIEW_STATE_FILE})`);
+				await jsonTransact(ctx, io, root, REVIEW_STATE_FILE, guard.wrap((current) => {
 					const stamped = { ...current ?? {} };
 					stamped[sessionId] = {
 						...record,
@@ -471,7 +519,8 @@ function apply(ctx, rawConfig = {}) {
 					const pruned = {};
 					for (const [id, row] of Object.entries(stamped)) if (!evict.has(id)) pruned[id] = row;
 					return pruned;
-				});
+				}));
+				guard.assertInvoked();
 			});
 		},
 		async loadCuratorState() {
@@ -481,22 +530,27 @@ function apply(ctx, rawConfig = {}) {
 		},
 		async saveCuratorState(record) {
 			await mutate(async () => {
-				await jsonTransact(ctx, io, root, CURATOR_STATE_FILE, (current) => ({
+				const guard = transactTaskGuard(`curator state (${CURATOR_STATE_FILE})`);
+				await jsonTransact(ctx, io, root, CURATOR_STATE_FILE, guard.wrap((current) => ({
 					...current ?? {},
 					[CURATOR_STATE_KEY]: record
-				}));
+				})));
+				guard.assertInvoked();
 			});
 		},
 		async transactCuratorState(task) {
 			await mutate(async () => {
-				await jsonTransact(ctx, io, root, CURATOR_STATE_FILE, (current) => {
-					const next = task(current?.[CURATOR_STATE_KEY] ?? null);
+				const guard = transactTaskGuard(`curator state transact (${CURATOR_STATE_FILE})`);
+				await jsonTransact(ctx, io, root, CURATOR_STATE_FILE, guard.wrap((current) => {
+					const stored = current?.[CURATOR_STATE_KEY] ?? null;
+					const next = task(stored === null ? null : cloneRecord(stored));
 					if (next === null) return current;
 					return {
 						...current ?? {},
 						[CURATOR_STATE_KEY]: next
 					};
-				});
+				}));
+				guard.assertInvoked();
 			});
 		},
 		async listPending(status = "pending") {
@@ -507,25 +561,22 @@ function apply(ctx, rawConfig = {}) {
 		},
 		async savePending(record) {
 			await mutate(async () => {
-				await jsonTransact(ctx, io, root, PENDING_STATE_FILE, async (current) => {
+				const guard = transactTaskGuard(`pending record "${record.id}" (${PENDING_STATE_FILE})`);
+				await pendingTransact(guard.wrap(async (current) => {
 					const map = {
 						...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson(PENDING_LEGACY_FILE), current ?? {}),
 						[record.id]: record
 					};
-					const liveCount = Object.values(map).filter((entry) => entry.status === "pending" || entry.status === "executing").length;
-					if (liveCount > PENDING_RESOLVED_CAP$1 && !warnedPendingCapacity) {
-						warnedPendingCapacity = true;
-						ctx.logger.warn(`evolution-state-json: ${liveCount} pending/executing staged records exceed the resolved cap (${PENDING_RESOLVED_CAP$1}) — they are never trimmed by design; resolve or reject them (/evolution pending) or the file keeps growing`);
-					}
-					if (liveCount <= PENDING_RESOLVED_CAP$1) warnedPendingCapacity = false;
+					warnPendingGrowth(map, "save");
 					return map;
-				});
+				}));
+				guard.assertInvoked();
 			});
 		},
 		async claimPending(id, claimId) {
 			return await mutate(async () => {
 				const slot = { claimed: null };
-				await jsonTransact(ctx, io, root, PENDING_STATE_FILE, async (current) => {
+				await pendingTransact(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;
@@ -539,12 +590,13 @@ function apply(ctx, rawConfig = {}) {
 					map[id] = slot.claimed;
 					return map;
 				});
+				warnPendingGrowth(await loadPendingMap(), "claim");
 				return slot.claimed ? { ...slot.claimed } : null;
 			});
 		},
 		async releasePendingClaim(id, claimId) {
 			await mutate(async () => {
-				await jsonTransact(ctx, io, root, PENDING_STATE_FILE, async (current) => {
+				await pendingTransact(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;
@@ -562,7 +614,7 @@ function apply(ctx, rawConfig = {}) {
 					record: null,
 					applied: false
 				};
-				await jsonTransact(ctx, io, root, PENDING_STATE_FILE, async (current) => {
+				await pendingTransact(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)) {
@@ -602,6 +654,7 @@ function apply(ctx, rawConfig = {}) {
 					}
 					return pruned.map;
 				});
+				warnPendingGrowth(await loadPendingMap(), "resolve");
 				return result;
 			});
 		}

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.81",
+  "version": "0.3.83",
   "publishConfig": {
     "access": "public"
   },
@@ -27,16 +27,16 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.81"
+    "@lmzhen/dsh-evolution-core": "^0.3.83"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.3.81",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.81"
+    "@lmzhen/dsh-evolution-io": "^0.3.83",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.83"
   },
   "devDependencies": {
-    "@lmzhen/dsh-evolution-io": "^0.3.81",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.81",
-    "@lmzhen/dsh-evolution-io-node": "^0.3.81"
+    "@lmzhen/dsh-evolution-io": "^0.3.83",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.83",
+    "@lmzhen/dsh-evolution-io-node": "^0.3.83"
   }
 }