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

package/README.md

@@ -1,30 +1,28 @@
 # @lmzhen/dsh-evolution-state-json
 
-JSON-file evolution state provider over the IO seam
+JSON-file evolution state provider over the IO seam: review, curator and pending records are JSON
+files under the state root, so the medium behind `ctx.evolutionIo` can change without a format
+change.
 
+## Model surface
 
-## Model Experience
+- **Model-visible:** nothing of its own: the rows that read this state own the injection.
+- **Prompt prefix / KV cache:** unchanged by this package: family-level rules single-sourced in `packages/README.md` §"Model-visible prompt prefix and the KV cache".
+- **Mount it?** yes — the `evolution-state-json` row, in `evolution-host`/`evolution-all`/one-click `evolution-preset` (it is the medium they pin).
 
-### Indirect model surface
+## Configuration
 
-#### What the model sees
+- `root`: the directory the state files live in; `''` means the evolution home.
 
-`@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.
+## Known limitations
 
-#### Token effect
-
-Zero direct token effect from this package; consumers add any model-visible tokens.
-
-#### KV Cache effect
-
-Independent of request-prefix construction. This package does not alter the assembled prompt or tool list.
-
-## 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.
-- V25-11 (v25): the review-state table is likewise BOUNDED — `REVIEW_STATE_SESSION_CAP` (500, seam constant) rows keyed by session; on every save the least-recently-active sessions (provider-stamped `updatedAt`, stored on disk only) are pruned. The stamp is stripped on read, so the consumer-facing record shape is unchanged.
-- 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.
+- Both tables are capped (200 pending, 500 sessions), and past the pending cap the DOMAIN provider deletes instead of archiving: this provider keeps an audit sidecar. The `updatedAt` stamp is stripped on read, so the consumer-facing record shape is unchanged.
+- The one medium without cross-process write locking is the `storage-json` store behind the DOMAIN provider: route multi-process deployments to a backend with cross-process semantics such as SQLite or remote storage.
 
 **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).
 
+## Notes and history
+
+- 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.
+- V25-11 (v25): the review-state table is likewise BOUNDED: `REVIEW_STATE_SESSION_CAP` (500, seam constant) rows keyed by session; on every save the least-recently-active sessions (provider-stamped `updatedAt`, stored on disk only) are pruned.
+- 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.

package/lib/index.js

@@ -274,6 +274,36 @@ function apply(ctx, rawConfig = {}) {
 		if (file === PENDING_STATE_FILE) gateDroppedCurrent.clear();
 		return parsed;
 	}
+	/** A5 (audit P2-9): the LEGACY pending sidecar is read LENIENTLY — the
+	* deliberate opposite of the live state file's fail-loud posture. This
+	* file's whole purpose is to be retired, but the retirement merge reads
+	* it first, so one truncated pre-migration `pending.json` used to make
+	* EVERY pending read and mutation throw `EvolutionStateCorruptFile`
+	* forever (a permanent operator outage no warning can repair). A
+	* QUARANTINE-CLASS failure (unreadable/corrupt content) is renamed aside
+	* so every later load sees a clean absence; any OTHER failure (EACCES,
+	* EIO — a permission-locked but possibly VALID file) is left in place and
+	* only skips this read, so a transient hold never exiles real records.
+	* Either way the view continues current-only with one warn per process.
+	* Note the moved-aside copy is NOT auto-swept (the stale-copy sweep only
+	* inspects entries prefixed like the file being written, and nothing
+	* writes a `pending.json` prefix anymore) — it persists until an operator
+	* deletes it after rescue, at most one per corruption episode. */
+	let legacyQuarantineWarned = false;
+	async function readLegacyPending() {
+		try {
+			return await readJson(PENDING_LEGACY_FILE);
+		} catch (error) {
+			if (error instanceof Error && error.name === QUARANTINE_ERROR_NAME) try {
+				await io().rename(pathOf(PENDING_LEGACY_FILE), `${pathOf(PENDING_LEGACY_FILE)}.corrupt.${Date.now()}`);
+			} catch {}
+			if (!legacyQuarantineWarned) {
+				legacyQuarantineWarned = true;
+				ctx.logger.warn(`evolution-state-json: legacy ${PENDING_LEGACY_FILE} is unreadable and was set aside (${error instanceof Error ? error.message : String(error)}); continuing WITHOUT legacy records`);
+			}
+			return null;
+		}
+	}
 	const mutate = makeSerialQueue();
 	let legacyMigrated = false;
 	async function readArchivedIds() {
@@ -356,7 +386,7 @@ function apply(ctx, rawConfig = {}) {
 		}
 	}
 	async function loadPendingMap() {
-		const [current, legacy] = await Promise.all([readJson(PENDING_STATE_FILE), readJson(PENDING_LEGACY_FILE)]);
+		const [current, legacy] = await Promise.all([readJson(PENDING_STATE_FILE), readLegacyPending()]);
 		const keyed = keyPendingById(current);
 		if (legacy !== null) return {
 			...await retireLegacyOnce(legacy),
@@ -564,7 +594,7 @@ function apply(ctx, rawConfig = {}) {
 				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 ?? {}),
+						...await mergedWithFilteredLegacy(legacyMigrated ? null : await readLegacyPending(), current ?? {}),
 						[record.id]: record
 					};
 					warnPendingGrowth(map, "save");
@@ -577,7 +607,7 @@ function apply(ctx, rawConfig = {}) {
 			return await mutate(async () => {
 				const slot = { claimed: null };
 				await pendingTransact(async (current) => {
-					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson(PENDING_LEGACY_FILE), current ?? {}) };
+					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readLegacyPending(), current ?? {}) };
 					const record = map[id] ?? null;
 					if (record === null || !canClaimPending(record.status)) return map;
 					const now = Date.now();
@@ -597,7 +627,7 @@ function apply(ctx, rawConfig = {}) {
 		async releasePendingClaim(id, claimId) {
 			await mutate(async () => {
 				await pendingTransact(async (current) => {
-					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson(PENDING_LEGACY_FILE), current ?? {}) };
+					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readLegacyPending(), current ?? {}) };
 					const record = map[id];
 					if (!record || record.claimedBy !== claimId) return map;
 					if (record.status !== "pending" && record.status !== "executing") return map;
@@ -615,7 +645,7 @@ function apply(ctx, rawConfig = {}) {
 					applied: false
 				};
 				await pendingTransact(async (current) => {
-					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readJson(PENDING_LEGACY_FILE), current ?? {}) };
+					const map = { ...await mergedWithFilteredLegacy(legacyMigrated ? null : await readLegacyPending(), current ?? {}) };
 					const record = map[id] ?? null;
 					if (record === null || !canResolvePending(record.status)) {
 						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.83",
+  "version": "0.4.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,16 +27,16 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.83"
+    "@lmzhen/dsh-evolution-core": "^0.4.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.3.83",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.83"
+    "@lmzhen/dsh-evolution-io": "^0.4.1",
+    "@lmzhen/dsh-evolution-state-storage": "^0.4.1"
   },
   "devDependencies": {
-    "@lmzhen/dsh-evolution-io": "^0.3.83",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.83",
-    "@lmzhen/dsh-evolution-io-node": "^0.3.83"
+    "@lmzhen/dsh-evolution-io": "^0.4.1",
+    "@lmzhen/dsh-evolution-state-storage": "^0.4.1",
+    "@lmzhen/dsh-evolution-io-node": "^0.4.1"
   }
 }