@allbluecn/web-app 0.18.2 → 0.19.0

package/src/server/serverFns/__tests__/update-bug-guard.test.ts

@@ -0,0 +1,325 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// updateBugFn × §5.3 写入门卫测试（Yjs 多人协作任务 22，结构对齐任务 21 的
+// update-story-guard.test）：
+// - 门卫在事务之前执行（T21 教训：网络 I/O 不进事务）
+// - patch 的 Y 属主面 = description content 镜像 + 6 字段 + reproduceSteps
+//   归一化 steps；门卫双写不互吞：forwarded → Y 属主面从直写数据与活动流剥离
+// - 纯 Y patch → web 侧零 mutation（不 bump updatedAt，防误判旁路写触发重
+//   种子化）；非 Y 字段（url/repoHints/firstOccurAt/lastOccurAt）照旧直写
+// - pass-through（无快照）→ 原行为零变化（全字段直写 + 活动记录 + updatedBy）
+// - C1 属主预检（项目成员资格）失败 → 短路，mutation 零发生
+// - S12：description 只在门卫面转发，UI 只读渲染不受影响（组件侧测试覆盖）
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@tanstack/react-start", () => {
+  const createServerFn = () => {
+    const capture: { validator?: unknown; handler?: unknown } = {};
+    const api = {
+      validator: (v: unknown) => {
+        capture.validator = v;
+        return api;
+      },
+      handler: (h: unknown) => {
+        capture.handler = h;
+        return async (args: { data: unknown }) => {
+          const v = capture.validator as { parse?: (d: unknown) => unknown } | undefined;
+          const data = v && v.parse ? v.parse(args.data) : args.data;
+          return (h as (p: { data: unknown }) => Promise<unknown>)({ data });
+        };
+      },
+    };
+    return api;
+  };
+  return { createServerFn };
+});
+vi.mock("@tanstack/react-start/server", () => ({ getRequest: () => ({}) }));
+
+const H = vi.hoisted(() => {
+  const fns = {
+    requireAuth: vi.fn(),
+    ensureBuiltinIndependentProject: vi.fn(),
+    resolveStoryScopeProjectId: vi.fn(),
+    isUserInTeam: vi.fn(),
+    withCollabGuard: vi.fn(),
+    bugFindUnique: vi.fn(),
+    bugUpdate: vi.fn(),
+    bugActivityCreate: vi.fn(),
+    labelFindMany: vi.fn(),
+    userFindUnique: vi.fn(),
+    memberFindUnique: vi.fn(),
+    projectFindUnique: vi.fn(),
+    collabDocumentUpdateMany: vi.fn(),
+    transaction: vi.fn(),
+  };
+  const prisma = {
+    bug: { findUnique: fns.bugFindUnique, update: fns.bugUpdate },
+    bugActivity: { create: fns.bugActivityCreate },
+    label: { findMany: fns.labelFindMany },
+    user: { findUnique: fns.userFindUnique },
+    projectMember: { findUnique: fns.memberFindUnique },
+    project: { findUnique: fns.projectFindUnique },
+    // R11 touch：纯非 Y 直写后同事务 touch 快照（无快照计 0）
+    collabDocument: { updateMany: fns.collabDocumentUpdateMany },
+    $transaction: fns.transaction,
+  };
+  return { fns, prisma };
+});
+const M = H.fns;
+const PRISMA = H.prisma;
+
+vi.mock("@allbluecn/database", () => ({ prisma: H.prisma, Prisma: {} }));
+vi.mock("@allbluecn/database/get-prisma", () => ({
+  getPrisma: async () => H.prisma,
+}));
+vi.mock("@/server/auth-helpers", () => ({ requireAuth: H.fns.requireAuth }));
+vi.mock("@/server/builtin-project", () => ({
+  ensureBuiltinIndependentProject: H.fns.ensureBuiltinIndependentProject,
+  resolveStoryScopeProjectId: H.fns.resolveStoryScopeProjectId,
+}));
+vi.mock("@/server/team-access", () => ({ isUserInTeam: H.fns.isUserInTeam }));
+vi.mock("@/server/collab/write-guard", () => ({
+  withCollabGuard: H.fns.withCollabGuard,
+  COLLAB_GUARD_TTL_MS: 3000,
+}));
+
+import { updateBugFn } from "../bug/bug-crud";
+import { BUG_LIST_SELECT } from "@/components/bug/types";
+
+const U = "u-1";
+const P = "pr-1";
+const BUG_ID = "bg-1";
+const DESC_JSON = JSON.stringify({ html: "<p>新描述</p>", markdown: "新描述" });
+const STEPS_JSON = {
+  steps: [
+    { order: 1, action: "步骤一", expected: "预期一" },
+    { order: 2, action: "步骤二" },
+  ],
+  expectedResult: "整体预期",
+};
+
+const userBrief = (id: string) => ({
+  id,
+  username: `user-${id}`,
+  email: `${id}@example.com`,
+  avatarConfig: null,
+  bgShape: null,
+  bgColor: null,
+});
+
+const bugRow = (over: Record<string, unknown> = {}) => ({
+  id: BUG_ID,
+  identifier: "PRJ-B1",
+  sequenceId: 1,
+  title: "旧标题",
+  description: null,
+  state: "open",
+  severity: "medium",
+  source: "manual",
+  env: null,
+  url: null,
+  totalCount: 1,
+  firstOccurAt: new Date("2026-01-01T12:00:00Z"),
+  lastOccurAt: new Date("2026-01-01T12:00:00Z"),
+  archived: false,
+  projectId: P,
+  storyId: null,
+  story: null,
+  assignee: null,
+  assigneeId: null,
+  createdBy: userBrief(U),
+  updatedBy: null,
+  labels: [],
+  createdAt: new Date("2026-01-01T12:00:00Z"),
+  updatedAt: new Date("2026-01-02T12:00:00Z"),
+  ...over,
+});
+
+/** $transaction(fn) 直接以 prisma 本身作为 tx 执行 */
+const txMock = async (fn: unknown) => {
+  if (Array.isArray(fn)) return Promise.all(fn);
+  return (fn as (tx: unknown) => Promise<unknown>)(PRISMA);
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  M.requireAuth.mockResolvedValue({ user: { id: U } });
+  M.isUserInTeam.mockResolvedValue(true);
+  M.bugFindUnique.mockResolvedValue(bugRow());
+  M.bugUpdate.mockResolvedValue(bugRow({ title: "新标题" }));
+  M.bugActivityCreate.mockImplementation(async (args: {
+    data: { action: string; field: string | null; oldValue?: string; newValue?: string };
+  }) => ({
+    id: `act-${Math.random().toString(36).slice(2, 8)}`,
+    action: args.data.action,
+    field: args.data.field,
+    oldValue: args.data.oldValue ?? null,
+    newValue: args.data.newValue ?? null,
+    isAI: false,
+    actorType: "user",
+    agentName: null,
+    createdAt: new Date("2026-02-01T12:00:00Z"),
+    user: userBrief(U),
+  }));
+  M.labelFindMany.mockResolvedValue([]);
+  M.userFindUnique.mockResolvedValue({ username: "user-u-2" });
+  M.memberFindUnique.mockResolvedValue({ status: "active" });
+  M.projectFindUnique.mockResolvedValue({ id: P, ownerId: "owner-1" });
+  M.collabDocumentUpdateMany.mockResolvedValue({ count: 1 });
+  M.transaction.mockImplementation(txMock);
+  // 缺省门卫：无快照 pass-through（非协同态零行为变化）
+  M.withCollabGuard.mockResolvedValue({ kind: "pass-through", reason: "no-snapshot" });
+});
+
+/** 忠实模拟真实门卫语义：快照命中 → 先执行属主预检 → 才返回 forwarded */
+function guardForwardsAfterAssert(): void {
+  M.withCollabGuard.mockImplementation(async (opts: { assertWriteAllowed?: () => Promise<void> }) => {
+    await opts.assertWriteAllowed?.();
+    return { kind: "forwarded" as const };
+  });
+}
+
+describe("updateBugFn × §5.3 写入门卫", () => {
+  it("门卫在事务之前执行（先于 existing 读取，T21 教训：网络 I/O 不进事务）", async () => {
+    await updateBugFn({
+      data: { bugId: BUG_ID, title: "新标题", description: DESC_JSON, state: "in_progress" },
+    });
+
+    expect(M.withCollabGuard).toHaveBeenCalledTimes(1);
+    expect(M.withCollabGuard).toHaveBeenCalledWith({
+      roomName: `entity:bug:${BUG_ID}`,
+      docId: BUG_ID,
+      actor: U,
+      patch: {
+        content: { html: "<p>新描述</p>", markdown: "新描述" },
+        fields: { title: "新标题", state: "in_progress" },
+      },
+      assertWriteAllowed: expect.any(Function),
+    });
+    const order = M.withCollabGuard.mock.invocationCallOrder[0]!;
+    const existingOrder = M.bugFindUnique.mock.invocationCallOrder[0]!;
+    expect(order).toBeLessThan(existingOrder);
+  });
+
+  it("patch.steps 面：reproduceSteps 归一化转发（order 剥离、expectedResult 不入 Y 面；无字段 patch 则无 fields 键）", async () => {
+    await updateBugFn({ data: { bugId: BUG_ID, reproduceSteps: STEPS_JSON } });
+
+    expect(M.withCollabGuard).toHaveBeenCalledWith(
+      expect.objectContaining({
+        patch: {
+          steps: [
+            { action: "步骤一", expected: "预期一" },
+            { action: "步骤二" },
+          ],
+        },
+      }),
+    );
+  });
+
+  it("pass-through（无快照）→ 非协同态零行为变化：全字段直写 + 活动记录 + updatedBy", async () => {
+    const res = await updateBugFn({
+      data: {
+        bugId: BUG_ID,
+        title: "新标题",
+        state: "fixed",
+        description: DESC_JSON,
+        env: "prod",
+        reproduceSteps: STEPS_JSON,
+      },
+    });
+
+    const args = M.bugUpdate.mock.calls[0]![0];
+    expect(args.where).toEqual({ id: BUG_ID });
+    expect(args.select).toEqual(BUG_LIST_SELECT);
+    expect(args.data).toMatchObject({
+      title: "新标题",
+      state: "fixed",
+      description: DESC_JSON,
+      env: "prod",
+      reproduceSteps: STEPS_JSON,
+    });
+    expect(args.data.updatedBy).toEqual({ connect: { id: U } });
+    expect(M.bugActivityCreate).toHaveBeenCalledTimes(3); // title/state/description
+    expect(res.activities).toHaveLength(3);
+  });
+
+  it("forwarded + 纯 Y patch（title/state）→ web 侧零 mutation：不 update、不写活动、不 bump updatedAt", async () => {
+    guardForwardsAfterAssert();
+    const res = await updateBugFn({ data: { bugId: BUG_ID, title: "新标题", state: "fixed" } });
+
+    expect(M.bugUpdate).not.toHaveBeenCalled();
+    expect(M.bugActivityCreate).not.toHaveBeenCalled();
+    // 响应回读 existing（door guard 已接管 Y 面）
+    expect(res.bug.title).toBe("旧标题");
+    expect(res.activities).toEqual([]);
+  });
+
+  it("forwarded → Y 属主面剥离；非 Y 字段（url/repoHints）照旧直写 + updatedBy", async () => {
+    guardForwardsAfterAssert();
+    await updateBugFn({
+      data: { bugId: BUG_ID, title: "新标题", env: "prod", url: "https://x", repoHints: "repo 线索" },
+    });
+
+    const args = M.bugUpdate.mock.calls[0]![0];
+    expect(args.data).toMatchObject({ url: "https://x", repoHints: "repo 线索" });
+    expect(args.data.title).toBeUndefined(); // Y 属主
+    expect(args.data.env).toBeUndefined(); // Y 属主
+    expect(args.data.updatedBy).toEqual({ connect: { id: U } });
+    // R11 touch：生效直写为纯非 Y patch → 同事务 touch 快照（防误判旁路写）
+    expect(M.collabDocumentUpdateMany).toHaveBeenCalledWith({
+      where: { roomName: `entity:bug:${BUG_ID}` },
+      data: { updatedAt: bugRow().updatedAt },
+    });
+  });
+
+  it("forwarded → 含 Y 属主面的降级直写不 touch（旁路反超语义，R11）", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "degraded", reason: "unreachable" });
+    await updateBugFn({ data: { bugId: BUG_ID, url: "https://x", state: "fixed" } });
+
+    const args = M.bugUpdate.mock.calls[0]![0];
+    expect(args.data.state).toBe("fixed"); // Y 属主直写（旁路）
+    expect(M.collabDocumentUpdateMany).not.toHaveBeenCalled();
+  });
+
+  it("forwarded + 仅 Y 面（description/reproduceSteps）→ 零 mutation，description 回显请求值", async () => {
+    guardForwardsAfterAssert();
+    M.bugFindUnique.mockResolvedValue(bugRow({ reproduceSteps: STEPS_JSON }));
+    const res = await updateBugFn({
+      data: { bugId: BUG_ID, description: DESC_JSON, reproduceSteps: STEPS_JSON },
+    });
+
+    // description 与 reproduceSteps 同属 Y 面（steps 列表归 Y），剥离后无非 Y
+    // 写入 → 零 mutation（不 update 不 bump updatedAt——防误判旁路写触发重种子化）
+    expect(M.bugUpdate).not.toHaveBeenCalled();
+    expect(M.bugActivityCreate).not.toHaveBeenCalled();
+    expect(res.bug.description).toBe(DESC_JSON);
+  });
+
+  it("C1 属主预检失败（非项目成员）→ 短路抛错，mutation 零发生", async () => {
+    guardForwardsAfterAssert();
+    M.memberFindUnique.mockResolvedValue({ status: "suspended" });
+
+    await expect(
+      updateBugFn({ data: { bugId: BUG_ID, title: "越权改" } }),
+    ).rejects.toThrow("无权限操作该项目的 BUG");
+    expect(M.bugUpdate).not.toHaveBeenCalled();
+    expect(M.bugActivityCreate).not.toHaveBeenCalled();
+  });
+
+  it("degraded（collab 不可达）→ 同原行为直写（信任重种子化兜底）", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "degraded", reason: "unreachable" });
+    await updateBugFn({ data: { bugId: BUG_ID, title: "降级直写" } });
+
+    const args = M.bugUpdate.mock.calls[0]![0];
+    expect(args.data).toMatchObject({ title: "降级直写" });
+    expect(args.data.updatedBy).toEqual({ connect: { id: U } });
+  });
+});

