viatris-exam-cli 1.8.1 → 1.9.0

package/README.md

@@ -102,7 +102,7 @@ viatris-exam products update-knowledge-tree "$PRODUCT_ID" \
 viatris-exam products delete-knowledge-tree "$PRODUCT_ID"
 ```
 
-产品主数据不属于业务知识树层级；详情查询使用产品主数据 ID，并兼容历史知识树根节点 ID。固定维度为 L1；知识树回写是完整替换操作，必须一次提交全部 15-500 个 L2/L3/L4 动态节点。整树删除会保留产品根和固定维度，但级联删除动态节点及文档并解绑题目，只能在明确要求时执行。
+产品主数据不属于业务知识树层级；详情、整树回写和整树删除均接受产品编码、产品主数据 ID 或历史知识树根节点 ID，推荐使用稳定的产品编码。固定维度为 L1；知识树回写是完整替换操作，必须一次提交全部 15-500 个 L2/L3/L4 动态节点。整树删除会保留产品根和固定维度，但级联删除动态节点及文档并解绑题目，只能在明确要求时执行。
 
 ### 知识节点与文档
 
@@ -118,6 +118,9 @@ viatris-exam knowledge documents list <node-id>
 viatris-exam knowledge documents create <node-id> --input document.json
 viatris-exam knowledge documents upsert <node-id> --input documents.json
 viatris-exam knowledge documents update <document-id> --input changes.json
+viatris-exam knowledge documents get <document-id>
+viatris-exam knowledge documents link <node-id> <document-id> --input reference.json
+viatris-exam knowledge documents unlink <node-id> <document-id>
 viatris-exam knowledge documents delete <document-id>
 ```
 
@@ -125,7 +128,9 @@ viatris-exam knowledge documents delete <document-id>
 
 `/knowledge` CRUD 响应中的 `level` 是物理存储层级（产品根为 1、固定维度为 2）；产品生成接口使用业务层级（产品隐藏、固定维度为 L1、动态节点为 L2-L4）。
 
-所有文档写入都会在请求发出前从 `title`、`url`、`summary` 中移除“小荷”“小荷医疗”和“小荷 AI 医生”及其空格变体。当前写接口只接受 `title` 和 `summary`，输入中的 `url` 会在净化后从出站载荷移除，但 URL 净化能力作为永久兼容规则保留。该规则覆盖文档创建、批量 upsert、单文档更新和整树回写中的嵌套文档；标题清洗后为空会直接返回校验错误。
+知识原文以产品级文档保存，L4 节点通过 `documentRefs` 引用文档，并可携带必须为原文逐字子串的 `markedExcerpts`。关联与解除关联只改变节点引用，不删除文档本体。
+
+所有文档写入都会在请求发出前从 `title`、`url`、`summary`、`content` 和 `markedExcerpts` 中移除“小荷”“小荷医疗”和“小荷 AI 医生”及其空格变体。新版写接口发送 `title`、`url`、`content` 和适用场景下的 `markedExcerpts`；兼容字段 `summary` 仍执行净化，但不再写入新版接口。该规则覆盖文档创建、批量 upsert、单文档更新、文档关联和整树回写；标题或原文清洗后为空会直接返回校验错误。
 
 ### 出题任务
 
@@ -137,7 +142,7 @@ viatris-exam gen-tasks submit "$TASK_ID" --input examples/generated-questions.js
 
 `externalRef` 是题目回写的幂等键。Agent 重试 POST 前应复用原值。
 
