@lmzhen/dsh-evolution-state-json 0.1.0-rc.1

package/README.md

@@ -0,0 +1,26 @@
+# @deepseek-ai/dsh-evolution-state-json
+
+JSON-file evolution state provider over the IO seam
+
+
+## Model Experience
+
+### Indirect model surface
+
+#### 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.
+
+#### 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
+
+
+- JSON provider serializes writers inside one process. Cross-process locking is a DSH storage-layer limitation (`storage-json` documents no cross-process write locking); 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

@@ -0,0 +1,132 @@
+import z from "@deepseek-ai/schemastery";
+import { homedir } from "node:os";
+import { join } from "node:path";
+//#region lib/types/index.js
+/**
+* JSON-file evolution state provider over the IO seam.
+*
+* This is the portable provider: `ctx.evolutionIo` may be node:fs today and a
+* network/shared medium tomorrow without any state-format changes.
+* @module @lmzhen/dsh-evolution-state-json
+*/
+const name = "evolution-state-json";
+const inject = ["evolutionStateStorage", "evolutionIo"];
+const Config = z.object({ root: z.string().default("") });
+function defaultRoot(env = process.env) {
+	return join(env.DSH_HOME ?? join(homedir(), ".dsh"), "evolution");
+}
+function apply(ctx, rawConfig) {
+	const root = rawConfig.root || defaultRoot();
+	const io = () => ctx.evolutionIo.provider();
+	const pathOf = (file) => join(root, file);
+	async function readJson(file) {
+		const raw = await io().readText(pathOf(file));
+		if (raw === null) return null;
+		try {
+			return JSON.parse(raw);
+		} catch {
+			return null;
+		}
+	}
+	async function writeJson(file, value) {
+		await io().writeText(pathOf(file), JSON.stringify(value, null, 2));
+	}
+	let chain = Promise.resolve();
+	function mutate(task) {
+		const run = chain.then(task, task);
+		chain = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	async function loadPendingMap() {
+		const [current, legacy] = await Promise.all([readJson("pending-state.json"), readJson("pending.json")]);
+		return {
+			...legacy ?? {},
+			...current ?? {}
+		};
+	}
+	const provider = {
+		name: "json",
+		async loadReviewState(sessionId) {
+			return await mutate(async () => {
+				return (await readJson("review-state.json"))?.[sessionId] ?? null;
+			});
+		},
+		async saveReviewState(sessionId, record) {
+			await mutate(async () => {
+				const map = await readJson("review-state.json") ?? {};
+				map[sessionId] = record;
+				await writeJson("review-state.json", map);
+			});
+		},
+		async loadCuratorState() {
+			return await mutate(async () => {
+				return (await readJson("curator-state.json"))?.primary ?? null;
+			});
+		},
+		async saveCuratorState(record) {
+			await mutate(async () => {
+				const map = await readJson("curator-state.json") ?? {};
+				map.primary = record;
+				await writeJson("curator-state.json", map);
+			});
+		},
+		async listPending(status = "pending") {
+			return await mutate(async () => {
+				const map = await loadPendingMap();
+				return Object.values(map).filter((record) => record.status === status);
+			});
+		},
+		async savePending(record) {
+			await mutate(async () => {
+				const map = await loadPendingMap();
+				map[record.id] = record;
+				await writeJson("pending-state.json", map);
+			});
+		},
+		async claimPending(id, claimId) {
+			return await mutate(async () => {
+				const map = await loadPendingMap();
+				const record = map[id] ?? null;
+				if (record === null || record.status !== "pending") return null;
+				const now = Date.now();
+				const claimedAt = typeof record.claimedAt === "string" ? Date.parse(record.claimedAt) : 0;
+				if (record.claimedBy !== void 0 && Number.isFinite(claimedAt) && now - claimedAt < 10 * 6e4) return null;
+				record.claimedBy = claimId;
+				record.claimedAt = new Date(now).toISOString();
+				await writeJson("pending-state.json", map);
+				return { ...record };
+			});
+		},
+		async releasePendingClaim(id, claimId) {
+			await mutate(async () => {
+				const map = await loadPendingMap();
+				const record = map[id];
+				if (record && record.status === "pending" && record.claimedBy === claimId) {
+					delete record.claimedBy;
+					delete record.claimedAt;
+					await writeJson("pending-state.json", map);
+				}
+			});
+		},
+		async tryResolvePending(id, status) {
+			return await mutate(async () => {
+				const map = await loadPendingMap();
+				const record = map[id] ?? null;
+				if (record === null || record.status !== "pending") return {
+					record,
+					applied: false
+				};
+				record.status = status;
+				record.resolvedAt = (/* @__PURE__ */ new Date()).toISOString();
+				await writeJson("pending-state.json", map);
+				return {
+					record,
+					applied: true
+				};
+			});
+		}
+	};
+	ctx.effect(() => ctx.evolutionStateStorage.registerProvider(provider), "evolution-state-json.provider");
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,8 @@
+//#region lib/types/invariant.js
+const PACKAGE_NAME = "@deepseek-ai/dsh-evolution-state-json";
+const name = "evolution-state-json-invariant";
+const inject = ["invariants"];
+const install = () => {};
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * JSON-file evolution state provider over the IO seam.
+ *
+ * This is the portable provider: `ctx.evolutionIo` may be node:fs today and a
+ * network/shared medium tomorrow without any state-format changes.
+ * @module @deepseek-ai/dsh-evolution-state-json
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "evolution-state-json";
+export declare const inject: string[];
+export interface Config {
+    root?: string;
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, rawConfig: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "evolution-state-json-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@lmzhen/dsh-evolution-state-json",
+  "description": "JSON-file evolution state provider over the IO seam (community build)",
+  "version": "0.1.0-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/dsh-evolution-state-json"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/invariant.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-state-storage": "^0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-state-storage": "^0.1.0-rc.1"
+  }
+}