@lmzhen/dsh-evolution-approval 0.32.4 → 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/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.5",
   "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.5"
   },
   "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.5",
+    "@lmzhen/dsh-evolution-state": "^0.32.5",
+    "@lmzhen/dsh-evolution-state-storage": "^0.32.5"
   },
   "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.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"