@lmzhen/dsh-evolution-state-json 0.3.62 → 0.3.64

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 —
@@ -90,7 +91,7 @@ const PENDING_STATUSES = new Set([
 ]);
 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 gatePendingRecord = (record) => typeof record.id === "string" && typeof record.kind === "string" && PENDING_KINDS.has(record.kind) && typeof record.summary === "string" && "args" in record && 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,
@@ -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,15 +177,15 @@ 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 new Error(`evolution state file "${file}" write-back carries ${failing.length} record(s) that fail the field gate (${failing.map(([id]) => id).join(", ")}); not written.`);
+			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);
 	});
 }
-function apply(ctx, rawConfig) {
+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();
@@ -240,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 {};
 		}
@@ -272,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);
@@ -309,7 +322,9 @@ function apply(ctx, rawConfig) {
 				if (current !== null) try {
 					const parsed = JSON.parse(current);
 					if (Array.isArray(parsed)) archive = parsed;
-				} catch {}
+				} catch {
+					await io().writeText(`${pathOf(PENDING_ARCHIVE_FILE)}.corrupt`, current).catch(() => {});
+				}
 				const shaped = archive.filter((entry) => entry !== null && typeof entry === "object");
 				const archiveKeys = /* @__PURE__ */ new Set();
 				const collapsed = shaped.filter((entry) => {

package/lib/types/index.d.ts

@@ -15,5 +15,5 @@ export interface Config {
 }
 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>): Promise<void>;
-export declare function apply(ctx: Context, rawConfig: Config): 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.62",
+  "version": "0.3.64",
   "publishConfig": {
     "access": "public"
   },
@@ -31,18 +31,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.62"
+    "@lmzhen/dsh-evolution-core": "^0.3.64"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.3.62",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.62"
+    "@lmzhen/dsh-evolution-io": "^0.3.64",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.64"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.3.62",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.62",
-    "@lmzhen/dsh-evolution-io-node": "^0.3.62"
+    "@lmzhen/dsh-evolution-io": "^0.3.64",
+    "@lmzhen/dsh-evolution-state-storage": "^0.3.64",
+    "@lmzhen/dsh-evolution-io-node": "^0.3.64"
   }
 }