@lmzhen/dsh-evolution-state-json 0.3.82 → 0.4.0

package/README.md

@@ -1,30 +1,28 @@
-# @deepseek-ai/dsh-evolution-state-json
+# @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.
 
-`@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.
+## 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

@@ -1,6 +1,6 @@
 import z from "@deepseek-ai/schemastery";
 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, recordIssue, releasedStatus, selectPendingOverflow, selectSessionOverflow } from "@lmzhen/dsh-evolution-state-storage";
+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
 /**
@@ -540,14 +540,17 @@ function apply(ctx, rawConfig = {}) {
 		},
 		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") {

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