dsh-plugin-guide 0.3.41 → 0.4.0

package/references/official-docs/docs/cookbook/adding-a-remote-api.md

@@ -1,197 +0,0 @@
-# Cookbook: adding a Remote API
-
-English | [中文](adding-a-remote-api.zh.md)
-
-Adding or changing a `ctx.remote` endpoint takes the five steps on this page: declare the method, declare its failures, register it on the package, consume it on the Client, and test it. Decorator semantics, lookup resolution, the generation pipeline, and the `/api` route are the mechanism and belong to the [API Gateway reference](../api-gateway.md); this page gives the action for each step and the conventions it must satisfy. Why the programming interface looks like this is in the [Typert Remote method calls Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md), and why a failure is one `RemoteError` plus a code table is in the [failure vocabulary Agent Note](../../.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.md).
-
-## 1. Declare the API
-
-The owner is a Host-side Cordis service: extend `TypertRemoteService` so the service key and the wire namespace are bound together, then mark the exposed methods with `@Remote`. Mark the business method itself when its signature already satisfies the wire conventions; write a `remoteExport*` adapter only when the shape has to change (adding `signal`, reordering parameters, exporting another name), and let that adapter call the unrenamed business method. Lookup objects (`Agent`, `Session`) may only occupy top-level parameter positions, and a method that supports cooperative cancellation takes `signal: AbortSignal` as its final parameter.
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
-
-/** One stored note as a Client reads it. */
-export interface NoteRow {
-  readonly noteId: string
-  readonly title: string
-}
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    notesController: NotesController
-  }
-}
-
-export class NotesController extends TypertRemoteService {
-  constructor(ctx: Context) {
-    super(ctx, 'notesController', { namespace: 'notes' })
-  }
-
-  /**
-   * @param agent - lookup parameter the Gateway resolves from its wire identity.
-   * @param signal - carrier cancellation, always the final parameter.
-   * @returns the notes this Agent's session owns.
-   */
-  @Remote('list')
-  async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
-    return await this.list(agent, signal)
-  }
-
-  /** The in-process API the adapter above delegates to, unchanged by it. */
-  async list(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
-    signal.throwIfAborted()
-    return await Promise.resolve([{ noteId: `${agent.id}-1`, title: 'draft' }])
-  }
-}
-```
-
-## 2. Declare the failures
-
-A Remote failure is one class, `RemoteError`: merge the domain codes into `RemoteErrorDetailsMap` through declaration merging and `throw new RemoteError(code, message, details)` at the failure point. Do not build a family of domain error classes, and do not write an exit-mapping function; an exception unrelated to this endpoint is not pre-classified, because the Gateway folds it into `gateway/internal`. Write a `catch` only to classify an arbitrary provider exception as one domain code, and attach the original exception as `cause`.
-
-A code reads `<domain>/<reason>`, and its declaration has four placement rules:
-
-- One producer only: declare it in the producing package, next to the throw.
-- Several packages produce it: declare it in the lowest domain package both depend on (`session/not-found` in `core/session`, `workspace/not-found` in `dsh-workspace`).
-- The carrier codes `gateway/bad-request`, `gateway/cancelled`, and `gateway/internal` are declared in protocol, and the Gateway infrastructure codes in gateway — use them, never copy them.
-- A local failure that never crosses the wire stays out of the code table; express it with the caller's own type.
-
-```ts
-import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
-
-declare module '@deepseek-ai/dsh-typert-protocol' {
-  interface RemoteErrorDetailsMap {
-    /** No stored note carries that id. */
-    'note/not-found': { readonly noteId: string }
-    /** The store refused an otherwise valid write. */
-    'note/rejected': { readonly noteId: string }
-  }
-}
-
-declare const stored: ReadonlyMap<string, string>
-declare function persist(noteId: string, title: string): Promise<void>
-
-export async function rename(noteId: string, title: string): Promise<void> {
-  if (!stored.has(noteId)) {
-    throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
-  }
-  try {
-    await persist(noteId, title)
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error)
-    throw new RemoteError('note/rejected', message, { noteId }, { cause: error })
-  }
-}
-```
-
-## 3. Register it on the package
-
-`@Remote` must live in a Loader entry plugin package; when the owner is an abstract seam, the controller goes in the matching package under `packages/api/`. The manifest gains the two generated entries and the protocol peer dependency, while on the Client side the `@deepseek-ai/dsh-api-remotes` assembly mounts the contribution and re-exports the type vocabulary that consumers need. Which generated artifact each entry points at, and how the generation pipeline is ordered, are in the [API Gateway reference](../api-gateway.md).
-
-```json
-{
-  "exports": {
-    "./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
-    "./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
-  },
-  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:*" },
-  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:*" }
-}
-```
-
-Rerun `pnpm run build:lib` after changing a signature, the code table, the namespace, or an export name, because that is what hands the Client its new declarations and codecs; changing only an implementation body needs no regeneration.
-
-## 4. Consume it on the Client
-
-The calling plugin declares both `remote` and `remote.<namespace>` in its `inject`, and the call site writes `ctx.remote.<namespace>.<method>(...)` directly: no `Pick<ClientRemote, …>` narrowing, no hand-written method signature, no wire relay object. The result is a `RemoteResult<T>`, so branch on `if (!result.ok)` in place and discriminate by `code` rather than `instanceof` — a code branch narrows `details` on its own. An exception-flow site writes `throw result.error` (it is a real Error); whoever catches it uses `isRemoteFailure` to tell a Remote failure from a local defect and rethrows the defect. Do not write a defensive catch: a Remote call does not reject, and an assembly mistake should crash.
-
-Fixed Host facts come from `ctx.remote.$host`: `home` and `isLoopback` are plain reads with no subscription and no generation counter, and `home` is `undefined` until the first ready frame. Refresh after a reconnect through `ctx.on('connection/reset')` or a domain's own remote event. When the caller aborts a unary call, the outcome is `gateway/cancelled` on the error branch rather than a throw.
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
-import type {} from '@deepseek-ai/dsh-api-remotes/client'
-
-export const inject = ['remote', 'remote.notes']
-
-declare const ctx: Context
-
-/** Store-side read: the error branch is handled where the code is meaningful. */
-export async function noteTitles(): Promise<readonly string[]> {
-  const result = await ctx.remote.notes.list()
-  if (!result.ok) {
-    if (result.error.code === 'note/not-found') return []
-    throw result.error
-  }
-  return result.value.map(row => row.title)
-}
-
-/** Action-side: a Remote failure becomes copy; a local fault keeps crashing. */
-export async function renderTitles(): Promise<string> {
-  try {
-    return (await noteTitles()).join(', ')
-  } catch (error: unknown) {
-    if (!isRemoteFailure(error)) throw error
-    return `unavailable (${error.code})`
-  }
-}
-
-/** Fixed Host facts as plain reads. */
-export function hostLabel(): string {
-  const { home, isLoopback } = ctx.remote.$host
-  return home ?? (isLoopback ? 'local host' : 'remote host')
-}
-```
-
-## 5. Test it
-
-On the owner side, assert the code that was thrown: recover the failure with `remoteErrorOf` after catching, then compare `code` and the details fields you care about with `toMatchObject` — never deep-compare the error object with `toEqual`, and never assert `instanceof`.
-
-```ts
-import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
-import { expect, it } from 'vitest'
-
-declare function rename(noteId: string, title: string): Promise<void>
-
-it('refuses an unknown note before writing', async () => {
-  const failure = await rename('n-404', 'fresh title').catch((error: unknown) => error)
-
-  expect(remoteErrorOf(failure)).toMatchObject({
-    code: 'note/not-found',
-    details: { noteId: 'n-404' },
-  })
-})
-```
-
-A Client-side double returns real instances: take the `RemoteError` and `TestRemote` value imports from `@deepseek-ai/dsh-client-test-runtime`, because a value import from the `api-remotes` facade would load the unbuilt assembly chain. `TestRemote.$host` is a plain field a spec assigns directly.
-
-```ts ignore-check
-import { Context } from '@deepseek-ai/cordis'
-import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
-import { expect, it } from 'vitest'
-
-it('renders the failure code the Host reported', async () => {
-  const ctx = new Context()
-  const remote = new TestRemote(ctx, {
-    notes: {
-      list: () => Promise.resolve({
-        ok: false as const,
-        error: new RemoteError('note/not-found', 'no note "n-404"', { noteId: 'n-404' }),
-      }),
-    },
-  })
-  remote.$host = { home: '/home/fixture', isLoopback: true }
-
-  await expect(ctx.remote.notes.list()).resolves.toMatchObject({ error: { code: 'note/not-found' } })
-})
-```
-
-## Verify
-
-1. `pnpm run build:lib`: mandatory once a signature, the code table, the namespace, or an export name changed, because it produces the Client declarations and codecs.
-2. `pnpm run typecheck`: both the Host and the Client program, where a code merged into an unreachable package turns red.
-3. Run both sides' specs by name: `npx vitest run <owner spec> <client spec>`.
-4. Add a recorded-session snapshot when the endpoint reaches a product-visible surface, per the [testing policy](../testing.md).

