@lmzhen/dsh-memory-files 0.16.1 → 0.17.0

package/lib/index.js

@@ -1,34 +1,53 @@
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import z from "@deepseek-ai/schemastery";
-import { DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_USER_CHAR_LIMIT, MemoryStore, PARAM_NAMESPACES, clampedNumber, evolutionIoAdapter, installParamSection, makeSerialQueue } from "@lmzhen/dsh-evolution-core";
+import { DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_USER_CHAR_LIMIT, MemoryStore, clampedNumber, evolutionIoAdapter, makeSerialQueue, paramRowId } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Local layered memory provider for `ctx.memory`.
 * @module @lmzhen/dsh-memory-files
 */
-const MEMORY_SETTINGS_SCHEMA = z.object({
-	memoryChars: z.number().min(1).default(DEFAULT_MEMORY_CHAR_LIMIT),
-	userChars: z.number().min(1).default(DEFAULT_USER_CHAR_LIMIT),
-	addDatePrefix: z.boolean().default(false),
-	maxConsolidationFailures: z.number().min(1).default(DEFAULT_CONSOLIDATION_FAILURES)
-});
 const name = "memory-files";
 const inject = ["memory", "evolutionIo"];
 const Config = z.object({
 	providerName: z.string().default("files"),
+	memoryChars: z.number().min(1).volatile(),
+	userChars: z.number().min(1).volatile(),
 	memoryCharLimit: z.number().min(1).default(DEFAULT_MEMORY_CHAR_LIMIT),
 	userCharLimit: z.number().min(1).default(DEFAULT_USER_CHAR_LIMIT),
-	addDatePrefix: z.boolean().default(false),
+	addDatePrefix: z.boolean().default(false).volatile(),
 	root: z.string().default(""),
-	maxConsolidationFailures: z.number().min(1).default(DEFAULT_CONSOLIDATION_FAILURES),
+	maxConsolidationFailures: z.number().min(1).default(DEFAULT_CONSOLIDATION_FAILURES).volatile(),
 	threatExemptLabels: z.array(z.string()).default([])
 });
 function apply(ctx, rawConfig = {}) {
-	const clamped = [];
+	ctx.inject(["settings"], (injected) => {
+		const settings = injected.settings;
+		if (typeof settings?.configure !== "function") return;
+		const disposer = settings.configure({ auto: false });
+		if (typeof disposer === "function") ctx.effect(() => disposer, "memory-files: settings presentation");
+	});
+	const clampedKeys = /* @__PURE__ */ new Set();
+	/**
+	* One live numeric row field as the platform resolved it.
+	* @param value - the field, or its volatile reference.
+	* @returns the current plain value, or undefined when nothing supplied one.
+	*/
+	const liveNumber = (value) => typeof value === "object" ? value.get() : value;
+	/**
+	* Clamp one supplied numeric value, warning once per key.
+	* @param name - the config key, for the warning.
+	* @param value - the value as supplied by the deployment or the user.
+	* @param fallback - the package default a corrected value falls back to.
+	* @returns the value the store may use.
+	*/
 	const field = (name, value, fallback) => {
-		const result = clampedNumber(value, fallback, { min: 1 });
-		if (value !== void 0 && result !== value) clamped.push(name);
+		const current = liveNumber(value);
+		const result = clampedNumber(current, fallback, { min: 1 });
+		if (current !== void 0 && result !== current && !clampedKeys.has(name)) {
+			clampedKeys.add(name);
+			ctx.logger.warn(`memory-files: ${name} provided an invalid value; falling back to the default`);
+		}
 		return result;
 	};
 	const floorLimit = (value) => Math.floor(value);
@@ -39,58 +58,99 @@ function apply(ctx, rawConfig = {}) {
 			user: snapshot?.userChars
 		};
 	};
