@lmzhen/dsh-evolution-approval 0.20.0 → 0.21.0

package/lib/index.js

@@ -1,6 +1,6 @@
 import { Service } from "@deepseek-ai/cordis";
 import { randomUUID } from "node:crypto";
-import { elapsedSince, isLoopbackRequest, isProcessAlive, parseLockBody, readJsonObject, textDiffFacts, writeJson } from "@lmzhen/dsh-evolution-core";
+import { clampOnce, elapsedSince, isLoopbackRequest, isProcessAlive, parseLockBody, readJsonObject, textDiffFacts, writeJson } from "@lmzhen/dsh-evolution-core";
 import z from "@deepseek-ai/schemastery";
 import { PENDING_STATUSES } from "@lmzhen/dsh-evolution-state-storage";
 //#region lib/types/routes.js
@@ -242,13 +242,15 @@ var EvolutionApproval = class extends Service {
 	static Config = z.object({
 		enabled: z.boolean().default(false),
 		stageForeground: z.boolean().default(true),
-		pendingTtlMs: z.number().min(0).default(0)
+		pendingTtlMs: z.number().min(0).default(0).volatile()
 	});
 	enabled;
 	stageForegroundConfig;
-	/** Effective TTL in ms; 0 = the window never expires (T4-09/A51). A non-finite or negative value
-	* is clamped here because the schema only guards the loader path. */
-	pendingTtlMs;
+	/** The TTL carrier as configured: a plain number, or the live reference `.volatile()` hands a
+	* user-layer field. Read through {@link ttl} at every use, never cached (registry row: live). */
+	pendingTtlMsConfig;
+	/** Keys this instance already warned about (clampOnce's once-per-key sink). */
+	clampedKeys = /* @__PURE__ */ new Set();
 	/** P3 (v16): public read for staging pre-checks (learning-graph refuses a
 	* stage that no runner could replay only when foreground writes stage at
 	* all). Mirrors `this.stageForeground`. */
@@ -262,8 +264,13 @@ var EvolutionApproval = class extends Service {
 		super(ctx, "evolutionApproval");
 		this.enabled = config.enabled ?? false;
 		this.stageForegroundConfig = config.stageForeground ?? true;
-		const ttl = config.pendingTtlMs ?? 0;
-		this.pendingTtlMs = Number.isFinite(ttl) && ttl > 0 ? Math.floor(ttl) : 0;
+		this.pendingTtlMsConfig = config.pendingTtlMs;
+		this.ctx.inject(["settings"], (injected) => {
+			const settings = injected.settings;
+			if (typeof settings?.configure !== "function") return;
+			const disposer = settings.configure({ auto: false }, this.ctx.fiber);
+			if (typeof disposer === "function") this.ctx.effect(() => disposer, "evolution-approval: settings presentation");
+		});
 		this.ctx.inject(["webServer"], (scope) => {
 			scope.effect(() => {
 				const disposers = makeApprovalRoutes(this).map((route) => scope.webServer.register(route));
@@ -360,7 +367,22 @@ var EvolutionApproval = class extends Service {
 	/** T4-09/A51: the effective expiry of the staged window, 0 = never. Read by the command surface
 	* and the doctor so both can say which of the three human-confirmation states is in force. */
 	get ttlMs() {
-		return this.pendingTtlMs;
+		return this.ttl();
+	}
+	/**
+	* The effective TTL in ms (0 = never expire), read at USE time.
+	*
+	* `clampOnce` is the family's ONE clamp-and-warn helper for a numeric knob that may be a live
+	* settings reference (S2.9/T3-10): a plain number, a `{ get() }` reference, or nothing all land
+	* on the same floor, and an invalid value warns once per instance instead of silently disabling
+	* the window. The old inline `Number.isFinite` read stopped working the moment the field became
+	* `.volatile()` — a reference is not a finite number, so the TTL silently read as 0.
+	* @returns the TTL the sweep may use.
+	*/
+	ttl() {
+		return Math.floor(clampOnce(this.clampedKeys, (message) => {
+			this.ctx.logger.warn(message);
+		}, "pendingTtlMs", this.pendingTtlMsConfig, 0, 0));
 	}
 	/**
 	* Close every staged write that has been waiting longer than the TTL (T4-09/A51).
@@ -379,15 +401,16 @@ var EvolutionApproval = class extends Service {
 	* @returns the ids that were closed by this sweep (empty when the TTL is off or nothing was stale).
 	*/
 	async expireStale() {
-		if (this.pendingTtlMs <= 0) return [];
-		const cutoff = Date.now() - this.pendingTtlMs;
+		const ttl = this.ttl();
+		if (ttl <= 0) return [];
+		const cutoff = Date.now() - ttl;
 		const expired = [];
 		for (const record of await this.state().listPending("pending")) {
 			const stagedAt = Date.parse(record.createdAt);
 			if (!Number.isFinite(stagedAt) || stagedAt > cutoff) continue;
 			if ((await this.state().tryResolvePending(record.id, "rejected")).applied) expired.push(record.id);
 		}
-		if (expired.length > 0) this.ctx.logger.warn(`evolution-approval: ${expired.length} staged write(s) passed pendingTtlMs=${this.pendingTtlMs} and were closed as rejected WITHOUT executing: ${expired.join(", ")} — stage them again if they are still wanted`);
+		if (expired.length > 0) this.ctx.logger.warn(`evolution-approval: ${expired.length} staged write(s) passed pendingTtlMs=${ttl} and were closed as rejected WITHOUT executing: ${expired.join(", ")} — stage them again if they are still wanted`);
 		return expired;
 	}
 	async list(status = "pending") {

package/lib/types/index.d.ts

@@ -17,7 +17,8 @@
  * @module @lmzhen/dsh-evolution-approval
  */
 import { Context, Service } from '@deepseek-ai/cordis';
-import type Schema from '@deepseek-ai/schemastery';
+import type { Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 import type { PendingKind, PendingRecord, PendingStatus } from '@lmzhen/dsh-evolution-state-storage';
 export type { PendingKind, PendingRecord, PendingStatus };
 export type WriteRunner = (args: unknown) => Promise<{
@@ -158,17 +159,30 @@ export interface Config {
      * the window then behaves exactly as before. Expiry closes the record the same way a reject does
      * (status `rejected`, `resolvedAt` stamped, runner NEVER invoked): an expiry is a cleanup of the
      * window, never an approval, so nothing a human did not approve can execute.
+     *
+     * `.volatile()` (0.21.0, G1): the field carries a USER LAYER, so the value arrives as a live
+     * reference and is read at USE time — a settings write changes the window without a reload.
      */
-    pendingTtlMs?: number;
+    pendingTtlMs?: Volatile<number>;
 }
 export declare class EvolutionApproval extends Service {
     static inject: string[];
-    static Config: Schema<Config>;
+    static Config: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        stageForeground: z<boolean, boolean, "defined">;
+        pendingTtlMs: z<number, number, "volatile-defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        stageForeground: z<boolean, boolean, "defined">;
+        pendingTtlMs: z<number, number, "volatile-defined">;
+    }>>, "plain">;
     private readonly enabled;
     private readonly stageForegroundConfig;
-    /** Effective TTL in ms; 0 = the window never expires (T4-09/A51). A non-finite or negative value
-     * is clamped here because the schema only guards the loader path. */
-    private readonly pendingTtlMs;
+    /** The TTL carrier as configured: a plain number, or the live reference `.volatile()` hands a
+     * user-layer field. Read through {@link ttl} at every use, never cached (registry row: live). */
+    private readonly pendingTtlMsConfig?;
+    /** Keys this instance already warned about (clampOnce's once-per-key sink). */
+    private readonly clampedKeys;
     /** P3 (v16): public read for staging pre-checks (learning-graph refuses a
      * stage that no runner could replay only when foreground writes stage at
      * all). Mirrors `this.stageForeground`. */
@@ -209,6 +223,17 @@ export declare class EvolutionApproval extends Service {
     /** T4-09/A51: the effective expiry of the staged window, 0 = never. Read by the command surface
      * and the doctor so both can say which of the three human-confirmation states is in force. */
     get ttlMs(): number;
+    /**
+     * The effective TTL in ms (0 = never expire), read at USE time.
+     *
+     * `clampOnce` is the family's ONE clamp-and-warn helper for a numeric knob that may be a live
+     * settings reference (S2.9/T3-10): a plain number, a `{ get() }` reference, or nothing all land
+     * on the same floor, and an invalid value warns once per instance instead of silently disabling
+     * the window. The old inline `Number.isFinite` read stopped working the moment the field became
+     * `.volatile()` — a reference is not a finite number, so the TTL silently read as 0.
+     * @returns the TTL the sweep may use.
+     */
+    private ttl;
     /**
      * Close every staged write that has been waiting longer than the TTL (T4-09/A51).
      *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-approval",
   "description": "Stage/pending approval service for Hermes-style self-evolution writes (community build)",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,18 +27,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
-    "@lmzhen/dsh-evolution-core": "^0.20.0"
+    "@lmzhen/dsh-evolution-core": "^0.21.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
-    "@lmzhen/dsh-evolution-state-storage": "^0.20.0",
-    "@lmzhen/dsh-evolution-state": "^0.20.0"
+    "@lmzhen/dsh-evolution-state-storage": "^0.21.0",
+    "@lmzhen/dsh-evolution-state": "^0.21.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
-    "@lmzhen/dsh-evolution-core": "^0.20.0",
-    "@lmzhen/dsh-evolution-state-storage": "^0.20.0",
-    "@lmzhen/dsh-evolution-state": "^0.20.0"
+    "@lmzhen/dsh-evolution-core": "^0.21.0",
+    "@lmzhen/dsh-evolution-state-storage": "^0.21.0",
+    "@lmzhen/dsh-evolution-state": "^0.21.0"
   }
 }