package/references/official-docs/docs/cookbook/adding-a-remote-api.zh.md

@@ -1,197 +0,0 @@
-# 实操手册：新增一个 Remote API
-
-[English](adding-a-remote-api.md) | 中文
-
-新增或改动一个 `ctx.remote` 端点按本页五步走：声明方法、声明失败、在包上注册、在 Client 消费、写测试。decorator 语义、lookup 解析、生成管线与 `/api` 路由属于机制，由 [API Gateway 参考](../api-gateway.zh.md)负责；本页给的是每一步的动作与必须遵守的约定。为什么是这套编程面，见 [Typert Remote 方法调用 Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md)；为什么失败面是单个 `RemoteError` 加一张码表，见[失败词汇 Agent Note](../../.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.zh.md)。
-
-## 1. 声明 API
-
-owner 是一个 Host 侧 Cordis 服务：继承 `TypertRemoteService` 把 service 键与 wire namespace 一起绑定，再用 `@Remote` 标注对外暴露的方法。业务方法的签名若已符合 wire 约定就直接标注它本身；只有形态需要调整（补 `signal`、换参数顺序、换导出名）才写一个 `remoteExport*` adapter，由它调用不改名的业务方法。lookup 对象（`Agent`、`Session`）只能占顶层参数位，支持协作式取消的方法把 `signal: AbortSignal` 放在最后一位。
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
-
-/** One stored note as a Client reads it. */
-export interface NoteRow {
-  readonly noteId: string
-  readonly title: string
-}
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    notesController: NotesController
-  }
-}
-
-export class NotesController extends TypertRemoteService {
-  constructor(ctx: Context) {
-    super(ctx, 'notesController', { namespace: 'notes' })
-  }
-
-  /**
-   * @param agent - lookup parameter the Gateway resolves from its wire identity.
-   * @param signal - carrier cancellation, always the final parameter.
-   * @returns the notes this Agent's session owns.
-   */
-  @Remote('list')
-  async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
-    return await this.list(agent, signal)
-  }
-
-  /** The in-process API the adapter above delegates to, unchanged by it. */
-  async list(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
-    signal.throwIfAborted()
-    return await Promise.resolve([{ noteId: `${agent.id}-1`, title: 'draft' }])
-  }
-}
-```
-
-## 2. 声明失败
-
-Remote 失败只有一个类 `RemoteError`：域码经 declaration merging 进 `RemoteErrorDetailsMap`，失败点直接 `throw new RemoteError(code, message, details)`。不要建域异常类家族，也不要写出口映射函数；与本端点无关的异常不预先归类，Gateway 会兜底折成 `gateway/internal`。只有"把任意 provider 异常归为一个域码"这一种场景才写 `catch`，并把原始异常挂在 `cause` 上。
-
-码名是 `<域>/<理由>`，声明落点四条：
-
-- 只有一个生产者：声明落生产者包，紧挨抛出点。
-- 多个包共同生产：落双方共同依赖的最低层域包（`session/not-found` 在 `core/session`，`workspace/not-found` 在 `dsh-workspace`）。
-- 载体码 `gateway/bad-request`、`gateway/cancelled`、`gateway/internal` 已在 protocol 声明，Gateway 基础设施码已在 gateway 声明——直接用，不要复制。
-- 不上 wire 的本地失败不进码表，用调用方自己的类型表达。
-
-```ts
-import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
-
-declare module '@deepseek-ai/dsh-typert-protocol' {
-  interface RemoteErrorDetailsMap {
-    /** No stored note carries that id. */
-    'note/not-found': { readonly noteId: string }
-    /** The store refused an otherwise valid write. */
-    'note/rejected': { readonly noteId: string }
-  }
-}
-
-declare const stored: ReadonlyMap<string, string>
-declare function persist(noteId: string, title: string): Promise<void>
-
-export async function rename(noteId: string, title: string): Promise<void> {
-  if (!stored.has(noteId)) {
-    throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
-  }
-  try {
-    await persist(noteId, title)
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error)
-    throw new RemoteError('note/rejected', message, { noteId }, { cause: error })
-  }
-}
-```
-
-## 3. 在包上注册
-
-`@Remote` 必须落在一个 Loader entry 插件包里；owner 是抽象 seam 时把控制器放进 `packages/api/` 下的对应包。包清单要补两个生成入口与 protocol 的 peer 依赖，Client 侧则由 `@deepseek-ai/dsh-api-remotes` 的 assembly 挂载该贡献并按需转口类型词汇。两个入口分别指向哪个生成产物、生成管线如何排序，见 [API Gateway 参考](../api-gateway.zh.md)。
-
-```json
-{
-  "exports": {
-    "./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
-    "./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
-  },
-  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:*" },
-  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:*" }
-}
-```
-
-改动了签名、码表、namespace 或导出名之后重跑 `pnpm run build:lib`，Client 才拿得到新的声明与 codec；只改实现体不需要重新生成。
-
-## 4. 在 Client 消费
-
-调用插件在 `inject` 里同时声明 `remote` 与 `remote.<namespace>`，调用点直写 `ctx.remote.<namespace>.<method>(...)`：不要用 `Pick<ClientRemote, …>` 窄化、不要手写方法签名、不要造 wire 中转对象。结果是 `RemoteResult<T>`，就地 `if (!result.ok)` 分支，判 `code` 而不是 `instanceof`——code 分支会自动窄化 `details`。异常流的站点写 `throw result.error`（它是真 Error）；接住它的上层用 `isRemoteFailure` 区分 Remote 失败与本地缺陷，本地缺陷继续往上抛。不要写防御性 catch：Remote 调用不 reject，装配错误就该炸。
-
-Host 的固定事实读 `ctx.remote.$host`：`home` 与 `isLoopback` 是普通值读取，没有订阅也没有 generation 计数器，`home` 在第一帧 ready 之前是 `undefined`；重连后的刷新走 `ctx.on('connection/reset')` 或各域自己的 remote 事件。调用方 abort 掉一次一元调用时，结果落在错误分支上的 `gateway/cancelled`，而不是抛出。
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
-import type {} from '@deepseek-ai/dsh-api-remotes/client'
-
-export const inject = ['remote', 'remote.notes']
-
-declare const ctx: Context
-
-/** Store-side read: the error branch is handled where the code is meaningful. */
-export async function noteTitles(): Promise<readonly string[]> {
-  const result = await ctx.remote.notes.list()
-  if (!result.ok) {
-    if (result.error.code === 'note/not-found') return []
-    throw result.error
-  }
-  return result.value.map(row => row.title)
-}
-
-/** Action-side: a Remote failure becomes copy; a local fault keeps crashing. */
-export async function renderTitles(): Promise<string> {
-  try {
-    return (await noteTitles()).join(', ')
-  } catch (error: unknown) {
-    if (!isRemoteFailure(error)) throw error
-    return `unavailable (${error.code})`
-  }
-}
-
-/** Fixed Host facts as plain reads. */
-export function hostLabel(): string {
-  const { home, isLoopback } = ctx.remote.$host
-  return home ?? (isLoopback ? 'local host' : 'remote host')
-}
-```
-
-## 5. 测试
-
-owner 侧断言抛出的码：捕获后用 `remoteErrorOf` 取出失败，再用 `toMatchObject` 比对 `code` 与需要的 `details` 字段——不要用 `toEqual` 深比对错误对象，也不要断言 `instanceof`。
-
-```ts
-import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
-import { expect, it } from 'vitest'
-
-declare function rename(noteId: string, title: string): Promise<void>
-
-it('refuses an unknown note before writing', async () => {
-  const failure = await rename('n-404', 'fresh title').catch((error: unknown) => error)
-
-  expect(remoteErrorOf(failure)).toMatchObject({
-    code: 'note/not-found',
-    details: { noteId: 'n-404' },
-  })
-})
-```
-
-Client 侧的替身返回真实例：`RemoteError` 与 `TestRemote` 的值 import 一律取自 `@deepseek-ai/dsh-client-test-runtime`，因为从 `api-remotes` facade 值 import 会拉起尚未构建的装配链。`TestRemote.$host` 是普通字段，spec 直接赋值即可。
-
-```ts ignore-check
-import { Context } from '@deepseek-ai/cordis'
-import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
-import { expect, it } from 'vitest'
-
-it('renders the failure code the Host reported', async () => {
-  const ctx = new Context()
-  const remote = new TestRemote(ctx, {
-    notes: {
-      list: () => Promise.resolve({
-        ok: false as const,
-        error: new RemoteError('note/not-found', 'no note "n-404"', { noteId: 'n-404' }),
-      }),
-    },
-  })
-  remote.$host = { home: '/home/fixture', isLoopback: true }
-
-  await expect(ctx.remote.notes.list()).resolves.toMatchObject({ error: { code: 'note/not-found' } })
-})
-```
-
-## 验证
-
-1. `pnpm run build:lib`：签名、码表、namespace 或导出名变过就必须重跑，Client 声明与 codec 由它产出。
-2. `pnpm run typecheck`：Host 与 Client 两个 program 都过一遍，码表的 merge 落点错了会在这里红。
-3. 点名跑两侧 spec：`npx vitest run <owner spec> <client spec>`。
-4. 端点属于产品可见面时补一条录制会话快照，规则见[测试策略](../testing.zh.md)。

