dsh-plugin-guide 0.3.42 → 0.4.1

package/references/official-docs/docs/deepseek-llm-api-wire-extensions.md

@@ -1,162 +0,0 @@
-# Official DeepSeek LLM API wire extensions
-
-English | [中文](deepseek-llm-api-wire-extensions.zh.md)
-
-This reference defines every DeepSeek Harness-specific HTTP header and additive JSON field sent by [`@deepseek-ai/dsh-llm-deepseek`](../packages/llm/llm-deepseek/README.md) on `deepseek-official` Messages requests. It does not redefine fields owned by the upstream DeepSeek API. The provider-neutral LLM interface and `llm-pi-ai` do not implement these additions.
-
-The adapter sends the additions to its resolved `baseURL`, including a configured gateway. They remain outside `messages`, system prompts, and tool schemas, so they do not add model-input tokens or alter the model-visible prefix.
-
-## Wire namespaces and versioning
-
-| Location | Naming | Examples |
-|---|---|---|
-| HTTP field names | Lowercase kebab-case; HTTP matching remains case-insensitive | `user-agent`, `x-deepseek-harness-session-id` |
-| DeepSeek request-body extension fields | Snake case with the reserved `dsh_` prefix | `dsh_plugin_packages`, `dsh_session_log` |
-| DSH-owned nested JSON members | Camel case | `afterSeq`, `throughSeq`, `sessionId` |
-| Tagged values | Kebab-case strings; durable events use `domain/action` | `session-log-deepseek/delivery-accepted` |
-
-Each body extension owns its `version` independently. A version applies only to the object that contains it; no compatibility or ordering relationship exists between versions of different fields. JSON member order is not part of the protocol.
-
-The [`DeepSeekLlmApiExtensionRegistry`](../packages/llm/deepseek-llm-api-extensions/README.md) reserves one provider per top-level extension name. Empty or whitespace-padded names, duplicate registrations, and collisions with the base DeepSeek request fail before HTTP dispatch.
-
-## Request headers
-
-| Header | Presence | Value |
-|---|---|---|
-| `user-agent` | Every provider HTTP request, including Files API operations | Application identity in `product/version (+url)` form; the default product is `deepseek-harness` |
-| `x-deepseek-harness-user-id` | Every authorized model request | The stable anonymous UUID for the resolved Harness home |
-| `x-deepseek-harness-session-id` | Model requests carrying a Session id | The exact request `sessionId` string |
-| `x-deepseek-harness-compact` | Model requests whose purpose is `compaction` | The literal string `1` |
-
-Credential failure happens before anonymous-user-id resolution, so an unauthorized request neither sends these headers nor creates the identity file. A direct request without a Session omits `x-deepseek-harness-session-id`. Session-title requests have no additional purpose header; the ordinary Session-id rule still applies when one carries a `sessionId`.
-
-## Body-extension transaction
-
-The adapter serializes the complete base body, including the exact `messages`, before it asks registered providers to prepare fields. A provider receives that immutable body, the request cancellation signal, and optional `sessionId` and auxiliary-call `purpose`. Returning `undefined` omits that provider's field for the request.
-
-Prepared JSON values are detached from provider-owned state, merged as top-level siblings of the base fields, and serialized in the same HTTP body. A contributor whose preparation fails is omitted from that request, with only its first failure logged, while the other fields are still sent; a field that collides with a base field prevents the request. If the merged body fails to serialize, the adapter sends the base body without any extension field, skips the acceptance transaction so contributors resend their state on a later request, and logs the omitted field names. A composition without the registry sends the unextended base body.
-
-After the configured endpoint returns HTTP 2xx, the adapter runs the prepared `accept()` transaction before reading the SSE response body. Transport failures and non-2xx responses do not accept any contribution. An acceptance failure is logged and does not fail the model request; the contributor resends its unaccepted state on a later request. Acceptance records endpoint-level HTTP success; it does not assert that an SSE stream completed or that the endpoint persisted an extension.
-
-## `dsh_plugin_packages`
-
-[`@deepseek-ai/dsh-plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek/README.md) contributes the complete active Loader-backed plugin package inventory. The field is enabled by default.
-
-```json
-{
-  "dsh_plugin_packages": {
-    "version": 1,
-    "packages": [
-      {
-        "name": "@deepseek-ai/dsh-example",
-        "version": "0.1.1-rc.2"
-      }
-    ]
-  }
-}
-```
-
-| Member | Type | Meaning |
-|---|---|---|
-| `version` | `1` | Schema version for `dsh_plugin_packages` |
-| `packages` | array | Complete active set for this request |
-| `packages[].name` | string | Exact non-empty npm package name from the owning manifest |
-| `packages[].version` | optional string | Exact non-blank package version from the same manifest; absent when unavailable |
-
-Every request re-reads active non-group Loader entries from the host tree and, when available for the request Session, its standing agent-preset tree. Relative and absolute modules use their nearest owning manifest; bare package entries follow the Loader resolution base that activated them. A named manifest without a non-blank string version contributes `{ name }`, regardless of `private`. Missing names and unreadable manifests omit only the affected entries; package metadata does not block requests.
-
-The sender deduplicates exact `(name, optional version)` pairs and sorts first by `name`, then by `version`, with a locale-independent text comparison and absent versions first. Simultaneously active versions of one package remain separate entries, including a name-only entry. Receivers must accept absent versions, must not collapse the array by package name, and must not infer package activation from array order.
-
-Disabled, pending, failed, unloading, disposed, and structural Loader entries are absent. Ordinary dependencies, loose modules without a named owning package, programmatically mounted child fibers, and in-memory dynamic plugins are also absent because they have no authoritative Loader-backed package identity.
-
-An enabled inventory with no qualifying entries sends `packages: []`; disabling the contributor omits the entire `dsh_plugin_packages` field. Package identities are provider metadata and never enter model input.
-
-## `dsh_session_log`
-
-[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.md) contributes one contiguous suffix of the canonical Session log. The field is enabled by default. It applies to a request with a live Session and at least one event; a direct request, a stale Session id, or an empty log omits the field, as does a request whose first pending event alone exceeds `maxBytes` or cannot be serialized; a composition disables it with `enabled: false`. The examples below use logical Session format 2 only to illustrate the wire fields; they do not identify the [current writer format](session-format-status.md).
-
-```json
-{
-  "dsh_session_log": {
-    "version": 1,
-    "sessionFormatVersion": 2,
-    "session": {
-      "version": 2,
-      "id": "session-id",
-      "createdAt": 1780000000000
-    },
-    "afterSeq": -1,
-    "throughSeq": 0,
-    "events": [
-      {
-        "type": "turn/start",
-        "seq": 0,
-        "time": 1780000000001,
-        "data": {
-          "turn": 1
-        }
-      }
-    ]
-  }
-}
-```
-
-| Member | Type | Meaning |
-|---|---|---|
-| `version` | `1` | Schema version for `dsh_session_log` |
-| `sessionFormatVersion` | non-negative integer | Session format generation represented by this suffix |
-| `session` | object | Immutable wire projection of the current Session header |
-| `afterSeq` | integer | Greatest sequence recorded as accepted before this request, or `-1` |
-| `throughSeq` | non-negative integer | Greatest sequence represented by this request |
-| `events` | array | Contiguous events from `afterSeq + 1` through `throughSeq` |
-
-The first upload uses `afterSeq: -1`, and each later upload starts after the greatest accepted watermark for the same Session id. Each upload carries the longest contiguous run from that point whose serialized field fits `maxBytes`, 8 MiB by default and counted in UTF-8 bytes including the header and numeric fields, so a backlog above the limit spans several accepted requests. The sender snapshots the event array once per request; appends after that snapshot belong to a later request.
-
-### Wire Session header
-
-The `session` member projects logical Session metadata to raw JSON primitives. A seeded Session sends its exact `Session.inheritedEventCount` as `seedLength`; an unseeded Session omits that field. The logical `isSeeded` flag does not appear on this wire. The outer `dsh_session_log.version` selects this extension schema, while `session.version` selects the logical Session format. Changing the Session header projection requires an extension-schema bump even when the embedded logical format also changes.
-
-| Member | Presence | Meaning |
-|---|---|---|
-| `version` | required | Logical Session format version from `Session.header`; see [format status](session-format-status.md) |
-| `id` | required | Exact Session id |
-| `createdAt` | required | Non-negative safe-integer Unix epoch milliseconds |
-| `cwd` | optional | Absolute working directory recorded at Session creation |
-| `parentSession` | optional | Parent Session id for a fork |
-| `seedLength` | seeded Sessions only | Exact inherited event count, including zero for an empty inherited prefix |
-| `origin` | optional | Literal `subagent` for a subagent child |
-| `delegationDepth` | optional | Non-negative persisted subagent delegation depth |
-| `agentPreset` | optional | Agent preset id used to compose this Session |
-
-### Canonical event envelopes
-
-Each `events` item carries a canonical event as raw JSON primitives, independently of every other request field. Every event includes `type`, numeric `seq`, `time`, and `data`, with `ignorable: true` preserved when present. Surface events require `surfaceOp`; replacement ranges use numeric `startSeq` and `endSeq`, and system, user, and tool events may also carry numeric `sourceEventSeqs`. Assistant provider metadata remains in its embedded stream. Known log-only events omit surface metadata; restored unknown ignorable records preserve opaque metadata without treating it as a surface operation.
-
-### Acceptance watermark and at-least-once delivery
-
-After the endpoint returns HTTP 2xx, the contribution appends this canonical event to the same Session:
-
-```json
-{
-  "type": "session-log-deepseek/delivery-accepted",
-  "seq": 8,
-  "time": 1780000000002,
-  "data": {
-    "sessionId": "session-id",
-    "sessionFormatVersion": 2,
-    "throughSeq": 7
-  }
-}
-```
-
-`delivery-accepted` means that the configured endpoint returned HTTP 2xx for the containing LLM request. It does not assert SSE completion or remote persistence. The event's `throughSeq` must identify an earlier event, its `sessionId` identifies the Session whose suffix was sent, and `sessionFormatVersion` binds the watermark to that exact logical generation. Absence means historical format v0.
-
-The sender folds the greatest matching `throughSeq` for the current Session id and format generation, so concurrent accepted requests cannot move the cursor backward and a watermark from another generation cannot authorize the current suffix. A resumed process rebuilds the cursor from the durable log. A fork ignores inherited watermarks that name another Session, and therefore uploads its own inherited prefix from sequence zero, in requests bounded by `maxBytes`, before advancing under the child id. The watermark event itself belongs to the next unsent suffix.
-
-Transport failures, non-2xx responses, and requests sent without extension fields after a serialization failure append no watermark. A crash after endpoint acceptance but before local persistence may resend an already accepted range; uncertainty produces duplicates, never a sequence gap. There is no independent upload store or truncation path; `maxBytes` bounds each request's field instead.
-
-## Exposure and receiver requirements
-
-The request headers expose the Harness application version, one anonymous Harness-home identity, and an optional Session identity. `dsh_plugin_packages` exposes active npm package names and versions. Unless a composition disables it, `dsh_session_log` may expose the Session working directory, system-prompt snapshots, user and Assistant content, embedded Assistant streams, failed-attempt output, tool arguments and results, compaction summaries, feedback, and plugin-owned events. Adapter API keys are not Session events and therefore do not enter the field. A gateway selected through `baseURL` receives the same values as the official endpoint.
-
-Receivers address extension fields by name, dispatch each field by its own `version`, preserve distinct package versions, and ignore JSON member ordering. A session-log receiver validates the contiguous sequence range before interpreting event types. An unrecognized canonical event without `ignorable: true` prevents lossless reconstruction. The base request remains usable without either the registry or a particular contribution; field absence means that contribution did not apply to that request. While a session-log backlog drains, `throughSeq` trails the Session's latest event, so a 2xx does not show that the receiver holds the current log.

package/references/official-docs/docs/deepseek-llm-api-wire-extensions.zh.md

@@ -1,162 +0,0 @@
-# DeepSeek 官方 LLM API 协议扩展
-
-[English](deepseek-llm-api-wire-extensions.md) | 中文
-
-本参考定义 [`@deepseek-ai/dsh-llm-deepseek`](../packages/llm/llm-deepseek/README.zh.md) 在 `deepseek-official` Messages 请求中发送的全部 DeepSeek Harness 专用 HTTP 标头与附加 JSON 字段。它不重新定义上游 DeepSeek API 自有字段。提供方无关的 LLM 接口与 `llm-pi-ai` 不实现这些扩展。
-
-适配器将这些扩展发送至已解析的 `baseURL`，包括已配置的网关。扩展位于 `messages`、系统提示词和工具 schema 之外，因此不会增加模型输入 token，也不会改变模型可见前缀。
-
-## 协议命名空间与版本
-
-| 位置 | 命名方式 | 示例 |
-|---|---|---|
-| HTTP 字段名 | 小写 kebab-case；HTTP 匹配仍不区分大小写 | `user-agent`, `x-deepseek-harness-session-id` |
-| DeepSeek 请求正文扩展字段 | 使用保留 `dsh_` 前缀的 snake case | `dsh_plugin_packages`, `dsh_session_log` |
-| DSH 持有的嵌套 JSON 成员 | Camel case | `afterSeq`, `throughSeq`, `sessionId` |
-| 带标签的值 | 使用 kebab-case 字符串；持久事件采用 `domain/action` | `session-log-deepseek/delivery-accepted` |
-
-每个正文扩展独立持有自身的 `version`。版本仅适用于包含该字段的对象；不同字段的版本之间不存在兼容或排序关系。JSON 成员顺序不属于协议。
-
-[`DeepSeekLlmApiExtensionRegistry`](../packages/llm/deepseek-llm-api-extensions/README.zh.md) 为每个顶层扩展名保留一个提供方。空名称、两端带空白的名称、重复注册以及与 DeepSeek 基础请求冲突的名称都会在 HTTP 分派前失败。
-
-## 请求标头
-
-| 标头 | 出现条件 | 值 |
-|---|---|---|
-| `user-agent` | 每个提供方 HTTP 请求，包括 Files API 操作 | 采用 `product/version (+url)` 形式的应用身份；默认产品为 `deepseek-harness` |
-| `x-deepseek-harness-user-id` | 每个已授权的模型请求 | 已解析 Harness home 的稳定匿名 UUID |
-| `x-deepseek-harness-session-id` | 携带会话 id 的模型请求 | 确切的请求 `sessionId` 字符串 |
-| `x-deepseek-harness-compact` | 用途为 `compaction` 的模型请求 | 字面字符串 `1` |
-
-凭据失败发生在解析匿名用户 id 之前，因此未授权请求既不会发送这些标头，也不会创建身份文件。没有会话的直接请求会省略 `x-deepseek-harness-session-id`。会话标题请求没有额外的用途标头；请求携带 `sessionId` 时，仍然适用普通的会话 id 规则。
-
-## 正文扩展事务
-
-适配器先序列化包括确切 `messages` 在内的完整基础正文，再让已注册提供方准备字段。提供方会收到该不可变正文、请求取消信号，以及可选的 `sessionId` 和辅助调用 `purpose`。提供方返回 `undefined` 时，本次请求会省略其字段。
-
-系统将已准备的 JSON 值与提供方持有的状态分离，再将其作为基础字段的顶层同级成员合并，并序列化到同一个 HTTP 正文中。某个贡献方准备失败时，系统在该次请求中省略其字段，且只记录首次失败，其余字段照常发送；与基础字段冲突的字段会阻止请求。合并后的正文无法序列化时，适配器发送不含任何扩展字段的基础正文，跳过接受事务，让贡献方在之后的请求中重发自身状态，并记录被省略的字段名。组合未挂载注册表时，适配器发送未经扩展的基础正文。
-
-已配置端点返回 HTTP 2xx 后，适配器会在读取 SSE 正文之前运行已准备的 `accept()` 事务。传输失败和非 2xx 响应不会接受任何贡献。接受失败会记录告警，但不会使模型请求失败；贡献方会在之后的请求中重发未被接受的状态。接受仅记录端点级 HTTP 成功，不表示 SSE 流已完整结束，也不表示端点已持久化扩展。
-
-## `dsh_plugin_packages`
-
-[`@deepseek-ai/dsh-plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek/README.zh.md) 贡献完整存活的 Loader-backed 插件包清单。该字段默认启用。
-
-```json
-{
-  "dsh_plugin_packages": {
-    "version": 1,
-    "packages": [
-      {
-        "name": "@deepseek-ai/dsh-example",
-        "version": "0.1.1-rc.2"
-      }
-    ]
-  }
-}
-```
-
-| 成员 | 类型 | 含义 |
-|---|---|---|
-| `version` | `1` | `dsh_plugin_packages` 的 schema 版本 |
-| `packages` | 数组 | 本次请求的完整存活集合 |
-| `packages[].name` | 字符串 | 来自所属 manifest（元数据清单）的确切非空 npm 包名 |
-| `packages[].version` | 可选字符串 | 来自同一 manifest 的确切非空白包版本；不可用时省略 |
-
-每个请求都会重新读取宿主树中的存活非分组 Loader 配置项；请求会话存在 standing agent-preset 树时，也会读取该树。相对与绝对模块使用距离自身最近的所属 manifest；裸包配置项使用激活自身的 Loader 解析基准。具名 manifest 的版本不是非空白字符串时，会贡献 `{ name }`，不受 `private` 影响。名称缺失或 manifest 不可读时，只省略对应配置项；包元数据不会阻塞请求。
-
-发送方会对确切 `(name, 可选 version)` 组合去重，并使用与 locale 无关的文本比较，先按 `name`、再按 `version` 排序，缺失版本排在前面。同一包的多个同时存活版本会保留为独立配置项，包括只有名称的配置项。接收方必须接受版本缺失，不得按包名折叠该数组，也不得根据数组顺序推断包的激活关系。
-
-该清单不包含已禁用、pending、failed、unloading、disposed 和结构性 Loader 配置项。普通依赖、没有具名所属包的松散模块、以编程方式挂载的子 fiber，以及内存动态插件也不在其中，因为它们没有权威的 Loader 包来源信息。
-
-清单已启用但没有符合条件的配置项时，系统发送 `packages: []`；禁用贡献插件时，系统省略整个 `dsh_plugin_packages` 字段。包身份属于提供方元数据，绝不进入模型输入。
-
-## `dsh_session_log`
-
-[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.zh.md) 贡献权威会话日志的一段连续后缀。该字段默认启用。它适用于携带存活会话且至少存在一个事件的请求；直接请求、陈旧会话 id 或空日志会省略该字段，第一条待发事件本身超过 `maxBytes` 或无法序列化的请求也会省略该字段；组合可用 `enabled: false` 禁用它。下方示例使用逻辑 Session 格式 2 仅为说明协议字段，并不标识[当前写入格式](session-format-status.zh.md)。
-
-```json
-{
-  "dsh_session_log": {
-    "version": 1,
-    "sessionFormatVersion": 2,
-    "session": {
-      "version": 2,
-      "id": "session-id",
-      "createdAt": 1780000000000
-    },
-    "afterSeq": -1,
-    "throughSeq": 0,
-    "events": [
-      {
-        "type": "turn/start",
-        "seq": 0,
-        "time": 1780000000001,
-        "data": {
-          "turn": 1
-        }
-      }
-    ]
-  }
-}
-```
-
-| 成员 | 类型 | 含义 |
-|---|---|---|
-| `version` | `1` | `dsh_session_log` 的 schema 版本 |
-| `sessionFormatVersion` | 非负整数 | 该后缀所表示的 Session 格式 generation |
-| `session` | 对象 | 当前 Session header 的不可变协议投影 |
-| `afterSeq` | 整数 | 本次请求前记录为已接受的最大序号，或 `-1` |
-| `throughSeq` | 非负整数 | 本次请求所表示的最大序号 |
-| `events` | 数组 | 从 `afterSeq + 1` 到 `throughSeq` 的连续事件 |
-
-首次上传使用 `afterSeq: -1`，此后每次上传都从同一会话 id 的最大已接受水位（watermark）之后开始。每次上传携带从该位置起、序列化后能放进 `maxBytes` 的最长连续事件段；`maxBytes` 默认 8 MiB，按 UTF-8 字节计算，包括 header 与数值字段，因此超过上限的积压会分多次已接受的请求传完。发送方为每次请求仅快照一次事件数组；快照后的追加内容属于后续请求。
-
-### Session 协议 header
-
-`session` 成员将逻辑 Session 元数据投影为原始 JSON 基元。seeded Session 以 `seedLength` 发送确切的 `Session.inheritedEventCount`；未 seeded 的 Session 省略该字段。逻辑 `isSeeded` 标志不出现在此协议中。外层 `dsh_session_log.version` 选择本扩展 schema，`session.version` 则选择逻辑 Session 格式。即使嵌入的逻辑格式同时变化，只要 Session header 投影变化，扩展 schema 也必须升版。
-
-| 成员 | 出现条件 | 含义 |
-|---|---|---|
-| `version` | 必需 | 来自 `Session.header` 的逻辑 Session 格式版本；见[格式状态](session-format-status.zh.md) |
-| `id` | 必需 | 确切的会话 id |
-| `createdAt` | 必需 | 非负安全整数 Unix epoch 毫秒数 |
-| `cwd` | 可选 | 创建会话时记录的绝对工作目录 |
-| `parentSession` | 可选 | fork 的父会话 id |
-| `seedLength` | 仅 seeded Session | 确切的继承事件数量；空的继承前缀使用零 |
-| `origin` | 可选 | subagent 子项使用的字面值 `subagent` |
-| `delegationDepth` | 可选 | 持久化的非负 subagent 委派深度 |
-| `agentPreset` | 可选 | 用于组合该会话的 agent preset id |
-
-### 权威事件信封
-
-每个 `events` 元素以原始 JSON 基元承载规范事件，不依赖任何其他请求字段。每个事件包含 `type`、数值型 `seq`、`time` 与 `data`，存在 `ignorable: true` 时保留该值。表层事件必须携带 `surfaceOp`；替换范围使用数值型 `startSeq` 与 `endSeq`，system、user 和 tool 事件还可携带数值型 `sourceEventSeqs`。assistant 的提供方元数据保留在内嵌流中。已知的仅日志事件省略表层元数据；恢复的未知可忽略记录保留不透明元数据，但不将其解释为表层操作。
-
-### 接受水位与至少一次交付
-
-端点返回 HTTP 2xx 后，该贡献会向同一会话追加以下权威事件：
-
-```json
-{
-  "type": "session-log-deepseek/delivery-accepted",
-  "seq": 8,
-  "time": 1780000000002,
-  "data": {
-    "sessionId": "session-id",
-    "sessionFormatVersion": 2,
-    "throughSeq": 7
-  }
-}
-```
-
-`delivery-accepted` 表示已配置端点为包含该字段的 LLM 请求返回 HTTP 2xx。它不表示 SSE 已完整结束，也不表示远端已经持久化。该事件的 `throughSeq` 必须标识一项更早的事件，`sessionId` 标识已发送后缀所属的 Session，`sessionFormatVersion` 则把水位绑定到该逻辑 generation。缺少该字段表示历史格式 v0。
-
-发送方只会为当前 Session id 与格式 generation 折叠最大的匹配 `throughSeq`，因此并发已接受请求无法使游标倒退，其他 generation 的水位也不能授权当前后缀。恢复后的进程会从持久日志重建游标。fork 会忽略命名其他 Session 的继承水位，因此从序号零开始、按 `maxBytes` 分多次请求上传自身的继承前缀，再以子会话 id 推进。水位事件自身属于下一段未发送后缀。
-
-传输失败、非 2xx 响应，以及序列化失败后不带扩展字段发出的请求，都不会追加水位。端点接受后、本地持久化前发生崩溃时，系统可能重新发送已接受范围；不确定性只会产生重复，绝不会产生序号缺口。系统没有独立上传存储或截断路径；`maxBytes` 负责限制每次请求的字段大小。
-
-## 暴露内容与接收方要求
-
-请求标头会暴露 Harness 应用版本、一个匿名 Harness-home 身份和可选的会话身份。`dsh_plugin_packages` 会暴露存活 npm 包的名称与版本。除非组合禁用该字段，`dsh_session_log` 可能暴露会话工作目录、系统提示词快照、用户与 Assistant 内容、嵌入式 Assistant stream、失败 attempt 输出、工具参数与结果、压缩摘要、反馈和插件持有的事件。适配器 API key 不是会话事件，因此不会进入该字段。通过 `baseURL` 选择的网关会收到与官方端点相同的值。
-
-接收方按名称定位扩展字段，按各字段自己的 `version` 分派，保留不同的包版本，并忽略 JSON 成员顺序。会话日志接收方必须先校验连续序号范围，再解释事件类型。遇到不带 `ignorable: true` 的未知权威事件时，接收方无法进行无损重建。即使缺少注册表或某项贡献，基础请求仍然可用；字段缺失表示该项贡献不适用于本次请求。会话日志积压补传期间，`throughSeq` 落后于会话的最新事件，因此 2xx 并不表示接收方已持有当前完整日志。

