better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/conversation.md

@@ -0,0 +1,258 @@
+# Conversation assembly
+
+English | [中文](conversation.zh.md)
+
+Conversation is the target-neutral assembly layer between a Client `SessionEventLikeEntry` window and browser views. [`ui-conversation`](../../packages/client/ui-conversation/README.md) owns the event and view registries, one identity-stable binding per `SessionBinding`, Turn/Step locations, incremental Context assembly, target sources, the shared shell, and input orchestration. Target packages such as [`ui-chat`](../../packages/client/ui-chat/README.md) and [`ui-trajectory`](../../packages/client/ui-trajectory/README.md) own their Definitions, final snapshots, and rendering.
+
+This page defines the data model and the extension path for a business-owned Conversation node. The [Web Client architecture](web-client.md) places the subsystem between Client models and Slots; the [Conversation Node assembly decision](../../.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md) owns its rationale.
+
+## Data model and ownership
+
+The Session Controller owns the contiguous loaded logical-event window. Each `SessionEventLikeEntry` is either `{ type: 'event', event: SessionEvent }` for one durable event or `{ type: 'transient', event: AssistantLiveChunkEvent }` for one Client-only `assistant/live-chunk` presentation. Both inner events expose `type`, `seq`, `time`, and `data`. `ui-conversation` passes these entries to the assembler without opening a second history stream. One `ConversationNodeAssembler` per Session applies every registered Definition and publishes an independent source for each registered view target.
+
+| Concept | Owner and purpose |
+|---|---|
+| Event Definition | A business package matches one durable or Client-only transient event at a time, correlates it by stable `(kind, id)`, folds deterministic State, and optionally materializes one target node. |
+| Context | The engine-owned ordered Matches and current State for one `(kind, id)`. A transient event occupies one update Match; update-only evidence may remain pending until pagination supplies its unique durable start. |
+| Location | The engine-owned Session, Turn, or Step coordinates derived from durable boundary events. Definitions may publish typed data onto one Turn or Step. |
+| View Definition | A target package creates one incremental builder per Session and owns the final snapshot type for that target. |
+| View | A Slot entry such as Chat or Trajectory reads only its target snapshot and renders target-owned nodes. |
+
+Chat and Trajectory may recognize the same durable event family, but each keeps its own Definition State and final node payload. Shared target-neutral machinery is limited to identity routing, ordered replay, Location data, predecessor dependencies, and publication cadence.
+
+## Target activation
+
+Each Session keeps a monotonic set of active targets. Creating or reading a target source does not activate it. The shell explicitly activates its persisted or newly selected View, while another consumer activates a target through its first source subscription. First activation creates that target's builder and calls `replace()` once from the current target-indexed Contexts. Later flushes call `apply()` for every active target, and unsubscription does not remove one.
+
+The shell owns View selection and resolves the registered preferred View or Chat fallback before rendering when a binding is created or selected as current, and after View-roster changes. The assembler receives only the resolved target id and does not select Chat or another default target. A third-party View participates through the same selection and activation operations.
+
+## Replayable event families
+
+Choose one stable business id before writing the Definition. Every event that contributes to the same Node must carry that id or derive it independently from its own payload; the client must never assign an update to “the latest unfinished” Context.
+
+For a review job, the event contract could be:
+
+| Event | Role | Required durable facts |
+|---|---|---|
+| `review/start` | unique start | `reviewId`, Turn/Step coordinates, title |
+| `review/progress` | update | the same `reviewId`, coordinates, replayable progress |
+| `review/end` | update | the same `reviewId`, coordinates, final summary |
+
+Use the producer-owned branded id type across the process boundary. Put the `SessionEventMap` merge and payload types on the producer's type-only export, then import that export for side effects from the client package. Each `(kind, id)` may have at most one start event. A single-event business can use the event's stable identity, such as `event.seq`, as its Definition-local id.
+
+Incremental events are supported. Prefer whole-value checkpoints when the producer can emit them cheaply, because they remain useful when the start is outside the loaded window. Each delta must carry the stable id and produce deterministic State when replayed in ascending log `seq`; it must not depend on live-only memory. If the current history window contains only updates, the assembler keeps a pending Context and builds no State until an older page supplies the start. If the product must render before the start is loaded, a terminal or checkpoint event must carry enough whole fallback state for the Definition to build that result directly; do not recover it by scanning unrelated events.
+
+Live Assistant deltas arrive as Client-only `assistant/live-chunk` updates. Reconnect baselines expand the active process-local compact stream into the same transient events, while durable `assistant/message` and `assistant/attempt` events embed complete compact streams for history replay. Transient events can only be updates; `start()` receives a standard `SessionEvent`. A Definition that consumes Assistant output handles live chunks and durable settlements in the same `match()` and `update()` methods, while unrelated Definitions return `null` without expanding a stream.
+
+## Definition and typed Chat payload
+
+The example keeps the producer declarations and client contribution in one block so the complete relationship is visible. In a package family, keep the branded id and `SessionEventMap` declaration with the event producer, and keep the Definition, Chat data merge, and renderer in the client plugin.
+
+```ts ignore-check
+import { createElement } from 'react'
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type {
+  ConversationLocation, ConversationNodeContext,
+  ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-chat/client'
+
+type ReviewId = Branded<'ReviewId'>
+
+interface ReviewStartData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly title: string
+}
+
+interface ReviewProgressData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly completed: number
+}
+
+interface ReviewEndData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly summary: string
+}
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * Opens one durable review job.
+     * @mode emit
+     * @param data - stable identity, location, and initial display state.
+     */
+    'review/start': ReviewStartData
+    /**
+     * Records replayable progress for one review job.
+     * @mode emit
+     * @param data - stable identity, location, and latest progress.
+     */
+    'review/progress': ReviewProgressData
+    /**
+     * Closes one review job with its final summary.
+     * @mode emit
+     * @param data - stable identity, location, and final display state.
+     */
+    'review/end': ReviewEndData
+  }
+}
+
+interface ReviewChatData {
+  readonly title: string
+  readonly completed: number
+  readonly status: 'running' | 'completed'
+  readonly summary?: string
+}
+
+declare module '@deepseek-ai/dsh-client-ui-chat/client' {
+  interface ChatNodeDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ConversationStepDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+interface ReviewState extends ReviewChatData {
+  readonly turn: number
+  readonly step: number
+}
+
+function locationOf(context: ConversationNodeContext): ConversationLocation {
+  return context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' }
+}
+
+function viewData(state: ReviewState): ReviewChatData {
+  return {
+    title: state.title,
+    completed: state.completed,
+    status: state.status,
+    ...state.summary === undefined ? {} : { summary: state.summary },
+  }
+}
+
+const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
+  kind: 'review-job',
+  target: 'chat',
+  match: (event) => {
+    if (event.type === 'review/start') {
+      return { id: String(event.data.reviewId), role: 'start' }
+    }
+    if (event.type === 'review/progress' || event.type === 'review/end') {
+      return { id: String(event.data.reviewId), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'review/start') throw new Error('review-job requires review/start')
+    return {
+      turn: match.event.data.turn,
+      step: match.event.data.step,
+      title: match.event.data.title,
+      completed: 0,
+      status: 'running',
+    }
+  },
+  update: (context, match) => {
+    if (match.event.type === 'review/progress') {
+      return { ...context.state, completed: match.event.data.completed }
+    }
+    if (match.event.type === 'review/end') {
+      return { ...context.state, completed: 100, status: 'completed', summary: match.event.data.summary }
+    }
+    return context.state
+  },
+  publication: match => match.event.type === 'review/progress'
+    ? 'animation-frame'
+    : 'immediate',
+  buildLocationData: (context, scope) => {
+    if (scope !== 'step' || context.state === undefined) return null
+    return {
+      kind: 'step',
+      turn: context.state.turn,
+      step: context.state.step,
+      key: 'review-job',
+      value: viewData(context.state),
+    }
+  },
+  buildViewNode: (context) => {
+    if (context.state === undefined) return null
+    return {
+      key: context.key,
+      kind: 'review-job',
+      id: context.id,
+      target: 'chat',
+      anchorSeq: context.start?.event.seq ?? context.matches[0]?.event.seq ?? 0,
+      location: locationOf(context),
+      visibility: 'visible',
+      data: viewData(context.state),
+    }
+  },
+}
+
+function ReviewNodeView({ node }: ChatNodeViewProps<'review-job'>) {
+  const text = node.data.summary ?? `${node.data.title}: ${node.data.completed}%`
+  return createElement('p', null, text)
+}
+
+export const inject = ['uiConversation', 'slots']
+
+export function apply(ctx: ClientContext): void {
+  ctx.uiConversation.events.register(reviewDefinition)
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'review-job',
+  }, ReviewNodeView))
+}
+```
+
+`match(event)` is an identity extractor, not a fold: it receives only the current `SessionEventLike` and returns the Definition-local id and lifecycle role. After a match, the assembler locates the Context by `(kind, id)` and calls `start` once for a standard event or `update` for a standard or packed event. Both functions return the State that the engine adopts; returning a new immutable value is preferred, but a function that mutates and returns the same object has the same adoption semantics.
+
+`buildLocationData(context, scope)` optionally publishes Definition-owned data onto an engine-owned Turn or Step. Use declaration merging to give each key a precise value type. Another Node in the same Location can consume that value through its constrained slot hook, such as `useTurnData(key)`, without receiving the Session or scanning `snapshot.chat.nodes`.
+
+`target` and `buildViewNode(context)` declare one target-owned rendering contribution and must appear together. Preserve `context.key` as the React-facing identity, choose `anchorSeq` from durable ordering evidence, and return only renderer-ready data. Once a target Node has been published, keep returning the same key; use `visibility: 'hidden'` when it must temporarily leave the visible flow rather than withdrawing it with `null`.
+
+## Predecessor reads
+
+Some Definitions need the latest earlier State of another business kind. `start` receives a `ConversationContextReader`; call `reader.previous<State>(kind)` there instead of accepting a Context collection or scanning events. The reader returns the nearest started Context before the current start `seq` as read-only data.
+
+The assembler records that dependency. If an older prepend later supplies a nearer predecessor, closes a previously unknown window gap, or revises the predecessor State, it reruns the dependent Context from `start` and replays its updates in ascending `seq`. The queried Definition remains responsible for writing useful State; the reader exposes no business-specific query methods and grants no mutation authority over another Context.
+
+## Window update paths
+
+History may be requested from the tail backward one page at a time. The Session journal validates non-overlapping logical sequence ranges first; the Assembler then orders accepted inputs by their first `seq` before State replay.
+
+| Path | Engine work | Definition-visible behavior |
+|---|---|---|
+| Replace on open, resync, or gap repair | Rebuild the loaded window, match every standard event or packed run once per Definition, then replay each started Context | `start`, followed by its updates in ascending logical `seq`; pending update-only Contexts remain without State |
+| Prepend one older page | Match only fresh older inputs, merge them into Contexts by `(kind, id)`, preserve existing keyed nodes, and replay only affected Contexts and dependencies | A newly found scalar start activates its collected scalar and packed updates; a changed Location or predecessor may rerun the Context |
+| Append one live event | Call each Definition's `match` once, look up the matched Context by key, and update only that Context | One scalar `update` and one requested publication for a matching post-start event; no existing Context scan |
+
+With `D` registered Definitions, one incoming scalar event or packed run performs `D` current-input matches and constant-time Context-key lookup after a match. Definition code must preserve that property: do not traverse the complete event window, every Context, `context.matches`, or the rendered Node collection on the normal append path. Use State for accumulated facts, Location data for same-Turn/Step sharing, and `reader.previous()` for indexed predecessor dependencies.
+
+`publication` controls when changed State is materialized. Use `immediate` for structural or terminal changes, `animation-frame` for high-frequency visible deltas, and `none` when the State change feeds only a later publication. The engine applies every scalar update in log order and every packed run in one batch update; cadence only coalesces view publication.
+
+## Verification obligations
+
+Add focused tests that establish these outcomes:
+
+1. A complete window passed through replace produces the expected final State, Location data, Node payload, and `anchorSeq`.
+2. An update-only tail stays pending; prepending the unique start produces the same result as a complete replace.
+3. Initial history followed by live append produces the same result as replaying the combined window.
+4. Prepending an older page adds earlier rows without replacing existing keyed Node values whose data did not change.
+5. Repeated visible deltas preserve `context.key` and publish at most once per animation frame when requested.
+6. The keyed renderer consumes `node.data` and constrained Location hooks only; it does not scan the Session event window, Contexts, or Chat Nodes.
+7. Scalar and packed Assistant history produce the same final State, timing boundaries, and target snapshot, while one packed run remains one Match through replace, prepend, Location replay, and registry rebuild.
+8. Creating a target source performs no builder work; explicit selection or the first subscription performs one complete replacement, later updates reach every active target, and repeated activation performs no replacement.
+
+Use [`packages/client/ui-chat/src/client/conversation-nodes/assistant.ts`](../../packages/client/ui-chat/src/client/conversation-nodes/assistant.ts) for streaming and interruption, [`inbox.ts`](../../packages/client/ui-chat/src/client/conversation-nodes/inbox.ts) plus [`message.ts`](../../packages/client/ui-chat/src/client/conversation-nodes/message.ts) for predecessor queries, and [`packages/client/ui-deliverables`](../../packages/client/ui-deliverables) for a Definition that publishes Turn data without creating its own Node.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/conversation.zh.md

