fix(ui-trajectory): tighten conversation assembly contracts

docs/cookbook/adding-a-conversation-node.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-conversation-node.md
-adding-a-conversation-node.md: ea4ec73eb109af6b0e4c7cf50fc8692942c75dd4
-adding-a-conversation-node.zh.md: 4b9a8049e2f1d060ec4bc3334036559b989ea562
+adding-a-conversation-node.md: c1965dc8a3081eebb8c1026ac53d2f7b8964edb7
+adding-a-conversation-node.zh.md: 92445e1432369a4e42cc372b5d5869c3cdeada4a

docs/cookbook/adding-a-conversation-node.md

@@ -120,6 +120,7 @@ function viewData(state: ReviewState): ReviewChatData {
 
 const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
   kind: 'review-job',
+  target: 'chat',
   match: (event) => {
     if (event.type === 'review/start') {
       return { id: String(event.data.reviewId), role: 'start' }
@@ -161,8 +162,8 @@ const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
       value: viewData(context.state),
     }
   },
-  buildViewNode: (context, target) => {
-    if (target !== 'chat' || context.state === undefined) return null
+  buildViewNode: (context) => {
+    if (context.state === undefined) return null
     return {
       key: context.key,
       kind: 'review-job',
@@ -196,7 +197,7 @@ export function apply(ctx: ClientContext): void {
 
 `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`.
 
-`buildViewNode(context, target)` materializes the final target-specific Node. 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`.
+`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`.
 
 ## 3. Query an earlier business Context only at start
 

docs/cookbook/adding-a-conversation-node.zh.md

@@ -120,6 +120,7 @@ function viewData(state: ReviewState): ReviewChatData {
 
 const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
   kind: 'review-job',
+  target: 'chat',
   match: (event) => {
     if (event.type === 'review/start') {
       return { id: String(event.data.reviewId), role: 'start' }
@@ -161,8 +162,8 @@ const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
       value: viewData(context.state),
     }
   },
-  buildViewNode: (context, target) => {
-    if (target !== 'chat' || context.state === undefined) return null
+  buildViewNode: (context) => {
+    if (context.state === undefined) return null
     return {
       key: context.key,
       kind: 'review-job',
@@ -196,7 +197,7 @@ export function apply(ctx: ClientContext): void {
 
 `buildLocationData(context, scope)` 可以把 Definition 拥有的数据发布到引擎拥有的 Turn 或 Step 上。通过 declaration merging 为每个 key 指定精确 value 类型。同一 Location 内的另一个 Node 可以使用受限 slot hook（例如 `useTurnData(key)`）读取该值，无须取得 Session，也无须扫描 `snapshot.chat.nodes`。
 
-`buildViewNode(context, target)` 物化最终的目标专用 Node。把 `context.key` 保留为 React 侧身份，根据持久排序证据选择 `anchorSeq`，并且只返回 renderer 可以直接使用的数据。某个 target Node 一旦发布，就要继续返回同一个 key；需要暂时离开可见流时使用 `visibility: 'hidden'`，不要改为返回 `null` 撤回它。
+`target` 与 `buildViewNode(context)` 必须同时声明一项由 target 拥有的渲染贡献。把 `context.key` 保留为 React 侧身份，根据持久排序证据选择 `anchorSeq`，并且只返回 renderer 可以直接使用的数据。某个 target Node 一旦发布，就要继续返回同一个 key；需要暂时离开可见流时使用 `visibility: 'hidden'`，不要改为返回 `null` 撤回它。
 
 ## 3. 只在 start 时查询更早的业务 Context