package/src/server/serverFns/__tests__/update-document-guard.test.ts

@@ -0,0 +1,285 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// updateDocumentFn × 写入门卫测试（Yjs 多人协作 §5.3，任务 17）：
+// 门卫裁决三态在 serverFn 侧的落点——
+// - pass-through / degraded → 原行为（content 随直写落库 + 索引 + 审计）
+// - forwarded → 直写数据剥离 content（防互吞），元数据照旧直写（属主校验
+//   合并在 updateManyAndReturn）；content-only patch 走只读属主探针；
+//   索引交由 collab 侧单源触发，web 不重复；content 回显请求值
+// - 双写不互吞的 web 侧钉子：forwarded + title patch → title 进直写数据、
+//   content 不进（与 collab 侧集成测试「title 列在 content 回写中保持」组合
+//   论证非协同改标题 + 协同改正文共存）
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@tanstack/react-start", () => ({
+  createServerFn: (_config: unknown) => {
+    const api: any = {
+      _validator: undefined,
+      validator(schema: any) {
+        this._validator = schema;
+        return this;
+      },
+      handler(fn: Function) {
+        return async (args: any) => {
+          let data = args?.data;
+          if (this._validator && data !== undefined) {
+            data = this._validator.parse(data);
+          }
+          return fn({ data });
+        };
+      },
+    };
+    return api;
+  },
+}));
+vi.mock("@tanstack/react-start/server", () => ({ getRequest: () => ({}) }));
+
+const M = vi.hoisted(() => {
+  const f = () => vi.fn();
+  return {
+    requireAuth: f(),
+    requirePermission: f(),
+    auditLog: f(),
+    indexDocumentById: f(),
+    withCollabGuard: f(),
+    knowledgeDocument: {
+      findFirst: f(),
+      findUnique: f(),
+      update: f(),
+      updateMany: f(),
+      updateManyAndReturn: f(),
+    },
+    collabDocument: { findUnique: f(), deleteMany: f(), updateMany: f() },
+    transaction: f(),
+  };
+});
+
+vi.mock("@allbluecn/database/get-prisma", () => ({
+  getPrisma: async () => (await import("@allbluecn/database")).prisma,
+}));
+vi.mock("@allbluecn/database", () => ({
+  prisma: {
+    knowledgeDocument: M.knowledgeDocument,
+    collabDocument: M.collabDocument,
+    // R11：生效写入与快照 touch 同事务（tx 即 prisma 本形）
+    $transaction: M.transaction,
+  },
+}));
+vi.mock("@/server/auth-helpers", () => ({ requireAuth: M.requireAuth }));
+vi.mock("@/server/permissions", () => ({ requirePermission: M.requirePermission }));
+vi.mock("@/server/audit", () => ({ auditLog: M.auditLog }));
+vi.mock("@/server/knowledge/knowledge-index-utils", () => ({
+  indexDocumentById: M.indexDocumentById,
+  resolveAiConfig: vi.fn(),
+  KB_EMBEDDINGS_TABLE: "knowledge_embeddings",
+}));
+vi.mock("@/server/ai-gateway/embedding", () => ({ generateEmbedding: vi.fn() }));
+vi.mock("@/server/ai-gateway/rerank", () => ({
+  rerankCandidates: vi.fn(),
+  RECALL_MULTIPLIER: 4,
+}));
+vi.mock("@/lib/vector-store", () => ({ getVectorStore: vi.fn() }));
+vi.mock("@/server/collab/write-guard", () => ({
+  withCollabGuard: M.withCollabGuard,
+  COLLAB_GUARD_TTL_MS: 3000,
+}));
+
+import { updateDocumentFn } from "../knowledge";
+
+const USER = "u-owner";
+const NOW = new Date("2026-10-07T00:00:00Z");
+const ROW_SELECT = {
+  id: true,
+  title: true,
+  content: true,
+  icon: true,
+  tags: true,
+  properties: true,
+  updatedAt: true,
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  M.requireAuth.mockResolvedValue({ user: { id: USER } });
+  M.requirePermission.mockResolvedValue(undefined);
+  M.auditLog.mockResolvedValue(undefined);
+  M.indexDocumentById.mockResolvedValue({ indexed: 1 });
+  M.collabDocument.updateMany.mockResolvedValue({ count: 1 });
+  M.transaction.mockImplementation(
+    async (fn: (tx: {
+      knowledgeDocument: typeof M.knowledgeDocument;
+      collabDocument: typeof M.collabDocument;
+    }) => unknown) =>
+      fn({ knowledgeDocument: M.knowledgeDocument, collabDocument: M.collabDocument }),
+  );
+});
+
+describe("updateDocumentFn × §5.3 写入门卫", () => {
+  it("pass-through（无快照）→ 原行为：content 随直写落库 + 索引 + 审计", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "pass-through", reason: "no-snapshot" });
+    const updated = { id: "doc-1", title: "t", content: { html: "<p>新</p>" }, icon: null, tags: [], properties: {}, updatedAt: NOW };
+    M.knowledgeDocument.updateManyAndReturn.mockResolvedValue([updated]);
+
+    const res = await updateDocumentFn({ data: { id: "doc-1", title: "t", content: { html: "<p>新</p>" } } });
+
+    expect(M.withCollabGuard).toHaveBeenCalledWith({
+      roomName: "doc:knowledge:doc-1",
+      docId: "doc-1",
+      actor: USER,
+      patch: { content: { html: "<p>新</p>" } },
+      assertWriteAllowed: expect.any(Function), // C1：属主预检随门卫入参
+    });
+    expect(M.knowledgeDocument.updateManyAndReturn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: "doc-1", isDeleted: false, kb: { userId: USER, isDeleted: false } },
+        data: { title: "t", content: { html: "<p>新</p>" } },
+      }),
+    );
+    expect(M.indexDocumentById).toHaveBeenCalledWith("doc-1");
+    expect(M.auditLog).toHaveBeenCalledWith(expect.objectContaining({ action: "document.update" }));
+    expect(res).toEqual(updated);
+  });
+
+  it("degraded（collab 不可达 TTL 降级）→ 同原行为：直写 + 索引", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "degraded", reason: "unreachable" });
+    const updated = { id: "doc-1", title: "t", content: { html: "<p>新</p>" }, icon: null, tags: [], properties: {}, updatedAt: NOW };
+    M.knowledgeDocument.updateManyAndReturn.mockResolvedValue([updated]);
+
+    const res = await updateDocumentFn({ data: { id: "doc-1", content: { html: "<p>新</p>" } } });
+
+    expect(M.knowledgeDocument.updateManyAndReturn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: { content: { html: "<p>新</p>" } },
+      }),
+    );
+    expect(M.indexDocumentById).toHaveBeenCalledWith("doc-1");
+    expect(res).toEqual(updated);
+  });
+
+  it("forwarded + 元数据 → 直写数据剥离 content、保留 title（双写不互吞 web 侧钉子）", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "forwarded" });
+    const updated = { id: "doc-1", title: "非协同改的标题", content: { html: "<p>旧</p>" }, icon: null, tags: [], properties: {}, updatedAt: NOW };
+    M.knowledgeDocument.updateManyAndReturn.mockResolvedValue([updated]);
+
+    const res = await updateDocumentFn({
+      data: { id: "doc-1", title: "非协同改的标题", content: { html: "<p>新</p>" } },
+    });
+
+    expect(M.knowledgeDocument.updateManyAndReturn).toHaveBeenCalledTimes(1);
+    const args = M.knowledgeDocument.updateManyAndReturn.mock.calls[0]![0];
+    expect(args.data).toEqual({ title: "非协同改的标题" }); // content 剥离
+    expect(args.where).toEqual({ id: "doc-1", isDeleted: false, kb: { userId: USER, isDeleted: false } });
+    // R11 touch：forwarded 组合 patch 的生效直写为纯元数据 → 同事务 touch 快照
+    expect(M.collabDocument.updateMany).toHaveBeenCalledWith({
+      where: { roomName: "doc:knowledge:doc-1" },
+      data: { updatedAt: NOW },
+    });
+    // 索引由 collab 侧单源触发
+    expect(M.indexDocumentById).not.toHaveBeenCalled();
+    expect(M.auditLog).toHaveBeenCalledWith(expect.objectContaining({ action: "document.update" }));
+    // content 回显请求值
+    expect(res).toEqual({ ...updated, content: { html: "<p>新</p>" } });
+  });
+
+  it("forwarded + content-only → 属主校验与行读取合并单查询 findFirst，不触发 updateManyAndReturn", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "forwarded" });
+    const row = { id: "doc-1", title: "t", content: { html: "<p>旧</p>" }, icon: null, tags: [], properties: {}, updatedAt: NOW };
+    M.knowledgeDocument.findFirst.mockResolvedValue(row);
+
+    const res = await updateDocumentFn({ data: { id: "doc-1", content: { html: "<p>新</p>" } } });
+
+    // assertOwned 单查询：属主校验 + 回读合一（无探针/回读两段 TOCTOU 窗口）
+    expect(M.knowledgeDocument.findFirst).toHaveBeenCalledWith({
+      where: { id: "doc-1", isDeleted: false, kb: { userId: USER, isDeleted: false } },
+      select: ROW_SELECT,
+    });
+    expect(M.knowledgeDocument.findUnique).not.toHaveBeenCalled();
+    expect(M.knowledgeDocument.updateManyAndReturn).not.toHaveBeenCalled();
+    expect(M.indexDocumentById).not.toHaveBeenCalled();
+    expect(res).toEqual({ ...row, content: { html: "<p>新</p>" } });
+  });
+
+  it("forwarded + content-only + 非属主/竞态删除 → findFirst 未命中报「未找到或无权限」", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "forwarded" });
+    M.knowledgeDocument.findFirst.mockResolvedValue(null);
+
+    await expect(
+      updateDocumentFn({ data: { id: "doc-1", content: { html: "<p>x</p>" } } }),
+    ).rejects.toThrow("未找到或无权限");
+    expect(M.knowledgeDocument.updateManyAndReturn).not.toHaveBeenCalled();
+    expect(M.auditLog).not.toHaveBeenCalled();
+  });
+
+  it("元数据 only（title）不惊动门卫网络面：门卫返回 pass-through，content 不在直写数据", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "pass-through", reason: "no-y-owned-field" });
+    const updated = { id: "doc-1", title: "t", content: { html: "<p>旧</p>" }, icon: null, tags: [], properties: {}, updatedAt: NOW };
+    M.knowledgeDocument.updateManyAndReturn.mockResolvedValue([updated]);
+
+    const res = await updateDocumentFn({ data: { id: "doc-1", title: "t" } });
+
+    expect(M.knowledgeDocument.updateManyAndReturn).toHaveBeenCalledWith(
+      expect.objectContaining({ data: { title: "t" } }),
+    );
+    // 元数据变更不触发内容索引
+    expect(M.indexDocumentById).not.toHaveBeenCalled();
+    // R11 touch：元数据-only 直写（无 Y 属主面）→ 同事务 touch 快照
+    // （防重命名后误判旁路写 → 下次打开全量重种子化）
+    expect(M.collabDocument.updateMany).toHaveBeenCalledWith({
+      where: { roomName: "doc:knowledge:doc-1" },
+      data: { updatedAt: NOW },
+    });
+    expect(res).toEqual(updated);
+  });
+
+  it("含 Y 属主面的直写（pass-through content）→ 不 touch（旁路反超语义，R11）", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "pass-through", reason: "no-snapshot" });
+    const updated = { id: "doc-1", title: "t", content: { html: "<p>新</p>" }, icon: null, tags: [], properties: {}, updatedAt: NOW };
+    M.knowledgeDocument.updateManyAndReturn.mockResolvedValue([updated]);
+
+    await updateDocumentFn({ data: { id: "doc-1", title: "t", content: { html: "<p>新</p>" } } });
+
+    expect(M.knowledgeDocument.updateManyAndReturn).toHaveBeenCalled();
+    expect(M.collabDocument.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("C1：越权（属主预检失败）→ 短路报错，转发链路 mutation 零发生", async () => {
+    // 忠实模拟真实门卫语义：快照命中 → 先执行属主预检 → 才返回 forwarded
+    M.withCollabGuard.mockImplementation(async (opts: {
+      assertWriteAllowed?: () => Promise<void>;
+    }) => {
+      await opts.assertWriteAllowed?.();
+      return { kind: "forwarded" as const };
+    });
+    M.knowledgeDocument.findFirst.mockResolvedValue(null); // 非属主
+
+    await expect(
+      updateDocumentFn({ data: { id: "doc-1", content: { html: "<p>越权</p>" } } }),
+    ).rejects.toThrow("未找到或无权限");
+
+    // 预检回调确实传入门卫（接线钉子）
+    expect(M.withCollabGuard).toHaveBeenCalledWith(
+      expect.objectContaining({ actor: USER, assertWriteAllowed: expect.any(Function) }),
+    );
+    // 转发后续的 web 侧 mutation 全部未发生（content 侧由 collab 承接，
+    // 转发未发生 = collab 侧零应用）
+    expect(M.knowledgeDocument.updateManyAndReturn).not.toHaveBeenCalled();
+    expect(M.indexDocumentById).not.toHaveBeenCalled();
+    expect(M.auditLog).not.toHaveBeenCalled();
+  });
+});