dsh-plugin-guide 0.1.2 → 0.3.1

package/guide/plugin-dev-guide.md

@@ -185,7 +185,7 @@ export function apply(ctx: Context, config: Config) { /* config 已校验+补默
 2. **waterfall 监听器必须调 `next()`**。
 3. **模型可见 ⟺ 已记录**（Model-visible ⟺ logged）：任何进入模型请求的内容必须能从会话日志重建；新增模型可见输入必须新增会话事件。运行时不变式会断言这一点。
 4. **跨边界 opaque id 用 branded**：`Branded<B>`（`dsh-brand`，纯类型、零运行时依赖），从不裸 `string`；构造走 per-type factory（`SessionId` / `CallId` / `JobId` / `GoalId` 等），防止不同 id 在类型层互换。
-5. **会话事件版本规则**：`SessionEventMap` 成员默认 required-on-read——不认识该事件类型的 build 拒绝日志，除非事件信封带 `ignorable: true`；只有结构格式变更才 bump `SESSION_FORMAT_VERSION`。插件新增会话事件时按此契约设计（新增模型可见输入见红线 3）。
+5. **会话事件版本规则**：`SessionEventMap` 成员默认 required-on-read，无信封豁免——`0.1.2-alpha.1` 已移除 `ignorable` 信封、读路径 fail-closed，不认识该事件类型的 build 一律拒绝日志；只有结构格式变更才 bump `SESSION_FORMAT_VERSION`。插件新增会话事件时按此契约设计：下游插件事件目前无注册面，写自定义事件的插件用自适应门在无信封宿主上停写（新增模型可见输入见红线 3）。
 
 ---
 

package/guide/quick-reference.es.md

@@ -138,7 +138,7 @@ Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloque com
 5. Paquetes de plugin independientes: cordis es peerDependency con la misma identidad del host (mezclar scoped `@deepseek-ai/cordis` y unscoped divide identidades); ESM; manifiesto `dsh.bundle`; instalaciones git necesitan `prepare` + `allowBuilds`; publica `lib/` o un tarball.
 6. Documentación bilingüe en pares; descripciones/prompts son comportamiento; cambios no triviales llevan Agent Note; ejecuta el conjunto mínimo de checks antes de empujar (dsh-pre-push-checks).
 7. Los ids opacos entre límites son branded (`Branded<B>` de `dsh-brand`), nunca `string` pelado.
-8. Los miembros de `SessionEventMap` son required-on-read: los eventos de tipo desconocido deben llevar `ignorable: true` (o el log se rechaza); solo los cambios de formato estructural bumpan `SESSION_FORMAT_VERSION`. El switch sobre `SessionEvent` cae por un `default` documentado — sin `assertNever` (unión merge-extensible).
+8. Los miembros de `SessionEventMap` son required-on-read: el sobre `ignorable` desaparece en 0.1.2-alpha.1 (la lectura falla cerrada — un build que no conoce un tipo de evento rechaza el log), y los appends de eventos propios de plugins cruzan una puerta adaptativa que deja de escribir en hosts sin sobre; solo los cambios de formato estructural bumpan `SESSION_FORMAT_VERSION`. El switch sobre `SessionEvent` cae por un `default` documentado — sin `assertNever` (unión merge-extensible).
 
 ## Lista rápida de trampas comunitarias (detalles: guía §7.3 / community-repo-deep-dive.md)
 

package/guide/quick-reference.hi.md

@@ -138,7 +138,7 @@ Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(
 5. स्वतंत्र प्लगइन पैकेज: cordis peerDependency है और होस्ट पहचान से मेल खाना चाहिए (scoped `@deepseek-ai/cordis` और unscoped मिलाना पहचान बाँट देता है); ESM; `dsh.bundle` मैनिफ़ेस्ट; git इंस्टॉल को `prepare` + `allowBuilds` चाहिए; `lib/` या tarball प्रकाशित करें।
 6. दस्तावेज़ द्विभाषी जोड़ों में; टूल विवरण/प्रॉम्प्ट ही व्यवहार हैं; गैर-तुच्छ बदलाव में Agent Note चाहिए; पुश से पहले न्यूनतम जाँच सेट चलाएँ (dsh-pre-push-checks)।
 7. सीमाओं के पार अपारदर्शी ids branded होते हैं (`Branded<B>` from `dsh-brand`), कभी भी नंगे `string` नहीं।
-8. `SessionEventMap` सदस्य required-on-read हैं: अज्ञात प्रकार के इवेंट पर `ignorable: true` होना चाहिए (वरना log अस्वीकृत); केवल संरचनात्मक प्रारूप बदलाव ही `SESSION_FORMAT_VERSION` bump करते हैं। `SessionEvent` पर switch दस्तावेज़ित `default` में गिरता है — `assertNever` नहीं (merge-extensible union)।
+8. `SessionEventMap` सदस्य required-on-read हैं: 0.1.2-alpha.1 में `ignorable` लिफ़ाफ़ा हट गया है (पठन विफल-बंद है — जो build किसी इवेंट प्रकार को नहीं जानता वह log अस्वीकार करता है), और plugins के अपने इवेंट के append एक अनुकूली द्वार से चलते हैं जो बिना-लिफ़ाफ़े वाले hosts पर लिखना रोक देता है; केवल संरचनात्मक प्रारूप बदलाव ही `SESSION_FORMAT_VERSION` bump करते हैं। `SessionEvent` पर switch दस्तावेज़ित `default` में गिरता है — `assertNever` नहीं (merge-extensible union)।
 
 ## समुदाय की त्वरित समस्या-सूची (विवरण: गाइड §7.3 / community-repo-deep-dive.md)
 

package/guide/quick-reference.md

@@ -138,7 +138,7 @@ Chunk protocol: `block-start` → `text-delta*` → `block-end` (complete block)
 5. Standalone plugin packages: cordis is a peerDependency matching the host identity (mixing scoped `@deepseek-ai/cordis` and unscoped splits identities); ESM; `dsh.bundle` manifest; git installs need `prepare` + `allowBuilds`; ship `lib/` or a tarball.
 6. Bilingual docs in pairs; tool descriptions/prompts are behavior; non-trivial changes need an Agent Note; run the minimal check set before pushing (dsh-pre-push-checks).
 7. Opaque cross-boundary ids are branded (`Branded<B>` from `dsh-brand`), never bare `string`.
-8. `SessionEventMap` members are required-on-read: unknown event types must carry `ignorable: true` (or the log is refused); only structural format changes bump `SESSION_FORMAT_VERSION`. Switch over `SessionEvent` falls through a documented `default` — no `assertNever` (merge-extensible union).
+8. `SessionEventMap` members are required-on-read: the `ignorable` envelope is gone on 0.1.2-alpha.1 (reads fail closed — a build that does not know an event type refuses the log), and plugin appends of custom events ride an adaptive gate that stops writing on envelope-less hosts; only structural format changes bump `SESSION_FORMAT_VERSION`. Switch over `SessionEvent` falls through a documented `default` — no `assertNever` (merge-extensible union).
 
 ## Community pitfalls quick list (details: guide §7.3 / community-repo-deep-dive.md)
 

package/guide/quick-reference.pt.md

@@ -138,7 +138,7 @@ Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloco comp
 5. Pacotes de plugin independentes: cordis é peerDependency com a mesma identidade do host (misturar scoped `@deepseek-ai/cordis` e unscoped divide identidades); ESM; manifesto `dsh.bundle`; instalações git precisam de `prepare` + `allowBuilds`; publique `lib/` ou um tarball.
 6. Documentação bilíngue em pares; descrições/prompts são comportamento; mudanças não triviais levam Agent Note; rode o conjunto mínimo de verificações antes de empurrar (dsh-pre-push-checks).
 7. IDs opacos entre limites são branded (`Branded<B>` de `dsh-brand`), nunca `string` crua.
-8. Membros de `SessionEventMap` são required-on-read: eventos de tipo desconhecido devem levar `ignorable: true` (ou o log é recusado); apenas mudanças de formato estrutural bumpam `SESSION_FORMAT_VERSION`. O switch sobre `SessionEvent` cai num `default` documentado — sem `assertNever` (união merge-extensible).
+8. Membros de `SessionEventMap` são required-on-read: o envelope `ignorable` desaparece no 0.1.2-alpha.1 (a leitura falha fechada — um build que não conhece um tipo de evento recusa o log), e appends de eventos próprios de plugins cruzam uma porta adaptativa que para de gravar em hosts sem envelope; apenas mudanças de formato estrutural bumpam `SESSION_FORMAT_VERSION`. O switch sobre `SessionEvent` cai num `default` documentado — sem `assertNever` (união merge-extensible).
 
 ## Lista rápida de armadilhas da comunidade (detalhes: guia §7.3 / community-repo-deep-dive.md)
 

package/guide/quick-reference.zh-CN.md

@@ -137,7 +137,7 @@ Chunk 协议：`block-start` → `text-delta*` → `block-end`（完整块）→
 5. 独立插件包：cordis 是 peerDependency（与宿主同身份：scoped `@deepseek-ai/cordis` 与 unscoped 混用会"双 Cordis 分裂"）；ESM；`dsh.bundle` 清单；git 安装配 `prepare` + `allowBuilds`；发布带 `lib/` 或 tarball。
 6. 文档双语成对；工具描述/提示词即行为；非平凡变更加 Agent Note；提交前跑最小检查集（dsh-pre-push-checks）。
 7. 跨边界 opaque id 用 branded（`Branded<B>` from `dsh-brand`），从不裸 `string`。
-8. `SessionEventMap` 成员默认 required-on-read：不认识类型的会话事件必须带 `ignorable: true`（否则日志被拒读）；只有结构格式变更才 bump `SESSION_FORMAT_VERSION`。对 `SessionEvent` 的 switch 落入文档化 `default`——**禁用 `assertNever`**（merge-extensible union）。
+8. `SessionEventMap` 成员默认 required-on-read：`ignorable` 信封在 0.1.2-alpha.1 已移除（读路径 fail-closed——不认识该事件类型的 build 一律拒绝日志），插件自定义事件的追加走自适应门、在无信封宿主上停写；只有结构格式变更才 bump `SESSION_FORMAT_VERSION`。对 `SessionEvent` 的 switch 落入文档化 `default`——**禁用 `assertNever`**（merge-extensible union）。
 
 ## 社区实测坑速查（详见 guide §7.3 / community-repo-deep-dive.md）
 

package/package.json

@@ -1,11 +1,21 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.1.2",
-  "description": "The dsh-plugin-guide knowledge base as an installable DeepSeek Harness plugin: official docs, Cordis primer, community deep-dives, and battle-tested pitfalls registered as an on-demand agent skill.",
+  "version": "0.3.1",
+  "description": "The dsh-plugin-guide knowledge base plus the dsh-plugin-dev CLI toolchain: official docs, Cordis primer, community deep-dives, and battle-tested pitfalls registered as an on-demand agent skill, with a scaffolder, static checker, and pack verifier for building DSH plugins.",
   "type": "module",
   "main": "index.js",
+  "bin": {
+    "dsh-plugin-dev": "./bin/dsh-plugin-dev.js"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "index.js",
+    "bin",
+    "dist",
+    "templates",
     "cordis.patch.yml",
     "SKILL.md",
     "guide",
@@ -26,13 +36,36 @@
     "cordis",
     "agent-skill",
     "plugin-development",
-    "knowledge-base"
+    "knowledge-base",
+    "cli",
+    "scaffold",
+    "checker"
   ],
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/PerryLink/dsh-plugin-guide.git"
   },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "typecheck:ci": "tsc --noEmit --pretty false",
+    "test": "vitest run",
+    "check:readmes": "node scripts/check-readme-sync.mjs",
+    "check:kit": "pwsh -File scripts/verify-kit.ps1",
+    "verify:artifacts": "node scripts/verify-artifacts.mjs",
+    "verify:self-contained": "pnpm run build && node dist/dsh-plugin-dev.js verify",
+    "prepare": "tsdown",
+    "prepack": "tsdown"
+  },
+  "dependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "vitest": "^3.2.7"
+  },
   "peerDependencies": {
     "@deepseek-ai/dsh": ">=0.1.0-rc.8 <0.2.0"
   },
@@ -46,6 +79,10 @@
       "patch": "./cordis.patch.yml"
     }
   },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
   "dshWorkshop": {
     "schema": "omdsh-workshop-package/v1",
     "type": "plugin",
@@ -63,9 +100,13 @@
       "activation": "restart-profile",
       "dispose": "supported"
     },
-    "permissions": ["filesystem:read"],
+    "permissions": [
+      "filesystem:read"
+    ],
     "compatibility": {
-      "dshVersions": ["0.1.1-rc.2"]
+      "dshVersions": [
+        "0.1.1-rc.2"
+      ]
     },
     "capability": {
       "id": "dsh-plugin-guide",
@@ -79,5 +120,9 @@
       "hotReload": null,
       "remove": null
     }
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/PerryLink"
   }
 }

package/references/harness-repo.md

@@ -489,7 +489,7 @@ skill 目录结构：`packages/skill/` 下有 `skill`（registry/Service Definit
 - `strict: true` + `noImplicitAny`；每个残留 `any` 解释为何无法收窄。
 - 每个 module/export 有简洁 JSDoc（`@param`/`@returns`），由 `verify-export-jsdoc` 强制。
 - typed events 用 declaration merging + merge-extensible maps；event JSDoc 需 `@mode` 和 payload `@param`；scoped keys 缺 payload 需 `@dshScopeScan unsupported`。
-- `SessionEventMap` 成员默认 required-on-read；不认其类型的 build 拒绝该 log，除非 event 带 envelope 的 `ignorable: true`；只有结构格式变更才 bump `SESSION_FORMAT_VERSION`。
+- `SessionEventMap` 成员默认 required-on-read，无信封豁免：不认其类型的 build 一律拒绝该 log；只有结构格式变更才 bump `SESSION_FORMAT_VERSION`。
 - switch 用 discriminant tags：closed union 结尾 `assertNever`；merge-extensible union 走文档化 default。
 - opaque 跨边界 id 用 branded（`Branded<B>` from `dsh-brand`），从不裸 `string`。
 - 每个包拥有 `./invariant`（注册 manifest 名；检查 event/data 关系或给空 installer 一个包特定 `No runtime invariant:` 理由），由 `verify-package-invariants` 强制（`packages/AGENTS.md` L18）。

package/references/official-docs/AGENTS.md

@@ -101,7 +101,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - ESM everywhere (`"type": "module"`). Use package names across packages and `.ts` in local relative imports. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only exports) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. Without a plausible relationship, an explained empty companion is correct ([package invariant rules](packages/AGENTS.md)).
-- **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. A `SessionEventMap` member is required-on-read by default — builds that do not know its type refuse the log unless the event carries the envelope's `ignorable: true`; only structural format changes bump `SESSION_FORMAT_VERSION` ([mechanism](.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)).
+- **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. Every `SessionEventMap` member is required-on-read: builds that do not know its type refuse the log; only structural format changes bump `SESSION_FORMAT_VERSION` ([mechanism](.agents/notes/implemented/simplification/2026-08-25-fail-closed-session-event-vocabulary.md)).
 - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.

package/references/official-docs/docs/persistence-catalog.md

@@ -7,7 +7,7 @@ Every event type that can appear in a session's durable event log: the complete
 
 This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).
 
-The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, the optional `ignorable` unknown-type skip marker, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.
+The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.
 
 ## Event envelope
 
@@ -63,17 +63,6 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
-    /**
-     * Marks an event a reader may safely skip when it does not recognize
-     * `type`. Absent means required: a reader meeting an unrecognized type
-     * without this marker MUST refuse to reconstruct the session instead of
-     * silently dropping the event, because an unrecognized required event may
-     * change how the rest of the log is interpreted. A writer sets `true` only
-     * on purely informational records whose loss cannot affect reconstruction;
-     * defaulting to required means a forgotten marker over-refuses (an
-     * inconvenience) rather than silently resuming a gutted session.
-     */
-    ignorable?: true
   } & (K extends SurfaceEventType ? {
     /**
      * Seq numbers of earlier events that this event cites as sources

package/references/official-docs/docs/persistence-catalog.zh.md

@@ -9,7 +9,7 @@
 
 英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（doc-typecheck 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
 
-以下信封声明组合了每个事件的 `type`、单调递增的 `seq`、以 epoch 毫秒表示的 `time`、`data`、可选的未知类型跳过标记 `ignorable`，以及条件字段 `surfaceOp`／`sourceEventSeqs`。**surface** 表示 `SurfaceEventType` 成员：它会生成一条 LLM（大语言模型）消息，并声明该事件如何加入 surface 列表。**log-only** 表示其他所有事件：这类记录可持久化、可回放，但不参与派生历史。每个 payload 均可进行 JSON 序列化（在 `Session.append` 处强制执行），整个格式固定为 `SESSION_FORMAT_VERSION = 0`：这是预发布格式，不暗示任何兼容性（参见[版本立场](subsystems/persistence.md)）。范围仅限本仓库中的包；下游插件可以继续合并其他事件类型，而这些类型按设计不属于本目录。
+以下信封声明组合了每个事件的 `type`、单调递增的 `seq`、以 epoch 毫秒表示的 `time`、`data`，以及条件字段 `surfaceOp`／`sourceEventSeqs`。**surface** 表示 `SurfaceEventType` 成员：它会生成一条 LLM（大语言模型）消息，并声明该事件如何加入 surface 列表。**log-only** 表示其他所有事件：这类记录可持久化、可回放，但不参与派生历史。每个 payload 均可进行 JSON 序列化（在 `Session.append` 处强制执行），整个格式固定为 `SESSION_FORMAT_VERSION = 0`：这是预发布格式，不暗示任何兼容性（参见[版本立场](subsystems/persistence.md)）。范围仅限本仓库中的包；下游插件可以继续合并其他事件类型，而这些类型按设计不属于本目录。
 
 ## 事件信封
 
@@ -65,17 +65,6 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
-    /**
-     * Marks an event a reader may safely skip when it does not recognize
-     * `type`. Absent means required: a reader meeting an unrecognized type
-     * without this marker MUST refuse to reconstruct the session instead of
-     * silently dropping the event, because an unrecognized required event may
-     * change how the rest of the log is interpreted. A writer sets `true` only
-     * on purely informational records whose loss cannot affect reconstruction;
-     * defaulting to required means a forgotten marker over-refuses (an
-     * inconvenience) rather than silently resuming a gutted session.
-     */
-    ignorable?: true
   } & (K extends SurfaceEventType ? {
     /**
      * Seq numbers of earlier events that this event cites as sources

package/references/official-docs/docs/subsystems/persistence.md

@@ -91,7 +91,7 @@ interface SessionHeader {
 
 ## Format refusal — logs a build cannot faithfully read
 
-A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupportedError`, distinct from `SessionPersistenceCorruptionError` because nothing is damaged. A header `version` ahead of `SESSION_FORMAT_VERSION` names the direction ("written by a newer harness — upgrade the harness to open it"); one behind it states that this build ships no upgrade path. After legacy-shape normalization, an event type outside this build's generated vocabulary (`KNOWN_SESSION_EVENT_TYPES`, emitted by `gen-persistence-catalog`) refuses the same way unless the event's envelope carries `ignorable: true` — silently skipping an unrecognized required event could change how the rest of the log must be read. The message appends the raw log path when the backend keeps one artifact per session, so the refused text stays reachable. The JSONL backend refuses a foreign version straight from the raw header line, before validating today's header shape or decoding any event row — a structurally different future format still reports the upgrade direction, never "corrupt"; SQLite gates whole-file structure through its own `SCHEMA_VERSION` pragma first. Design rationale and the deferred upgrader chain live in the [session-log-version-mechanism note](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md).
+A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupportedError`, distinct from `SessionPersistenceCorruptionError` because nothing is damaged. A header `version` ahead of `SESSION_FORMAT_VERSION` names the direction ("written by a newer harness — upgrade the harness to open it"); one behind it states that this build ships no upgrade path. After legacy-shape normalization, an event type outside this build's generated set (`KNOWN_SESSION_EVENT_TYPES`, emitted by `gen-persistence-catalog`) also refuses reconstruction because silently skipping it could change how the rest of the log must be read. The message appends the raw log path when the backend keeps one artifact per session, so the refused text stays reachable. The JSONL backend refuses a foreign version straight from the raw header line, before validating this format version's header fields or decoding any event row — a structurally different future format still reports the upgrade direction, never "corrupt"; SQLite gates whole-file structure through its own `SCHEMA_VERSION` pragma first. Design rationale and the deferred upgrader chain live in the [fail-closed event-vocabulary note](../../.agents/notes/implemented/simplification/2026-08-25-fail-closed-session-event-vocabulary.md).
 
 ## `CreateSessionOptions` — seeding and metadata
 

package/references/official-docs/docs/subsystems/persistence.zh.md

@@ -91,7 +91,7 @@ interface SessionHeader {
 
 ## 格式拒绝：本构建无法可靠读取的日志
 
-后端用 `SessionFormatUnsupportedError` 拒绝无法可靠解读的日志，它与 `SessionPersistenceCorruptionError` 区分，因为数据没有损坏。header 的 `version` 比 `SESSION_FORMAT_VERSION` 新时，消息说明方向（"由更新的 harness 写入，请升级 harness 后打开"）；比它旧时说明本构建没有升级路径。经过 legacy 形状归一化后，本构建生成词汇表（`KNOWN_SESSION_EVENT_TYPES`，由 `gen-persistence-catalog` 生成）之外的事件类型同样被拒绝，除非该事件的信封带 `ignorable: true`：静默跳过一个不认识的必需事件可能改变日志其余部分的解读方式。后端为每个会话保留独立文件时，消息附上原始日志路径，被拒绝的文本仍然可读。JSONL 后端直接从原始 header 行拒绝外来版本，先于当前 header 形状校验和任何事件行解码，因此结构完全不同的未来格式仍会报告升级方向，绝不会报"损坏"；SQLite 则先由自己的 `SCHEMA_VERSION` pragma 把关整个文件的结构。设计理由与推迟建设的升级器链见 [session-log 版本机制 Agent Note](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)。
+后端用 `SessionFormatUnsupportedError` 拒绝无法可靠解读的日志，它与 `SessionPersistenceCorruptionError` 区分，因为数据没有损坏。header 的 `version` 比 `SESSION_FORMAT_VERSION` 新时，消息说明方向（"由更新的 harness 写入，请升级 harness 后打开"）；比它旧时说明本构建没有升级路径。经过 legacy 形状归一化后，本构建生成集合（`KNOWN_SESSION_EVENT_TYPES`，由 `gen-persistence-catalog` 生成）之外的事件类型也会拒绝重建，因为静默跳过该事件可能改变日志其余部分的解读方式。后端为每个会话保留独立文件时，消息附上原始日志路径，被拒绝的文本仍然可读。JSONL 后端直接从原始 header 行拒绝外来版本，先于校验本格式版本的 header 字段和解码任何事件行，因此结构完全不同的未来格式仍会报告升级方向，绝不会报"损坏"；SQLite 则先由自己的 `SCHEMA_VERSION` pragma 把关整个文件的结构。设计理由与推迟建设的升级器链见[事件词汇表显式拒绝 Agent Note](../../.agents/notes/implemented/simplification/2026-08-25-fail-closed-session-event-vocabulary.zh.md)。
 
 ## `CreateSessionOptions`：seed 与元数据
 

package/references/official-docs/docs/subsystems/session.md

@@ -217,17 +217,6 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
-    /**
-     * Marks an event a reader may safely skip when it does not recognize
-     * `type`. Absent means required: a reader meeting an unrecognized type
-     * without this marker MUST refuse to reconstruct the session instead of
-     * silently dropping the event, because an unrecognized required event may
-     * change how the rest of the log is interpreted. A writer sets `true` only
-     * on purely informational records whose loss cannot affect reconstruction;
-     * defaulting to required means a forgotten marker over-refuses (an
-     * inconvenience) rather than silently resuming a gutted session.
-     */
-    ignorable?: true
   } & (K extends SurfaceEventType ? {
     /**
      * Seq numbers of earlier events that this event cites as sources

package/references/official-docs/docs/subsystems/session.zh.md

@@ -217,17 +217,6 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
-    /**
-     * Marks an event a reader may safely skip when it does not recognize
-     * `type`. Absent means required: a reader meeting an unrecognized type
-     * without this marker MUST refuse to reconstruct the session instead of
-     * silently dropping the event, because an unrecognized required event may
-     * change how the rest of the log is interpreted. A writer sets `true` only
-     * on purely informational records whose loss cannot affect reconstruction;
-     * defaulting to required means a forgotten marker over-refuses (an
-     * inconvenience) rather than silently resuming a gutted session.
-     */
-    ignorable?: true
   } & (K extends SurfaceEventType ? {
     /**
      * Seq numbers of earlier events that this event cites as sources

package/scripts/check-docs-drift.ps1

@@ -0,0 +1,55 @@
+# dsh-plugin-guide official-docs freshness probe.
+# Purpose: detect drift between the KB mirror (references/official-docs) and the
+#   upstream deepseek-harness repository WITHOUT a local checkout. It compares the
+#   upstream branch tip SHA (git ls-remote) against the pinned "Source commit" SHA
+#   recorded in references/official-docs/SNAPSHOT.md — the SHA-locked authority the
+#   mirror was synced from. It never edits the mirror; drift is only reported.
+# Usage:  pwsh -File scripts/check-docs-drift.ps1 [-Repo <url>] [-Branch <name>] [-Snapshot <path>] [-FailOnDrift]
+#   Exit codes: 0 = FRESH, 1 = DRIFT (with -FailOnDrift), 2 = probe could not run (snapshot/parse/fetch failure).
+#   In CI it also writes `drift=yes|no|error` to $env:GITHUB_OUTPUT when that variable is set.
+param(
+  [string]$Repo = 'https://github.com/deepseek-ai/deepseek-harness.git',
+  [string]$Branch = 'master',
+  [string]$Snapshot = 'references/official-docs/SNAPSHOT.md',
+  [switch]$FailOnDrift
+)
+$ErrorActionPreference = 'Stop'
+$kit = Split-Path $PSScriptRoot -Parent
+$snapshotPath = Join-Path $kit $Snapshot
+
+# ---- 1) Read the pinned source commit SHA from SNAPSHOT.md ----
+$pinned = $null
+if (-not (Test-Path $snapshotPath)) { Write-Error "snapshot not found: $snapshotPath"; exit 2 }
+foreach ($line in Get-Content $snapshotPath -Encoding UTF8) {
+  if ($line -match '^\|\s*Source commit\s*\|\s*`([0-9a-f]{40})`\s*\|') {
+    $pinned = $Matches[1]
+    break
+  }
+}
+if (-not $pinned) { Write-Error "cannot parse the pinned 'Source commit' SHA from $Snapshot"; exit 2 }
+
+# ---- 2) Fetch the upstream branch tip SHA (no clone required) ----
+$remoteLine = (& git ls-remote $Repo "refs/heads/$Branch" 2>$null | Select-Object -First 1)
+if (-not $remoteLine -or $remoteLine -notmatch '^([0-9a-f]{40})\s') {
+  $message = "cannot reach upstream $Repo (branch $Branch)"
+  Write-Output "ERROR: $message"
+  if ($env:GITHUB_OUTPUT) { Add-Content -Path $env:GITHUB_OUTPUT -Value 'drift=error' }
+  exit 2
+}
+$upstream = $Matches[1]
+
+# ---- 3) Compare and report ----
+$fresh = ($upstream -eq $pinned)
+Write-Output "pinned (SNAPSHOT.md): $pinned"
+Write-Output "upstream ($Branch): $upstream"
+if ($fresh) {
+  Write-Output 'FRESH: references/official-docs matches the upstream branch tip'
+} else {
+  Write-Output "DRIFT: references/official-docs is pinned to $pinned but upstream is at $upstream"
+  Write-Output 'Action: run  pwsh -File scripts/sync-official-docs.ps1  to refresh the mirror (do not hand-edit the mirror).'
+}
+if ($env:GITHUB_OUTPUT) {
+  Add-Content -Path $env:GITHUB_OUTPUT -Value ($(if ($fresh) { 'drift=no' } else { 'drift=yes' }))
+}
+if (-not $fresh -and $FailOnDrift) { exit 1 }
+exit 0

package/scripts/check-readme-sync.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Five-language README sync gate: the English file is the source of truth.
+// Every translation must carry the same `## ` section headings in the same
+// order and the same configuration-table keys, so a config change cannot
+// ship without its translations.
+import { readFileSync, existsSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
+const LANGUAGES = [
+  ['README.md', 'en'],
+  ['README.zh.md', 'zh'],
+  ['README.es.md', 'es'],
+  ['README.pt.md', 'pt'],
+  ['README.hi.md', 'hi'],
+]
+
+const headingsOf = (text) => text.split(/\r?\n/u)
+  .map(line => /^##\s+(.+)$/u.exec(line)?.[1]?.trim())
+  .filter((heading) => heading !== undefined)
+
+// Configuration-table keys: the first cell of every row under the
+// "Configuration" section (until the next `## ` heading).
+const configKeysOf = (text) => {
+  const lines = text.split(/\r?\n/u)
+  const start = lines.findIndex(line => /^##\s+Configuration\s*$/u.test(line))
+  if (start === -1) return []
+  const end = lines.findIndex((line, index) => index > start && line.startsWith('## '))
+  const section = lines.slice(start, end === -1 ? undefined : end)
+  const keys = []
+  let headerSkipped = false
+  for (const line of section) {
+    if (!line.startsWith('|')) continue
+    if (!headerSkipped) { headerSkipped = true; continue }
+    const cells = line.split('|').map(cell => cell.trim())
+    if (cells.length < 2) continue
+    const key = cells[1]
+    if (key === '' || key === 'Key') continue
+    if (/^-+$/u.test(key)) continue
+    keys.push(key)
+  }
+  return keys
+}
+
+const failures = []
+const reference = LANGUAGES[0]
+if (reference === undefined) process.exit(1)
+const refPath = path.join(root, reference[0])
+if (!existsSync(refPath)) {
+  console.error(`${reference[0]} is missing`)
+  process.exit(1)
+}
+const refText = readFileSync(refPath, 'utf8')
+const refHeadings = headingsOf(refText)
+const refKeys = configKeysOf(refText)
+
+for (const [file, label] of LANGUAGES.slice(1)) {
+  const filePath = path.join(root, file)
+  if (!existsSync(filePath)) {
+    failures.push(`${file}: missing (${label})`)
+    continue
+  }
+  const text = readFileSync(filePath, 'utf8')
+  const headings = headingsOf(text)
+  for (let index = 0; index < refHeadings.length; index++) {
+    if (headings[index] !== refHeadings[index]) {
+      failures.push(`${file}: heading ${index + 1} is ${JSON.stringify(headings[index])}, expected ${JSON.stringify(refHeadings[index])}`)
+    }
+  }
+  if (headings.length !== refHeadings.length) {
+    failures.push(`${file}: ${headings.length} headings, expected ${refHeadings.length}`)
+  }
+  const keys = configKeysOf(text)
+  if (keys.length !== refKeys.length) {
+    failures.push(`${file}: ${keys.length} config keys, expected ${refKeys.length}`)
+    continue
+  }
+  for (let index = 0; index < refKeys.length; index++) {
+    if (keys[index] !== refKeys[index]) {
+      failures.push(`${file}: config key ${index + 1} is ${JSON.stringify(keys[index])}, expected ${JSON.stringify(refKeys[index])}`)
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error('readme-sync failed:')
+  for (const failure of failures) console.error(`  - ${failure}`)
+  process.exit(1)
+}
+console.log(`readme-sync: all ${LANGUAGES.length} READMEs share section structure and config keys`)

package/scripts/verify-artifacts.mjs

@@ -0,0 +1,70 @@
+// Artifact gate for the dsh-plugin-guide CLI. Runs after `pnpm run build` and
+// verifies the shipped surfaces without any network access:
+//   1. the built CLI, bin shim, and template trees exist;
+//   2. the CLI self-checks this repo (dogfood) and reports `ok: true`;
+//   3. the scaffolder produces TS and JS skeletons inside a mkdtemp sandbox
+//      (never touching a real home directory), which are then removed.
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, rmSync, readdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const failures = []
+
+function check(condition, message) {
+  if (condition) {
+    console.log(`ok - ${message}`)
+  } else {
+    failures.push(message)
+    console.error(`FAIL - ${message}`)
+  }
+}
+
+function runNode(args, options = {}) {
+  return spawnSync(process.execPath, args, { cwd: root, encoding: 'utf8', ...options })
+}
+
+// 1. Shipped surfaces.
+check(existsSync(join(root, 'dist', 'dsh-plugin-dev.js')), 'dist/dsh-plugin-dev.js exists (run pnpm run build first)')
+check(existsSync(join(root, 'bin', 'dsh-plugin-dev.js')), 'bin/dsh-plugin-dev.js exists')
+check(existsSync(join(root, 'templates', 'ts')), 'templates/ts exists')
+check(existsSync(join(root, 'templates', 'js')), 'templates/js exists')
+
+// 2. Version + dogfood self-check.
+const version = runNode(['dist/dsh-plugin-dev.js', '--version'])
+check(version.status === 0 && /\d+\.\d+\.\d+/.test(version.stdout.trim()), `--version prints a semver (${version.stdout.trim()})`)
+
+const selfCheck = runNode(['dist/dsh-plugin-dev.js', 'check', '--json'], { stdio: ['ignore', 'pipe', 'pipe'] })
+let ok = false
+if (selfCheck.status === 0) {
+  try {
+    ok = JSON.parse(selfCheck.stdout).ok === true
+  } catch {
+    ok = false
+  }
+}
+check(selfCheck.status === 0 && ok, `self-check (dogfood) reports ok (exit ${selfCheck.status})`)
+
+// 3. Scaffold smoke in a mkdtemp sandbox.
+const sandbox = mkdtempSync(join(tmpdir(), 'dsh-pd-artifacts-'))
+try {
+  for (const lang of ['ts', 'js']) {
+    const target = join(sandbox, lang, 'demo-plugin')
+    const result = runNode(['dist/dsh-plugin-dev.js', 'new', 'demo-plugin', '--lang', lang, '--dir', target])
+    const hasEntry = lang === 'ts' ? existsSync(join(target, 'src', 'index.ts')) : existsSync(join(target, 'index.js'))
+    const hasPatch = existsSync(join(target, 'cordis.patch.yml'))
+    const readmeCount = readdirSync(target).filter((f) => /^README(\.\w{2})?\.md$/.test(f)).length
+    check(result.status === 0 && hasEntry && hasPatch, `${lang} scaffold produces entry + cordis.patch.yml (exit ${result.status})`)
+    check(readmeCount === 5, `${lang} scaffold produces 5 README languages (${readmeCount})`)
+  }
+} finally {
+  rmSync(sandbox, { recursive: true, force: true })
+}
+
+if (failures.length > 0) {
+  console.error(`\nverify:artifacts FAILED (${failures.length})`)
+  process.exit(1)
+}
+console.log('\nverify:artifacts OK')

package/templates/js/LICENSE

@@ -0,0 +1,15 @@
+Apache License 2.0
+
+Copyright (c) {{year}} {{pkgName}} contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/templates/js/README.es.md

@@ -0,0 +1,42 @@
+# {{pkgName}}
+
+Un plugin de DeepSeek Harness (DSH) generado con [`dsh-plugin-dev new`](https://github.com/PerryLink/dsh-plugin-guide).
+
+## Compatibility
+
+| Superficie | Estado |
+|---|---|
+| Harness | DeepSeek Harness `0.1.1-rc.2` |
+| Node | `^22.19.0 || >=24.0.0` |
+| Plataformas | Todas (ESM puro; sin código nativo, sin red) |
+
+## What it does
+
+Registra la herramienta `{{name}}_echo`. Al llamarla responde `<greeting>: <text>`, donde `<greeting>` proviene de la configuración del plugin y `<text>` es el argumento.
+
+## Install
+
+```sh
+pnpm pack
+dsh plugin --profile <name> add ./{{pkgName}}-{{version}}.tgz
+dsh --profile <name> --dump-config | grep '{{pkgName}}'
+```
+
+## Configuration
+
+| Clave | Tipo | Valor por defecto | Descripción |
+|---|---|---|---|
+| `greeting` | string | `Hello` | Prefijo de la respuesta echo |
+
+La configuración se valida con el esquema Schemastery `Config` de `index.js`; ningún ajuste está codificado de forma fija.
+
+## Development
+
+```sh
+pnpm install
+pnpm test
+```
+
+## License
+
+[Apache License 2.0](LICENSE) © {{year}} {{pkgName}} contributors.