@@ -0,0 +1,258 @@
+# Conversation 组装
+
+[English](conversation.md) | 中文
+
+Conversation 是 Client `SessionEventLikeEntry` window 与浏览器 view 之间的 target-neutral assembly 层。[`ui-conversation`](../../packages/client/ui-conversation/README.zh.md)拥有 event 与 view registry、每个 `SessionBinding` 对应的 identity-stable binding、Turn/Step Location、增量 Context assembly、target source、共享 shell 与输入编排。[`ui-chat`](../../packages/client/ui-chat/README.zh.md)和 [`ui-trajectory`](../../packages/client/ui-trajectory/README.zh.md)等 target 包拥有各自的 Definition、最终 snapshot 与渲染。
+
+本文定义数据模型与业务自有 Conversation node 的扩展路径。[Web Client 架构](web-client.zh.md)说明该子系统在 Client model 与 Slots 之间的位置；[Conversation Node 组装决策](../../.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md)记录其设计理由。
+
+## 数据模型与所有权
+
+Session Controller 拥有连续的已加载逻辑 event window。每个 `SessionEventLikeEntry` 要么是表示一个持久事件的 `{ type: 'event', event: SessionEvent }`，要么是表示一个 Client-only `assistant/live-chunk` 呈现的 `{ type: 'transient', event: AssistantLiveChunkEvent }`；两种内部 event 都公开 `type`、`seq`、`time` 与 `data`。`ui-conversation` 把这些 entry 直接交给 assembler，不另开 history stream。每个 Session 对应一个 `ConversationNodeAssembler`，它应用所有已注册 Definition，并为每个已注册 view target 发布独立 source。
+
+| 概念 | Owner 与用途 |
+|---|---|
+| Event Definition | 业务包一次匹配一个持久 event 或 Client-only 瞬态 event，以稳定 `(kind, id)` 关联输入、折叠确定性 State，并可选择 materialize 一个 target node。 |
+| Context | Engine 为一个 `(kind, id)` 拥有的有序 Match 与当前 State。一个瞬态 event 只占一个 update Match；只有 update 的证据可以保持 pending，直到分页补齐其唯一持久 start。 |
+| Location | Engine 根据持久 boundary event 推导的 Session、Turn 或 Step 坐标。Definition 可以向一个 Turn 或 Step 发布类型化数据。 |
+| View Definition | Target 包为每个 Session 创建一个增量 builder，并拥有该 target 的最终 snapshot 类型。 |
+| View | Chat 或 Trajectory 等 Slot entry 只读取自身 target snapshot，并渲染 target 自有 node。 |
+
+Chat 与 Trajectory 可以识别同一个持久 event family，但各自保留自己的 Definition State 与最终 node payload。共享的 target-neutral 机制只包括 identity routing、有序 replay、Location data、predecessor dependency 与 publication cadence。
+
+## Target 激活
+
+每个 Session 都保留单调增长的 active target 集合。创建或读取 target source 不会激活它。shell 会显式激活持久化选择或新选择的 View，其他消费者则通过 target source 的首个订阅激活 target。首次激活会创建该 target 的 builder，并从当前按 target 索引的 Context 调用一次 `replace()`。后续 flush 对每个 active target 调用 `apply()`，取消订阅不会移除 target。
+
+shell 拥有 View 选择，并在 binding 创建、被选为 current 或 View roster 变化时，于渲染前解析已注册的偏好 View 或 Chat fallback。assembler 只接收解析后的 target id，不自行选择 Chat 或其他默认 target。第三方 View 使用相同的选择与激活操作。
+
+## 可回放 event family
+
+编写 Definition 前先选定稳定的业务 id。构成同一个 Node 的每条事件都必须携带该 id，或只凭自身 payload 独立推导出该 id；Client 绝不能把 update 猜测为属于“最近一个未完成”的 Context。
+
+以一个 review job 为例，事件约定可以是：
+
+| 事件 | 角色 | 必须持久化的事实 |
+|---|---|---|
+| `review/start` | 唯一 start | `reviewId`、Turn/Step 坐标、标题 |
+| `review/progress` | update | 相同的 `reviewId`、坐标、可回放进度 |
+| `review/end` | update | 相同的 `reviewId`、坐标、最终摘要 |
+
+跨进程边界使用生产方拥有的 branded id 类型。把 `SessionEventMap` 合并和 payload 类型放在生产方的纯类型导出中，再由 Client 包通过仅类型副作用导入该导出。每个 `(kind, id)` 最多只能有一条 start 事件。单事件业务可以把事件自身的稳定身份（例如 `event.seq`）作为 Definition 内部 id。
+
+系统支持增量事件。如果生产方能以较低成本发出 whole-value checkpoint，应优先采用，因为 start 位于已加载窗口之外时它仍可直接使用。每条 delta 都必须携带稳定 id，并且按照日志 `seq` 升序回放时能够确定性地产生 State；它不能依赖只存在于实时内存中的状态。如果当前历史窗口只有 update，Assembler 会保留一个 pending Context，并在更早分页补齐 start 前不构造 State。如果产品必须在 start 尚未加载时渲染，terminal 或 checkpoint 事件就必须携带足够的完整 fallback 状态，让 Definition 能直接构造结果；不要通过扫描无关事件恢复它。
+
+实时 Assistant delta 作为 Client-only `assistant/live-chunk` update 到达。重连 baseline 会把活跃的进程内紧凑 stream 展开为相同的瞬态 event，持久 `assistant/message` 与 `assistant/attempt` event 则嵌入完整紧凑 stream 供历史回放。瞬态 event 只能充当 update；`start()` 只接收标准 `SessionEvent`。消费 Assistant 输出的 Definition 在同一组 `match()` 与 `update()` 方法里处理 live chunk 与持久 settlement，其他 Definition 直接返回 `null`，无需展开 stream。
+
+## Definition 与类型化 Chat payload
+
+为了完整展示关联关系，下面把生产方声明和 Client 贡献写在同一个代码块里。实际的包族中，branded id 与 `SessionEventMap` 声明留在事件生产方，Definition、Chat data 合并与 renderer 留在 Client 插件。
+
+```ts ignore-check
+import { createElement } from 'react'
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type {
+  ConversationLocation, ConversationNodeContext,
+  ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-chat/client'
+
+type ReviewId = Branded<'ReviewId'>
+
+interface ReviewStartData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly title: string
+}
+
+interface ReviewProgressData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly completed: number
+}
+
+interface ReviewEndData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly summary: string
+}
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * Opens one durable review job.
+     * @mode emit
+     * @param data - stable identity, location, and initial display state.
+     */
+    'review/start': ReviewStartData
+    /**
+     * Records replayable progress for one review job.
+     * @mode emit
+     * @param data - stable identity, location, and latest progress.
+     */
+    'review/progress': ReviewProgressData
+    /**
+     * Closes one review job with its final summary.
+     * @mode emit
+     * @param data - stable identity, location, and final display state.
+     */
+    'review/end': ReviewEndData
+  }
+}
+
+interface ReviewChatData {
+  readonly title: string
+  readonly completed: number
+  readonly status: 'running' | 'completed'
+  readonly summary?: string
+}
+
+declare module '@deepseek-ai/dsh-client-ui-chat/client' {
+  interface ChatNodeDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ConversationStepDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+interface ReviewState extends ReviewChatData {
+  readonly turn: number
+  readonly step: number
+}
+
+function locationOf(context: ConversationNodeContext): ConversationLocation {
+  return context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' }
+}
+
+function viewData(state: ReviewState): ReviewChatData {
+  return {
+    title: state.title,
+    completed: state.completed,
+    status: state.status,
+    ...state.summary === undefined ? {} : { summary: state.summary },
+  }
+}
+
+const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
+  kind: 'review-job',
+  target: 'chat',
+  match: (event) => {
+    if (event.type === 'review/start') {
+      return { id: String(event.data.reviewId), role: 'start' }
+    }
+    if (event.type === 'review/progress' || event.type === 'review/end') {
+      return { id: String(event.data.reviewId), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'review/start') throw new Error('review-job requires review/start')
+    return {
+      turn: match.event.data.turn,
+      step: match.event.data.step,
+      title: match.event.data.title,
+      completed: 0,
+      status: 'running',
+    }
+  },
+  update: (context, match) => {
+    if (match.event.type === 'review/progress') {
+      return { ...context.state, completed: match.event.data.completed }
+    }
+    if (match.event.type === 'review/end') {
+      return { ...context.state, completed: 100, status: 'completed', summary: match.event.data.summary }
+    }
+    return context.state
+  },
+  publication: match => match.event.type === 'review/progress'
+    ? 'animation-frame'
+    : 'immediate',
+  buildLocationData: (context, scope) => {
+    if (scope !== 'step' || context.state === undefined) return null
+    return {
+      kind: 'step',
+      turn: context.state.turn,
+      step: context.state.step,
+      key: 'review-job',
+      value: viewData(context.state),
+    }
+  },
+  buildViewNode: (context) => {
+    if (context.state === undefined) return null
+    return {
+      key: context.key,
+      kind: 'review-job',
+      id: context.id,
+      target: 'chat',
+      anchorSeq: context.start?.event.seq ?? context.matches[0]?.event.seq ?? 0,
+      location: locationOf(context),
+      visibility: 'visible',
+      data: viewData(context.state),
+    }
+  },
+}
+
+function ReviewNodeView({ node }: ChatNodeViewProps<'review-job'>) {
+  const text = node.data.summary ?? `${node.data.title}: ${node.data.completed}%`
+  return createElement('p', null, text)
+}
+
+export const inject = ['uiConversation', 'slots']
+
+export function apply(ctx: ClientContext): void {
+  ctx.uiConversation.events.register(reviewDefinition)
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'review-job',
+  }, ReviewNodeView))
+}
+```
+
+`match(event)` 是身份提取器，不是 fold：它只能收到当前 `SessionEventLike`，并返回 Definition 内部 id 与生命周期角色。命中后，Assembler 通过 `(kind, id)` 定位 Context；标准 event 可触发一次 `start`，标准或 packed event 可把当前 State 交给 `update`。两个函数都必须返回引擎随后采用的 State；推荐返回新的 immutable value，但函数原地修改后返回同一对象时，采用语义也相同。
+
+`buildLocationData(context, scope)` 可以把 Definition 拥有的数据发布到引擎拥有的 Turn 或 Step 上。通过 declaration merging 为每个 key 指定精确 value 类型。同一 Location 内的另一个 Node 可以使用受限 slot hook（例如 `useTurnData(key)`）读取该值，无须取得 Session，也无须扫描 `snapshot.chat.nodes`。
+
+`target` 与 `buildViewNode(context)` 必须同时声明一项由 target 拥有的渲染贡献。把 `context.key` 保留为 React 侧身份，根据持久排序证据选择 `anchorSeq`，并且只返回 renderer 可以直接使用的数据。某个 target Node 一旦发布，就要继续返回同一个 key；需要暂时离开可见流时使用 `visibility: 'hidden'`，不要改为返回 `null` 撤回它。
+
+## Predecessor read
+
+有些 Definition 需要另一个业务 kind 在当前位置之前的最新 State。`start` 会收到 `ConversationContextReader`；应在这里调用 `reader.previous<State>(kind)`，不要接收 Context 集合或扫描事件。Reader 返回当前 start `seq` 之前最近一个已启动 Context 的只读数据。
+
+Assembler 会记录这项依赖。如果后续 older prepend 带来了更近的前序 Context、补齐了原先未知的窗口缺口，或者前序 State 被修订，引擎会从 `start` 重新运行依赖方 Context，并按 `seq` 升序回放其 update。被查询的 Definition 仍负责把有用信息写入自身 State；Reader 不提供业务专用查询方法，也不授予修改其他 Context 的权限。
+
+## Window 更新路径
+
+历史可能从尾部开始一页一页向前请求。Session journal 先校验互不重叠的逻辑 seq range，Assembler 再按每个已接受 input 的首 `seq` 排序并进入 State 回放。
+
+| 路径 | 引擎工作 | Definition 可观察到的行为 |
+|---|---|---|
+| open、resync 或 gap repair 时 replace | 重建已加载窗口，每条标准 event 或 packed run 对每个 Definition 匹配一次，再回放每个已有 start 的 Context | 先执行 `start`，再按逻辑 `seq` 升序执行其 update；只有 update 的 pending Context 仍没有 State |
+| prepend 一页更早历史 | 只匹配新增的更早 input，按 `(kind, id)` 合并进 Context，保留现有 keyed node，并只重放受影响的 Context 与依赖 | 新发现的 scalar start 会激活已收集的 scalar 与 packed update；Location 或前序依赖变化也可能重跑 Context |
+| append 一条实时事件 | 每个 Definition 各调用一次 `match`，按 key 查找命中的 Context，只更新该 Context | 对 start 之后的匹配事件执行一次 scalar `update` 并请求一次发布；不扫描已有 Context |
+
+注册 `D` 个 Definition 时，一条新 scalar event 或 packed run 会进行 `D` 次仅当前 input 匹配；命中后的 Context key 查询是常数时间。Definition 代码必须维持这个性质：正常 append 热路径不得遍历完整事件窗口、所有 Context、`context.matches` 或已渲染 Node 集合。累计事实放进 State，同 Turn/Step 共享信息放进 Location data，有索引的前序依赖使用 `reader.previous()`。
+
+`publication` 控制发生 State 变更后何时物化。结构或 terminal 变化使用 `immediate`，高频可见 delta 使用 `animation-frame`，只为后续发布积累 State 时使用 `none`。引擎按日志顺序应用每条 scalar update，并用一次 batch update 应用一个 packed run；该选项只合并视图发布频率。
+
+## 验证要求
+
+添加聚焦测试，证明以下结果：
+
+1. 完整窗口通过 replace 后产生预期的最终 State、Location data、Node payload 与 `anchorSeq`。
+2. 只有 update 的尾部窗口保持 pending；prepend 唯一 start 后，结果与完整 replace 相同。
+3. 初始历史后继续实时 append，与回放合并后的完整窗口得到相同结果。
+4. prepend 更早分页只增加更早的行；数据未变化的既有 keyed Node value 不被替换。
+5. 重复的可见 delta 保持 `context.key`，并在请求 `animation-frame` 时每帧最多发布一次。
+6. keyed renderer 只消费 `node.data` 与受限 Location hook，不扫描 Session 事件窗口、Context 或 Chat Node。
+7. scalar 与 packed Assistant 历史产生相同的最终 State、timing boundary 和 target snapshot；一个 packed run 在 replace、prepend、Location replay 与 registry rebuild 中始终只保留一个 Match。
+8. 创建 target source 不执行 builder 工作；显式选择或首次订阅执行一次完整 replace，后续更新送达所有 active target，重复激活不会再次 replace。
+
+流式与中断处理可参考 [`packages/client/ui-chat/src/client/conversation-nodes/assistant.ts`](../../packages/client/ui-chat/src/client/conversation-nodes/assistant.ts)，前序查询可参考 [`inbox.ts`](../../packages/client/ui-chat/src/client/conversation-nodes/inbox.ts) 与 [`message.ts`](../../packages/client/ui-chat/src/client/conversation-nodes/message.ts)，只发布 Turn data 而不创建自有 Node 的例子见 [`packages/client/ui-deliverables`](../../packages/client/ui-deliverables)。