-	const budget = policyBudget();
-	const schemaDefaults = Config["~standard"].validate({}).value;
-	const explicitLimit = (name) => rawConfig[name] !== void 0 && rawConfig[name] !== schemaDefaults[name];
-	const config = Object.assign({}, rawConfig, {
-		memoryCharLimit: floorLimit(field("memoryCharLimit", explicitLimit("memoryCharLimit") ? rawConfig.memoryCharLimit : budget.memory, DEFAULT_MEMORY_CHAR_LIMIT)),
-		userCharLimit: floorLimit(field("userCharLimit", explicitLimit("userCharLimit") ? rawConfig.userCharLimit : budget.user, DEFAULT_USER_CHAR_LIMIT)),
-		maxConsolidationFailures: field("maxConsolidationFailures", rawConfig.maxConsolidationFailures, DEFAULT_CONSOLIDATION_FAILURES)
-	});
-	if (clamped.length > 0) ctx.logger.warn(`memory-files: ${clamped.join(", ")} provided an invalid value; falling back to the default`);
-	if (explicitLimit("memoryCharLimit") && budget.memory !== void 0 && config.memoryCharLimit !== budget.memory) ctx.logger.warn(`memory-files: memoryCharLimit=${config.memoryCharLimit} contradicts evolution-policy memoryChars=${budget.memory} — the store enforces the row value while the review plans against the policy value; align them or leave the row unset`);
-	if (explicitLimit("userCharLimit") && budget.user !== void 0 && config.userCharLimit !== budget.user) ctx.logger.warn(`memory-files: userCharLimit=${config.userCharLimit} contradicts evolution-policy userChars=${budget.user} — same divergence as memoryCharLimit`);
+	const aliasDefaults = Config["~standard"].validate({}).value;
+	const ALIAS_OF = {
+		memoryChars: "memoryCharLimit",
+		userChars: "userCharLimit"
+	};
+	const DEFAULTS = {
+		memoryChars: DEFAULT_MEMORY_CHAR_LIMIT,
+		userChars: DEFAULT_USER_CHAR_LIMIT
+	};
+	/**
+	* The live value of one canonical budget key (G1 §8.3).
+	* @param id - the canonical registry id.
+	* @returns the value the platform resolved (user layer included), or undefined.
+	*/
+	const canonicalBudget = (id) => liveNumber(id === "memoryChars" ? rawConfig.memoryChars : rawConfig.userChars);
+	/**
+	* Whether the OPERATOR set this budget on THIS ROW (G0/S0.4 + G1).
+	*
+	* The canonical key answers through its live reference — a user-layer value
+	* arrives the same way, which is what keeps a user choice ahead of the policy —
+	* and the deprecated alias through the default comparison above. The pair is
+	* documented in the Config JSDoc and reported by /evolution doctor (budgetIssues).
+	* @param id - the canonical registry id.
+	* @returns whether the row or the user supplied a value.
+	*/
+	const explicitBudget = (id) => {
+		if (canonicalBudget(id) !== void 0) return true;
+		const alias = rawConfig[ALIAS_OF[id]];
+		return alias !== void 0 && alias !== aliasDefaults[ALIAS_OF[id]];
+	};
+	/**
+	* The budget one key resolves to (G1 §8.4-A): the row's own value — canonical or
+	* alias — over the mounted policy, over the package default.
+	* @param id - the canonical registry id.
+	* @returns the resolved, unclamped budget.
+	*/
+	const budget = (id) => {
+		const explicit = canonicalBudget(id) ?? (explicitBudget(id) ? rawConfig[ALIAS_OF[id]] : void 0);
+		if (explicit !== void 0) return explicit;
+		const policy = policyBudget();
+		return (id === "memoryChars" ? policy.memory : policy.user) ?? DEFAULTS[id];
+	};
+	const memoryChars = () => floorLimit(field("memoryCharLimit", budget("memoryChars"), DEFAULT_MEMORY_CHAR_LIMIT));
+	const userChars = () => floorLimit(field("userCharLimit", budget("userChars"), DEFAULT_USER_CHAR_LIMIT));
+	const consolidationFailures = () => field("maxConsolidationFailures", rawConfig.maxConsolidationFailures, DEFAULT_CONSOLIDATION_FAILURES);
+	const addDatePrefix = () => rawConfig.addDatePrefix?.get() ?? false;
+	const policyAtMount = policyBudget();
+	if (explicitBudget("memoryChars") && policyAtMount.memory !== void 0 && memoryChars() !== policyAtMount.memory) ctx.logger.warn(`memory-files: the row's memoryChars=${memoryChars()} contradicts evolution-policy memoryChars=${policyAtMount.memory} — the store enforces the row value while the review plans against the policy value; align them or leave the row unset`);
+	if (explicitBudget("userChars") && policyAtMount.user !== void 0 && userChars() !== policyAtMount.user) ctx.logger.warn(`memory-files: the row's userChars=${userChars()} contradicts evolution-policy userChars=${policyAtMount.user} — same divergence as memoryChars`);
 	const io = evolutionIoAdapter(() => ctx.evolutionIo.provider());
 	const serializedWrite = makeSerialQueue();
