@lmzhen/dsh-evolution-approval 0.32.3 → 0.32.5

package/README.md

@@ -1,73 +1,19 @@
 # @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.
+> 审批窗口：让记忆/技能写入等你批准。
 
-Tests:
+## 你会看到
 
-```sh
-node node_modules/vitest/vitest.mjs run packages/evolution-approval/tests   # overlay: packages/evolution/evolution-approval/tests
-```
+`/evolution pending`、`approve`、`reject`，以及设置页待批卡。
 
-## Model surface
+## 什么时候会用到
 
-- **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).
+你打开审批后，每次可暂存的写入。
 
-## Configuration
+## 默认 / 前提
 
-- `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.
-
-- **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.
+批准/拒绝是人工决定；`release` 不是批准。

package/lib/index.js

@@ -408,7 +408,9 @@ var EvolutionApproval = class extends Service {
 		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);
+			const claimId = this.newClaimId();
+			if (!await this.state().claimPending(record.id, claimId)) continue;
+			if ((await this.state().tryResolvePending(record.id, "rejected", claimId)).applied) expired.push(record.id);
 		}
 		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;
@@ -418,6 +420,7 @@ var EvolutionApproval = class extends Service {
 		return await this.state().listPending(status);
 	}
 	async approve(id, audit) {
+		await this.expireStale();
 		return await this.dedupe(`approve:${id}`, () => this.doApprove(id, audit));
 	}
 	/** S2-P2-22 (0.3.80): return an ORPHANED executing record to the pending
@@ -641,11 +644,6 @@ var EvolutionApproval = class extends Service {
 			message: `已批准写入「${id}」已重放，但了结记录返回空记录：请核验该写入。`
 		};
 		await this.recordDecision(resolution.record, audit);
-		this.ctx.emit("evolution/approval-decided", {
-			record: resolution.record,
-			action: "approve",
-			ok: true
-		});
 		return {
 			ok: true,
 			message: `已批准 ${record.kind} 写入「${id}」（${record.summary}）。`

package/lib/types/index.d.ts

@@ -18,7 +18,6 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import type { Volatile } from '@deepseek-ai/cordis';
-import { type WriteConfirmMode } from '@lmzhen/dsh-evolution-core';
 import z from '@deepseek-ai/schemastery';
 import type { PendingKind, PendingRecord, PendingStatus } from '@lmzhen/dsh-evolution-state-storage';
 import type { DecisionAudit } from '@lmzhen/dsh-evolution-core/http-routes';
@@ -157,15 +156,6 @@ declare module '@deepseek-ai/cordis' {
         evolutionApproval: EvolutionApproval;
     }
     interface Events {
-        /**
-         * Emitted after an approval decision has been durably recorded.
-         * @mode emit
-         */
-        'evolution/approval-decided'(payload: {
-            readonly record: PendingRecord;
-            readonly action: 'approve' | 'reject';
-            readonly ok: boolean;
-        }): void;
     }
 }
 export interface Config {
@@ -184,12 +174,12 @@ export interface Config {
      */
     pendingTtlMs?: Volatile<number>;
     /**
-     * U-6: what the confirmation before an APPROVE does. The same three words the skill-write gate uses
-     * (`WriteConfirmMode`, whose home is `evolution-core/src/write-authority.ts` - moved there with the
-     * authority that carries it; the re-export from `write-gates.ts` was removed in G1/1.8) - and now the
-     * IMPORT below is what makes that true: without it the docblock claimed an import the file did not have.
+     * U-6: what the confirmation before an APPROVE does: auto (execute immediately) or ask (wait for a
+     * human answer). Legacy `timeout` is accepted only so an old value can migrate to `ask`; it is not
+     * exposed and is owned by ControlPlane when that lands.
      */
-    approvalConfirm?: Volatile<WriteConfirmMode>;
+    /** Legacy `timeout` is accepted only to migrate to `ask`; it is no longer exposed or implemented. */
+    approvalConfirm?: Volatile<'auto' | 'ask' | 'timeout'>;
 }
 export declare class EvolutionApproval extends Service {
     static inject: string[];

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