@lmzhen/dsh-evolution-approval 0.17.1 → 0.18.0

package/README.md

@@ -59,6 +59,8 @@ preview, or a resolver that cannot answer (a stale anchor, an operation with no
 - `approve()` dedupes inside one process and providers resolve the record atomically, but the replay runner executes BEFORE that resolution: two OS processes approving one id can both write while one wins the audit transition. Run approvals from one writer process, or make runners idempotent.
 - **Approve + reject on one id** are not serialized inside a process: a reject can resolve a still-executing record while the runner completes and the write still lands: verify the write state, or reject only when no approve is in flight.
 
+- **The HTTP face is loopback-only by design.** The fence is the family's shared loopback check, authoritative on the socket (`X-Forwarded-For` is never trusted), so a deployment that opens the host to a LAN — where the platform's own `/api` answers normally — gets **403** on all four routes from any non-loopback client. Reach the host over loopback (a local browser, or an SSH tunnel). Whether the family should follow the platform's `trustedHosts` instead is an open decision (v46 `决策 3`; the mechanism lives in `evolution-core`'s `http-routes.ts`).
+
 **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
@@ -68,4 +70,4 @@ preview, or a resolver that cannot answer (a stale anchor, an operation with no
   would drift from what the replay writes (the write path owns its own normalization).
 
 - **Concurrent approve + reject on the same id (F-204).** Inside one process the dedupe keys are `approve:<id>` / `reject:<id>`, so the two paths are not serialized against each other. When an approve runner is slow, a reject resolves the still-executing record to `rejected` **without holding a claim**; the runner may then complete and the write can still land while the audit history reads `rejected`: the write effect, not the audit verdict, is what actually persists (`写效果以实际为准`). `reject` on an executing record reports this and asks you to verify the write state manually. Only reject a write after confirming no approve is in flight, or verify the write effect manually afterwards.
-- **No staged-content freshness re-validation (F-328).** The staged record stores the `args` snapshot captured at request time and replays exactly those args, but does not record a content hash, so `approve()` does **not** re-check whether the on-disk skill/memory the write targets changed since staging. The write is applied as staged regardless. The pending surface (`/evolution pending --detail`) exposes the staged `args` so you can review what will actually be replayed before approving; there is no automatic drift warning if the target changed in the meantime.
+- **No freshness re-validation for kinds WITHOUT an anchor (F-328, corrected).** The staged record stores the `args` snapshot captured at request time and replays exactly those args. Kinds that carry no anchor — **`memory` today** — replay that snapshot as-is, so a target that changed after staging is not re-checked. A skill write is NOT in that class: it carries `staged_from_sha256`, so its replay and its preview refuse a changed target (the per-kind rule above). The pending surface (`/evolution pending --detail`) exposes the staged `args` so you can review what will actually be replayed before approving.

package/lib/index.js

@@ -2,9 +2,10 @@ 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 z from "@deepseek-ai/schemastery";
+import { PENDING_STATUSES } from "@lmzhen/dsh-evolution-state-storage";
 //#region lib/types/routes.js
 /**
-* The approval HTTP surface: three loopback routes over the write gate's pending window.
+* The approval HTTP surface: four loopback routes over the write gate's pending window.
 *
 * Layering: this module maps a route to a USE CASE and does nothing else. The pending window itself
 * (ids, statuses, claim/resolve rules, the replay runners) lives in this package's service and in
@@ -23,17 +24,7 @@ const APPROVAL_ROUTES = {
 	preview: "/api/dsh-evolution/approval/preview"
 };
 /**
-* The statuses a caller may ask for, in the order the window moves through them. Annotated with the
-* storage type so a change to that union fails to compile here instead of drifting silently.
-*/
-const PENDING_STATUSES = [
-	"pending",
-	"executing",
-	"approved",
-	"rejected"
-];
-/**
-* Build the three routes over the approval service.
+* Build the four routes over the approval service.
 * @param approval - the host's approval face (the service instance, or a spec fixture).
 * @returns the route list for `ctx.webServer.register`.
 */
@@ -250,10 +241,14 @@ var EvolutionApproval = class extends Service {
 	static inject = ["evolutionState"];
 	static Config = z.object({
 		enabled: z.boolean().default(false),
-		stageForeground: z.boolean().default(true)
+		stageForeground: z.boolean().default(true),
+		pendingTtlMs: z.number().min(0).default(0)
 	});
 	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;
 	/** 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`. */
@@ -267,6 +262,8 @@ 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.ctx.inject(["webServer"], (scope) => {
 			scope.effect(() => {
 				const disposers = makeApprovalRoutes(this).map((route) => scope.webServer.register(route));
@@ -360,7 +357,41 @@ var EvolutionApproval = class extends Service {
 			message: "Foreground write allowed."
 		};
 	}
+	/** 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;
+	}
+	/**
+	* Close every staged write that has been waiting longer than the TTL (T4-09/A51).
+	*
+	* The window had THREE terminal states only — approve, reject, release — all of them human, so an
+	* unattended deployment accumulated staged records for ever. Expiry is the missing third state of
+	* the human-confirmation triangle ("never pop up and just run" / "wait indefinitely" / "cancel on
+	* timeout"), and it is deliberately implemented as the reject side: the record converges through
+	* the seam's exactly-once transition to `rejected` with its `resolvedAt` stamped, and the runner
+	* is never invoked. NOTHING a human did not approve can execute; the cost of a wrong TTL is a
+	* staged write that must be staged again.
+	*
+	* A sweep, not a timer: every read of the window converges it (the CLI, the settings card and the
+	* doctor all read through {@link list}), so the family does not gain a background timer that would
+	* have to be unref'd, disposed and reasoned about for process liveness.
+	* @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 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`);
+		return expired;
+	}
 	async list(status = "pending") {
+		await this.expireStale();
 		return await this.state().listPending(status);
 	}
 	async approve(id) {

package/lib/types/index.d.ts

@@ -113,6 +113,10 @@ export type ApprovalLike = {
      * not pre-refuse on it. */
     stageForeground?: boolean;
     registerRunner(kind: PendingKind, runner: WriteRunner, preview?: WritePreview): () => void;
+    /** T4-09/A51: the staged window's effective expiry in ms, 0 = never. Optional for the same reason
+     * the other reads are: an older/partial implementation simply does not answer, and a caller must not
+     * read that absence as "expires immediately". */
+    ttlMs?: number;
     list(status?: PendingStatus): Promise<PendingRecord[]>;
     approve(id: string): Promise<{
         ok: boolean;
@@ -149,12 +153,22 @@ export interface Config {
     enabled?: boolean;
     /** Require approval for foreground writes as well. */
     stageForeground?: boolean;
+    /**
+     * T4-09/A51: milliseconds after which a STAGED write expires. `0` (the default) means never —
+     * 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.
+     */
+    pendingTtlMs?: number;
 }
 export declare class EvolutionApproval extends Service {
     static inject: string[];
     static Config: Schema<Config>;
     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;
     /** 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`. */
@@ -192,6 +206,26 @@ export declare class EvolutionApproval extends Service {
     }>;
     /** Evaluate one mutation. Returns allow, or stores the write and returns staged. */
     request(input: ApprovalRequest): Promise<ApprovalDecision>;
+    /** 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;
+    /**
+     * Close every staged write that has been waiting longer than the TTL (T4-09/A51).
+     *
+     * The window had THREE terminal states only — approve, reject, release — all of them human, so an
+     * unattended deployment accumulated staged records for ever. Expiry is the missing third state of
+     * the human-confirmation triangle ("never pop up and just run" / "wait indefinitely" / "cancel on
+     * timeout"), and it is deliberately implemented as the reject side: the record converges through
+     * the seam's exactly-once transition to `rejected` with its `resolvedAt` stamped, and the runner
+     * is never invoked. NOTHING a human did not approve can execute; the cost of a wrong TTL is a
+     * staged write that must be staged again.
+     *
+     * A sweep, not a timer: every read of the window converges it (the CLI, the settings card and the
+     * doctor all read through {@link list}), so the family does not gain a background timer that would
+     * have to be unref'd, disposed and reasoned about for process liveness.
+     * @returns the ids that were closed by this sweep (empty when the TTL is off or nothing was stale).
+     */
+    expireStale(): Promise<string[]>;
     list(status?: PendingStatus): Promise<PendingRecord[]>;
     approve(id: string): Promise<{
         ok: boolean;

package/lib/types/routes.d.ts

@@ -1,5 +1,5 @@
 /**
- * The approval HTTP surface: three loopback routes over the write gate's pending window.
+ * The approval HTTP surface: four loopback routes over the write gate's pending window.
  *
  * Layering: this module maps a route to a USE CASE and does nothing else. The pending window itself
  * (ids, statuses, claim/resolve rules, the replay runners) lives in this package's service and in
@@ -53,7 +53,7 @@ export interface ApprovalFace {
     previewOf(kind: PendingKind): WritePreview | undefined;
 }
 /**
- * Build the three routes over the approval service.
+ * Build the four routes over the approval service.
  * @param approval - the host's approval face (the service instance, or a spec fixture).
  * @returns the route list for `ctx.webServer.register`.
  */

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.17.1",
+  "version": "0.18.0",
   "publishConfig": {
     "access": "public"
   },
@@ -26,19 +26,19 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.17.1"
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "@lmzhen/dsh-evolution-core": "^0.18.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
-    "@lmzhen/dsh-evolution-state-storage": "^0.17.1",
-    "@lmzhen/dsh-evolution-state": "^0.17.1"
+    "@lmzhen/dsh-evolution-state-storage": "^0.18.0",
+    "@lmzhen/dsh-evolution-state": "^0.18.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
-    "@lmzhen/dsh-evolution-core": "^0.17.1",
-    "@lmzhen/dsh-evolution-state-storage": "^0.17.1",
-    "@lmzhen/dsh-evolution-state": "^0.17.1"
+    "@lmzhen/dsh-evolution-core": "^0.18.0",
+    "@lmzhen/dsh-evolution-state-storage": "^0.18.0",
+    "@lmzhen/dsh-evolution-state": "^0.18.0"
   }
 }