@lmzhen/dsh-evolution-approval 0.32.4 → 0.32.6

package/README.md

@@ -1,73 +1,27 @@
 # @lmzhen/dsh-evolution-approval
 
-Stage/pending approval service for self-evolution writes. DSH native approval is
-one-shot; this service adds the Hermes staged queue: `request()` stores background writes,
-`approve()` replays them through a runner, `reject()` discards them. The model-facing write tools
-register their own runners (`tool-memory` via `registerRunner('memory', …)`, `tool-skill-manage`
-via `registerRunner('skill', …)`), so staged writes are replayable only when the corresponding
-tool package is composed. The pending window is also reachable from the browser half over four
-loopback routes (§HTTP surface), so the settings panel can list, decide and PREVIEW staged writes
-without the console command.
+Staged approval service for memory and skill writes. It records a proposed mutation, then replays the registered runner only after an operator approves it.
 
-Tests:
+## Operator surface
 
-```sh
-node node_modules/vitest/vitest.mjs run packages/evolution-approval/tests   # overlay: packages/evolution/evolution-approval/tests
-```
+Use `/evolution pending`, `approve <id>`, and `reject <id>`. The settings UI can show the pending queue and, when the owning tool registered a preview, a before/after diff without executing the write.
 
-## Model surface
+`/evolution release <id>` is different from approval. It returns an orphaned `executing` record to `pending` after a crashed approval. A live foreign process or an in-flight local decision blocks release.
 
-- **Model-visible:** nothing of its own: a staged write's effect is what the model notices.
-- **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-approval` row, in `evolution-host`/`evolution-all`/one-click `evolution-preset` (`enabled: false` there).
+## Defaults
 
-## Configuration
+| Setting | Default | Effect |
+|---|---|---|
+| `enabled` | `false` | Writes proceed without this staged queue. |
+| `stageForeground` | `true` | Once enabled, foreground writes also stage unless the effective session policy is `never`. |
+| `pendingTtlMs` | `0` | Pending records never expire automatically. |
+| `approvalConfirm` | `auto` | Approving does not add a second confirmation by default. |
 
-- `enabled` (default `false`): master switch (off = ungated).
-- `stageForeground` (default `true`): stage foreground writes too.
+A positive `pendingTtlMs` closes expired records as `rejected` and never executes them. Expiry is evaluated on queue reads and decisions, not by a background timer.
 
-## HTTP surface
+## Boundaries
 
-Four loopback routes over the same service methods the console command uses, so the two faces cannot drift:
-
-| route | what it does |
-|---|---|
-| `GET /api/dsh-evolution/approval/pending?status=` | the staged rows the settings card renders (id, kind, summary, staged-at, age) — never the staged `args` |
-| `POST …/approve`, `POST …/reject` | forward to `approve(id)` / `reject(id)`; a refusal is HTTP 200 carrying the service's own sentence |
-| `GET …/preview?id=` | what that write WOULD store, resolved read-only |
-
-The fence is the family's shared loopback check (`evolution-core`'s `http-routes.ts`, one home for every
-route surface), and every "cannot answer" path is a JSON body with a `code` and a `message` rather than an
-empty response.
-
-**Previews** come from the package that OWNS the replay: `registerRunner(kind, runner, preview?)` takes an
-optional read-only companion that resolves the same `args` into `{path, before, after}`, and the route turns
-that into the same diff facts the history panel's diff route uses (`textDiffFacts`). A kind without a
-preview, or a resolver that cannot answer (a stale anchor, an operation with no byte-level change), answers
-`{available: false, reason}` — the card prints that sentence instead of an empty diff.
-
-## Known limitations
-
-- **Freshness re-validation is per KIND:** a skill write carries `staged_from_sha256`, so its replay (and its
-  preview) refuses a target that changed after staging; kinds that carry no anchor replay the `args` snapshot
-  as-is. `/evolution pending --detail` shows what will be replayed.
-- **A preview is a read, not a reservation:** it resolves the bytes on disk right now, so a target that
-  changes between the preview and the approve is refused by the replay's own anchor check rather than by the
-  preview that was shown.
-- **Previews exist only where a resolver is registered** (`skill` today; `tool-skill-manage` supplies it). Every
-  other kind answers `{available: false, reason}`.
-- `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
-
-- **The HTTP face + preview seam (G3, 2026-09-30).** The routes exist so a reader can act on the window
-  without the console; the preview is registered BESIDE the runner because a preview derived anywhere else
-  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 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.
+- Background-review writes require a registered replay runner. Staging a record without one is not a usable approval flow.
+- Curator and merge writes have their own controls; they do not pass through this ordinary memory/skill approval queue.
+- Before using `release`, verify whether the original runner already landed the write and what effect it had. Approving the returned record replays that operation, which may be non-idempotent.
+- Resolved history is bounded by the state provider. The JSON provider archives older resolved records; the domain provider does not create that JSON archive sidecar.