-产品全节点任务的 `dimension` 为 `all`。应按 `knowledgeContexts` 覆盖每个叶子节点，并在回写题目时携带对应 `knowledgeNodeId`。
+产品全节点任务的 `dimension` 为 `all`。应按 `knowledgeContexts` 覆盖每个叶子节点，并在回写题目时携带对应 `knowledgeNodeId`。上下文中的证据文档通过 `excerpts` 提供可用于出题的标记片段；未标记时该数组包含完整原文。
 
 ### 考试记录
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viatris-exam-cli",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Agent-friendly CLI for the Viatris exam OpenAPI",
   "type": "module",
   "bin": {

package/skills/viatris-exam-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: viatris-exam-cli
 description: Operate the Viatris exam OpenAPI through its agent-friendly CLI. Use for login, products, knowledge, generation tasks, exam records, scoring, exams, questions, or medical search.
-version: 1.8.1
+version: 1.9.0
 ---
 
 # Viatris Exam CLI
@@ -33,8 +33,9 @@ Use the installed CLI for every supported API operation. Do not call the HTTP en
 - Apply every returned generation rule. Product-scoped rules identify applicable product codes through `products`; global rules return an empty `products` array.
 - Prefer scoring rule V2 for generated questions and scoring results. Use stable point and deduction-rule IDs.
 - Treat product master records as outside business knowledge-tree levels. Fixed dimensions are business L1; generated nodes are L2-L4. Product detail lookup also accepts a historical knowledge-tree root ID.
-- Document writes automatically remove 小荷 source-brand labels, including 小荷医疗 and whitespace variants of 小荷 AI 医生, from title, URL, and summary. Never reintroduce these labels after CLI sanitization.
-- Current document write APIs accept only `title` and `summary`; the CLI drops an input `url` before sending. Keep URL sanitization in the permanent sanitizer for backward and future compatibility.
+- Store full evidence sources as product-level documents and attach them to L4 nodes through document references. Keep `markedExcerpts` as exact substrings of the referenced `content`.
+- Document writes automatically remove 小荷 source-brand labels, including 小荷医疗 and whitespace variants of 小荷 AI 医生, from title, URL, summary, content, and marked excerpts. Never reintroduce these labels after CLI sanitization.
+- Current document write APIs accept `title`, `url`, `content`, and `markedExcerpts` as applicable. The CLI retains summary sanitization for compatibility but drops an input `summary` from current outbound document payloads.
 - Treat knowledge-tree and recursive node deletion as destructive. Inspect the target first and perform them only when the user explicitly requests deletion.
 - Do not automatically retry POST, PUT, PATCH, or DELETE commands. Inspect the returned error and determine whether the server accepted the request.
 - Keep temporary payloads outside the repository unless they are requested deliverables.

package/skills/viatris-exam-cli/references/cli-reference.md

@@ -98,7 +98,7 @@ Get a product and its fixed L1 dimensions:
 viatris-exam products get "$PRODUCT_ID" --compact
 ```
 
-Use the product master `id`; historical knowledge-tree root IDs remain accepted for compatibility. The response also contains nullable `nameEn`, `genericName`, `indication`, `dosageForm`, and `remark`. Product master data is outside business levels L1-L4. Use each returned `fixedDimensions[].clientRef` as the parent reference for an L2 node. Each fixed dimension also returns `level: 1` and a display `codePrefix`.
+Product detail, full-tree update, and full-tree deletion accept a stable product code, product master ID, or historical knowledge-tree root ID. Prefer the product code. The response also contains nullable `nameEn`, `genericName`, `indication`, `dosageForm`, and `remark`. Product master data is outside business levels L1-L4. Use each returned `fixedDimensions[].clientRef` as the parent reference for an L2 node. Each fixed dimension also returns `level: 1` and a display `codePrefix`.
 
 Update verified optional medical master data:
 
@@ -126,6 +126,14 @@ Payload shape:
 
 ```json
 {
+  "documents": [
+    {
+      "clientRef": "doc.lipitor_pi",
+      "title": "立普妥说明书",
+      "url": "https://example.com/evidence/lipitor.pdf",
+      "content": "阿托伐他汀每日一次，给药剂量为10～80mg。"
+    }
+  ],
   "nodes": [
     {
       "clientRef": "disease.hypertension",
@@ -150,10 +158,12 @@ Payload shape:
       "dimensionCode": "disease",
       "name": "诊断阈值",
       "sortOrder": 1,
-      "documents": [
+      "documentRefs": [
         {
-          "title": "药品说明书",
-          "summary": "与该知识点直接对应的证据摘录"
+          "documentRef": "doc.lipitor_pi",
+          "markedExcerpts": [
+            "阿托伐他汀每日一次，给药剂量为10～80mg"
+          ]
         }
       ]
     }
@@ -161,7 +171,7 @@ Payload shape:
 }
 ```
 
-Submit the complete L2/L3/L4 node set, between 15 and 500 nodes. Every `clientRef` must be unique within the payload. L2 nodes use `dimension:<code>` as `parentClientRef`; L3/L4 nodes use their direct parent's `clientRef`. Every L4 node needs at least one document. A successful PUT replaces the previous dynamic nodes, so do not send a partial tree.
+Submit up to 200 product-level source documents and the complete L2/L3/L4 node set, between 15 and 500 nodes. Every document and node `clientRef` must be unique within its collection. L2 nodes use `dimension:<code>` as `parentClientRef`; L3/L4 nodes use their direct parent's `clientRef`. Only L4 nodes may use `documentRefs`, every L4 node needs at least one reference, and every marked excerpt must be an exact substring of the referenced document content. A successful PUT replaces the previous dynamic nodes, so do not send a partial tree.
 
 Delete all dynamic knowledge-tree content:
 
@@ -216,19 +226,25 @@ Manage documents:
 ```bash
 viatris-exam knowledge documents list "$NODE_ID"
 viatris-exam knowledge documents create "$NODE_ID" \
-  --json '{"title":"说明书","summary":"摘录"}'
+  --json '{"title":"说明书","url":"https://example.com/pi.pdf","content":"完整原文","markedExcerpts":["完整原文"]}'
 viatris-exam knowledge documents upsert "$NODE_ID" \
-  --json '{"items":[{"title":"说明书","summary":"更新后的摘录"}]}'
+  --json '{"items":[{"title":"说明书","content":"更新后的完整原文","markedExcerpts":["完整原文"]}]}'
 viatris-exam knowledge documents update "$DOCUMENT_ID" \
-  --json '{"summary":"更新后的摘要"}'
+  --json '{"content":"更新后的完整原文"}'
+viatris-exam knowledge documents get "$DOCUMENT_ID"
+viatris-exam knowledge documents link "$NODE_ID" "$DOCUMENT_ID" \
+  --json '{"markedExcerpts":["更新后的完整原文"]}'
+viatris-exam knowledge documents unlink "$NODE_ID" "$DOCUMENT_ID"
 viatris-exam knowledge documents delete "$DOCUMENT_ID"
 ```
 
-Create reuses a document with the same title under the node. Batch upsert accepts 1-20 items and updates `summary` for existing titles. A single-document update changes only supplied fields; send `summary: null` to clear the summary. Current write contracts accept only `title` and `summary`; if input contains `url`, the CLI drops it before sending. Read responses may still contain historical URL data. Inspect a document before an explicitly requested delete.
+Documents are product-level source records containing full `content`; nodes hold references to them. Create requires `title` and `content`, reuses a document with the same title, and attaches it to the node. Batch upsert accepts 1-20 items. For an existing title, omitted `content` keeps the stored source, omitted `markedExcerpts` keeps the reference marks, and an empty `markedExcerpts` array clears them. A single-document update changes only supplied `title`, `url`, or `content`; send `url: null` to clear the URL.
+
+`get` returns the full source and every referencing node. `link` attaches an existing document from the same product; its request body is optional. Supplying `markedExcerpts` replaces the existing marks, an empty array clears them, and omission preserves them. `unlink` deletes only the node reference. Inspect references before an explicitly requested document delete.
 
 ### Document Sanitization
 
-Before every document write, the CLI removes source-brand labels from `title`, `url`, and `summary`. This applies to document create, batch upsert, single-document update, and documents nested in `products update-knowledge-tree`. URL filtering remains a permanent compatibility rule even though the current API drops URL from write payloads.
+Before every document write, the CLI removes source-brand labels from `title`, `url`, `summary`, `content`, and `markedExcerpts`. This applies to document create, batch upsert, single-document update, node links, and product-level documents plus L4 references in `products update-knowledge-tree`. The compatibility `summary` field remains sanitized but is dropped from current outbound document payloads.
 
 Removed forms include:
 
@@ -236,7 +252,7 @@ Removed forms include:
 - `小荷医疗`, including whitespace between `小荷` and `医疗`
 - `小荷AI医生` with arbitrary whitespace, including `小荷 AI 医生`, `小荷 AI医生`, and `小荷AI 医生`
 
-Whitespace is normalized after removal, and leading or trailing title separators are removed. If a supplied title becomes empty, the CLI returns `validation_error` without sending the request.
+Whitespace is normalized after removal, and leading or trailing title separators are removed. If a supplied title, content, or marked excerpt becomes empty, the CLI returns `validation_error` without sending the request. When source content and excerpts are supplied together, the CLI also verifies every sanitized excerpt remains an exact substring of the sanitized content.
 
 List generation tasks:
 
@@ -255,7 +271,7 @@ Get one generation task:
 viatris-exam gen-tasks get "$TASK_ID" --compact
 ```
 
-For a leaf-node task, `knowledgeContext` is the mandatory target context. For a product-wide task, `dimension` is `all`, `knowledgeContext` is null, and `knowledgeContexts` contains every leaf context. Generate `questionsPerNode` questions for every listed context and follow all returned `rules`.
+For a leaf-node task, `knowledgeContext` is the mandatory target context. For a product-wide task, `dimension` is `all`, `knowledgeContext` is null, and `knowledgeContexts` contains every leaf context. Generate `questionsPerNode` questions for every listed context and follow all returned `rules`. Each context document exposes `excerpts`; these are the marked source substrings when marks exist, otherwise the array contains the full source content.
 
 Each rule has `scope` and `products`. For `scope: "product"`, `products` contains one or more applicable product codes. For `scope: "global"`, `products` is an empty array. Do not read the removed single-value `product` field.
 

package/src/command-handlers/knowledge.js

@@ -3,10 +3,11 @@ import {
   assertOptions,
   requiredId,
 } from "../args.js";
-import { readJsonInput } from "../input.js";
+import { readJsonInput, readOptionalJsonInput } from "../input.js";
 import {
   sanitizeDocumentBatchPayload,
   sanitizeDocumentPayload,
+  sanitizeDocumentReferencePayload,
 } from "../sanitizers/documents.js";
 
 async function jsonCommand(
@@ -27,6 +28,16 @@ function nodePath(positionals, label) {
   return requiredId(positionals, 3, label);
 }
 
+async function optionalJsonCommand(method, path, options, transform) {
+  assertOptions(options, ["input", "json"]);
+  const body = await readOptionalJsonInput(options);
+  return {
+    method,
+    path,
+    ...(body === undefined ? {} : { body: transform(body) }),
+  };
+}
+
 export async function resolveKnowledge(positionals, options) {
   const [resource, area, action] = positionals;
   if (resource !== "knowledge") return null;
@@ -135,6 +146,47 @@ export async function resolveKnowledge(positionals, options) {
     );
   }
 
+  if (area === "documents" && action === "get") {
+    assertNoExtraPositionals(positionals, 4);
+    assertOptions(options);
+    const id = nodePath(positionals, "knowledge document ID");
+    return {
+      method: "GET",
+      path: `/openapi/knowledge/documents/${id}`,
+    };
+  }
+
+  if (area === "documents" && action === "link") {
+    assertNoExtraPositionals(positionals, 5);
+    const nodeId = nodePath(positionals, "knowledge node ID");
+    const documentId = requiredId(
+      positionals,
+      4,
+      "knowledge document ID",
+    );
+    return optionalJsonCommand(
+      "PUT",
+      `/openapi/knowledge/nodes/${nodeId}/documents/${documentId}`,
+      options,
+      sanitizeDocumentReferencePayload,
+    );
+  }
+
+  if (area === "documents" && action === "unlink") {
+    assertNoExtraPositionals(positionals, 5);
+    assertOptions(options);
+    const nodeId = nodePath(positionals, "knowledge node ID");
+    const documentId = requiredId(
+      positionals,
+      4,
+      "knowledge document ID",
+    );
+    return {
+      method: "DELETE",
+      path: `/openapi/knowledge/nodes/${nodeId}/documents/${documentId}`,
+    };
+  }
+
   if (area === "documents" && action === "delete") {
     assertNoExtraPositionals(positionals, 4);
     assertOptions(options);

package/src/help.js

@@ -27,6 +27,9 @@ Commands:
   knowledge documents create <node-id> --input <file|->
   knowledge documents upsert <node-id> --input <file|->
   knowledge documents update <document-id> --input <file|->
+  knowledge documents get <document-id>
+  knowledge documents link <node-id> <document-id> [--input <file|->]
+  knowledge documents unlink <node-id> <document-id>
   knowledge documents delete <document-id>
   gen-tasks list [--status STATUS] [--limit N]
   gen-tasks get <task-id>

package/src/input.js

@@ -11,8 +11,7 @@ export function hasPipedInput() {
   return !process.stdin.isTTY;
 }
 
-export async function readJsonInput(options) {
-  const canReadStdin = hasPipedInput();
+async function readJsonSource(options, required) {
   if (options.input !== undefined && options.json !== undefined) {
     throw new CliError("usage_error", "Use only one of --input and --json.");
   }
@@ -25,10 +24,11 @@ export async function readJsonInput(options) {
   } else if (options.json !== undefined) {
     source = "--json";
     text = options.json;
-  } else if (canReadStdin) {
+  } else if (hasPipedInput()) {
     source = "stdin";
     text = await readStdin();
   } else {
+    if (!required) return undefined;
     throw new CliError(
       "usage_error",
       "JSON input is required. Use --input <file>, --input -, --json <value>, or stdin.",
@@ -36,6 +36,7 @@ export async function readJsonInput(options) {
   }
 
   if (!text.trim()) {
+    if (!required && source === "stdin") return undefined;
     throw new CliError("input_error", `JSON input from ${source} is empty.`);
   }
   try {
@@ -51,3 +52,11 @@ export async function readJsonInput(options) {
     );
   }
 }
+
+export async function readJsonInput(options) {
+  return readJsonSource(options, true);
+}
+
+export async function readOptionalJsonInput(options) {
+  return readJsonSource(options, false);
+}

package/src/metadata.js

@@ -1,7 +1,7 @@
 import { CREDENTIAL_FILE_DISPLAY } from "./credentials.js";
 import { DOCUMENT_SANITIZATION_POLICY } from "./sanitizers/documents.js";
 
-export const VERSION = "1.8.1";
+export const VERSION = "1.9.0";
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const DEFAULT_RETRIES = 2;
 
@@ -54,8 +54,8 @@ export const COMMANDS = Object.freeze([
     command: "products update-knowledge-tree <product-id>",
     method: "PUT",
     path: "/openapi/products/{id}/knowledge-tree",
-    input: "{nodes: [...]}",
-    summary: "Replace the product's dynamic L2/L3/L4 knowledge-tree nodes.",
+    input: "{documents?: [...], nodes: [...documentRefs]}",
+    summary: "Replace product documents and dynamic L2/L3/L4 nodes.",
   },
   {
     command: "products delete-knowledge-tree <product-id>",
@@ -122,8 +122,8 @@ export const COMMANDS = Object.freeze([
     command: "knowledge documents create <node-id>",
     method: "POST",
     path: "/openapi/knowledge/nodes/{id}/documents",
-    input: "{title, summary?}",
-    summary: "Idempotently create a document under a node.",
+    input: "{title, content, url?, markedExcerpts?}",
+    summary: "Create or reuse a product document and attach it to a node.",
   },
   {
     command: "knowledge documents upsert <node-id>",
@@ -136,9 +136,28 @@ export const COMMANDS = Object.freeze([
     command: "knowledge documents update <document-id>",
     method: "PUT",
     path: "/openapi/knowledge/documents/{id}",
-    input: "{title?, summary?}",
+    input: "{title?, url?, content?}",
     summary: "Update supplied fields on a knowledge document.",
   },
+  {
+    command: "knowledge documents get <document-id>",
+    method: "GET",
+    path: "/openapi/knowledge/documents/{id}",
+    summary: "Get document source content and all referencing nodes.",
+  },
+  {
+    command: "knowledge documents link <node-id> <document-id>",
+    method: "PUT",
+    path: "/openapi/knowledge/nodes/{id}/documents/{documentId}",
+    input: "{markedExcerpts?} (optional)",
+    summary: "Attach an existing product document or update its excerpts.",
+  },
+  {
+    command: "knowledge documents unlink <node-id> <document-id>",
+    method: "DELETE",
+    path: "/openapi/knowledge/nodes/{id}/documents/{documentId}",
+    summary: "Remove a node reference without deleting the document.",
+  },
   {
     command: "knowledge documents delete <document-id>",
     method: "DELETE",

package/src/sanitizers/documents.js

@@ -1,9 +1,9 @@
 import { CliError } from "../errors.js";
 
 export const DOCUMENT_SANITIZATION_POLICY = Object.freeze({
-  fields: ["title", "url", "summary"],
-  writableFields: ["title", "summary"],
-  droppedWriteFields: ["url"],
+  fields: ["title", "url", "summary", "content", "markedExcerpts"],
+  writableFields: ["title", "url", "content", "markedExcerpts"],
+  droppedWriteFields: ["summary"],
   removedLabels: [
     "小荷",
     "小荷医疗",
@@ -14,8 +14,10 @@ export const DOCUMENT_SANITIZATION_POLICY = Object.freeze({
     "knowledge documents create",
     "knowledge documents upsert",
     "knowledge documents update",
+    "knowledge documents link",
   ],
   emptyTitle: "validation_error",
+  emptyContent: "validation_error",
 });
 
 const PROHIBITED_LABEL = /小荷\s*(?:AI\s*医生|医疗)?/giu;
@@ -51,14 +53,57 @@ export function sanitizeDocument(document, location = "document") {
       );
     }
   }
-  for (const field of ["url", "summary"]) {
+  for (const field of ["url", "summary", "content"]) {
     if (typeof sanitized[field] === "string") {
       sanitized[field] = sanitizeText(sanitized[field]);
     }
   }
+  if (typeof sanitized.content === "string" && !sanitized.content) {
+    throw new CliError(
+      "validation_error",
+      `${location}.content is empty after prohibited source labels are removed.`,
+    );
+  }
+  if (Array.isArray(sanitized.markedExcerpts)) {
+    sanitized.markedExcerpts = sanitizeMarkedExcerpts(
+      sanitized.markedExcerpts,
+      `${location}.markedExcerpts`,
+    );
+    validateMarkedExcerpts(
+      sanitized.markedExcerpts,
+      sanitized.content,
+      `${location}.markedExcerpts`,
+    );
+  }
   return sanitized;
 }
 
+function sanitizeMarkedExcerpts(excerpts, location) {
+  return excerpts.map((excerpt, index) => {
+    if (typeof excerpt !== "string") return excerpt;
+    const sanitized = sanitizeText(excerpt);
+    if (!sanitized) {
+      throw new CliError(
+        "validation_error",
+        `${location}[${index}] is empty after prohibited source labels are removed.`,
+      );
+    }
+    return sanitized;
+  });
+}
+
+function validateMarkedExcerpts(excerpts, content, location) {
+  if (typeof content !== "string") return;
+  excerpts.forEach((excerpt, index) => {
+    if (typeof excerpt === "string" && !content.includes(excerpt)) {
+      throw new CliError(
+        "validation_error",
+        `${location}[${index}] must be an exact substring of the sanitized document content.`,
+      );
+    }
+  });
+}
+
 function prepareDocumentForWrite(document, location) {
   const sanitized = sanitizeDocument(document, location);
   if (
@@ -68,7 +113,7 @@ function prepareDocumentForWrite(document, location) {
   ) {
     return sanitized;
   }
-  const { url: _unsupportedUrl, ...writableDocument } = sanitized;
+  const { summary: _unsupportedSummary, ...writableDocument } = sanitized;
   return writableDocument;
 }
 
@@ -86,28 +131,92 @@ export function sanitizeDocumentBatchPayload(body) {
   };
 }
 
+export function sanitizeDocumentReferencePayload(
+  body,
+  location = "documentReference",
+) {
+  if (
+    body === null ||
+    Array.isArray(body) ||
+    typeof body !== "object"
+  ) {
+    return body;
+  }
+  return prepareDocumentForWrite(body, location);
+}
+
 export function sanitizeKnowledgeTreePayload(body) {
-  if (!Array.isArray(body.nodes)) return body;
+  const documents = Array.isArray(body.documents)
+    ? body.documents.map((document, documentIndex) =>
+        prepareDocumentForWrite(
+          document,
+          `documents[${documentIndex}]`,
+        ),
+      )
+    : body.documents;
+  const documentsByRef = new Map(
+    Array.isArray(documents)
+      ? documents
+          .filter(
+            (document) =>
+              document &&
+              typeof document === "object" &&
+              typeof document.clientRef === "string",
+          )
+          .map((document) => [document.clientRef, document])
+      : [],
+  );
+  const nodes = Array.isArray(body.nodes)
+    ? body.nodes.map((node, nodeIndex) => {
+        if (
+          node === null ||
+          Array.isArray(node) ||
+          typeof node !== "object"
+        ) {
+          return node;
+        }
+        const sanitizedNode = { ...node };
+        if (Array.isArray(node.documentRefs)) {
+          sanitizedNode.documentRefs = node.documentRefs.map(
+            (reference, referenceIndex) => {
+              const location =
+                `nodes[${nodeIndex}].documentRefs[${referenceIndex}]`;
+              const sanitizedReference =
+                sanitizeDocumentReferencePayload(reference, location);
+              const document = documentsByRef.get(
+                sanitizedReference?.documentRef,
+              );
+              if (
+                document &&
+                Array.isArray(sanitizedReference.markedExcerpts)
+              ) {
+                validateMarkedExcerpts(
+                  sanitizedReference.markedExcerpts,
+                  document.content,
+                  `${location}.markedExcerpts`,
+                );
+              }
+              return sanitizedReference;
+            },
+          );
+        }
+        // Keep sanitizing the legacy shape so no document write path can bypass
+        // the permanent source-label policy.
+        if (Array.isArray(node.documents)) {
+          sanitizedNode.documents = node.documents.map(
+            (document, documentIndex) =>
+              prepareDocumentForWrite(
+                document,
+                `nodes[${nodeIndex}].documents[${documentIndex}]`,
+              ),
+          );
+        }
+        return sanitizedNode;
+      })
+    : body.nodes;
   return {
     ...body,
-    nodes: body.nodes.map((node, nodeIndex) => {
-      if (
-        node === null ||
-        Array.isArray(node) ||
-        typeof node !== "object" ||
-        !Array.isArray(node.documents)
-      ) {
-        return node;
-      }
-      return {
-        ...node,
-        documents: node.documents.map((document, documentIndex) =>
-          prepareDocumentForWrite(
-            document,
-            `nodes[${nodeIndex}].documents[${documentIndex}]`,
-          ),
-        ),
-      };
-    }),
+    ...(body.documents !== undefined ? { documents } : {}),
+    ...(body.nodes !== undefined ? { nodes } : {}),
   };
 }