package/references/official-docs/docs/defensive-patterns/README.i18n.yaml

@@ -1,10 +0,0 @@
-# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/defensive-patterns/README.md
-/defensive-patterns:
-  en: 7229c49e920aa5b3
-  zh: 1dd52db6b4d84952
-/defensive-patterns/why-these-rules:
-  en: 7c012071b5af8c98
-  zh: 298aaba83625c7a0

package/references/official-docs/docs/defensive-patterns/README.md

@@ -1,25 +0,0 @@
-# Defensive patterns
-
-English | [中文](README.zh.md)
-
-Hard-won rules: each pattern in this directory is a requirement this repository enforces in review, stated as the rule and the defect it prevents. Every rule states what must hold, the condition a reviewer judges it by, its boundary and who approves an exception, and a correct and a wrong example. Read the page for the artifact you are about to change, before you change it.
-
-## Why these rules
-
-Five habits cover most of what follows, and each page is their application to one artifact:
-
-- **Make correctness explicit.** Write it into the structure — named call points, explicit lifecycles, explicit conditions and types — rather than compensating for it afterwards with timing.
-- **Keep one source of truth.** One read path for a piece of data, one home for a fact, one owner for shared state.
-- **Extend through the registered seam.** A new capability registers; an existing carrier stops taking new logic instead of growing a branch inside it.
-- **Keep the change face equal to the review face.** A change carries only the lines its stated behavior change needs, a migration moves code rather than rewriting it, and a performance-sensitive change carries its measurement.
-- **Require evidence.** A claim is falsifiable and recomputable — measured before and after, or checked by a gate — rather than kept in sync by hand.
-
-| Changing | Read |
-|---|---|
-| Package exports, package shape, build faces, dependency declarations | [package-surface.md](package-surface.md) |
-| Remote services, `@Remote` methods, API dispatch, business ownership at the API layer | [remote-and-api.md](remote-and-api.md) |
-| Client components, slots, stores, hooks, effects | [client-components.md](client-components.md) |
-| Session reads, retention, conversation nodes, renderers | [conversation-and-session.md](conversation-and-session.md) |
-| Timing, state representation, shared ownership, decentralization, refactors, migrations, performance evidence, disposal, callbacks, subprocesses | [general.md](general.md) |
-
-Type definitions and per-subsystem semantics live in [subsystems/](../subsystems/README.md); this directory carries the rules, and the semantics pages carry what the types mean. [dsh-code-review](../../.agents/skills/dsh-code-review/SKILL.md) reads this directory when judging a pull request, and Development routes through the same table from [AGENTS.md](../../AGENTS.md).