package/lib/index.js

@@ -1,6 +1,6 @@
+import { clampOnce, elapsedSince, registerOwnerSettings, textDiffFacts, unwrapLive } from "@lmzhen/dsh-evolution-core";
 import { Service } from "@deepseek-ai/cordis";
 import { randomUUID } from "node:crypto";
-import { clampOnce, elapsedSince, textDiffFacts, unwrapLive } from "@lmzhen/dsh-evolution-core";
 import z from "@deepseek-ai/schemastery";
 import { PENDING_STATUSES } from "@lmzhen/dsh-evolution-state-storage";
 import { HOST_ROUTES, json, methodNotAllowed, readJsonObject, registerHostRoutes } from "@lmzhen/dsh-evolution-core/http-routes";
@@ -31,6 +31,26 @@ const APPROVAL_ROUTES = HOST_ROUTES.approval;
 * reported the same way rather than escaping as an empty 500, because the operator's next step
 * ("reject it", "retry") is only actionable if the reason is visible.
 */
+function structuredOf(record) {
+	const args = record.args;
+	if (record.kind === "memory") {
+		const operations = Array.isArray(args?.operations) ? args.operations : [];
+		const first = operations[0];
+		return {
+			verb: typeof first?.action === "string" ? first.action : typeof args?.action === "string" ? args.action : "update",
+			target: typeof args?.target === "string" ? args.target : "memory",
+			operationCount: operations.length === 0 ? 1 : operations.length,
+			actions: record.status === "executing" ? ["release"] : ["approve", "reject"]
+		};
+	}
+	const operation = args?.operation;
+	return {
+		verb: typeof operation?.action === "string" ? operation.action : "update",
+		target: typeof operation?.name === "string" ? operation.name : record.summary,
+		operationCount: 1,
+		actions: record.status === "executing" ? ["release"] : ["approve", "reject"]
+	};
+}
 async function decide(run, id) {
 	try {
 		const result = await run(id);
@@ -85,7 +105,8 @@ function makeApprovalRoutes(approval, audit) {
 							createdAt: record.createdAt,
 							age: elapsedSince(record.createdAt, Date.now()),
 							status: record.status,
-							...record.claimedBy === void 0 ? {} : { claimedBy: record.claimedBy }
+							...record.claimedBy === void 0 ? {} : { claimedBy: record.claimedBy },
+							...structuredOf(record)
 						}))
 					});
 				} catch (error) {
@@ -165,6 +186,26 @@ function makeApprovalRoutes(approval, audit) {
 				return await decide((current) => approval.approve(current, audit), id);
 			}
 		},
