@lmzhen/dsh-evolution-core 0.17.1 → 0.18.0

package/README.md

@@ -11,6 +11,7 @@ section, and importing the package root is its only entry.
 
 ## Known limitations
 
+- **The family tree IS the platform's USER skill root.** `skillsRoot()` resolves to `<dshHome>/skills` — the root the platform's `skill-filesystem` serves at rank 400 — so "the same tree" holds while that root is enabled. Two divergences stay documented rather than mirrored: a platform row with `includeDefaultRoots:false` (or a composition without this family's catalog row) removes the only providers that serve the tree while family writes still succeed, and the platform's CWD-derived PROJECT roots (`<cwd>/.dsh/skills`, `<cwd>/.agents/skills`) are not read by the family at all, so `ctx.skills.get(name).path` and `SkillLibrary.read(name)` can name different files. Mirroring project roots is `U-3`, deliberately not started; point `customSkillDirs` (platform side) or `root` (family side) at a shared directory when the project tree has to be visible to both.
 - This package is a library, not a Cordis row; do not mount it as a plugin.
 - 数值配置已在消费方 Config 面钳制（`min 1`/各字段域）；`MemoryStore` 内部对 `limit <= 0` 仍按 unbounded 防御处理——那是库内部防御，不构成"0 = 禁用"的配置语义。
 - **Content-history storage grows with the number of DISTINCT bodies a skill has ever been written
@@ -46,3 +47,31 @@ section, and importing the package root is its only entry.
 - When the backend provides `transact` (nodeEvolutionIo and the io adapter do), the constructor binds it BY DEFAULT since 0.3.27: the single-file entry points (`update`, `patch`, `writeSupportFile`, and each per-file piece of `restructure`) run their read→write inside the cross-process lock for every instantiation, so same-file concurrent writes from different processes no longer resolve to last-writer-wins there.
 - The two-phase paths deliberately stay outside that lock: `create`'s exists probe runs inside the transact when a transact backend is bound (v18), so only a transact-less custom backend can still double-pass the probe across processes; `archive`/`consolidate` are rename-based with best-effort rollback (an archive loser's rollback surfaces the raw failure when the source vanished), and `restructure`'s multi-file swap can expose an interleaved tree to a concurrent reader.
 - These residual windows are documented rather than locked: cross-process writers to the SAME skill file should serialize through the single-file paths above.
+
+## Events (the family's own, process-local)
+
+Six process events ride the cordis bus (`evolution-core/src/events.ts` declares the payloads;
+producers call `ctx.emit`, consumers `ctx.on`). They are NOT session events — appending one to a
+session log made the session unresumable (A-line P0-1), which is why the payload file says so.
+
+| event | mode today | emitted by |
+|---|---|---|
+| `evolution/skill-mutated` | emit (notification) | `evolution-core` skill store |
+| `evolution/skills-refresh` | emit (notification) | `evolution-commands` `/evolution` verbs |
+| `evolution/review-scheduled` | emit (notification) | `evolution-review` cadence paths |
+| `evolution/review-error` | emit (notification) | `evolution-review` failure paths |
+| `evolution/plan-applied` | emit (notification) | `evolution-review` after a plan lands |
+| `evolution/memory-applied` | emit (notification) | `memory` after a memory write |
+
+The mode column is what the code does today: every one of them is an announcement, and each
+declaration carries it as a `@mode` tag (finding O-1, landed) — `verify-arch-guards`' rule **N33** checks that
+tag against THIS table and against the dispatch site (`ctx.emit('…'`), so a declaration that drifts from
+the table, or an event with no `@mode`, fails. This table stays the set's ONE home: the machine check here
+(`machine.kind = event-mode`) re-derives the SET from the emit sites, so an event added or renamed in
+code without this table fails N19.
+
+The last two rows have no in-family consumer: `evolution/review-scheduled` and `evolution/review-error`
+are emitted for operators and observability (5 and 3 dispatch sites, 0 `ctx.on` subscribers here). They are
+**kept deliberately** — the observation surface is the point, and a deployment's own listener is the intended
+consumer — so the `@mode` target stays at six (decision 10, provisional: keep).
+