package/references/official-docs/docs/defensive-patterns/README.zh.md

@@ -1,27 +0,0 @@
-# 防御性模式
-
-[English](README.md) | 中文
-
-来之不易的规则：本目录中每条模式都是本仓库在评审中执行的**要求**，以「规则 + 它所防止的缺陷」的形式陈述。每条规则都写明：必须成立什么、评审据什么判定、边界在哪、例外由谁批准，以及一个正例与一个反例。动手修改某类制品之前，先读对应那一页。
-
-<a id="why-these-rules"></a>
-
-## 这些规则背后的思想
-
-下面五条习惯覆盖了绝大部分内容，每一页都是它们在某类制品上的落地：
-
-- **把正确性显式化。** 把它写进结构——具名调用点、显式生命周期、显式条件与类型——而不是事后用时序去补偿。
-- **只留一个真相。** 一份数据一条读取路径，一个事实一个正家，共享状态一个所有者。
-- **走注册面扩展。** 新能力靠注册接入；既有载体不再承接新逻辑，而不是在它内部长出分支。
-- **把改动面压成评审面。** 改动只包含其声明的行为变化所需的行；迁移是搬代码而不是重写；涉及性能的改动附带测量。
-- **要求可证伪、可复算。** 口径能被改动前后的实测或门禁证明/否证，而不是靠人肉同步。
-
-| 你在改什么 | 读哪篇 |
-|---|---|
-| 包导出面、包形态、构建面、依赖声明 | [package-surface.zh.md](package-surface.zh.md) |
-| 远程服务、`@Remote` 方法、API 分发、API 层的业务归属 | [remote-and-api.zh.md](remote-and-api.zh.md) |
-| 客户端组件、slots、store、hooks、effect | [client-components.zh.md](client-components.zh.md) |
-| Session 读取、持有、会话节点、renderer | [conversation-and-session.zh.md](conversation-and-session.zh.md) |
-| 时序、状态表示、共享归属、去中心化、重构、迁移、性能证据、清理、回调、子进程 | [general.zh.md](general.zh.md) |
-
-类型定义与各子系统语义见 [subsystems/](../subsystems/README.zh.md)；本目录承载**规则**，语义页承载**类型的含义**。[dsh-code-review](../../.agents/skills/dsh-code-review/SKILL.md) 在评审 pull request 时读本目录，日常修改经 [AGENTS.md](../../AGENTS.md) 路由到同一张表。