package/references/official-docs/docs/cookbook/adding-a-session-format-version.i18n.yaml

@@ -1,40 +0,0 @@
-# Bilingual-pair consistency record for adding-a-session-format-version.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/cookbook/adding-a-session-format-version.md
-/cookbook-adding-a-session-log-format-version:
-  en: 71132d61e41cb40b
-  zh: 0b56ed8893bf8d0a
-/cookbook-adding-a-session-log-format-version/summary:
-  en: 3dc6121d1fcef4f8
-  zh: 178bcf02b63c4fbf
-/cookbook-adding-a-session-log-format-version/table-of-contents:
-  en: 6977fff29f49e4a4
-  zh: 7ffb6f5490831dce
-/cookbook-adding-a-session-log-format-version/1-choose-the-version-and-release-base:
-  en: 3e763cfbe8cd11d5
-  zh: 2d4998217cbe8030
-/cookbook-adding-a-session-log-format-version/2-add-an-identity-edge:
-  en: 77c9c26d94fb33ca
-  zh: 313c54c45cfc7dbc
-/cookbook-adding-a-session-log-format-version/3-implement-per-artifact-stages-and-validation:
-  en: c8d879d5c9fb14ed
-  zh: ea19e54c808fea0b
-/cookbook-adding-a-session-log-format-version/4-update-current-version-consumers:
-  en: a285126945d02c12
-  zh: e039c77cf7866ad2
-/cookbook-adding-a-session-log-format-version/5-create-snapshot-successors:
-  en: 7f865673d550a949
-  zh: 8bde6a9ef29f382a
-/cookbook-adding-a-session-log-format-version/6-validate-the-integrated-result:
-  en: fb1c6d23599659c5
-  zh: b51e4ee8c0d1daeb
-/cookbook-adding-a-session-log-format-version/6-validate-the-integrated-result/developer-v4-corpus-trial:
-  en: f22ab2d7b089a6d2
-  zh: 0a47f543899f0161
-/cookbook-adding-a-session-log-format-version/6-validate-the-integrated-result/final-v3-event-vocabulary-before-v4-publication:
-  en: a6ed1788dc64efbe
-  zh: 9ca3382f92df986b
-/cookbook-adding-a-session-log-format-version/dev-note:
-  en: b75c8458928b72b9
-  zh: 003ba4e17b4b5269