-	const trimmedRoot = (config.root || "").trim();
+	const trimmedRoot = (rawConfig.root || "").trim();
 	const resolvedRoot = trimmedRoot === "" ? "" : resolve(trimmedRoot);
-	const section = {};
-	const buildStore = () => new MemoryStore({
-		memoryCharLimit: section.overrides?.get("memoryChars") ?? config.memoryCharLimit,
-		userCharLimit: section.overrides?.get("userChars") ?? config.userCharLimit,
-		addDatePrefix: section.overrides?.get("addDatePrefix") ?? config.addDatePrefix,
-		maxConsolidationFailures: section.overrides?.get("maxConsolidationFailures") ?? config.maxConsolidationFailures,
-		threatExemptLabels: config.threatExemptLabels,
-		...resolvedRoot !== "" ? { root: resolvedRoot } : {},
-		io
-	});
-	let store = buildStore();
-	section.overrides = installParamSection(ctx, PARAM_NAMESPACES["memory-files"] ?? "evolution-memory", MEMORY_SETTINGS_SCHEMA, {
-		memoryChars: config.memoryCharLimit,
-		userChars: config.userCharLimit,
-		addDatePrefix: config.addDatePrefix,
-		maxConsolidationFailures: config.maxConsolidationFailures
-	}, {
-		warn: (message) => {
-			ctx.logger.warn("memory-files: " + message);
-		},
-		onChange: () => {
-			store = buildStore();
-		}
-	});
+	let store;
+	let storeKey = "";
+	/**
+	* The store for the configuration as it stands right now.
+	* @returns the current store, rebuilt when a resolved limit changed.
+	*/
+	const currentStore = () => {
+		const options = {
+			memoryCharLimit: memoryChars(),
+			userCharLimit: userChars(),
+			addDatePrefix: addDatePrefix(),
+			maxConsolidationFailures: consolidationFailures()
+		};
+		const key = `${options.memoryCharLimit}|${options.userCharLimit}|${options.addDatePrefix}|${options.maxConsolidationFailures}`;
+		if (store !== void 0 && key === storeKey) return store;
+		store = new MemoryStore({
+			...options,
+			...rawConfig.threatExemptLabels !== void 0 ? { threatExemptLabels: rawConfig.threatExemptLabels } : {},
+			...resolvedRoot !== "" ? { root: resolvedRoot } : {},
+			io
+		});
+		storeKey = key;
+		return store;
+	};
 	const provider = {
-		name: config.providerName,
-		read: (target) => store.read(target),
+		name: rawConfig.providerName ?? "files",
+		read: (target) => currentStore().read(target),
 		applyBatch: async (target, operations) => {
 			const normalized = operations.map((op) => ({
 				action: op.action,
 				facts: op.facts ?? op.content,
 				old_text: op.old_text
 			}));
-			return await serializedWrite(() => store.applyBatch(target, normalized));
+			return await serializedWrite(() => currentStore().applyBatch(target, normalized));
 		},
 		snapshot: async () => {
-			const [memory, user] = await serializedWrite(async () => [await store.read("memory"), await store.read("user")]);
+			const [memory, user] = await serializedWrite(async () => {
+				const current = currentStore();
+				return [await current.read("memory"), await current.read("user")];
+			});
 			const text = JSON.stringify([memory, user]);
 			return {
 				version: 1,
@@ -99,30 +159,51 @@ function apply(ctx, rawConfig = {}) {
 				user
 			};
 		},
-		renderContext: () => serializedWrite(() => store.renderContext())
+		renderContext: () => serializedWrite(() => currentStore().renderContext())
+	};
+	/**
+	* The keys the user set in this row's namespace (G1 §8.4-A). This is the ONLY
+	* remaining read of the settings user layer, and it reads KEY NAMES, never
+	* values: the platform resolves the user layer into the row's live fields, so the
+	* value comes from `budget` — but naming the winning surface needs to know
+	* whether the user set the key at all.
+	* @returns the keys present in this row's user layer.
+	*/
+	const userSetKeys = () => {
+		const entry = ctx.get("settings")?.describe?.({ redactSecrets: false }).find((item) => item.ns === paramRowId("memory-files"));
+		return new Set(Object.keys(entry?.user ?? {}));
 	};
-	const limitSource = (name, explicit, policyValue) => {
-		if (section.overrides?.get(name) !== void 0) return "user";
-		if (explicit) return "config";
-		return policyValue === void 0 ? "default" : "policy";
+	/**
+	* Which surface supplied one budget.
+	* @param id - the canonical registry id.
+	* @returns 'user', 'config', 'policy' or 'default'.
+	*/
+	const limitSource = (id) => {
+		if (userSetKeys().has(id)) return "user";
+		if (explicitBudget(id)) return "config";
+		return (id === "memoryChars" ? policyBudget().memory : policyBudget().user) === void 0 ? "default" : "policy";
 	};
 	ctx.provide("evolutionMemoryBudget", {
 		get memoryCharLimit() {
-			return section.overrides?.get("memoryChars") ?? config.memoryCharLimit;
+			return memoryChars();
 		},
 		get userCharLimit() {
-			return section.overrides?.get("userChars") ?? config.userCharLimit;
+			return userChars();
 		},
 		get memorySource() {
-			return limitSource("memoryChars", explicitLimit("memoryCharLimit"), budget.memory);
+			return limitSource("memoryChars");
 		},
 		get userSource() {
-			return limitSource("userChars", explicitLimit("userCharLimit"), budget.user);
+			return limitSource("userChars");
 		},
-		policyMemoryChars: budget.memory,
-		policyUserChars: budget.user
+		get policyMemoryChars() {
+			return policyBudget().memory;
+		},
+		get policyUserChars() {
+			return policyBudget().user;
+		}
 	});
 	ctx.effect(() => ctx.memory.registerProvider(provider), "memory-files.provider");
 }
 //#endregion
-export { Config, MEMORY_SETTINGS_SCHEMA, apply, inject, name };
+export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -2,46 +2,59 @@
  * Local layered memory provider for `ctx.memory`.
  * @module @lmzhen/dsh-memory-files
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-/** G3/S3.2: the memory section's schema. Field names are the CANONICAL ids from
- * the parameter registry (`memoryChars`/`userChars` are the policy-side names the
- * review planner reads too), so the settings document, the params output, the
- * doctor report and the cards spell one name. */
-export interface MemorySettings {
-    /** Character budget the store enforces for MEMORY.md. */
-    memoryChars: number;
-    /** Character budget the store enforces for USER.md. */
-    userChars: number;
-    /** Prefix stored entries with their date heading. */
-    addDatePrefix: boolean;
-    /** Consolidation failures one turn tolerates before the tool stops retrying. */
-    maxConsolidationFailures: number;
-}
-export declare const MEMORY_SETTINGS_SCHEMA: z<MemorySettings>;
 export declare const name = "memory-files";
 export declare const inject: string[];
 export interface Config {
     providerName?: string;
-    /** Store-enforced character budget for MEMORY.md. The policy row's
-     * `memoryChars` is the same semantic on the review-planner side and is the
-     * canonical id (G0/S0.2); the two are NOT auto-synchronised —
-     * `/evolution doctor` reports the divergence (budgetIssues). Deprecated alias
-     * (G0/S0.3): still readable, refused by writes; removed in 0.7.0. */
+    /** Store-enforced character budget for MEMORY.md — the CANONICAL registry id
+     * (G1) and a LIVE row field (registry tier E3). The policy row's `memoryChars`
+     * is the same semantic on the review-planner side; the two are NOT
+     * auto-synchronised — `/evolution doctor` reports the divergence (budgetIssues).
+     * A row may spell either this name or the deprecated alias below. No schema
+     * default: the alias carries it, and a default on the canonical key would fill
+     * it and leave the alias unreachable (the store resolves
+     * DEFAULT_MEMORY_CHAR_LIMIT after the alias fallback). */
+    memoryChars?: Volatile<number | undefined>;
+    /** Store-enforced character budget for USER.md — the CANONICAL registry id (G1),
+     * a live row field on the same terms as `memoryChars`. */
+    userChars?: Volatile<number | undefined>;
+    /** Deprecated alias of `memoryChars` (G0/S0.3): still readable, refused by
+     * writes; removed in 0.7.0. */
     memoryCharLimit?: number;
-    /** Store-enforced character budget for USER.md; the canonical id is the policy
-     * row's `userChars`. Divergence is reported by `/evolution doctor`. Deprecated
-     * alias (G0/S0.3): still readable, refused by writes; removed in 0.7.0. */
+    /** Deprecated alias of `userChars` (G0/S0.3): still readable, refused by
+     * writes; removed in 0.7.0. */
     userCharLimit?: number;
-    addDatePrefix?: boolean;
+    addDatePrefix?: Volatile<boolean>;
     root?: string;
     /** How many consolidation failures one turn tolerates before the tool tells the model to stop retrying. */
-    maxConsolidationFailures?: number;
+    maxConsolidationFailures?: Volatile<number>;
     /** F-2 (v18): deployment-declared benign threat labels for the MEMORY store.
      * The skill/guard channels already read this option; without it the
      * README's "MemoryStore store option" exemption was unreachable. */
     threatExemptLabels?: string[];
 }
-export declare const Config: z<Config>;
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    providerName: z<string, string, "defined">;
+    memoryChars: z<number, number, "volatile">;
+    userChars: z<number, number, "volatile">;
+    memoryCharLimit: z<number, number, "defined">;
+    userCharLimit: z<number, number, "defined">;
+    addDatePrefix: z<boolean, boolean, "volatile-defined">;
+    root: z<string, string, "defined">;
+    maxConsolidationFailures: z<number, number, "volatile-defined">;
+    threatExemptLabels: z<string[], string[], "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    providerName: z<string, string, "defined">;
+    memoryChars: z<number, number, "volatile">;
+    userChars: z<number, number, "volatile">;
+    memoryCharLimit: z<number, number, "defined">;
+    userCharLimit: z<number, number, "defined">;
+    addDatePrefix: z<boolean, boolean, "volatile-defined">;
+    root: z<string, string, "defined">;
+    maxConsolidationFailures: z<number, number, "volatile-defined">;
+    threatExemptLabels: z<string[], string[], "defined">;
+}>>, "plain">;
 export declare function apply(ctx: Context, rawConfig?: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-memory-files",
   "description": "Local layered memory provider (community build)",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,16 +27,16 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.16.1"
+    "@lmzhen/dsh-evolution-core": "^0.17.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.16.1",
-    "@lmzhen/dsh-memory": "^0.16.1"
+    "@lmzhen/dsh-evolution-io": "^0.17.0",
+    "@lmzhen/dsh-memory": "^0.17.0"
   },
   "devDependencies": {
-    "@lmzhen/dsh-evolution-core": "^0.16.1",
-    "@lmzhen/dsh-evolution-io": "^0.16.1",
-    "@lmzhen/dsh-memory": "^0.16.1"
+    "@lmzhen/dsh-evolution-core": "^0.17.0",
+    "@lmzhen/dsh-evolution-io": "^0.17.0",
+    "@lmzhen/dsh-memory": "^0.17.0"
   }
 }