package/references/official-docs/docs/defensive-patterns/client-components.i18n.yaml

@@ -1,46 +0,0 @@
-# Bilingual-pair consistency record for client-components.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/defensive-patterns/client-components.md
-/client-component-rules:
-  en: a6e8a87976040c04
-  zh: 08b59ad3c14fe250
-/client-component-rules/state-arrives-through-injection:
-  en: 112232a703ce472d
-  zh: cf42bda22d8e4da4
-/client-component-rules/props-carry-data-and-callbacks-not-react-nodes:
-  en: 253f05568dd7e26f
-  zh: fa12565ff5afb8bd
-/client-component-rules/a-slot-registration-is-a-stable-function-component:
-  en: 784d3a4bba02f8a4
-  zh: 0ccfcc1a504b135c
-/client-component-rules/components-never-receive-a-cordis-context:
-  en: 8bb102b178615c03
-  zh: 93cb177a578a1373
-/client-component-rules/context-comes-from-the-current-scope:
-  en: 652ec94d13ee51c9
-  zh: b47c39e96c53cfac
-/client-component-rules/resource-consumers-go-through-useresource:
-  en: 6650c772df96f935
-  zh: 57fc0a564caf62a8
-/client-component-rules/store-usage-is-narrow-and-explicit:
-  en: 697b2e81a862e3bf
-  zh: 13cf31bef332a601
-/client-component-rules/identity-and-initial-state-are-deliberate:
-  en: a34c30b8f7c415d4
-  zh: cbd0c0cf0c0db57c
-/client-component-rules/uselayouteffect-is-not-a-default:
-  en: f53f17846a8a89b2
-  zh: 94d205c4d85f1de9
-/client-component-rules/effects-never-push-render-derived-data-to-a-parent:
-  en: 580441bd6cce9ee9
-  zh: a5f093d8e7dec2ee
-/client-component-rules/build-and-style-follow-their-owners:
-  en: 561df1e1709a004c
-  zh: 89ca6eb4533648b8
-/client-component-rules/a-key-states-what-it-identifies:
-  en: 1d6f9bdc2b267fef
-  zh: cf4d579ca877c422
-/client-component-rules/each-shared-layer-keeps-its-own-isolation-level:
-  en: 3faec81a6a7c9fdd
-  zh: aa512c089b5f9afc