+		{
+			path: APPROVAL_ROUTES.release,
+			methods: ["POST"],
+			requestBody: "buffered",
+			fetch: async (request) => {
+				if (request.method !== "POST") return methodNotAllowed(["POST"]);
+				const id = idOf(await readJsonObject(request));
+				if (id === "") return json(400, {
+					ok: false,
+					code: "bad-request",
+					message: "缺少 id"
+				});
+				if (approval.release === void 0) return json(200, {
+					ok: false,
+					code: "approval-refused",
+					message: "这个部署没有提供 release"
+				});
+				return await decide((current) => approval.release(current), id);
+			}
+		},
 		{
 			path: APPROVAL_ROUTES.reject,
 			methods: ["POST"],
@@ -235,7 +276,7 @@ function effectiveSessionPolicy(ctx, session) {
 	if (!approval || session === void 0) return void 0;
 	return approval.overrideOf(session) ?? approval.config?.policy ?? "ask";
 }
-var EvolutionApproval = class extends Service {
+var EvolutionApproval = class EvolutionApproval extends Service {
 	static inject = ["evolutionState"];
 	static Config = z.object({
 		enabled: z.boolean().default(false).volatile(),
@@ -265,6 +306,7 @@ var EvolutionApproval = class extends Service {
 	inFlight = /* @__PURE__ */ new Map();
 	constructor(ctx, config = {}) {
 		super(ctx, "evolutionApproval");
+		registerOwnerSettings(this.ctx, "evolution-approval", EvolutionApproval.Config);
 		this.enabledConfig = config.enabled;
 		this.stageForegroundConfig = config.stageForeground ?? true;
 		this.pendingTtlMsConfig = config.pendingTtlMs;

package/lib/types/routes.d.ts

@@ -24,6 +24,7 @@ export declare const APPROVAL_ROUTES: {
     readonly preview: "/api/dsh-evolution/approval/preview";
     readonly approve: "/api/dsh-evolution/approval/approve";
     readonly reject: "/api/dsh-evolution/approval/reject";
+    readonly release: "/api/dsh-evolution/approval/release";
 };
 /** What one row of the pending list carries to the browser half. */
 export interface PendingRow {
@@ -36,6 +37,11 @@ export interface PendingRow {
     readonly status: PendingStatus;
     /** Present on a claimed-but-unfinished approve: the operator clears it by rejecting (doctor says so too). */
     readonly claimedBy?: string | undefined;
+    /** Structured summary derived from the staged args; the raw summary stays for details. */
+    readonly verb: string;
+    readonly target: string;
+    readonly operationCount: number;
+    readonly actions: readonly string[];
 }
 /**
  * The slice of the approval service these routes read.
@@ -54,6 +60,11 @@ export interface ApprovalFace {
         ok: boolean;
         message: string;
     }>;
+    /** Release an executing claim; absent on fixtures that only model approve/reject. */
+    release?(id: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
     /** The preview the replayer of that kind registered, when it registered one. */
     previewOf(kind: PendingKind): WritePreview | undefined;
 }

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.32.4",
+  "version": "0.32.6",
   "publishConfig": {
     "access": "public"
   },
@@ -27,18 +27,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "@lmzhen/dsh-evolution-core": "^0.32.4"
+    "@lmzhen/dsh-evolution-core": "^0.32.6"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",
-    "@lmzhen/dsh-evolution-core": "^0.32.4",
-    "@lmzhen/dsh-evolution-state": "^0.32.4",
-    "@lmzhen/dsh-evolution-state-storage": "^0.32.4"
+    "@lmzhen/dsh-evolution-core": "^0.32.6",
+    "@lmzhen/dsh-evolution-state": "^0.32.6",
+    "@lmzhen/dsh-evolution-state-storage": "^0.32.6"
   },
   "devDependencies": {
-    "@lmzhen/dsh-evolution-core": "^0.32.4",
-    "@lmzhen/dsh-evolution-state": "^0.32.4",
-    "@lmzhen/dsh-evolution-state-storage": "^0.32.4"
+    "@lmzhen/dsh-evolution-core": "^0.32.6",
+    "@lmzhen/dsh-evolution-state": "^0.32.6",
+    "@lmzhen/dsh-evolution-state-storage": "^0.32.6"
   },
   "engines": {
     "dsh": ">=0.2.1-rc.2 <0.2.2-0"