@lmzhen/dsh-evolution-approval 0.15.2 → 0.16.0

package/README.md

@@ -5,7 +5,9 @@ one-shot; this service adds the Hermes staged queue: `request()` stores backgrou
 `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.
+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.
 
 Tests:
 
@@ -24,15 +26,46 @@ node node_modules/vitest/vitest.mjs run packages/evolution-approval/tests   # ov
 - `enabled` (default `false`): master switch (off = ungated).
 - `stageForeground` (default `true`): stage foreground writes too.
 
+## HTTP surface
+
+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.
-- **No freshness re-validation:** the staged `args` snapshot is replayed as-is (no content hash), so `approve()` never checks whether the target changed; `/evolution pending --detail` shows what will be replayed.
 
 **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 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.

package/lib/index.js

@@ -1,7 +1,223 @@
 import { Service } from "@deepseek-ai/cordis";
 import { randomUUID } from "node:crypto";
-import { isProcessAlive, parseLockBody } from "@lmzhen/dsh-evolution-core";
+import { elapsedSince, isLoopbackRequest, isProcessAlive, parseLockBody, readJsonObject, textDiffFacts, writeJson } from "@lmzhen/dsh-evolution-core";
 import z from "@deepseek-ai/schemastery";
+//#region lib/types/routes.js
+/**
+* The approval HTTP surface: three 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
+* `evolution-state-storage`; the routes only read the window and forward the two decisions, so the
+* console command face (`/evolution pending`, `approve <id>`) and this one cannot drift — both call
+* the same methods.
+*
+* The browser half never touches the state medium: it lists, it approves, it rejects.
+* @module @lmzhen/dsh-evolution-approval/routes
+*/
+/** Route paths. The browser half mirrors these literals; a spec asserts the two sides agree. */
+const APPROVAL_ROUTES = {
+	pending: "/api/dsh-evolution/approval/pending",
+	approve: "/api/dsh-evolution/approval/approve",
+	reject: "/api/dsh-evolution/approval/reject",
+	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.
+* @param approval - the host's approval face (the service instance, or a spec fixture).
+* @returns the route list for `ctx.webServer.register`.
+*/
+function makeApprovalRoutes(approval) {
+	/** Guard: trust fence, then method. Every refusal is a JSON body, never an empty response. */
+	const guard = (req, res, method) => {
+		if (!isLoopbackRequest(req)) {
+			writeJson(res, 403, { error: "forbidden: loopback-only" });
+			return false;
+		}
+		if (req.method !== method) {
+			writeJson(res, 405, { error: "method not allowed: " + method });
+			return false;
+		}
+		return true;
+	};
+	/**
+	* Run one decision against the service.
+	*
+	* A refusal is a BUSINESS answer, not a transport failure: the body carries the service's own
+	* sentence — the same one the console command prints — so the two faces cannot drift. A throw is
+	* 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.
+	*/
+	const decide = async (res, run, id) => {
+		try {
+			const result = await run(id);
+			writeJson(res, 200, result.ok ? {
+				ok: true,
+				data: result
+			} : {
+				ok: false,
+				code: "approval-refused",
+				message: result.message
+			});
+		} catch (error) {
+			writeJson(res, 200, {
+				ok: false,
+				code: "approval-failed",
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	};
+	/** The one shape a decision route accepts: a non-empty string id. */
+	const idOf = (payload) => typeof payload?.id === "string" ? payload.id.trim() : "";
+	return [
+		{
+			kind: "exact",
+			path: APPROVAL_ROUTES.pending,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const raw = new URL(req.url ?? "/", "http://loopback").searchParams.get("status")?.trim() ?? "";
+				const status = raw === "" ? "pending" : raw;
+				if (!PENDING_STATUSES.includes(status)) {
+					writeJson(res, 400, {
+						ok: false,
+						code: "bad-request",
+						message: "status must be one of " + PENDING_STATUSES.join(", ")
+					});
+					return;
+				}
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						data: (await approval.list(status)).map((record) => ({
+							id: record.id,
+							kind: record.kind,
+							summary: record.summary,
+							createdAt: record.createdAt,
+							age: elapsedSince(record.createdAt, Date.now()),
+							status: record.status,
+							...record.claimedBy === void 0 ? {} : { claimedBy: record.claimedBy }
+						}))
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "approval-failed",
+						message: error instanceof Error ? error.message : String(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: APPROVAL_ROUTES.preview,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const id = new URL(req.url ?? "/", "http://loopback").searchParams.get("id")?.trim() ?? "";
+				if (id === "") {
+					writeJson(res, 400, {
+						ok: false,
+						code: "bad-request",
+						message: "id is required"
+					});
+					return;
+				}
+				try {
+					const record = [...await approval.list("pending"), ...await approval.list("executing")].find((candidate) => candidate.id === id);
+					if (record === void 0) {
+						writeJson(res, 200, {
+							ok: false,
+							code: "not-found",
+							message: "no staged write with id \"" + id + "\""
+						});
+						return;
+					}
+					const preview = approval.previewOf(record.kind);
+					if (preview === void 0) {
+						writeJson(res, 200, {
+							ok: true,
+							data: {
+								available: false,
+								reason: "a \"" + record.kind + "\" write has no preview"
+							}
+						});
+						return;
+					}
+					const answer = await preview(record.args);
+					if (!answer.available) {
+						writeJson(res, 200, {
+							ok: true,
+							data: {
+								available: false,
+								reason: answer.reason
+							}
+						});
+						return;
+					}
+					const facts = textDiffFacts(answer.before ?? "", answer.after ?? "", answer.path);
+					writeJson(res, 200, {
+						ok: true,
+						data: {
+							available: true,
+							path: answer.path,
+							...facts
+						}
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "approval-failed",
+						message: error instanceof Error ? error.message : String(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: APPROVAL_ROUTES.approve,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const id = idOf(await readJsonObject(req));
+				if (id === "") {
+					writeJson(res, 400, {
+						ok: false,
+						code: "bad-request",
+						message: "id is required"
+					});
+					return;
+				}
+				await decide(res, (current) => approval.approve(current), id);
+			}
+		},
+		{
+			kind: "exact",
+			path: APPROVAL_ROUTES.reject,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const id = idOf(await readJsonObject(req));
+				if (id === "") {
+					writeJson(res, 400, {
+						ok: false,
+						code: "bad-request",
+						message: "id is required"
+					});
+					return;
+				}
+				await decide(res, (current) => approval.reject(current), id);
+			}
+		}
+	];
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Stage/pending write approval for self-evolution mutations.
@@ -45,11 +261,20 @@ var EvolutionApproval = class extends Service {
 		return this.stageForegroundConfig;
 	}
 	runners = /* @__PURE__ */ new Map();
+	previews = /* @__PURE__ */ new Map();
 	inFlight = /* @__PURE__ */ new Map();
 	constructor(ctx, config = {}) {
 		super(ctx, "evolutionApproval");
 		this.enabled = config.enabled ?? false;
 		this.stageForegroundConfig = config.stageForeground ?? true;
+		this.ctx.inject(["webServer"], (scope) => {
+			scope.effect(() => {
+				const disposers = makeApprovalRoutes(this).map((route) => scope.webServer.register(route));
+				return () => {
+					for (const dispose of disposers) dispose();
+				};
+			}, "evolution-approval: routes");
+		});
 	}
 	state() {
 		return this.ctx.evolutionState;
@@ -58,13 +283,19 @@ var EvolutionApproval = class extends Service {
 	get isEnabled() {
 		return this.enabled;
 	}
-	registerRunner(kind, runner) {
+	registerRunner(kind, runner, preview) {
 		if (this.runners.has(kind)) throw new Error(`approval runner for "${kind}" is already registered`);
 		this.runners.set(kind, runner);
+		if (preview !== void 0) this.previews.set(kind, preview);
 		return () => {
 			if (this.runners.get(kind) === runner) this.runners.delete(kind);
+			if (preview !== void 0 && this.previews.get(kind) === preview) this.previews.delete(kind);
 		};
 	}
+	/** The preview registered for `kind`, if that kind can show what its replay would write. */
+	previewOf(kind) {
+		return this.previews.get(kind);
+	}
 	/**
 	* Whether a replay runner is registered for `kind` (rc.42 audit P1-9
 	* pre-check surface): callers that can execute a write directly (the review

package/lib/types/index.d.ts

@@ -24,6 +24,33 @@ export type WriteRunner = (args: unknown) => Promise<{
     ok: boolean;
     message: string;
 }>;
+/**
+ * What one staged write WOULD store, resolved by the package that owns its replay.
+ *
+ * `available: false` is a business answer, not an error: plenty of staged writes have no bytes worth
+ * showing (a request that carries no content, a target whose replay the host cannot resolve yet), and
+ * the reader is owed the reason rather than an empty diff.
+ */
+export type PreviewAnswer = {
+    readonly available: true;
+    /** The artifact the bytes belong to, for the reader's label (a file name, or the skill name). */
+    readonly path: string;
+    /** The bytes the replay would replace; null when the target does not exist yet. */
+    readonly before: string | null;
+    /** The bytes it would write; null when the operation removes the target. */
+    readonly after: string | null;
+} | {
+    readonly available: false;
+    readonly reason: string;
+};
+/**
+ * Resolve one staged write's before/after WITHOUT running it.
+ *
+ * Registered beside the runner by the same package, and deliberately not derived from it: a preview
+ * that re-derived the bytes would drift from what the replay writes, and the family's rule is that the
+ * write path owns its own normalization (anchors, frontmatter quoting) — one home, two readers.
+ */
+export type WritePreview = (args: unknown) => Promise<PreviewAnswer>;
 export interface ApprovalRequest {
     kind: PendingKind;
     summary: string;
@@ -85,7 +112,7 @@ export type ApprovalLike = {
      * actually be staged). Optional: absent means "unknown" and callers must
      * not pre-refuse on it. */
     stageForeground?: boolean;
-    registerRunner(kind: PendingKind, runner: WriteRunner): () => void;
+    registerRunner(kind: PendingKind, runner: WriteRunner, preview?: WritePreview): () => void;
     list(status?: PendingStatus): Promise<PendingRecord[]>;
     approve(id: string): Promise<{
         ok: boolean;
@@ -133,12 +160,15 @@ export declare class EvolutionApproval extends Service {
      * all). Mirrors `this.stageForeground`. */
     get stageForeground(): boolean;
     private readonly runners;
+    private readonly previews;
     private readonly inFlight;
     constructor(ctx: Context, config?: Config);
     private state;
     /** Fail-closed capability adapters need to distinguish "allowed" from "enabled". */
     get isEnabled(): boolean;
-    registerRunner(kind: PendingKind, runner: WriteRunner): () => void;
+    registerRunner(kind: PendingKind, runner: WriteRunner, preview?: WritePreview): () => void;
+    /** The preview registered for `kind`, if that kind can show what its replay would write. */
+    previewOf(kind: PendingKind): WritePreview | undefined;
     /**
      * Whether a replay runner is registered for `kind` (rc.42 audit P1-9
      * pre-check surface): callers that can execute a write directly (the review

package/lib/types/routes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The approval HTTP surface: three 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
+ * `evolution-state-storage`; the routes only read the window and forward the two decisions, so the
+ * console command face (`/evolution pending`, `approve <id>`) and this one cannot drift — both call
+ * the same methods.
+ *
+ * The browser half never touches the state medium: it lists, it approves, it rejects.
+ * @module @lmzhen/dsh-evolution-approval/routes
+ */
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { PendingKind, PendingRecord, PendingStatus } from '@lmzhen/dsh-evolution-state-storage';
+import { elapsedSince } from '@lmzhen/dsh-evolution-core';
+import type { WritePreview } from './index.ts';
+/** Route paths. The browser half mirrors these literals; a spec asserts the two sides agree. */
+export declare const APPROVAL_ROUTES: {
+    readonly pending: "/api/dsh-evolution/approval/pending";
+    readonly approve: "/api/dsh-evolution/approval/approve";
+    readonly reject: "/api/dsh-evolution/approval/reject";
+    readonly preview: "/api/dsh-evolution/approval/preview";
+};
+/** What one row of the pending list carries to the browser half. */
+export interface PendingRow {
+    readonly id: string;
+    readonly kind: PendingKind;
+    readonly summary: string;
+    readonly createdAt: string;
+    /** How long ago it was staged, in the family's `{unit, n}` closed vocabulary (the host owns the clock). */
+    readonly age: ReturnType<typeof elapsedSince>;
+    readonly status: PendingStatus;
+    /** Present on a claimed-but-unfinished approve: the operator clears it by rejecting (doctor says so too). */
+    readonly claimedBy?: string | undefined;
+}
+/**
+ * The slice of the approval service these routes read.
+ *
+ * Structural on purpose: a spec fixture implements it without constructing the service, and the
+ * routes stay usable from any host that exposes the same three methods.
+ */
+export interface ApprovalFace {
+    list(status?: PendingStatus): Promise<PendingRecord[]>;
+    approve(id: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    reject(id: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** The preview the replayer of that kind registered, when it registered one. */
+    previewOf(kind: PendingKind): WritePreview | undefined;
+}
+/**
+ * Build the three 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`.
+ */
+export declare function makeApprovalRoutes(approval: ApprovalFace): WebRoute[];
+//# sourceMappingURL=routes.d.ts.map

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.15.2",
+  "version": "0.16.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,16 +27,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.15.2"
+    "@lmzhen/dsh-evolution-core": "^0.16.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-state-storage": "^0.15.2",
-    "@lmzhen/dsh-evolution-state": "^0.15.2"
+    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.2",
+    "@lmzhen/dsh-evolution-state-storage": "^0.16.0",
+    "@lmzhen/dsh-evolution-state": "^0.16.0"
   },
   "devDependencies": {
-    "@lmzhen/dsh-evolution-core": "^0.15.2",
-    "@lmzhen/dsh-evolution-state-storage": "^0.15.2",
-    "@lmzhen/dsh-evolution-state": "^0.15.2"
+    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.2",
+    "@lmzhen/dsh-evolution-core": "^0.16.0",
+    "@lmzhen/dsh-evolution-state-storage": "^0.16.0",
+    "@lmzhen/dsh-evolution-state": "^0.16.0"
   }
 }