@lmzhen/dsh-evolution-state-json 0.3.61 → 0.3.63

package/README.md

@@ -22,5 +22,6 @@ Independent of request-prefix construction. This package does not alter the asse
 ## Known Limitations and Deferred Work
 
 
+- P2-4 (v15): the live pending map is BOUNDED — resolved (approved/rejected) records are kept to the most recent `PENDING_RESOLVED_CAP` (200, seam constant in `evolution-state-storage`); the oldest by `resolvedAt` rotate into the `pending-state-archive.json` sidecar (with `.bak` rotation), which is JSON-provider-specific. The DOMAIN provider enforces the same live cap but has no sidecar: past the cap its resolved records are deleted, not archived.
 - 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,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, 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 { CURATOR_STATE_FILE, CURATOR_STATE_KEY, PENDING_ARCHIVE_BAK_FILE, PENDING_ARCHIVE_FILE, PENDING_LEGACY_FILE, PENDING_RESOLVED_CAP, 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
 /**
@@ -15,9 +15,10 @@ const inject = ["evolutionStateStorage", "evolutionIo"];
 const Config = z.object({ root: z.string().default("") });
 /** 0.3.22 (F-336): resolved (approved/rejected) audit records are capped in
 * the LIVE pending map so a long-running deployment never grows it without
-* bound; the oldest over the cap are archived (made package-private so the
-* archive sidecar and the provider enforce one number). */
-const PENDING_RESOLVED_CAP = 200;
+* bound; the oldest over the cap are archived. P2-4 (v15): the number lives
+* on the seam (`SEAM_PENDING_RESOLVED_CAP`) so the domain provider enforces
+* the same bound; the archive sidecar below stays json-specific. */
+const PENDING_RESOLVED_CAP$1 = PENDING_RESOLVED_CAP;
 /** 0.3.27 (V4-01): the audit sidecar (pending-state-archive.json) is bounded
 * at this many resolved records. Past it the oldest history rotates to a
 * `.bak` sidecar, so the file — and the full-array rewrite on every append —
@@ -123,6 +124,15 @@ function gateScan(file, parsed) {
 const recordGateWarned = /* @__PURE__ */ new Set();
 const corruptWritten = /* @__PURE__ */ new Map();
 const corruptWriteWarned = /* @__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. */
+const WRITE_GATE_ERROR_NAME = "EvolutionStateWriteGate";
+function writeGateError(message) {
+	const error = new Error(message);
+	error.name = WRITE_GATE_ERROR_NAME;
+	return error;
+}
 function reportGateViolation(ctx, file, failing) {
 	if (recordGateWarned.has(file)) return;
 	recordGateWarned.add(file);
@@ -130,7 +140,10 @@ function reportGateViolation(ctx, file, failing) {
 }
 async function ensureCorruptCopy(ctx, io, root, file, bad) {
 	const corruptPath = `${join(root, file)}.corrupt`;
-	const corruptKey = JSON.stringify(Object.keys(bad).sort());
+	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(corruptPath)) return;
 	if (await io().writeText(corruptPath, JSON.stringify(bad, null, 2)).then(() => true).catch(() => false)) {
 		corruptWritten.set(file, corruptKey);
@@ -164,7 +177,11 @@ async function jsonTransact(ctx, io, root, file, task) {
 			}
 		}
 		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.`);
+		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.`);
+		if (next !== null && RECORD_MAP_FILES.has(file)) {
+			const failing = gateScan(file, next);
+			if (failing.length > 0) throw writeGateError(`evolution state file "${file}" write-back carries ${failing.length} record(s) that fail the field gate (${failing.map(([id]) => id).join(", ")}); not written.`);
+		}
 		return next === null ? null : JSON.stringify(next, null, 2);
 	});
 }
@@ -236,7 +253,7 @@ function apply(ctx, rawConfig) {
 			legacyMigrated = true;
 			return retired;
 		} catch (error) {
-			if (error instanceof Error && error.name === QUARANTINE_ERROR_NAME) throw 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 {};
 		}
@@ -268,11 +285,11 @@ function apply(ctx, rawConfig) {
 	* mutating in place) plus the evicted records. */
 	function enforceResolvedCap(map) {
 		const resolved = Object.values(map).filter((record) => record.status === "approved" || record.status === "rejected");
-		if (resolved.length <= PENDING_RESOLVED_CAP) return {
+		if (resolved.length <= PENDING_RESOLVED_CAP$1) return {
 			map,
 			evicted: []
 		};
-		const overflow = resolved.length - PENDING_RESOLVED_CAP;
+		const overflow = resolved.length - PENDING_RESOLVED_CAP$1;
 		const entryTime = (record) => {
 			if (!record.resolvedAt) return Number.MAX_SAFE_INTEGER;
 			const parsed = Date.parse(record.resolvedAt);
@@ -420,7 +437,7 @@ function apply(ctx, rawConfig) {
 				});
 			});
 		},
-		async tryResolvePending(id, status) {
+		async tryResolvePending(id, status, expectedClaimId) {
 			return await mutate(async () => {
 				let result = {
 					record: null,
@@ -437,6 +454,13 @@ function apply(ctx, rawConfig) {
 						};
 						return map;
 					}
+					if (expectedClaimId !== void 0 && record.claimedBy !== expectedClaimId) {
+						result = {
+							record,
+							applied: false
+						};
+						return map;
+					}
 					const resolved = {
 						...record,
 						status,

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.61",
+  "version": "0.3.63",
   "publishConfig": {
     "access": "public"
   },
@@ -31,18 +31,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.61"
+    "@lmzhen/dsh-evolution-core": "^0.3.63"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.3.61",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.61"
+    "@lmzhen/dsh-evolution-io": "^0.3.63",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.63"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.3.61",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.61",
-    "@lmzhen/dsh-evolution-io-node": "^0.3.61"
+    "@lmzhen/dsh-evolution-io": "^0.3.63",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.63",
+    "@lmzhen/dsh-evolution-io-node": "^0.3.63"
   }
 }