package/references/official-docs/docs/cookbook/adding-a-session-format-version.md

@@ -1,153 +0,0 @@
-# Cookbook: adding a Session log format version
-
-English | [中文](adding-a-session-format-version.zh.md)
-
-## Summary
-
-Use this tutorial to introduce the next Session log format version without rewriting released data. Read the [version and release-status authority](../session-format-status.md) to identify the checkout writer and the latest released format. Let N denote that verified released format and N+1 the target; substitute numeric values for these placeholders in names and metadata. Start with a working contributor checkout and read the [package checklist](adding-a-package.md), [format library](../../packages/session/session-format/README.md), and [released-format decision](../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md).
-
-## Table of Contents
-
-- [1. Choose the version and release base](#choose-the-version)
-- [2. Add an identity edge](#add-an-identity-edge)
-- [3. Implement per-artifact stages and validation](#stages-and-validation)
-- [4. Update current-version consumers](#current-version-consumers)
-- [5. Create snapshot successors](#snapshot-successors)
-- [6. Validate the integrated result](#validate)
-- [Developer V4 corpus trial](#v4-corpus-trial)
-- [Dev Note](#dev-note)
-
-<a id="choose-the-version"></a>
-## 1. Choose the version and release base
-
-Bump the format only when an effective discriminator cannot prevent unsafe interpretation. A structural change to headers, event envelopes, event semantics, or reconstruction requires assessment under the [reader-compatibility rule](../../.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.md), not an automatic bump. Record safe same-version evolution through the [type-change procedure](reviewing-persistence-type-changes.md). Distinguish the Session format integer from package release versions, SQLite schema versions, projection-unit versions, and protocol-wrapper versions.
-
-Let N be the accepted or published version in [version/status](../session-format-status.md) when a bump is required. After accepted V4, that bump needs V5 even before V4 publication is recorded; reviewed same-version evolution does not require that step.
-
-Use a shared `release/*` integration base for N+1. The base change adds the writer, codec, catalog wiring, identity migration, and verification. Create each independent child branch from that base and target its PR at the release branch, not another independent child’s branch. Each child adds its structural transformation, validators, consumers, and tests to the same adjacent migration package. Do not allocate extra versions just to represent review order. Merge reviewed children into the release branch through PRs, then validate the combined result before release. Honor release-branch force-push and deletion protections; do not force-sync it.
-
-Released codecs preserve accepted interpretations. A current-version codec can admit explicitly discriminated variants while retaining historical readability; do not broaden an older codec to admit a current feature. The N→N+1 converter may receive fixes or support additional historical cases after N+1 ships if its output remains compatible with N+1. A fix affects subsequent conversions, not existing N+1 successors. Document changed mappings and continued support for existing output; apply the reader-compatibility rule to any new target representation.
-
-Same-version logs bypass adjacent migrations and can mix historical and newer record variants after resume. Each integer therefore identifies a family of supported representations, not one fixed schema. Owning readers must retain and distinguish those variants; the next outgoing migration must handle them. Do not add same-version migrations or rely on `restoreCurrent` alone for normalization: current-version JSONL reads using transformed validation bypass that hook. Use disposable, isolated Harness homes for interim integration formats; rerun changed adjacent conversions from unchanged historical input rather than rewriting a committed generation or using a real user's home.
-
-Before changing the writer, use the [archive command](../persistence-changes/historical-formats/README.md#maintenance) to preserve its complete persistence schema, then add the bilingual format reference under `docs/persistence-changes/historical-formats/vN.*`. Preserve all earlier records. The format coverage check requires every integer below the new writer to have its own document; the current generated catalog covers only the new writer.
-
-<a id="add-an-identity-edge"></a>
-## 2. Add an identity edge
-
-Follow the package checklist to create a library for N→N+1, not a mounted plugin. An identity body conversion is only an initial wiring scaffold. The [V2-to-V3 specification](../../packages/session/session-format-v2-to-v3/README.md#v2-to-v3-specification) is a fixed example of explicit transformations and preservation rules, not an edge to extend or treat as an identity conversion.
-
-Declare `dsh.sessionFormatMigration` with numeric `from: N` and `to: N+1`, an export path, and the exported migration, source codec, target codec, target-header validator, and target restorer. Reuse the source codec exported by the preceding edge package and depend on that package; do not copy or redefine a released codec. Export the target codec and validators from the new package. Add the edge as a direct dependency of the catalog and add the workspace’s TypeScript paths and project references.
-
-Set `SESSION_FORMAT_VERSION` in [core Session types](../../packages/core/session/src/types.ts) to N+1 alongside the new edge declarations, then generate the catalog. The command below generates only the declared chain; it does not implement a new version:
-
-```sh
-pnpm run gen-session-format-catalog
-```
-
-The [generator](../../scripts/gen-session-format-catalog.ts) requires exactly one adjacent package for every step from zero to the writer version, matching directory/package names, matching adjacent codec exports, and declared dependencies. It rejects gaps, duplicate or extra edges, unknown metadata members, and a catalog that does not share Session through peer plus development dependencies. Fix the declarations rather than hand-editing `generated.ts`. The catalog is build-static; plugin mounting must not determine historical readability.
-
-<a id="stages-and-validation"></a>
-## 3. Implement per-artifact stages and validation
-
-Use the [Stage interfaces](../../packages/session/session-format/src/types.ts), not a whole-artifact array-to-array migrator. An immutable `SessionFormatMigration` declaration supplies `migrateHeader`, `validateTargetHeader`, and `createStage`. Every call to `createStage` creates independent state for one source artifact. Keep counters, pending events, and reference maps there; never share a mutable stage across Sessions.
-
-Implement `transformEvent(event, context)`, `transformRun(run, context)`, and `finish(context)`. Emit synchronously through `context.emitEvent` or `context.emitRun`; a call can produce zero, one, or many outputs. Let a stage consume codec-owned compact runs directly, or iterate `run.expand()` without materializing an intermediate array. The caller owns scheduling, and the chain finishes upstream stages before downstream stages.
-
-Treat the inherited cut as a logical event count, not a physical row count. Expose `headerInheritedEventCount` only when it is known before EOF; `finish` returns the exact target cut. A preceding cardinality-changing edge can make that count unavailable at construction. Derive it from validated seed markers when required, and test seeded multi-hop restoration from each supported historical generation through N+1, not just direct N input. Never substitute zero for an unknown cut.
-
-Define the new edge's event admission and transformation rules explicitly. The [V2-to-V3 source audit](../../packages/session/session-format-v2-to-v3/README.md#source-audit) and [alpha V0→V1 rule](../../.agents/notes/implemented/architecture/2026-08-31-alpha-historical-unknown-event-refusal.md) own the policies of those released edges, not the new edge. Do not generalize either to every edge. A change to structure or event positions requires classifying source events, payload members, and references, and explicitly deciding whether opaque data can remain valid. [Equal-version retention](../../.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md) alone does not prove a structural transformation safe. Validate target semantics and give each newly accepted case a rejecting counterexample; never widen older edges to hide an unsupported transformation.
-
-Plugin records that `appendPluginRecord()` writes are ignorable events in the `plugin:` namespace, which experimental packages read back by type. Carry them forward under their names when the target format can represent them, and state in the edge README which records it drops otherwise; the [ignorable events decision](../../.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md) keeps them on a best-effort basis. Apply this policy even when a stored record has no declaration in the [experimental persistence catalog](../experimental-persistence-catalog.md).
-
-Use native writer output as the conversion oracle: replay the same recorded LLM messages, tool outputs, and other inputs through the old and target writers. Compare migrated old output with raw target output before any format-normalizing helper; mask only documented volatile fields. For V4, ordinary tool results become flat tool-role messages with ordinary content blocks. A theoretically permitted old structure alone does not justify a new core content type.
-
-Alpha converters may explicitly refuse historical cases without an implemented, evidenced mapping, including otherwise valid logs. Keep the source unchanged and publish no partial successor. Prefer real corpora and reproducible writers when extending support; inspect user corpora read-only and create sanitized regression fixtures.
-
-Document only the identifier and field mappings needed by the target format in the edge README, with a reason for each. Do not add namespaces to direct source kinds or ordinary metadata solely because they are extensible. Preserve opaque nested data. Alpha converters may refuse unexpected source fields that would acquire new target meanings rather than invent an interpretation.
-
-Maintain the new edge's README as its single complete transformation and admission catalog, following the [V2-to-V3 specification](../../packages/session/session-format-v2-to-v3/README.md#v2-to-v3-specification). Enumerate every converted header, event, message slot, and payload field; exact rename or collision rules; preserved ids, coordinates, references, and inherited cuts; external prerequisites; refusal and opaque-data policies; and unsupported or deferred behavior. Separate historical source conversion from native target admission, and state which codec, restorer, installed validator, and recovery policy performs each check. Record any validation that is deliberately narrower than the declared schema. Update this catalog in the same change as its code; a generated schema inventory or PR description does not replace it.
-
-Prove strict restoration through `sessionFormatCatalog.createRestore(header, { recovery: 'strict', validation: 'current' })`, feeding rows in order and calling `finish()`. This exercises physical decoding, the complete chain, and installed current Session validation. Production's recoverable/transformed policy is not a replacement for strict fixture and publication verification. Preserve documented historical validation exceptions rather than claiming stricter source validation than the edge actually performs.
-
-<a id="current-version-consumers"></a>
-## 4. Update current-version consumers
-
-Trace each current-version consumer, including Session creation/restoration, JSONL filename selection and publication, the catalog's current encoder/restorer, projection-cache generation identity, replay and snapshot normalization, [physical fixture-layout validation](../../scripts/session-fixture-layout.ts), and TypeScript/Python SDK recordings. Use the writer constant where a value means current; keep literal historical versions in released codecs and historical fixtures. Update current documentation and generated references through their owners.
-
-Do not bump unrelated versions automatically. A request wrapper's `sessionFormatVersion` identifies its embedded Session generation; its outer schema version has its own meaning. Projection-unit state versions likewise do not replace the cache's Session-generation identity.
-
-Verify both read and write paths. Header-only listing must not read bodies or publish. Historical read open may return the migrated in-memory artifact without writing; write open must verify and publish only the final current successor before append. The source path, bytes, and inode stay unchanged. A newer or invalid selected generation must not cause fallback to a predecessor. The [preparation decision](../../.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.md) owns publication timing.
-
-<a id="snapshot-successors"></a>
-## 5. Create snapshot successors
-
-Read [snapshot ownership](../../snapshots/AGENTS.md) and the [snapshot library](../../packages/test-support/session-snapshot/README.md). The [corpus policy](../../scripts/session-snapshot-corpus-policy.ts) keeps its declared baseline as replay input so upgrades exercise the adjacent chain; a writer bump does not require refreshing that corpus. Select the owning scenario when a current-generation successor is needed, keep each historical file, and use the target version’s canonical parent and child filenames. Never rename a predecessor to the target filename or change only its header.
-
-For unchanged replay input, use keyless refresh on the owner, then replay without write-back. These SDK commands use `text-turn` and the checkout's writer version. Implement and wire N+1 before using them to generate that version, and select the actual affected owner for a feature:
-
-```sh
-pnpm run test:snapshot:refresh snapshots/sdk/sdk.snapshot.ts -t text-turn
-pnpm run test:snapshot snapshots/sdk/sdk.snapshot.ts -t text-turn
-```
-
-Review the new generation, request sidecars, and protocol output together. Verify every predecessor remains byte-identical and that parent/child roles remain contiguous. Selection uses the numerically highest generation, so update shared references to the owner's selected parent. Do not use the packed-layout migrator as a version upgrader. If the model transcript must change, the scenario owner uses live recording under the [testing policy](../testing.md), with its required provider key.
-
-Keep cases older than the retained baseline explicit through `snapshot.yml`'s `sessionFormat.version` and supported `coverage` names; record and refresh leave pinned Session fixtures untouched. Update the [corpus policy](../../scripts/session-snapshot-corpus-policy.ts) for the current generation while retaining focused direct-edge, multi-hop, packed-row, retry/failure, and shipped-profile coverage. Check the corpus and both SDK projections; do not mass-refresh unrelated scenarios merely to silence a validation failure.
-
-<a id="validate"></a>
-## 6. Validate the integrated result
-
-Run from the repository root. These commands check catalog declarations, Stage composition, the released V2→V3 edge, and generation selection. They are a baseline; add focused coverage for the new edge:
-
-```sh
-pnpm run verify-session-format-catalog
-pnpm exec vitest run scripts/gen-session-format-catalog.spec.ts packages/session/session-format/tests packages/session/session-format-v2-to-v3/tests packages/session/session-format-catalog/tests
-pnpm run test:snapshot scripts/session-snapshot-corpus.corpus.ts
-```
-
-After implementing the new edge, add its actual test path to the focused Vitest run. Add the changed JSONL, replay, projection, and SDK tests selected by the actual diff, plus the built publication-Worker smoke when that path changes. Require successful strict migration, identity preservation for the skeleton, malformed and unknown-required-event refusal, deterministic repeated restores, independent concurrent stage state, seeded multi-hop cuts, unchanged predecessors, and no fallback. Report exact commands and failures, not an inferred full-suite result.
-
-Update the [owning Agent Note](../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md) rather than adding a redundant decision record. Keep the [release record](../session-format-status.md#updating-the-record) unchanged until publication; after publication, update it with verified release evidence. Audit related active notes for supersession; retain independent rationale and leave archived notes frozen. Update bilingual prose together, re-record each changed pair with the repository tool, then run documentation checks:
-
-```sh
-pnpm run verify-translation-pairing --write docs/cookbook/adding-a-session-format-version.md
-pnpm run test:docs
-pnpm run doc-sync
-pnpm run lint
-git diff --check
-```
-
-<a id="v4-corpus-trial"></a>
-### Developer V4 corpus trial
-
-Use the one-time [migration script](../../scripts/migrate-sessions-to-v4.ts) from an installed contributor checkout whose writer is V4. Stop DSH processes using the target root before starting so writer locks and changing child logs do not prevent migration. Run from the repository root:
-
-```sh
-pnpm run migrate:sessions-to-v4
-```
-
-The default root is `~/.dsh/sessions`. Use `--sessions-dir /path/to/sessions-copy` for another corpus, or `--help` for usage. Concurrent jobs default to the available CPU count capped at 16; `--jobs N` accepts any positive safe integer, including larger expert overrides, and `--jobs 1` runs serially. A bounded queue opens only that many Sessions at once, regardless of corpus size. Each historical Session goes through the normal locked, validated publication path to create a V4 successor beside its unchanged source files. Existing V4 Sessions are opened read-only; rerunning does not reconvert them. The script makes no model requests and does not change conversion or refusal rules.
-
-The terminal reports each Session's selected file, version, progress, outcome, and elapsed time. Individual errors do not stop later Sessions. The final summary lists every failure and the full diagnostic log under the system temporary directory; any failure returns a nonzero exit status. It also prints JSON and saves the same report as `summary.json` beside `migration.log`: counts by source version and outcome, grouped failure reasons, per-input diagnostics, runtime details, and both report paths. Known diagnostics expose event types, unexpected members, child-log involvement, and sequence numbers; unrecognized errors retain their messages without inferred causes. Include these reports when reporting a migration problem. Sessions converted during this run remain distinct from those already at V4.
-
-Concurrent conversion can invalidate a parent’s child evidence when the child publishes V4. Only that source-change error receives one sequential retry after all initial jobs finish; corruption, unsupported formats, and held locks are reported immediately. Completion lines keep the original input index and a separate completed count, so out-of-order results remain readable.
-
-<a id="final-v3-vocabulary"></a>
-### Final V3 event vocabulary before V4 publication
-
-While the published format remains V3 and the integration writer is V4, master can still add valid V3 event types. After each master integration and before the first V4 publication, compare the migration-owned `RELEASED_V3_EVENT_TYPES` with the latest V3-writer commit used by that refresh. Capture its full immutable id while the locally verified `origin/master` still writes V3:
-
-```sh
-V3_SOURCE_REF="$(git rev-parse --verify 'origin/master^{commit}')"
-pnpm run verify-v3-event-vocabulary --source-ref "$V3_SOURCE_REF"
-```
-
-The verifier reads only that local commit and requires exact event-name equality. It rejects missing V3 names, extra copied names, and a source writer other than V3. In particular, V4-only `developer/message` must not enter the frozen V3 set. Review each difference against the V3 payload, required conversions, target admission, and consumers; adding the name alone does not establish a complete migration. Add the corresponding migration regression before accepting a new source event.
-
-This command does not fetch or establish remote freshness. The release operator must verify that the selected commit is the latest V3 writer included in the integration; an old remote-tracking ref or passing result for an older pin is insufficient. Record the checked id with release validation. If master already writes V4, reuse the recorded final V3 commit rather than resolving current master. After V4 ships, keep the V3 vocabulary tied to that historical source; later V4 event additions do not update it. Regular static CI has no dependency on a mutable master ref.
-
-<a id="dev-note"></a>
-## Dev Note
-
-None.