@lmzhen/dsh-evolution-approval 0.3.83 → 0.4.0

package/README.md

@@ -1,42 +1,38 @@
 # @lmzhen/dsh-evolution-approval
 
-Stage/pending approval service for Hermes-style self-evolution writes.
+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.
 
-DSH native approval is one-shot; this service adds the Hermes staged queue:
-`request()` stores background writes, `approve()` replays them through a runner,
-and `reject()` discards them. The model-facing write tools register their own
-runners — `tool-memory` via `registerRunner('memory', …)` and
-`tool-skill-manage` via `registerRunner('skill', …)` — so staged writes are
-replayable only when the corresponding tool package is composed.
-
-Run the package tests:
+Tests:
 
 ```sh
-node node_modules/vitest/vitest.mjs run packages/evolution/evolution-approval/tests   # overlay layout
-# flat mirror: node node_modules/vitest/vitest.mjs run packages/evolution-approval/tests
+node node_modules/vitest/vitest.mjs run packages/evolution-approval/tests   # overlay: packages/evolution/evolution-approval/tests
 ```
 
-## Model Experience
-
-### Indirect model surface
-
-#### What the model sees
+## Model surface
 
-`@lmzhen/dsh-evolution-approval` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
+- **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).
 
-#### Token effect
+## Configuration
 
-Zero direct token effect from this package; consumers add any model-visible tokens.
+- `enabled` (default `false`): master switch (off = ungated).
+- `stageForeground` (default `true`): stage foreground writes too.
 
-#### KV Cache effect
+## Known limitations
 
-Independent of request-prefix construction. This package does not alter the assembled prompt or tool list.
+- `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.
 
-## Known Limitations and Deferred Work
+**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
 
-- `approve()` deduplicates concurrent approvals inside one process, and state providers resolve the pending record atomically. However, the replay runner executes **before** that atomic resolution, so two OS processes approving the same id can each perform the write once while only one process wins the audit transition. Run approvals from a single writer process, or make replay runners idempotent when multi-process approval is required.
-- **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.
+- **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.
-
-**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).

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.3.83",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,16 +27,16 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.83"
+    "@lmzhen/dsh-evolution-core": "^0.4.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.83",
-    "@lmzhen/dsh-evolution-state": "^0.3.83"
+    "@lmzhen/dsh-evolution-state-storage": "^0.4.0",
+    "@lmzhen/dsh-evolution-state": "^0.4.0"
   },
   "devDependencies": {
-    "@lmzhen/dsh-evolution-core": "^0.3.83",
-    "@lmzhen/dsh-evolution-state-storage": "^0.3.83",
-    "@lmzhen/dsh-evolution-state": "^0.3.83"
+    "@lmzhen/dsh-evolution-core": "^0.4.0",
+    "@lmzhen/dsh-evolution-state-storage": "^0.4.0",
+    "@lmzhen/dsh-evolution-state": "^0.4.0"
   }
 }