fix(ai-chat): hydrate crashed mid-run steps for model replay + cover write/read seams (#492)

F1: the server model-replay loaded history via findAllByChat().map(rowToUiMessage)
WITHOUT hydrating parts from ai_chat_run_steps. A HARD crash mid-run (SIGKILL/OOM)
fires no terminal callback, so the assistant row stays parts:[] and its partial
tool-calls/results/text (durable in the steps table) dropped out of the model's
next-turn context. Hydrate needy assistant rows (role==='assistant' &&
!rowHasInlineParts) via findByMessageIds + hydrateAssistantParts before the replay
map — mirroring the controller's withReconstructedParts exactly — guarded on the
optional repo. Fix the now-false interrupt-resume comment.

F2: add a service int-spec that drives the REAL onStep append-persist WRITE branch
through AiChatService.stream with a real AiChatRunStepRepo injected, asserting the
per-step rows' stepIndex + parts slice and the step-marker metadata match a
single-row flush (catches an stepsPersisted-1 off-by-one).

F3: add a controller int-spec that drives withReconstructedParts through getMessages
WITH the repo present (a mid-run marker-only row + its step rows), asserting the
reconstructed metadata.parts and workspace-scoping.

F4: remove the dead countByMessage (zero prod callers; reconstructRunParts derives
stepsPersisted inline) + its now-unused sql import and the redundant test assertion.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -392,6 +392,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `@docmost/token-estimate` package) so they can never diverge. Deferred-tool
   activation is also cached in the chat metadata to avoid re-resolving it each
   turn. (#490)
+- **Cyrillic (and any non-ASCII) draw.io labels no longer turn into mojibake
+  when a diagram is opened in the draw.io editor.** Agent-created diagrams
+  (`drawioCreate`) and Confluence-imported diagrams stored their model in the
+  SVG's `content=` attribute as base64; the draw.io editor decodes that via
+  Latin-1 `atob` (no UTF-8 step), so every non-ASCII char (e.g. `Старт-бит`,
+  `ё`, `—`) split into garbage and the editor's autosave then persisted the
+  corrupted model, breaking the page preview too. Both write paths
+  (`buildDrawioSvg`, the import service's `createDrawioSvg`) now write `content=`
+  as XML-entity-escaped mxfile XML — draw.io's own native form, decoded by the
+  DOM as UTF-8 — so labels open intact. The decoder reads both the new
+  entity-encoded form and the old base64 form, so existing diagrams still open.
+  *Healing pre-fix diagrams:* only a diagram that still holds its original
+  (correct-UTF-8) base64 — i.e. one not yet opened/autosaved in the draw.io
+  editor — can be repaired in place by `drawioGet` → `drawioUpdate` with the
+  same XML (rewrites the attachment in the new form); no migration script is
+  needed. A diagram that was already opened in the editor persisted the
+  mojibake at rest, so `drawioGet` reads the already-corrupted text and
+  `drawioUpdate` faithfully rewrites it — that text is lost and is not
+  recoverable by a rewrite. (#507)
 - **A chat with one malformed message part no longer 500s on every turn, and a
   failed send no longer duplicates the user's message.** Incoming client parts
   are now whitelisted to `text` (a forged tool-result part can no longer reach

apps/client/src/features/ai-chat/components/message-item-memo.test.tsx

@@ -27,6 +27,7 @@ vi.mock("@/features/ai-chat/utils/markdown.ts", async () => {
 
 import MessageItem from "./message-item";
 import { messageSignature } from "@/features/ai-chat/utils/message-signature.ts";
+import { splitPlainChunks } from "./streaming-plain-text";
 
 // matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
 
@@ -114,3 +115,89 @@ describe("MessageItem markdown memoization", () => {
     expect(queryByText("streamed answer")).not.toBeNull();
   });
 });
+
+// PERF SMOKE (#492): the whole point of the incremental streaming render is that
+// the ANSWER path costs O(number of markdown blocks), NOT O(number of throttled
+// ~20Hz ticks). Pre-#492 the finalized MarkdownPart re-parsed the WHOLE growing
+// answer on every delta — a synthetic ~100 KB stream measured 394 renderChatMarkdown
+// calls (one per tick). With the incremental render each STABILIZED block is parsed
+// exactly once (memoized in MarkdownChunk) and the live tail is cheap plain text, so
+// the call count collapses to ~= the block count regardless of tick granularity.
+describe("MessageItem streaming answer render is O(blocks), not O(ticks)", () => {
+  // ~100 KB answer. Each section is a heading + a paragraph — TWO blank-line
+  // delimited markdown blocks — so the safe-cut block count is ~2× the section
+  // count. The perf claim is about the BLOCK count (the memoization granularity),
+  // measured directly with splitPlainChunks below, not the section count.
+  const buildAnswer = () => {
+    const SECTIONS = 100;
+    const paragraphs: string[] = [];
+    for (let i = 0; i < SECTIONS; i++) {
+      paragraphs.push(`## Section ${i}\n\n` + "lorem ipsum dolor ".repeat(55));
+    }
+    const full = paragraphs.join("\n\n");
+    // The number of memoized markdown blocks the incremental render splits into
+    // (all but the live tail are parsed once each).
+    return { full, blocks: splitPlainChunks(full).length };
+  };
+
+  const streamMsg = (text: string, state: "streaming" | "done"): UIMessage =>
+    ({
+      id: "m1",
+      role: "assistant",
+      parts: [{ type: "text", text, state }],
+    }) as UIMessage;
+
+  it("parses each block ~once over a 100KB stream (≈blocks, ≪ ticks)", () => {
+    renderChatMarkdownSpy.mockClear();
+    const { full, blocks } = buildAnswer();
+    const CHUNK = 128; // a realistic ~20Hz throttled delta size
+    const ticks = Math.ceil(full.length / CHUNK);
+
+    let msg = streamMsg(full.slice(0, CHUNK), "streaming");
+    const { rerender } = render(
+      <MantineProvider>
+        <MessageItem
+          message={msg}
+          signature={messageSignature(msg)}
+          turnStreaming
+        />
+      </MantineProvider>,
+    );
+    for (let end = 2 * CHUNK; end < full.length; end += CHUNK) {
+      msg = streamMsg(full.slice(0, end), "streaming");
+      rerender(
+        <MantineProvider>
+          <MessageItem
+            message={msg}
+            signature={messageSignature(msg)}
+            turnStreaming
+          />
+        </MantineProvider>,
+      );
+    }
+    // Finalize: the streaming→done flip renders the whole answer through ONE
+    // canonical pass (visual parity), so the finished DOM matches the pre-#492
+    // output. This is the single extra parse on top of the per-block ones.
+    const done = streamMsg(full, "done");
+    rerender(
+      <MantineProvider>
+        <MessageItem message={done} signature={messageSignature(done)} />
+      </MantineProvider>,
+    );
+
+    const calls = renderChatMarkdownSpy.mock.calls.length;
+    // Sanity: the stream really had far more ticks than blocks (else the test is
+    // vacuous — the point is that calls scale with blocks, not ticks).
+    expect(ticks).toBeGreaterThan(blocks * 3);
+    // O(blocks): each stabilized block parsed once + the single final whole-text
+    // parse. A small constant absorbs the finalize render and the live-tail block;
+    // the load-bearing claim is the bound below.
+    expect(calls).toBeLessThanOrEqual(blocks + 2);
+    // ≪ ticks — and, non-vacuously, the blocks WERE parsed (not skipped entirely).
+    expect(calls).toBeLessThan(ticks / 3);
+    expect(calls).toBeGreaterThan(blocks / 2);
+    // MUTATION-VERIFY (documented, not run here): dropping the `memo()` wrapper on
+    // MarkdownChunk (so every stable block re-parses each tick) drives `calls`
+    // toward `ticks` (~394), reddening both upper-bound assertions above.
+  });
+});

apps/client/src/features/ai-chat/components/message-item.render.test.tsx

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from "vitest";
+import { render } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import type { UIMessage } from "@ai-sdk/react";
+
+// Stub react-i18next (the component reads `useTranslation`). Mirrors the other
+// message-item specs.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import MessageItem from "./message-item";
+import { messageSignature } from "@/features/ai-chat/utils/message-signature.ts";
+// The REAL canonical renderer (NOT the spy the memo test installs): this file
+// exercises the actual markdown output so the visual-regression assertions below
+// compare against genuine HTML (incl. the schema's `<li><p>` wrappers).
+import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
+import classes from "./ai-chat.module.css";
+
+const msg = (
+  parts: UIMessage["parts"],
+  extra?: Partial<UIMessage>,
+): UIMessage =>
+  ({ id: "m1", role: "assistant", parts, ...extra }) as UIMessage;
+
+const renderRow = (message: UIMessage, turnStreaming = false) =>
+  render(
+    <MantineProvider>
+      <MessageItem
+        message={message}
+        signature={messageSignature(message)}
+        turnStreaming={turnStreaming}
+      />
+    </MantineProvider>,
+  );
+
+// A rich multi-block answer that exercises headings, a list (the `<li><p>` case
+// the scoped CSS tightens), inline emphasis, and multiple paragraphs.
+const ANSWER = [
+  "# Заголовок",
+  "",
+  "Первый абзац с **жирным** и `кодом`.",
+  "",
+  "- пункт один",
+  "- пункт два",
+  "",
+  "Второй абзац.",
+].join("\n");
+
+describe("MessageItem final render — visual parity with the canonical pipeline", () => {
+  it("a finalized text part renders exactly renderChatMarkdown(text)", () => {
+    const { container } = renderRow(
+      msg([{ type: "text", text: ANSWER, state: "done" }]),
+    );
+    const block = container.querySelector(`.${classes.markdown}`);
+    expect(block).not.toBeNull();
+    // Byte-for-byte the canonical output (the SAME whole-text pass the pre-#492
+    // MarkdownPart produced), including `<li><p>…</p></li>` wrappers.
+    expect(block!.innerHTML).toBe(renderChatMarkdown(ANSWER, {}));
+    // The list wrapper is really present (guards against a vacuous empty render).
+    expect(container.querySelectorAll("li p").length).toBe(2);
+  });
+
+  it("the streaming incremental view CONVERGES to the canonical render on finish", () => {
+    // Mount mid-stream (live tail) — the DOM here is the incremental view.
+    const { container, rerender } = render(
+      <MantineProvider>
+        <MessageItem
+          message={msg([{ type: "text", text: ANSWER, state: "streaming" }])}
+          signature={messageSignature(
+            msg([{ type: "text", text: ANSWER, state: "streaming" }]),
+          )}
+          turnStreaming
+        />
+      </MantineProvider>,
+    );
+    // Finish the turn: state flips to done AND the turn is no longer streaming.
+    const done = msg([{ type: "text", text: ANSWER, state: "done" }]);
+    rerender(
+      <MantineProvider>
+        <MessageItem message={done} signature={messageSignature(done)} />
+      </MantineProvider>,
+    );
+    // After finish there is exactly ONE canonical markdown container whose HTML is
+    // the whole-text render — identical to the non-streaming path above.
+    const blocks = container.querySelectorAll(`.${classes.markdown}`);
+    expect(blocks.length).toBe(1);
+    expect(blocks[0].innerHTML).toBe(renderChatMarkdown(ANSWER, {}));
+  });
+
+  it("neutralizeInternalLinks is honored on the finalized render", () => {
+    const linkAnswer = "См. [страницу](/p/abc).";
+    const { container } = render(
+      <MantineProvider>
+        <MessageItem
+          message={msg([{ type: "text", text: linkAnswer, state: "done" }])}
+          signature={messageSignature(
+            msg([{ type: "text", text: linkAnswer, state: "done" }]),
+          )}
+          neutralizeInternalLinks
+        />
+      </MantineProvider>,
+    );
+    const block = container.querySelector(`.${classes.markdown}`);
+    expect(block!.innerHTML).toBe(
+      renderChatMarkdown(linkAnswer, { neutralizeInternalLinks: true }),
+    );
+    // The internal link was made inert (no href) by the neutralization flag.
+    const a = container.querySelector("a");
+    expect(a?.hasAttribute("href")).toBe(false);
+  });
+});

apps/client/src/features/ai-chat/components/message-item.tsx

@@ -4,6 +4,7 @@ import { useTranslation } from "react-i18next";
 import type { UIMessage } from "@ai-sdk/react";
 import ToolCallCard from "@/features/ai-chat/components/tool-call-card.tsx";
 import ReasoningBlock from "@/features/ai-chat/components/reasoning-block.tsx";
+import { StreamingMarkdownText } from "@/features/ai-chat/components/streaming-markdown-text.tsx";
 import ChatErrorAlert from "@/features/ai-chat/components/chat-error-alert.tsx";
 import ChatStoppedNotice from "@/features/ai-chat/components/chat-stopped-notice.tsx";
 import { ToolUiPart, isToolPart } from "@/features/ai-chat/utils/tool-parts.tsx";
@@ -86,17 +87,39 @@ interface MessageItemProps {
  * One assistant text part rendered as sanitized markdown. Memoized on its inputs
  * so a finalized text part is NOT re-parsed on every streamed delta: during a
  * turn only the actively-growing tail part changes its `text`, so every earlier
- * part hits the memo and skips the expensive marked + DOMPurify pass. Props are
- * primitives, so React.memo's default shallow compare is exactly right (the
- * `text` string is compared by value).
+ * part hits the memo and skips the expensive canonical parse + DOMPurify pass.
+ * Props are primitives, so React.memo's default shallow compare is exactly right
+ * (the `text` string is compared by value).
+ *
+ * Streaming gate (#492) — mirrors ReasoningBlock:
+ *  - `streaming` (this is the live, actively-growing tail part of an in-flight
+ *    turn): render incrementally via StreamingMarkdownText — the stabilized blocks
+ *    go through the canonical pipeline (each parsed ONCE, memoized) and only the
+ *    live tail is cheap plain text. This makes the per-tick cost O(new blocks),
+ *    not the pre-#492 O(ticks) whole-answer re-parse on every ~20Hz delta.
+ *  - finalized (the common case, and the turn-end flip): render the WHOLE text
+ *    through ONE canonical pass — byte-identical to the pre-#492 output (visual
+ *    parity). The row re-renders on the streaming→done flip because
+ *    `messageSignature` tracks each part's `state` (and `turnStreaming` flips at
+ *    turn end), so the incremental view always converges to this single render.
  */
 const MarkdownPart = memo(function MarkdownPart({
   text,
   neutralizeInternalLinks,
+  streaming,
 }: {
   text: string;
   neutralizeInternalLinks: boolean;
+  streaming: boolean;
 }) {
+  if (streaming) {
+    return (
+      <StreamingMarkdownText
+        text={text}
+        neutralizeInternalLinks={neutralizeInternalLinks}
+      />
+    );
+  }
   const html = renderChatMarkdown(text, { neutralizeInternalLinks });
   if (html) {
     return (
@@ -179,47 +202,10 @@ function MessageItem({
         {resolveAssistantName(assistantName) ?? t("AI agent")}
       </Text>
       {message.parts.map((part, index) => {
-        if (part.type === "reasoning") {
-          // Reasoning ("thinking") -> a collapsible block with its own token
-          // count. Empty/whitespace reasoning with no authoritative count carries
-          // nothing to show, so skip it (avoids an empty 0-token block).
-          const text = (part as { text?: string }).text ?? "";
-          if (!text.trim() && !(reasoningTokens && reasoningTokens > 0))
-            return null;
-          // Absent state (persisted rows) and "done" both mean finalized.
-          // `messageSignature` already includes each part's `state`, so the
-          // streaming→done flip changes the row signature and re-renders this
-          // row — which is what lets ReasoningBlock switch from chunked plain
-          // text to its one-time markdown parse (see reasoning-block.tsx).
-          // ALSO require the turn to be live: a part stranded at
-          // `state:"streaming"` after the turn ended (no `reasoning-end` — see
-          // the `turnStreaming` prop doc) must still finalize and parse.
-          const streaming =
-            turnStreaming && (part as { state?: string }).state === "streaming";
-          return (
-            <ReasoningBlock
-              key={index}
-              text={text}
-              tokens={reasoningTokens}
-              streaming={streaming}
-            />
-          );
-        }
-
-        if (part.type === "text") {
-          // Skip empty/whitespace-only text parts (a streaming message often
-          // starts with an empty text part before the first token arrives); the
-          // typing indicator covers that gap until real content streams in.
-          if (!part.text.trim()) return null;
-          return (
-            <MarkdownPart
-              key={index}
-              text={part.text}
-              neutralizeInternalLinks={neutralizeInternalLinks}
-            />
-          );
-        }
-
+        // Tool parts (`tool-*` / `dynamic-tool`) are template-literal kinds, so
+        // they cannot be a `switch` case; the runtime guard handles them, and the
+        // switch below covers every CLOSED (literal-typed) part kind with a
+        // compile-time exhaustiveness check in its default.
         if (isToolPart(part.type)) {
           return (
             <ToolCallCard
@@ -232,7 +218,76 @@ function MessageItem({
           );
         }
 
-        return null;
+        switch (part.type) {
+          case "reasoning": {
+            // Reasoning ("thinking") -> a collapsible block with its own token
+            // count. Empty/whitespace reasoning with no authoritative count
+            // carries nothing to show, so skip it (avoids an empty 0-token block).
+            const text = part.text ?? "";
+            if (!text.trim() && !(reasoningTokens && reasoningTokens > 0))
+              return null;
+            // Absent state (persisted rows) and "done" both mean finalized.
+            // `messageSignature` already includes each part's `state`, so the
+            // streaming→done flip changes the row signature and re-renders this
+            // row — which is what lets ReasoningBlock switch from chunked plain
+            // text to its one-time markdown parse (see reasoning-block.tsx).
+            // ALSO require the turn to be live: a part stranded at
+            // `state:"streaming"` after the turn ended (no `reasoning-end` — see
+            // the `turnStreaming` prop doc) must still finalize and parse.
+            const streaming = turnStreaming && part.state === "streaming";
+            return (
+              <ReasoningBlock
+                key={index}
+                text={text}
+                tokens={reasoningTokens}
+                streaming={streaming}
+              />
+            );
+          }
+
+          case "text": {
+            // Skip empty/whitespace-only text parts (a streaming message often
+            // starts with an empty text part before the first token arrives); the
+            // typing indicator covers that gap until real content streams in.
+            if (!part.text.trim()) return null;
+            // The live, actively-growing tail part of the in-flight turn renders
+            // incrementally (see MarkdownPart); a finalized part (persisted, or
+            // the turn-end flip) renders the whole text through one canonical
+            // pass. Same liveness rule as the reasoning branch above.
+            const streaming = turnStreaming && part.state === "streaming";
+            return (
+              <MarkdownPart
+                key={index}
+                text={part.text}
+                neutralizeInternalLinks={neutralizeInternalLinks}
+                streaming={streaming}
+              />
+            );
+          }
+
+          case "source-url":
+          case "source-document":
+          case "file":
+          case "step-start":
+            // Not surfaced in the chat bubble (v1) — same as the pre-#492 default.
+            return null;
+
+          default: {
+            // Compile-time exhaustiveness over the CLOSED union members: every
+            // literal-typed part kind is handled above, so the only kinds that
+            // can reach here are the OPEN template-literal ones (`tool-*` — caught
+            // by the guard at runtime — and `data-*`) plus `dynamic-tool`. Adding
+            // a NEW closed part kind to UIMessagePart makes this assignment fail
+            // to compile, forcing it to be handled instead of silently ignored
+            // (this replaces the pre-#492 fall-through `return null` + WARNING).
+            const _exhaustive:
+              | `tool-${string}`
+              | "dynamic-tool"
+              | `data-${string}` = part.type;
+            void _exhaustive;
+            return null;
+          }
+        }
       })}
       {/* A persisted turn error (server stored it in metadata.error). Rendered
           here so it survives a thread remount and shows in reopened history. */}

apps/client/src/features/ai-chat/components/streaming-markdown-text.tsx

@@ -0,0 +1,96 @@
+import { memo, useMemo } from "react";
+import { splitPlainChunks } from "@/features/ai-chat/components/streaming-plain-text.tsx";
+import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
+import classes from "@/features/ai-chat/components/ai-chat.module.css";
+
+/**
+ * One STABILIZED markdown block, rendered through the canonical pipeline and
+ * memoized on its string prop. During streaming only the TAIL chunk grows (the
+ * `splitPlainChunks` append-only invariant guarantees every earlier chunk is
+ * byte-identical across deltas), so React skips every stable block and each one
+ * is parsed by `renderChatMarkdown` EXACTLY ONCE — turning the pre-#492
+ * "re-parse the whole accumulated answer on every ~20Hz tick" (O(ticks)) into
+ * O(number of blocks). The markup is DOMPurify-sanitized inside renderChatMarkdown
+ * before it reaches `dangerouslySetInnerHTML`.
+ *
+ * NOTE (transient streaming-only artifact): a safe cut is a blank-line boundary,
+ * so a construct that legitimately contains a blank line (e.g. a fenced code block
+ * with an empty line) can be split across chunks and render oddly WHILE it is still
+ * streaming. This is cosmetic and self-heals: the moment the part finalizes,
+ * MarkdownPart renders the WHOLE text through one canonical pass (visual parity
+ * with the pre-#492 output). The reasoning path makes the same trade (plain text
+ * while streaming, one markdown parse at the end).
+ */
+const MarkdownChunk = memo(function MarkdownChunk({
+  text,
+  neutralizeInternalLinks,
+}: {
+  text: string;
+  neutralizeInternalLinks: boolean;
+}) {
+  const html = renderChatMarkdown(text, { neutralizeInternalLinks });
+  if (html) {
+    return (
+      <div
+        className={classes.markdown}
+        // Sanitized by renderChatMarkdown (DOMPurify) before insertion.
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    );
+  }
+  // Malformed/unsupported markdown could not render synchronously: raw text.
+  return (
+    <div className={classes.markdown} style={{ whiteSpace: "pre-wrap" }}>
+      {text}
+    </div>
+  );
+});
+
+/**
+ * The cheap streaming-time stand-in for the finalized answer's one-time markdown
+ * parse (see MarkdownPart in message-item.tsx). Mirrors StreamingPlainText's
+ * chunked-memo pattern but renders the STABILIZED prefix as real markdown (each
+ * block parsed once, memoized) and only the LIVE tail as flat plain text — so the
+ * user sees formatted output for everything up to the last safe cut, and the not-
+ * yet-stable tail (which markdown-parsing every tick would make O(ticks)) stays a
+ * single cheap escaped text node until it stabilizes into a new block.
+ *
+ * `splitPlainChunks` yields chunks where, under append-only growth, every chunk
+ * except the LAST is immutable; the last chunk is the live tail. Index keys are
+ * therefore stable (a given index never changes to a different chunk's content).
+ */
+export function StreamingMarkdownText({
+  text,
+  neutralizeInternalLinks,
+}: {
+  text: string;
+  neutralizeInternalLinks: boolean;
+}) {
+  const chunks = useMemo(() => splitPlainChunks(text), [text]);
+  return (
+    <>
+      {chunks.map((chunk, index) =>
+        index < chunks.length - 1 ? (
+          <MarkdownChunk
+            key={index}
+            text={chunk}
+            neutralizeInternalLinks={neutralizeInternalLinks}
+          />
+        ) : (
+          // The live tail: flat, React-escaped plain text (no markdown parse, no
+          // sanitizer, no innerHTML). `pre-wrap` preserves its newlines; trailing
+          // separator newlines are dropped at display time so the block gap comes
+          // from the markdown margins, not a doubled empty line (mirrors
+          // PlainChunk in streaming-plain-text.tsx).
+          <div
+            key={index}
+            className={classes.markdown}
+            style={{ whiteSpace: "pre-wrap" }}
+          >
+            {chunk.replace(/\n+$/, "")}
+          </div>
+        ),
+      )}
+    </>
+  );
+}

apps/server/src/core/ai-chat/ai-chat.controller.ts

@@ -35,6 +35,7 @@ import {
 import { PaginationOptions } from '@docmost/db/pagination/pagination-options';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import { AiChatRunStepRepo } from '@docmost/db/repos/ai-chat/ai-chat-run-step.repo';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { UserThrottlerGuard } from '../../integrations/throttle/user-throttler.guard';
 import { AI_CHAT_THROTTLER } from '../../integrations/throttle/throttler-names';
@@ -43,6 +44,8 @@ import {
   AiChatRunHooks,
   AiChatService,
   AiChatStreamBody,
+  rowHasInlineParts,
+  hydrateAssistantParts,
 } from './ai-chat.service';
 import { AiChatRunService } from './ai-chat-run.service';
 import { AiTranscriptionService } from './ai-transcription.service';
@@ -129,8 +132,39 @@ export class AiChatController {
     // production. Only touched on the resumable-stream (flag-on) path.
     private readonly streamRegistry?: AiChatStreamRegistryService,
     private readonly environment?: EnvironmentService,
+    // #492: reconstruct a #492 mid-run record's parts from the steps table before
+    // returning rows to the client / export. OPTIONAL so positional controller
+    // specs compile unchanged; when absent, hydration is skipped (old-era rows
+    // already carry inline parts, so nothing to reconstruct).
+    private readonly aiChatRunStepRepo?: AiChatRunStepRepo,
   ) {}
 
+  /**
+   * Reconstruct parts for any assistant rows that don't carry them INLINE — a
+   * #492 mid-run record whose per-step parts live in `ai_chat_run_steps` (the
+   * append-persist backend). Every FINISHED row (old-era + #492) and every old-era
+   * streaming snapshot already has inline `metadata.parts`, so the common path
+   * fetches NOTHING and returns the rows untouched; only an actively-streaming
+   * new-style row triggers the batch step fetch. Consumers (seed/poll/export) read
+   * `metadata.parts` off the returned rows exactly as before — the era switch is
+   * invisible to them (reconstructRunParts contract).
+   */
+  private async withReconstructedParts(
+    rows: AiChatMessage[],
+    workspaceId: string,
+  ): Promise<AiChatMessage[]> {
+    if (!this.aiChatRunStepRepo) return rows;
+    const needy = rows.filter(
+      (r) => r.role === 'assistant' && !rowHasInlineParts(r),
+    );
+    if (needy.length === 0) return rows;
+    const stepsByMessage = await this.aiChatRunStepRepo.findByMessageIds(
+      needy.map((r) => r.id),
+      workspaceId,
+    );
+    return hydrateAssistantParts(rows, stepsByMessage);
+  }
+
   /** List the requesting user's chats in this workspace (paginated). */
   @HttpCode(HttpStatus.OK)
   @Post('chats')
@@ -184,11 +218,17 @@ export class AiChatController {
     @AuthWorkspace() workspace: Workspace,
   ) {
     await this.assertOwnedChat(dto.chatId, user, workspace);
-    return this.aiChatMessageRepo.findByChat(
+    const page = await this.aiChatMessageRepo.findByChat(
       dto.chatId,
       workspace.id,
       pagination,
     );
+    // #492: reconstruct parts for any active new-style row so the client seed sees
+    // `metadata.parts` unchanged (a no-op for the finished rows that fill a page).
+    return {
+      ...page,
+      items: await this.withReconstructedParts(page.items, workspace.id),
+    };
   }
 
   /**
@@ -225,7 +265,10 @@ export class AiChatController {
       workspace.id,
     );
     return {
-      rows,
+      // #492: the delta of an actively-streaming new-style row carries its parts
+      // reconstructed from the steps table, so the degraded poll shows persisted
+      // progress exactly as the pre-#492 full-row snapshot did.
+      rows: await this.withReconstructedParts(rows, workspace.id),
       cursor,
       run: run ? { id: run.id, status: run.status } : null,
     };
@@ -247,8 +290,10 @@ export class AiChatController {
     @AuthWorkspace() workspace: Workspace,
   ): Promise<{ markdown: string }> {
     const chat = await this.assertOwnedChat(dto.chatId, user, workspace);
-    const rows = await this.aiChatMessageRepo.findAllByChat(
-      dto.chatId,
+    const rows = await this.withReconstructedParts(
+      await this.aiChatMessageRepo.findAllByChat(dto.chatId, workspace.id),
+      // #492: an interrupted-but-still-active turn exports its persisted steps
+      // (reconstructed from the steps table) just like the pre-#492 full row did.
       workspace.id,
     );
     const markdown = buildChatMarkdown({
@@ -288,7 +333,13 @@ export class AiChatController {
           workspace.id,
         )
       : undefined;
-    return { run, message: message ?? null };
+    // #492: reconnect to an IN-FLIGHT run reconstructs the projection row's parts
+    // from the steps table (the row itself carries only the step marker mid-run);
+    // a finished run's row already has inline parts, so this is a no-op.
+    const [hydrated] = message
+      ? await this.withReconstructedParts([message], workspace.id)
+      : [undefined];
+    return { run, message: hydrated ?? null };
   }
 
   /**

apps/server/src/core/ai-chat/ai-chat.service.ts

@@ -22,6 +22,7 @@ import { AiSettingsService } from '../../integrations/ai/ai-settings.service';
 import { describeProviderError } from '../../integrations/ai/ai-error.util';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import { AiChatRunStepRepo } from '@docmost/db/repos/ai-chat/ai-chat-run-step.repo';
 import { AiChatPageSnapshotRepo } from '@docmost/db/repos/ai-chat/ai-chat-page-snapshot.repo';
 import { AiAgentRoleRepo } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
@@ -189,10 +190,11 @@ export function stepBudgetWarning(stepNumber: number): string {
 //
 // `system` is the in-scope system prompt; we CONCATENATE so the original
 // persona/context is preserved — a bare `system` override would REPLACE the
-// whole system prompt for the step. `activatedTools` is PER-TURN mutable state
-// owned by the streaming loop (a closure Set grown by loadTools); it is passed
-// in (not module-global, not persisted) so this stays a pure function of its
-// arguments.
+// whole system prompt for the step. `activatedTools` is a closure Set grown by
+// loadTools and owned by the streaming loop; the caller seeds it from and
+// persists it to the chat's metadata across turns (#490), but this function only
+// READS the Set it is handed, so it stays a pure function of its arguments (not
+// module-global).
 //
 // NOTE: at AI SDK v7 the per-step `system` field is renamed to `instructions`.
 // On v6 (`^6.0.134`) `system` is the correct field — adjust when bumping.
@@ -517,6 +519,12 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
     // constructions compile unchanged; Nest always injects the real singleton, so
     // reconcile sees the SAME in-memory active/zombie maps the runner mutates.
     private readonly aiChatRunService?: AiChatRunService,
+    // #492 append-persist: per-step INSERT into the lightweight steps table (the
+    // O(Σ steps) replacement for the O(n²) full-row `metadata.parts` rewrite).
+    // OPTIONAL so existing positional constructions (int-specs) compile unchanged;
+    // Nest injects the real singleton. When ABSENT the per-step path falls back to
+    // the pre-#492 full-row flush (no regression, only no WAL win).
+    private readonly aiChatRunStepRepo?: AiChatRunStepRepo,
   ) {}
 
   // #487: periodic reconcile timer (single-process phase 1). Started in
@@ -1113,8 +1121,34 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
         chatId,
         workspace.id,
       );
+      // #492: HYDRATE needy assistant rows from the steps table BEFORE the replay
+      // map. A #492 mid-run assistant row carries only a step marker
+      // (metadata.parts:[]); its real per-step parts live in `ai_chat_run_steps`.
+      // The graceful terminal callbacks (onFinish/onError/onAbort -> flushAssistant)
+      // assemble the full inline parts, so a normally-ended turn already has them.
+      // But a HARD crash mid-run (SIGKILL/OOM) fires NO terminal callback, so the
+      // row stays parts:[]; without this, rowToUiMessage falls back to an empty
+      // text part and the partial tool-calls/results/text — durable in the steps
+      // table — would DROP OUT of the model's replay context (regressing #183
+      // step-granular durability for the model consumer). Mirrors the controller's
+      // withReconstructedParts EXACTLY (same needy predicate + hydration helper).
+      // Guarded on the optional repo: absent (positional test builds) degrades to
+      // the current behavior rather than crashing.
+      let replayHistory = oldHistory;
+      if (this.aiChatRunStepRepo) {
+        const needy = oldHistory.filter(
+          (r) => r.role === 'assistant' && !rowHasInlineParts(r),
+        );
+        if (needy.length > 0) {
+          const stepsByMessage = await this.aiChatRunStepRepo.findByMessageIds(
+            needy.map((r) => r.id),
+            workspace.id,
+          );
+          replayHistory = hydrateAssistantParts(oldHistory, stepsByMessage);
+        }
+      }
       const uiMessages: Array<Omit<UIMessage, 'id'> & { id: string }> = [
-        ...oldHistory.map(rowToUiMessage),
+        ...replayHistory.map(rowToUiMessage),
         {
           id: 'pending-user',
           role: 'user',
@@ -1153,7 +1187,9 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       // hint — confirm it against the persisted history (the preceding assistant
       // turn must really be aborted/streaming) so a spoofed flag cannot inject the
       // interrupt note onto an ordinary turn. The partial output the model needs is
-      // already in `messages` (the aborted assistant row replays via findRecent).
+      // already in `messages`: a #492 mid-run row's per-step parts live only in the
+      // `ai_chat_run_steps` table and were hydrated into the replay history above,
+      // so the aborted assistant turn replays WITH its partial parts intact.
       // Append the new user turn (shape-only) so index -2 is the prior assistant.
       const interrupted = isInterruptResume(
         [...oldHistory, { role: 'user', status: null, metadata: null }],
@@ -1410,10 +1446,11 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       const baseTools = { ...external.tools, ...docmostTools };
 
       // Deferred tool loading state (#332), scoped to THIS streaming loop:
-      //  - `activatedTools` is per-TURN mutable state — a fresh closure Set created
-      //    per streamText call, NOT module-global and NOT persisted, so a new turn
-      //    starts cold. loadTools.execute adds to it; prepareAgentStep reads it to
-      //    widen `activeTools` on the NEXT step.
+      //  - `activatedTools` is a fresh closure Set per streamText call (not
+      //    module-global), SEEDED from the chat's persisted metadata.activatedTools
+      //    (#490, just below) so activation carries across turns. loadTools.execute
+      //    adds to it; prepareAgentStep reads it to widen `activeTools` on the NEXT
+      //    step; turn end persists it back.
       //  - `validDeferredNames` = every tool that is NOT core (the in-app deferred
       //    tools + ALL external MCP tools), computed from the ACTUAL toolset so an
       //    external tool is loadable by its namespaced name. loadTools rejects any
@@ -1557,17 +1594,57 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
         // connection when finalize runs, so the SQL `WHERE status='streaming'`
         // (not this flag) is what prevents it clobbering the terminal row.
         if (finalized) return null;
-        // Build the flush ONCE so the returned count is EXACTLY the persisted
-        // `stepsPersisted` (both derive from capturedSteps.length at this instant).
-        const flushed = flushAssistant(capturedSteps, '', 'streaming', {
-          pageChanged,
-          partsCache,
-        });
-        const stepsPersisted = flushed.metadata.stepsPersisted as number;
+        // The count derives from capturedSteps.length at THIS instant, so the
+        // returned value is EXACTLY the persisted `stepsPersisted` the ring rotates
+        // on (whether we take the append-persist path or the legacy fallback).
+        const stepsPersisted = capturedSteps.length;
         try {
-          await this.aiChatMessageRepo.update(assistantId, workspace.id, flushed, {
-            onlyIfStreaming: true,
-          });
+          if (this.aiChatRunStepRepo) {
+            // #492 APPEND-PERSIST: write only THIS finished step's parts to the
+            // steps table (O(step) WAL), then bump the row's CHEAP step marker —
+            // NO growing `metadata.parts` blob (that O(n²) full-row rewrite is
+            // exactly what this removes). The full `metadata.parts` is assembled
+            // once at finalize; a mid-run resume seed is reconstructed from the
+            // step rows (reconstructRunParts). The INSERT is idempotent
+            // (ON CONFLICT DO NOTHING), so a re-fired step never doubles the parts.
+            const index = stepsPersisted - 1;
+            if (index >= 0) {
+              const stepParts = assistantParts(
+                [capturedSteps[index]],
+                '',
+                partsCache,
+              );
+              await this.aiChatRunStepRepo.insertStep(
+                assistantId,
+                workspace.id,
+                index,
+                stepParts,
+              );
+            }
+            // Marker UPDATE: advance stepsPersisted + keep the toolTrace era marker
+            // (bumps updatedAt so the delta poll observes the step, and carries the
+            // frontier a resuming client attaches from). Scoped onlyIfStreaming so a
+            // late marker never clobbers the terminal finalize.
+            await this.aiChatMessageRepo.update(
+              assistantId,
+              workspace.id,
+              { metadata: stepMarkerMetadata(stepsPersisted) },
+              { onlyIfStreaming: true },
+            );
+          } else {
+            // Legacy fallback (no steps table wired — positional test builds): the
+            // pre-#492 full-row flush, so parts still land inline on the row.
+            const flushed = flushAssistant(capturedSteps, '', 'streaming', {
+              pageChanged,
+              partsCache,
+            });
+            await this.aiChatMessageRepo.update(
+              assistantId,
+              workspace.id,
+              flushed,
+              { onlyIfStreaming: true },
+            );
+          }
           return stepsPersisted;
         } catch (err) {
           this.logger.warn(
@@ -2747,6 +2824,122 @@ export function rowToUiMessage(row: AiChatMessage): Omit<UIMessage, 'id'> & {
   return { id: row.id, role, parts: parts as UIMessage['parts'] };
 }
 
+/**
+ * Cheap step-marker metadata for the #492 per-step UPDATE. Advances
+ * `stepsPersisted` (the resume attach frontier) and keeps the `toolTraceVersion`
+ * era marker, WITHOUT the growing `parts` blob (those live in the steps table
+ * now; the full `metadata.parts` is assembled once at finalize by flushAssistant).
+ * `parts: []` is kept for shape stability — it reads as an empty inline-parts row,
+ * which is exactly the discriminator that routes reconstruction to the steps table.
+ */
+export function stepMarkerMetadata(
+  stepsPersisted: number,
+): Record<string, unknown> {
+  return { parts: [], toolTraceVersion: 2, stepsPersisted };
+}
+
+/**
+ * Whether an assistant row already carries its full UI parts INLINE on the row
+ * (`metadata.parts`). TRUE for every FINISHED row — old-era rows AND #492 rows,
+ * whose full parts are assembled once at finalize — and for old-era streaming
+ * snapshots (the pre-#492 per-step full-row flush). FALSE for a #492 MID-RUN
+ * record, whose per-step parts live in the `ai_chat_run_steps` table. This is the
+ * era discriminator the reconstruct seam branches on — no schema flag needed.
+ */
+export function rowHasInlineParts(row: { metadata?: unknown }): boolean {
+  const meta = (row.metadata ?? {}) as { parts?: unknown };
+  return Array.isArray(meta.parts) && meta.parts.length > 0;
+}
+
+/**
+ * Concatenate persisted per-step parts (in `stepIndex` order) into the turn's UI
+ * parts (#492). Reproduces EXACTLY what flushAssistant → assistantParts would have
+ * written to `metadata.parts` for those finished steps, since each step row stored
+ * `assistantParts([step])` at persist time.
+ */
+export function assembleStepParts(
+  stepRows: ReadonlyArray<{ stepIndex: number; parts: unknown }>,
+): UIMessage['parts'] {
+  const parts: Array<Record<string, unknown>> = [];
+  for (const step of [...stepRows].sort((a, b) => a.stepIndex - b.stepIndex)) {
+    if (Array.isArray(step.parts)) {
+      parts.push(...(step.parts as Array<Record<string, unknown>>));
+    }
+  }
+  return parts as UIMessage['parts'];
+}
+
+/**
+ * reconstructRunParts (#492) — the single backend-switch seam. Given an assistant
+ * ROW and its persisted step rows, return the turn's UI `parts` + the persisted
+ * step count, reading from the ROW when it already carries inline parts (old-era
+ * records AND every finished record) and from the STEPS TABLE otherwise (a #492
+ * mid-run record). The higher-level consumers (attach seed, delta poll, export)
+ * route their row→parts through this / {@link hydrateAssistantParts}, so old and
+ * new records reconstruct identically WITHOUT the consumers branching on the era.
+ */
+export function reconstructRunParts(
+  row: { metadata?: unknown; content?: string | null },
+  stepRows: ReadonlyArray<{ stepIndex: number; parts: unknown }>,
+): { parts: UIMessage['parts']; stepsPersisted: number } {
+  if (rowHasInlineParts(row)) {
+    const meta = row.metadata as {
+      parts: UIMessage['parts'];
+      stepsPersisted?: number;
+    };
+    return {
+      parts: meta.parts,
+      stepsPersisted:
+        typeof meta.stepsPersisted === 'number'
+          ? meta.stepsPersisted
+          : stepRows.length,
+    };
+  }
+  if (stepRows.length > 0) {
+    return {
+      parts: assembleStepParts(stepRows),
+      stepsPersisted: stepRows.length,
+    };
+  }
+  // No inline parts and no step rows: an old-era seed / empty streaming row. Fall
+  // back to a single text part from `content` (mirrors rowToUiMessage).
+  return {
+    parts: textPart(row.content ?? '') as UIMessage['parts'],
+    stepsPersisted: 0,
+  };
+}
+
+/**
+ * Fill each assistant row's `metadata.parts` from its step rows when the row does
+ * not already carry them inline (a #492 mid-run record), so a consumer that reads
+ * `metadata.parts` off the RAW row (the client seed/poll, the Markdown export)
+ * sees the reconstructed parts with NO change to itself. Rows that already have
+ * inline parts (old-era + finished) and non-assistant rows pass through untouched.
+ * Pure: returns new row objects, never mutates the inputs.
+ */
+export function hydrateAssistantParts<
+  T extends { id: string; role?: string; metadata?: unknown },
+>(
+  rows: ReadonlyArray<T>,
+  stepsByMessage: Map<
+    string,
+    ReadonlyArray<{ stepIndex: number; parts: unknown }>
+  >,
+): T[] {
+  return rows.map((row) => {
+    if (row.role !== 'assistant' || rowHasInlineParts(row)) return row;
+    const steps = stepsByMessage.get(row.id);
+    if (!steps || steps.length === 0) return row;
+    return {
+      ...row,
+      metadata: {
+        ...((row.metadata ?? {}) as Record<string, unknown>),
+        parts: assembleStepParts(steps),
+      },
+    };
+  });
+}
+
 /**
  * The persisted-row patch shape produced by {@link flushAssistant}. It is the
  * SAME shape the assistant repo insert/update consume (content + toolCalls +

apps/server/src/database/database.module.ts

@@ -32,6 +32,7 @@ import { TemplateRepo } from '@docmost/db/repos/template/template.repo';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
 import { AiChatRunRepo } from '@docmost/db/repos/ai-chat/ai-chat-run.repo';
+import { AiChatRunStepRepo } from '@docmost/db/repos/ai-chat/ai-chat-run-step.repo';
 import { AiChatPageSnapshotRepo } from '@docmost/db/repos/ai-chat/ai-chat-page-snapshot.repo';
 import { AiProviderCredentialsRepo } from '@docmost/db/repos/ai-chat/ai-provider-credentials.repo';
 import { AiMcpServerRepo } from '@docmost/db/repos/ai-chat/ai-mcp-server.repo';
@@ -125,6 +126,7 @@ import { firstSqlToken } from '../integrations/metrics/metrics.constants';
     AiChatRepo,
     AiChatMessageRepo,
     AiChatRunRepo,
+    AiChatRunStepRepo,
     AiChatPageSnapshotRepo,
     AiProviderCredentialsRepo,
     AiMcpServerRepo,
@@ -161,6 +163,7 @@ import { firstSqlToken } from '../integrations/metrics/metrics.constants';
     AiChatRepo,
     AiChatMessageRepo,
     AiChatRunRepo,
+    AiChatRunStepRepo,
     AiChatPageSnapshotRepo,
     AiProviderCredentialsRepo,
     AiMcpServerRepo,

apps/server/src/database/migrations/20260708T120000-ai-chat-run-steps.ts

@@ -0,0 +1,70 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * `ai_chat_run_steps` — append-only per-step persistence for an assistant turn
+ * (#492 wave C). Each finished agent step's UI `parts` (its text part + a part
+ * per tool call, WITH the tool output) is INSERTed as its own lightweight row the
+ * moment the step ends, instead of REWRITING the whole assistant row's growing
+ * `metadata.parts` jsonb on every `onStepFinish`.
+ *
+ * WHY a separate table + INSERT (not a jsonb `||` append on the message row): a
+ * Postgres jsonb UPDATE rewrites the ENTIRE TOASTed row version under MVCC, so
+ * re-persisting a growing `metadata.parts` on every step is O(n²) write volume
+ * (a 50-step run with ~100 KB tool outputs wrote hundreds of MB of WAL / dead
+ * tuples per turn, hammering autovacuum). `||` would only shave the network
+ * payload — the WAL/TOAST rewrite harm remains. An INSERT into a per-step table
+ * writes ONLY that step's bytes, so the per-turn write volume is O(Σ steps).
+ *
+ * The full `metadata.parts` on the message row is assembled ONCE at finalize (the
+ * terminal completed/error/aborted write). Mid-run, a resuming client's seed is
+ * reconstructed by concatenating these step rows in `step_index` order — which
+ * reproduces exactly what the old per-step full-row rewrite persisted. Records
+ * written the OLD way (full `metadata.parts` on the row, no step rows) still
+ * reconstruct from the row unchanged; the two eras are distinguished by whether
+ * the row already carries non-empty `metadata.parts` (see reconstructRunParts /
+ * assembleStepParts in ai-chat.service.ts).
+ *
+ * ON DELETE CASCADE on `message_id`: the step rows are a derived projection of the
+ * assistant message; they must vanish with it (or with its workspace).
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('ai_chat_run_steps')
+    .ifNotExists()
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    // The assistant message row this step belongs to (the #183 projection). The
+    // step rows are a derived, per-step slice of that message, so they cascade.
+    .addColumn('message_id', 'uuid', (col) =>
+      col.references('ai_chat_messages.id').onDelete('cascade').notNull(),
+    )
+    .addColumn('workspace_id', 'uuid', (col) =>
+      col.references('workspaces.id').onDelete('cascade').notNull(),
+    )
+    // 0-based index of the finished step within the turn. Ordering key for
+    // reconstruction; unique per message (idempotent step re-persist).
+    .addColumn('step_index', 'integer', (col) => col.notNull())
+    // The step's UI parts (text part + a `tool-*` part per call, WITH output).
+    // Concatenated in step order to rebuild the turn's `metadata.parts`.
+    .addColumn('parts', 'jsonb', (col) => col.notNull())
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .execute();
+
+  // Idempotent per-step persist: a retried INSERT of the same (message, step)
+  // is a no-op (the service uses ON CONFLICT DO NOTHING). This also serves the
+  // reconstruction read (WHERE message_id ORDER BY step_index).
+  await db.schema
+    .createIndex('ai_chat_run_steps_message_step_uidx')
+    .ifNotExists()
+    .on('ai_chat_run_steps')
+    .columns(['message_id', 'step_index'])
+    .unique()
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('ai_chat_run_steps').ifExists().execute();
+}

apps/server/src/database/repos/ai-chat/ai-chat-run-step.repo.ts

@@ -0,0 +1,95 @@
+import { Injectable } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
+import { dbOrTx } from '../../utils';
+import { AiChatRunStep } from '@docmost/db/types/entity.types';
+
+/**
+ * Append-only per-step persistence for an assistant turn (#492). Each finished
+ * agent step's UI `parts` (its text part + a `tool-*` part per call, WITH the
+ * tool output) is INSERTed as its own lightweight row the moment the step ends —
+ * instead of REWRITING the assistant row's growing `metadata.parts` jsonb on every
+ * `onStepFinish` (a Postgres jsonb UPDATE rewrites the whole TOASTed row version
+ * under MVCC, so that was O(n²) WAL/dead-tuple churn per turn).
+ *
+ * The full `metadata.parts` on the message row is assembled ONCE at finalize;
+ * mid-run, a resuming client's seed is rebuilt from these rows in `stepIndex`
+ * order (see `assembleStepParts` / the reconstruct seam in ai-chat.service.ts).
+ * Every method is workspace-scoped as defense-in-depth.
+ */
+@Injectable()
+export class AiChatRunStepRepo {
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+
+  /**
+   * Append one finished step's parts. Idempotent: a retried persist of the SAME
+   * (message, stepIndex) is a no-op via ON CONFLICT DO NOTHING — the per-step
+   * writes are fired fire-and-forget + serialized, and a duplicate must never
+   * throw into the stream or double the parts. Returns whether a NEW row landed
+   * (false = the step was already persisted).
+   */
+  async insertStep(
+    messageId: string,
+    workspaceId: string,
+    stepIndex: number,
+    parts: unknown,
+    trx?: KyselyTransaction,
+  ): Promise<boolean> {
+    const db = dbOrTx(this.db, trx);
+    const inserted = await db
+      .insertInto('aiChatRunSteps')
+      .values({
+        messageId,
+        workspaceId,
+        stepIndex,
+        // jsonb column: cast through never (same pattern as the message repo).
+        parts: parts as never,
+      })
+      .onConflict((oc) => oc.columns(['messageId', 'stepIndex']).doNothing())
+      .returning('id')
+      .executeTakeFirst();
+    return inserted !== undefined;
+  }
+
+  /** All persisted steps for ONE assistant message, in step order. */
+  async findByMessage(
+    messageId: string,
+    workspaceId: string,
+  ): Promise<AiChatRunStep[]> {
+    return this.db
+      .selectFrom('aiChatRunSteps')
+      .selectAll('aiChatRunSteps')
+      .where('messageId', '=', messageId)
+      .where('workspaceId', '=', workspaceId)
+      .orderBy('stepIndex', 'asc')
+      .execute();
+  }
+
+  /**
+   * All persisted steps for a SET of assistant messages, grouped by messageId
+   * (each group in step order). One query for the batch — the hydration seam
+   * (getMessages / delta / export) calls this only for the rows that actually
+   * need reconstruction (an active new-style row whose `metadata.parts` is still
+   * empty), which is usually none, so this is skipped on the common path.
+   */
+  async findByMessageIds(
+    messageIds: string[],
+    workspaceId: string,
+  ): Promise<Map<string, AiChatRunStep[]>> {
+    const byMessage = new Map<string, AiChatRunStep[]>();
+    if (messageIds.length === 0) return byMessage;
+    const rows = await this.db
+      .selectFrom('aiChatRunSteps')
+      .selectAll('aiChatRunSteps')
+      .where('messageId', 'in', messageIds)
+      .where('workspaceId', '=', workspaceId)
+      .orderBy('stepIndex', 'asc')
+      .execute();
+    for (const row of rows) {
+      const list = byMessage.get(row.messageId);
+      if (list) list.push(row);
+      else byMessage.set(row.messageId, [row]);
+    }
+    return byMessage;
+  }
+}

apps/server/src/database/types/db.d.ts

@@ -692,6 +692,22 @@ export interface AiChatRuns {
   updatedAt: Generated<Timestamp>;
 }
 
+// Append-only per-step persistence for an assistant turn (#492). Mirrors
+// migration 20260708T120000-ai-chat-run-steps.ts. Each finished agent step's UI
+// `parts` are INSERTed as their own row (instead of rewriting the message row's
+// growing `metadata.parts` jsonb every step — an O(n²) WAL/TOAST churn). The full
+// `metadata.parts` is assembled once at finalize; mid-run a resuming client's seed
+// is rebuilt by concatenating these rows in `stepIndex` order. Cascades with the
+// assistant message row it projects.
+export interface AiChatRunSteps {
+  id: Generated<string>;
+  messageId: string;
+  workspaceId: string;
+  stepIndex: number;
+  parts: Json;
+  createdAt: Generated<Timestamp>;
+}
+
 // Per-(chat,page) snapshot of the open page's Markdown at the END of the agent's
 // previous turn (#274). Mirrors migration 20260702T120000-ai-chat-page-snapshot.ts.
 // The next turn diffs the CURRENT Markdown against `contentMd` to surface edits a
@@ -729,6 +745,7 @@ export interface DB {
   aiChats: AiChats;
   aiChatMessages: AiChatMessages;
   aiChatRuns: AiChatRuns;
+  aiChatRunSteps: AiChatRunSteps;
   aiChatPageSnapshots: AiChatPageSnapshots;
   apiKeys: ApiKeys;
   attachments: Attachments;

apps/server/src/database/types/entity.types.ts

@@ -4,6 +4,7 @@ import {
   AiChats,
   AiChatMessages,
   AiChatRuns,
+  AiChatRunSteps,
   AiChatPageSnapshots,
   Attachments,
   Comments,
@@ -64,6 +65,12 @@ export type InsertableAiChatMessage = Omit<Insertable<AiChatMessages>, 'tsv'>;
 export type AiChatRun = Selectable<AiChatRuns>;
 export type InsertableAiChatRun = Insertable<AiChatRuns>;
 
+// AI Chat Run Step (#492): append-only per-step parts persistence. Each finished
+// agent step's UI parts are stored as their own row; the full turn's parts are
+// assembled from these (in stepIndex order) for a mid-run resume seed.
+export type AiChatRunStep = Selectable<AiChatRunSteps>;
+export type InsertableAiChatRunStep = Insertable<AiChatRunSteps>;
+
 // AI Chat Page Snapshot (#274): per-(chat,page) Markdown snapshot taken at the
 // end of the agent's previous turn, diffed against the current page next turn to
 // detect human edits made between turns.

apps/server/src/integrations/export/internal-link-parity.spec.ts

@@ -1,70 +0,0 @@
-import { INTERNAL_LINK_REGEX } from './utils';
-import { isInternalPagePath } from '@docmost/prosemirror-markdown';
-
-/**
- * Cross-package DRIFT GUARD for the internal-link subset invariant (#522).
- *
- * The client-side `isInternalPagePath`
- * (`packages/prosemirror-markdown/src/lib/internal-links.ts`) promotes a markdown
- * link to `internal: true` on import. Every link it marks internal MUST be one
- * the server would backlink and export-rewrite — i.e. the client matcher MUST be
- * a STRICT SUBSET of the server's canonical `INTERNAL_LINK_REGEX`
- * (`./utils.ts`). If the client ever accepts a path the server rejects, that link
- * is stored internal but silently dropped from the backlink graph and broken on
- * export — the exact bug #522 fixed.
- *
- * This spec is the load-bearing guard: it imports the LIVE server regex AND the
- * LIVE `isInternalPagePath` (no hand-copied regex on either side). A narrowing of
- * EITHER — most dangerously the server regex — reddens here. The in-package
- * accept/reject test documents the client's behaviour but cannot see the server
- * regex; this top-layer spec is what makes the subset relation mechanical
- * (AGENTS.md rule #7: a CI test that fails on drift of the source of truth).
- */
-describe('internal-link subset parity (client isInternalPagePath ⊆ server INTERNAL_LINK_REGEX)', () => {
-  // Every path the CLIENT accepts. Kept deliberately broad across the risky
-  // dimensions — the slug charset (digits, hyphens, mixed case, leading/trailing
-  // hyphen), the space charset, and the optional trailing slash — so a narrowing
-  // of the server regex on any of them reddens the subset assertion below.
-  const CLIENT_ACCEPTS = [
-    '/s/eng/p/abc123',
-    '/s/eng/p/abc123/', // trailing slash
-    '/s/My-Space/p/A-b-C-9', // hyphens + mixed case in both segments
-    '/s/x/p/z', // shortest
-    '/s/eng/p/my-page-abc123', // slug with hyphens (extractPageSlugId shape)
-    '/s/eng/p/-lead', // leading hyphen in slug
-    '/s/eng/p/trail-', // trailing hyphen in slug
-    '/s/eng/p/0123456789', // all-digit slug
-    '/s/a.b/p/abc', // dot in the SPACE segment (space charset is [^/]+)
-    '/s/space with space/p/abc', // space char in the SPACE segment
-  ];
-
-  it('every corpus path is actually client-accepted (guards the corpus itself)', () => {
-    // If a path here stopped being client-accepted the subset test would pass
-    // vacuously; assert acceptance up front so the corpus stays meaningful. The
-    // filter-to-empty form names the offending paths on failure.
-    const notAccepted = CLIENT_ACCEPTS.filter((h) => !isInternalPagePath(h));
-    expect(notAccepted).toEqual([]);
-  });
-
-  it('every client-accepted path also matches the LIVE server regex (subset)', () => {
-    // The mechanical drift guard: narrow the server INTERNAL_LINK_REGEX and at
-    // least one hyphen/charset/structure case appears here.
-    const notInServer = CLIENT_ACCEPTS.filter((h) => !INTERNAL_LINK_REGEX.test(h));
-    expect(notInServer).toEqual([]);
-  });
-
-  it('the client rejects forbidden-slug-char paths the server also rejects', () => {
-    // Documents the subset BOUNDARY: correct shape, forbidden slug char. The
-    // client and the LIVE server regex must agree on rejection.
-    const forbidden = [
-      '/s/eng/p/abc.def',
-      '/s/eng/p/abc_def',
-      '/s/eng/p/abc%20',
-      '/s/eng/p/abc~x',
-    ];
-    const clientAccepts = forbidden.filter((h) => isInternalPagePath(h));
-    const serverAccepts = forbidden.filter((h) => INTERNAL_LINK_REGEX.test(h));
-    expect(clientAccepts).toEqual([]);
-    expect(serverAccepts).toEqual([]);
-  });
-});

apps/server/src/integrations/import/services/import-attachment.service.drawio-svg.spec.ts

@@ -0,0 +1,131 @@
+// p-limit and @sindresorhus/slugify are ESM-only and not in jest's transform
+// allowlist; both are irrelevant to createDrawioSvg (a pure fs + string method),
+// so they are mocked out to keep the module graph loadable under ts-jest.
+jest.mock('p-limit', () => ({
+  __esModule: true,
+  default: () => (fn: () => unknown) => fn(),
+}));
+jest.mock('@sindresorhus/slugify', () => ({
+  __esModule: true,
+  default: (input: string) => String(input),
+}));
+
+import { promises as fs } from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ImportAttachmentService } from './import-attachment.service';
+
+/**
+ * Unit test for ImportAttachmentService.createDrawioSvg (issue #507).
+ *
+ * The Confluence import wraps a `.drawio` file into a `.drawio.svg` attachment.
+ * The `content=` payload MUST be the mxfile XML entity-escaped (draw.io's native
+ * form), NOT base64 — draw.io's editor decodes a base64 content= via Latin-1
+ * atob, mangling every non-ASCII char into mojibake. createDrawioSvg touches no
+ * injected dependency, so the service is built with placeholder deps.
+ */
+describe('ImportAttachmentService.createDrawioSvg (#507)', () => {
+  const service = new ImportAttachmentService(
+    {} as any,
+    {} as any,
+    {} as any,
+  );
+  const call = (p: string): Promise<Buffer> =>
+    (service as any).createDrawioSvg(p);
+
+  let tmpDir: string;
+  beforeAll(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'drawio-507-'));
+  });
+  afterAll(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  const writeDrawio = async (name: string, xml: string): Promise<string> => {
+    const p = path.join(tmpDir, name);
+    await fs.writeFile(p, xml, 'utf-8');
+    return p;
+  };
+
+  it('writes content= as entity-encoded XML, not base64', async () => {
+    const drawio =
+      '<mxfile host="Confluence"><diagram name="Схема — ёж">' +
+      '<mxGraphModel><root><mxCell id="0"/>' +
+      '<mxCell id="2" value="Старт-бит" vertex="1" parent="0"/>' +
+      '</root></mxGraphModel></diagram></mxfile>';
+    const p = await writeDrawio('cyrillic.drawio', drawio);
+
+    const svg = (await call(p)).toString('utf-8');
+    const content = /content="([^"]*)"/.exec(svg)?.[1];
+    expect(content).toBeDefined();
+
+    // Entity-encoded XML form, starting with &lt;mxfile — never a base64 blob.
+    expect(content).toMatch(/^&lt;mxfile/);
+    expect(content).toContain('&lt;');
+    // Non-ASCII survives as raw UTF-8, with no Latin-1 mojibake.
+    expect(content).toContain('Старт-бит');
+    expect(content).toContain('Схема — ёж');
+    expect(content).not.toContain('Ð');
+
+    // Decoding the attribute (un-escaping) yields the original drawio file.
+    const decoded = content!
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, '&');
+    expect(decoded).toBe(drawio);
+  });
+
+  it('encodes literal tab/newline/CR as numeric char-refs, not literal control chars (#507 F1)', async () => {
+    // A literal tab/newline/CR inside the mxfile XML would be collapsed to a
+    // single space by XML attribute-value normalization when the draw.io editor
+    // reads content=, silently flattening multi-line labels and tab-bearing
+    // values. They must be emitted as numeric char-refs instead.
+    const drawio =
+      '<mxfile><diagram name="p">' +
+      '<mxGraphModel><root><mxCell id="0"/>' +
+      '<mxCell id="2" value="col1\tcol2" style="html=1;\nshadow=0" vertex="1" parent="0"/>' +
+      '<mxCell id="3" value="Line1\nLine2\rLine3" vertex="1" parent="0"/>' +
+      '</root></mxGraphModel></diagram></mxfile>';
+    const p = await writeDrawio('ctrl.drawio', drawio);
+
+    const svg = (await call(p)).toString('utf-8');
+    const content = /content="([^"]*)"/.exec(svg)?.[1];
+    expect(content).toBeDefined();
+    // No literal control chars survive in the attribute value.
+    expect(content).not.toMatch(/[\t\n\r]/);
+    // They round-trip as numeric char-refs.
+    expect(content).toContain('&#x9;');
+    expect(content).toContain('&#xa;');
+    expect(content).toContain('&#xd;');
+    // Decoding (char-refs back to literal, entities back) recovers the file.
+    const decoded = content!
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&#x9;/gi, '\t')
+      .replace(/&#xa;/gi, '\n')
+      .replace(/&#xd;/gi, '\r')
+      .replace(/&amp;/g, '&');
+    expect(decoded).toBe(drawio);
+  });
+
+  it('escapes XML metacharacters in the drawio payload', async () => {
+    const drawio = '<mxfile><diagram name="a &amp; b">"q" &lt;x&gt;</diagram></mxfile>';
+    const p = await writeDrawio('meta.drawio', drawio);
+
+    const svg = (await call(p)).toString('utf-8');
+    const content = /content="([^"]*)"/.exec(svg)?.[1];
+    expect(content).toBeDefined();
+    // The attribute value must contain no bare `<`, `>` or `"` that would break
+    // out of the content="..." attribute or the SVG element.
+    expect(content).not.toMatch(/[<>"]/);
+    const decoded = content!
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, '&');
+    expect(decoded).toBe(drawio);
+  });
+});

apps/server/src/integrations/import/services/import-attachment.service.ts

@@ -8,6 +8,7 @@ import { createReadStream } from 'node:fs';
 import { promises as fs } from 'fs';
 import { Readable } from 'stream';
 import { getMimeType, sanitizeFileName } from '../../../common/helpers';
+import { htmlEscape } from '../../../common/helpers/html-escaper';
 import { v7 } from 'uuid';
 import { FileTask } from '@docmost/db/types/entity.types';
 import { getAttachmentFolderPath } from '../../../core/attachment/attachment.utils';
@@ -849,7 +850,12 @@ export class ImportAttachmentService {
   ): Promise<Buffer> {
     try {
       const drawioContent = await fs.readFile(drawioPath, 'utf-8');
-      const drawioBase64 = Buffer.from(drawioContent).toString('base64');
+      // Write the mxfile XML XML-entity-escaped (draw.io's native content= form),
+      // NOT base64. draw.io's editor decodes a base64 content= via Latin-1 atob
+      // (no UTF-8 step), turning every non-ASCII char (Cyrillic, ё, —) into
+      // mojibake; the entity-encoded form is decoded by the DOM as UTF-8 and
+      // opens intact. Docmost's own decoder reads both forms.
+      const drawioEscaped = this.xmlEscapeContent(drawioContent);
 
       let imageElement = '';
       // If we have a PNG, include it in the SVG
@@ -875,7 +881,7 @@ export class ImportAttachmentService {
       width="600"
       height="400"
       viewBox="0 0 600 400"
-      content="${drawioBase64}">${imageElement}</svg>`;
+      content="${drawioEscaped}">${imageElement}</svg>`;
 
       return Buffer.from(svgContent, 'utf-8');
     } catch (error) {
@@ -884,6 +890,24 @@ export class ImportAttachmentService {
     }
   }
 
+  /**
+   * Escape a string so it is safe as the value of a double-quoted XML attribute
+   * (the `content=` payload of a `.drawio.svg`). The shared `htmlEscape` covers
+   * `& < > " '` (a strict superset of what this attribute needs; the extra `'`
+   * escape is harmless in a `"`-delimited value). On top of that, the numeric
+   * char-refs for tab/newline/CR are required: a literal tab/newline/CR inside
+   * an attribute value is collapsed to a single space by XML attribute-value
+   * normalization on DOM read (both our decoder and the real draw.io editor),
+   * silently flattening multi-line labels and tab-bearing values. Char-refs
+   * survive that normalization (#507).
+   */
+  private xmlEscapeContent(s: string): string {
+    return htmlEscape(s)
+      .replace(/\t/g, '&#x9;')
+      .replace(/\n/g, '&#xa;')
+      .replace(/\r/g, '&#xd;');
+  }
+
   private async uploadWithRetry(opts: {
     abs: string;
     storageFilePath: string;

apps/server/test/integration/ai-chat-append-persist-service.int-spec.ts

@@ -0,0 +1,412 @@
+import * as http from 'node:http';
+import { Kysely } from 'kysely';
+import { tool } from 'ai';
+import { z } from 'zod';
+import { MockLanguageModelV3, convertArrayToReadableStream } from 'ai/test';
+import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
+import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import { AiChatRunStepRepo } from '@docmost/db/repos/ai-chat/ai-chat-run-step.repo';
+import {
+  AiChatService,
+  assembleStepParts,
+  assistantParts,
+  rowHasInlineParts,
+  stepMarkerMetadata,
+} from 'src/core/ai-chat/ai-chat.service';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createUser,
+  createChat,
+  createMessage,
+} from './db';
+
+/**
+ * #492 append-persist — the REAL onStep WRITE path (F2) and the model-REPLAY
+ * hydration path (F1), driven through `AiChatService.stream` against a LIVE
+ * Postgres with a REAL `AiChatRunStepRepo` INJECTED. The existing append-persist
+ * int-specs hand-roll the insert+marker cycle via the repos directly and build
+ * the service with `aiChatRunStepRepo: undefined` (only the legacy-fallback branch
+ * is covered), so an off-by-one on `stepsPersisted-1`, a wrong `capturedSteps`
+ * slice, or a broken marker payload would pass all of them. These tests exercise
+ * the actual `updateStreaming` append-persist branch end to end.
+ *
+ * The seam is the injected `model` (a seeded `MockLanguageModelV3` from `ai/test`)
+ * plus a REAL Node `ServerResponse` as the hijacked socket — mirrors
+ * ai-chat-stream.int-spec.ts.
+ */
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function waitFor(
+  cond: () => Promise<boolean> | boolean,
+  { timeoutMs = 15_000, stepMs = 25 } = {},
+): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await cond()) return;
+    await sleep(stepMs);
+  }
+  throw new Error('waitFor: condition not met within timeout');
+}
+
+// A real Node ServerResponse wired to a live socket (identical helper to the
+// stream int-spec) so the SDK's pipe/heartbeat writes behave as in prod.
+function makeRealResponse(): Promise<{
+  res: http.ServerResponse;
+  cleanup: () => Promise<void>;
+}> {
+  return new Promise((resolve) => {
+    const server = http.createServer((_req, res) => {
+      resolve({
+        res,
+        cleanup: () =>
+          new Promise<void>((done) => {
+            try {
+              if (!res.writableEnded) res.end();
+            } catch {
+              /* socket already gone */
+            }
+            server.close(() => done());
+          }),
+      });
+    });
+    server.listen(0, () => {
+      const port = (server.address() as any).port;
+      const creq = http.request({ port, method: 'GET' }, (cres) => {
+        cres.resume();
+      });
+      creq.on('error', () => undefined);
+      creq.end();
+    });
+  });
+}
+
+// Stream parts for a normal, successful single-step turn.
+function successStream() {
+  return convertArrayToReadableStream([
+    { type: 'stream-start', warnings: [] },
+    { type: 'text-start', id: 't1' },
+    { type: 'text-delta', id: 't1', delta: 'Hello' },
+    { type: 'text-delta', id: 't1', delta: ' there' },
+    { type: 'text-end', id: 't1' },
+    {
+      type: 'finish',
+      finishReason: 'stop',
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+    },
+  ] as any);
+}
+
+// A THREE-step turn: steps 0 and 1 each emit text + an `echo` tool call (the SDK
+// runs the tool and continues); step 2 answers and stops. Three steps is
+// deliberate: the LAST finished step's append-persist write races the terminal
+// finalize (which writes the full inline parts anyway, so a lost last-step row is
+// by design), but the NON-final steps 0 and 1 always drain to the steps table
+// before finalize — so those are what the test asserts on deterministically.
+function threeStepModel(): MockLanguageModelV3 {
+  let step = 0;
+  const toolStep = (i: number) => ({
+    stream: convertArrayToReadableStream([
+      { type: 'stream-start', warnings: [] },
+      { type: 'text-start', id: `s${i}` },
+      { type: 'text-delta', id: `s${i}`, delta: `step ${i} ` },
+      { type: 'text-end', id: `s${i}` },
+      {
+        type: 'tool-call',
+        toolCallId: `c${i}`,
+        toolName: 'echo',
+        input: JSON.stringify({ msg: `m${i}` }),
+      },
+      {
+        type: 'finish',
+        finishReason: 'tool-calls',
+        usage: { inputTokens: 5, outputTokens: 3, totalTokens: 8 },
+      },
+    ] as any),
+  });
+  return new MockLanguageModelV3({
+    doStream: async () => {
+      const n = step++;
+      // Realistic inter-step latency. A real model spends seconds per step, so the
+      // fire-and-forget per-step write chain drains to the steps table BETWEEN
+      // steps; the mock otherwise collapses all steps into microseconds and the
+      // terminal finalize wins the race before any but the first step persists.
+      if (n > 0) await sleep(200);
+      if (n < 2) return toolStep(n);
+      return {
+        stream: convertArrayToReadableStream([
+          { type: 'stream-start', warnings: [] },
+          { type: 'text-start', id: 's2' },
+          { type: 'text-delta', id: 's2', delta: 'final answer' },
+          { type: 'text-end', id: 's2' },
+          {
+            type: 'finish',
+            finishReason: 'stop',
+            usage: { inputTokens: 6, outputTokens: 4, totalTokens: 10 },
+          },
+        ] as any),
+      };
+    },
+  } as any);
+}
+
+describe('#492 append-persist service paths [integration]', () => {
+  let db: Kysely<any>;
+  let aiChatRepo: AiChatRepo;
+  let msgRepo: AiChatMessageRepo;
+  let stepRepo: AiChatRunStepRepo;
+  let workspaceId: string;
+  let userId: string;
+
+  let closeCalls: number;
+  const mcpClients = {
+    toolsFor: async () => ({
+      tools: {},
+      clients: [
+        {
+          close: async () => {
+            closeCalls += 1;
+          },
+        },
+      ],
+      outcomes: [],
+      instructions: [],
+    }),
+  };
+
+  // Build the service WITH a REAL AiChatRunStepRepo injected (the property under
+  // test) — unlike the legacy-fallback harness that passes it as undefined.
+  const echoTool = tool({
+    description: 'echo the message back',
+    inputSchema: z.object({ msg: z.string() }),
+    execute: async ({ msg }) => ({ echoed: msg }),
+  });
+
+  function buildService(): AiChatService {
+    return new AiChatService(
+      { getChatModel: async () => null } as any,
+      aiChatRepo,
+      msgRepo,
+      {} as any, // aiChatPageSnapshotRepo
+      { resolve: async () => null } as any, // aiSettings
+      { forUser: async () => ({ echo: echoTool }) } as any, // tools
+      mcpClients as any,
+      {} as any, // aiAgentRoleRepo
+      {} as any, // pageRepo
+      {} as any, // pageAccess
+      {
+        isAiChatDeferredToolsEnabled: () => false,
+        isAiChatFinalStepLockdownEnabled: () => false,
+      } as any, // environment (deferred OFF -> all tools active every step)
+      undefined, // streamRegistry
+      undefined, // aiChatRunService
+      stepRepo, // #492 aiChatRunStepRepo — the append-persist backend
+    );
+  }
+
+  function userUiMessage(text: string) {
+    return {
+      id: `u-${Math.random()}`,
+      role: 'user',
+      parts: [{ type: 'text', text }],
+    };
+  }
+
+  async function runStream(opts: {
+    model: MockLanguageModelV3;
+    chatId: string;
+    body: any;
+  }): Promise<void> {
+    closeCalls = 0;
+    const service = buildService();
+    const { res, cleanup } = await makeRealResponse();
+    try {
+      await service.stream({
+        user: { id: userId, workspaceId } as any,
+        workspace: { id: workspaceId, name: 'WS' } as any,
+        sessionId: 'sess-1',
+        body: opts.body,
+        res: { raw: res } as any,
+        signal: new AbortController().signal,
+        model: opts.model as any,
+        role: null,
+      } as any);
+      await waitFor(async () => {
+        const rows = await msgRepo.findAllByChat(opts.chatId, workspaceId);
+        return rows.some(
+          (r) =>
+            r.role === 'assistant' &&
+            ['completed', 'error', 'aborted'].includes(r.status as string),
+        );
+      });
+      await waitFor(() => closeCalls > 0, { timeoutMs: 5_000 });
+    } finally {
+      await cleanup();
+    }
+  }
+
+  beforeAll(async () => {
+    db = getTestDb();
+    aiChatRepo = new AiChatRepo(db as any);
+    msgRepo = new AiChatMessageRepo(db as any);
+    stepRepo = new AiChatRunStepRepo(db as any);
+    workspaceId = (await createWorkspace(db)).id;
+    userId = (await createUser(db, workspaceId)).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  // --- F2: the real onStep append-persist WRITE branch -----------------------
+  it('drives steps through the real onStep path: per-step rows + marker match a single-row flush', async () => {
+    const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
+    const model = threeStepModel();
+
+    // Capture the mid-run step-marker UPDATEs the append-persist branch writes on
+    // the assistant row (a { parts: [], toolTraceVersion, stepsPersisted } patch).
+    const updateSpy = jest.spyOn(msgRepo, 'update');
+    try {
+      await runStream({
+        model,
+        chatId,
+        body: { chatId, messages: [userUiMessage('call the tool then answer')] },
+      });
+
+      const rows = await msgRepo.findAllByChat(chatId, workspaceId);
+      const assistant = rows.find((r) => r.role === 'assistant')!;
+      expect(assistant).toBeDefined();
+      expect(assistant.status).toBe('completed');
+      // The turn finalizes with the FULL inline parts assembled by a single-row
+      // flush (assistantParts over every step) — the baseline the per-step slices
+      // must reproduce.
+      expect(rowHasInlineParts(assistant)).toBe(true);
+      const finalParts = (assistant.metadata as { parts: any[] }).parts;
+
+      // The two NON-final finished steps each landed their own row, in stepIndex
+      // order. (The fire-and-forget write chain drains before the next step, so
+      // poll until both are on disk; the LAST step's write may lose the finalize
+      // race, which is by design — its parts are already in `finalParts`.)
+      await waitFor(async () => {
+        const s = await stepRepo.findByMessage(assistant.id, workspaceId);
+        return s.length >= 2;
+      });
+      const steps = await stepRepo.findByMessage(assistant.id, workspaceId);
+      expect(steps[0].stepIndex).toBe(0);
+      expect(steps[1].stepIndex).toBe(1);
+
+      // Each per-step row carries a NON-trivial slice: this step's text part + its
+      // paired tool part (guards a mutation that persists empty/whole-turn parts).
+      const s0 = steps[0].parts as any[];
+      expect(s0).toContainEqual({ type: 'text', text: 'step 0 ' });
+      expect(s0.some((p) => p.type === 'tool-echo')).toBe(true);
+
+      // The per-step slices are EXACTLY the corresponding prefix of the single-row
+      // flush: assembleStepParts([step0, step1]) === finalParts[0 .. len0+len1].
+      // This is what an off-by-one on `stepsPersisted-1` (a wrong `capturedSteps`
+      // slice) or a shifted stepIndex breaks — the prefix no longer aligns.
+      const prefixLen =
+        (steps[0].parts as any[]).length + (steps[1].parts as any[]).length;
+      expect(assembleStepParts([steps[0], steps[1]] as any)).toEqual(
+        finalParts.slice(0, prefixLen),
+      );
+
+      // The mid-run step markers advanced 1 -> 2 -> ... (the resume frontier), each
+      // a shape-stable empty-parts marker equal to a single-row flush's marker.
+      const markerCounts = updateSpy.mock.calls
+        .map((c) => (c[2] as any)?.metadata)
+        .filter(
+          (m) =>
+            m &&
+            Array.isArray(m.parts) &&
+            m.parts.length === 0 &&
+            typeof m.stepsPersisted === 'number',
+        )
+        .map((m) => m.stepsPersisted);
+      // Monotonic from 1, covering at least the two non-final steps.
+      expect(markerCounts.slice(0, 2)).toEqual([1, 2]);
+      expect(
+        updateSpy.mock.calls
+          .map((c) => (c[2] as any)?.metadata)
+          .find((m) => m && m.stepsPersisted === 2),
+      ).toEqual(stepMarkerMetadata(2));
+    } finally {
+      updateSpy.mockRestore();
+    }
+  }, 60_000);
+
+  // --- F1: model-REPLAY hydrates a hard-crashed mid-run turn from the steps table
+  it('replays a hard-crashed mid-run turn WITH its partial steps hydrated from the steps table', async () => {
+    const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
+
+    // Prior turn: a genuine user question...
+    await createMessage(db, {
+      workspaceId,
+      chatId,
+      userId,
+      role: 'user',
+      content: 'What is in the design doc?',
+      createdAt: new Date(Date.now() - 3000),
+    });
+    // ...and an assistant row that a HARD crash (SIGKILL/OOM) left mid-run: only a
+    // step marker on the row (metadata.parts:[] , content:''), NO terminal
+    // callback ever fired, so its real parts live ONLY in ai_chat_run_steps.
+    const crashed = await createMessage(db, {
+      workspaceId,
+      chatId,
+      role: 'assistant',
+      content: '',
+      status: 'aborted',
+      metadata: stepMarkerMetadata(1),
+      createdAt: new Date(Date.now() - 2000),
+    });
+    // The durable partial step: some reasoning text + a completed getPage tool
+    // call (input + output), exactly what #183 step-granular durability preserves.
+    await stepRepo.insertStep(
+      crashed.id,
+      workspaceId,
+      0,
+      assistantParts(
+        [
+          {
+            text: 'HYDRATED_PARTIAL_STEP the doc says',
+            toolCalls: [
+              { toolCallId: 'g1', toolName: 'getPage', input: { id: 'p1' } },
+            ],
+            toolResults: [
+              {
+                toolCallId: 'g1',
+                toolName: 'getPage',
+                output: { id: 'p1', body: 'PARTIAL_TOOL_OUTPUT budget section' },
+              },
+            ],
+          } as any,
+        ],
+        '',
+      ),
+    );
+
+    // The NEXT turn: the model just answers. The service must REPLAY the crashed
+    // assistant turn with its partial parts hydrated from the steps table.
+    const model = new MockLanguageModelV3({
+      doStream: async () => ({ stream: successStream() }),
+    } as any);
+    await runStream({
+      model,
+      chatId,
+      body: { chatId, messages: [userUiMessage('Continue please')] },
+    });
+
+    expect(model.doStreamCalls.length).toBeGreaterThan(0);
+    const prompt = JSON.stringify(model.doStreamCalls[0].prompt);
+    // The partial step's TEXT reached the model context (it would be an empty text
+    // part without hydration — rowToUiMessage falls back to `content:''`).
+    expect(prompt).toContain('HYDRATED_PARTIAL_STEP');
+    // The partial TOOL RESULT survived too (durable in the steps table, replayed).
+    expect(prompt).toContain('PARTIAL_TOOL_OUTPUT');
+    // The genuine prior user turn is present as well (sanity: real history replay).
+    expect(prompt).toContain('What is in the design doc?');
+  }, 60_000);
+});

apps/server/test/integration/ai-chat-append-persist-wal.int-spec.ts

@@ -0,0 +1,173 @@
+import { randomBytes } from 'crypto';
+import { Kysely, sql } from 'kysely';
+import { AiChatRunStepRepo } from '@docmost/db/repos/ai-chat/ai-chat-run-step.repo';
+import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import {
+  assistantParts,
+  flushAssistant,
+  stepMarkerMetadata,
+} from '../../src/core/ai-chat/ai-chat.service';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createUser,
+  createChat,
+} from './db';
+
+/**
+ * #492 append-persist — WRITE-VOLUME regression on a LIVE Postgres, measured via
+ * the `pg_current_wal_lsn()` delta around a realistic multi-step run driven through
+ * the REAL repos (not a mock — a mock cannot observe MVCC/TOAST rewrite volume, the
+ * whole point). Proves the core claim:
+ *
+ *   NEW (per-step INSERT into ai_chat_run_steps + a CHEAP step-marker UPDATE on the
+ *   message row) writes O(Σ steps) of WAL — each step writes only its own bytes.
+ *
+ *   OLD (the pre-#492 full-row rewrite: re-persist the GROWING metadata.parts on
+ *   every onStepFinish) writes O(n²) — step k rewrites the whole TOASTed jsonb of
+ *   all k prior outputs.
+ *
+ * The OLD path here IS the reverted behavior, so this doubles as the mutation
+ * check: swapping the new path back to `flushAssistant` full-row UPDATEs reddens
+ * the assertion (OLD is many times larger).
+ */
+type Step = {
+  text: string;
+  toolCalls: Array<{ toolCallId: string; toolName: string; input: unknown }>;
+  toolResults: Array<{ toolCallId: string; toolName: string; output: unknown }>;
+};
+
+// ~100 KB INCOMPRESSIBLE output per step (a page read). Random base64 so TOAST
+// cannot compress it away and hide the real write volume.
+function makeStep(i: number, outputBytes = 100_000): Step {
+  const body = randomBytes(Math.ceil(outputBytes * 0.75)).toString('base64');
+  return {
+    text: `step ${i} reasoning`,
+    toolCalls: [
+      { toolCallId: `c${i}`, toolName: 'getPage', input: { id: `p${i}` } },
+    ],
+    toolResults: [
+      {
+        toolCallId: `c${i}`,
+        toolName: 'getPage',
+        output: { id: `p${i}`, title: `Page ${i}`, body },
+      },
+    ],
+  };
+}
+
+async function walDelta(
+  db: Kysely<any>,
+  fn: () => Promise<void>,
+): Promise<number> {
+  const before = (
+    await sql<{ l: string }>`select pg_current_wal_lsn() as l`.execute(db)
+  ).rows[0].l;
+  await fn();
+  // NOTE: no pg_switch_wal() — a segment switch pads the LSN to the next 16 MB
+  // boundary and would swamp the delta. The raw LSN advances by the WAL bytes.
+  const after = (
+    await sql<{ l: string }>`select pg_current_wal_lsn() as l`.execute(db)
+  ).rows[0].l;
+  return Number(
+    (
+      await sql<{
+        d: string;
+      }>`select pg_wal_lsn_diff(${after}::pg_lsn, ${before}::pg_lsn) as d`.execute(
+        db,
+      )
+    ).rows[0].d,
+  );
+}
+
+describe('#492 append-persist write volume (pg_current_wal_lsn delta) [integration]', () => {
+  let db: Kysely<any>;
+  let stepRepo: AiChatRunStepRepo;
+  let msgRepo: AiChatMessageRepo;
+  let workspaceId: string;
+  let userId: string;
+  let chatId: string;
+
+  beforeAll(async () => {
+    db = getTestDb();
+    stepRepo = new AiChatRunStepRepo(db as any);
+    msgRepo = new AiChatMessageRepo(db as any);
+    workspaceId = (await createWorkspace(db)).id;
+    userId = (await createUser(db, workspaceId)).id;
+    chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  const seedRow = () =>
+    msgRepo.insert({
+      chatId,
+      workspaceId,
+      userId,
+      role: 'assistant',
+      content: '',
+      status: 'streaming',
+      metadata: stepMarkerMetadata(0) as never,
+    });
+
+  const STEPS = 40;
+
+  it('NEW per-step INSERT is O(Σ steps); OLD full-row rewrite is O(n²)', async () => {
+    const steps: Step[] = [];
+    for (let i = 0; i < STEPS; i++) steps.push(makeStep(i));
+
+    // NEW: per-step INSERT of THIS step's parts + a cheap marker UPDATE.
+    const newRow = await seedRow();
+    const newWal = await walDelta(db, async () => {
+      for (let i = 0; i < STEPS; i++) {
+        await stepRepo.insertStep(
+          newRow.id,
+          workspaceId,
+          i,
+          assistantParts([steps[i]], ''),
+        );
+        await msgRepo.update(
+          newRow.id,
+          workspaceId,
+          { metadata: stepMarkerMetadata(i + 1) },
+          { onlyIfStreaming: true },
+        );
+      }
+    });
+
+    // OLD (the pre-#492 revert): re-persist the GROWING metadata.parts on the
+    // message row on every step.
+    const oldRow = await seedRow();
+    const oldWal = await walDelta(db, async () => {
+      const acc: Step[] = [];
+      for (let i = 0; i < STEPS; i++) {
+        acc.push(steps[i]);
+        await msgRepo.update(
+          oldRow.id,
+          workspaceId,
+          flushAssistant(acc as never, '', 'streaming'),
+          { onlyIfStreaming: true },
+        );
+      }
+    });
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `[#492 WAL] ${STEPS} steps ×100KB: new=${(newWal / 1e6).toFixed(1)}MB ` +
+        `old=${(oldWal / 1e6).toFixed(1)}MB (${(oldWal / newWal).toFixed(
+          1,
+        )}x smaller)`,
+    );
+
+    // O(Σ steps): ~STEPS × (100KB output + marker) of WAL. 40 × ~100KB parts plus
+    // 40 tiny markers is a few tens of MB at most — bounded, linear in step count.
+    expect(newWal).toBeLessThan(30_000_000);
+    // O(n²): step k rewrites ~k × 100KB. Σ over 40 steps ≈ 80+ MB — far larger.
+    expect(oldWal).toBeGreaterThan(30_000_000);
+    // The load-bearing claim: the new path writes a small FRACTION of the old.
+    expect(newWal).toBeLessThan(oldWal * 0.35);
+  }, 120_000);
+});

apps/server/test/integration/ai-chat-hydrate-controller.int-spec.ts

@@ -0,0 +1,169 @@
+import { Kysely } from 'kysely';
+import { AiChatController } from 'src/core/ai-chat/ai-chat.controller';
+import {
+  assembleStepParts,
+  assistantParts,
+  stepMarkerMetadata,
+} from 'src/core/ai-chat/ai-chat.service';
+import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
+import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import { AiChatRunStepRepo } from '@docmost/db/repos/ai-chat/ai-chat-run-step.repo';
+import type { User, Workspace } from '@docmost/db/types/entity.types';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createUser,
+  createChat,
+  createMessage,
+} from './db';
+
+/**
+ * #492 controller hydration (crash-before-finalize RESUME) on a LIVE Postgres.
+ * `AiChatController.withReconstructedParts` is wired into getMessages/delta/export/
+ * run, but `aiChatRunStepRepo` is OPTIONAL and every controller unit spec passes it
+ * as `undefined`, so the hydration branch early-returns and NEVER executes in those
+ * tests. This drives the real read path — a mid-run streaming row (marker only,
+ * empty inline parts) PLUS its `ai_chat_run_steps` rows — through getMessages WITH
+ * the repo present, exercising the `role==='assistant' && !rowHasInlineParts`
+ * needy predicate, the workspace-scoped batch step fetch, and the endpoint binding.
+ */
+describe('#492 controller hydration read path [integration]', () => {
+  let db: Kysely<any>;
+  let aiChatRepo: AiChatRepo;
+  let msgRepo: AiChatMessageRepo;
+  let stepRepo: AiChatRunStepRepo;
+  let workspaceId: string;
+  let otherWorkspaceId: string;
+  let userId: string;
+
+  // Build the controller WITH a real AiChatRunStepRepo injected (position 9), the
+  // seam the unit specs leave undefined. Only the read-path deps are real.
+  function buildController(): AiChatController {
+    return new AiChatController(
+      {} as any, // aiChatService
+      {} as any, // aiChatRunService
+      aiChatRepo,
+      msgRepo,
+      {} as any, // aiTranscription
+      {} as any, // pageRepo
+      undefined, // streamRegistry
+      undefined, // environment
+      stepRepo, // #492 aiChatRunStepRepo
+    );
+  }
+
+  beforeAll(async () => {
+    db = getTestDb();
+    aiChatRepo = new AiChatRepo(db as any);
+    msgRepo = new AiChatMessageRepo(db as any);
+    stepRepo = new AiChatRunStepRepo(db as any);
+    workspaceId = (await createWorkspace(db)).id;
+    otherWorkspaceId = (await createWorkspace(db)).id;
+    userId = (await createUser(db, workspaceId)).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  it('getMessages reconstructs a mid-run row from the steps table (finished rows untouched)', async () => {
+    const chatId = (
+      await createChat(db, { workspaceId, creatorId: userId })
+    ).id;
+    const user = { id: userId } as User;
+    const workspace = { id: workspaceId } as Workspace;
+
+    // A prior FINISHED assistant row that already carries inline parts — the needy
+    // predicate must SKIP it (no step fetch), returned untouched.
+    const finishedParts = assistantParts(
+      [{ text: 'done earlier', toolCalls: [], toolResults: [] } as any],
+      '',
+    );
+    await createMessage(db, {
+      workspaceId,
+      chatId,
+      role: 'assistant',
+      content: 'done earlier',
+      status: 'completed',
+      metadata: { parts: finishedParts, toolTraceVersion: 2, stepsPersisted: 1 },
+      createdAt: new Date(Date.now() - 3000),
+    });
+
+    // The mid-run row a crash-before-finalize left behind: a step marker only
+    // (parts:[] , content:''), status 'streaming'. Its real parts live ONLY in the
+    // steps table.
+    const midRun = await createMessage(db, {
+      workspaceId,
+      chatId,
+      role: 'assistant',
+      content: '',
+      status: 'streaming',
+      metadata: stepMarkerMetadata(2),
+      createdAt: new Date(Date.now() - 1000),
+    });
+
+    const step0 = assistantParts(
+      [
+        {
+          text: 'reasoning about the page',
+          toolCalls: [
+            { toolCallId: 'g1', toolName: 'getPage', input: { id: 'p1' } },
+          ],
+          toolResults: [
+            { toolCallId: 'g1', toolName: 'getPage', output: { id: 'p1', body: 'B' } },
+          ],
+        } as any,
+      ],
+      '',
+    );
+    const step1 = assistantParts(
+      [{ text: 'partial synthesis so far', toolCalls: [], toolResults: [] } as any],
+      '',
+    );
+    await stepRepo.insertStep(midRun.id, workspaceId, 0, step0);
+    await stepRepo.insertStep(midRun.id, workspaceId, 1, step1);
+
+    // Workspace-scoping guard: a step row for the SAME message id under a DIFFERENT
+    // workspace must NEVER leak into this workspace's reconstruction.
+    await stepRepo.insertStep(midRun.id, otherWorkspaceId, 99, [
+      { type: 'text', text: 'FOREIGN_WORKSPACE_LEAK' },
+    ]);
+
+    const res = await buildController().getMessages(
+      { chatId } as any,
+      { limit: 50 } as any,
+      user,
+      workspace,
+    );
+
+    const items = res.items as any[];
+    const finished = items.find((r) => r.status === 'completed');
+    const reconstructed = items.find((r) => r.id === midRun.id);
+
+    // The finished row passed through with its inline parts unchanged.
+    expect(finished.metadata.parts).toEqual(finishedParts);
+
+    // The mid-run row's parts were reconstructed from the two step rows, in order,
+    // exactly as assembleStepParts concatenates them — the client seed sees the
+    // persisted progress with no change to itself.
+    const expected = assembleStepParts([
+      { stepIndex: 0, parts: step0 },
+      { stepIndex: 1, parts: step1 },
+    ] as any);
+    expect(reconstructed.metadata.parts).toEqual(expected);
+    // The foreign-workspace step row did NOT leak in.
+    expect(JSON.stringify(reconstructed.metadata.parts)).not.toContain(
+      'FOREIGN_WORKSPACE_LEAK',
+    );
+    // Sanity: reconstruction produced real content (text + the paired tool part +
+    // the second step's text), not an empty fallback.
+    expect(reconstructed.metadata.parts).toContainEqual({
+      type: 'text',
+      text: 'reasoning about the page',
+    });
+    expect(
+      (reconstructed.metadata.parts as any[]).some((p) => p.type === 'tool-getPage'),
+    ).toBe(true);
+  }, 60_000);
+});

apps/server/test/integration/ai-chat-run-step-repo.int-spec.ts

@@ -0,0 +1,163 @@
+import { randomBytes } from 'crypto';
+import { Kysely } from 'kysely';
+import { AiChatRunStepRepo } from '@docmost/db/repos/ai-chat/ai-chat-run-step.repo';
+import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import {
+  assistantParts,
+  reconstructRunParts,
+  hydrateAssistantParts,
+  stepMarkerMetadata,
+  rowHasInlineParts,
+} from '../../src/core/ai-chat/ai-chat.service';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createUser,
+  createChat,
+} from './db';
+
+/**
+ * #492 append-persist — the reconstruct CONTRACT on a live Postgres. Proves that a
+ * turn persisted the NEW way (per-step rows in `ai_chat_run_steps`, only a step
+ * marker on the message row) reconstructs to the SAME UI parts as a turn persisted
+ * the OLD way (full `metadata.parts` inline on the row, no step rows) — so the
+ * era-switch is invisible to attach / delta-poll / export. Real repos + real jsonb
+ * roundtrip, not a mock (a mock cannot prove the parts survive the jsonb column
+ * byte-identical).
+ */
+type Step = {
+  text: string;
+  toolCalls: Array<{ toolCallId: string; toolName: string; input: unknown }>;
+  toolResults: Array<{ toolCallId: string; toolName: string; output: unknown }>;
+};
+
+// A realistic step: some text + a getPage tool call whose ~100 KB body is
+// INCOMPRESSIBLE random base64 (a 'x'.repeat filler would TOAST away and hide the
+// real bytes). Under MAX_TOOL_OUTPUT_BYTES (200 KB) it is stored uncompacted.
+function makeStep(i: number, outputBytes = 4_000): Step {
+  const body = randomBytes(Math.ceil(outputBytes * 0.75)).toString('base64');
+  return {
+    text: `step ${i} text`,
+    toolCalls: [
+      { toolCallId: `c${i}`, toolName: 'getPage', input: { id: `p${i}` } },
+    ],
+    toolResults: [
+      {
+        toolCallId: `c${i}`,
+        toolName: 'getPage',
+        output: { id: `p${i}`, title: `Page ${i}`, body },
+      },
+    ],
+  };
+}
+
+describe('AiChatRunStepRepo + reconstruct contract [integration]', () => {
+  let db: Kysely<any>;
+  let stepRepo: AiChatRunStepRepo;
+  let msgRepo: AiChatMessageRepo;
+  let workspaceId: string;
+  let userId: string;
+  let chatId: string;
+
+  beforeAll(async () => {
+    db = getTestDb();
+    stepRepo = new AiChatRunStepRepo(db as any);
+    msgRepo = new AiChatMessageRepo(db as any);
+    workspaceId = (await createWorkspace(db)).id;
+    userId = (await createUser(db, workspaceId)).id;
+    chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  const seedRow = (metadata: unknown, status: string) =>
+    msgRepo.insert({
+      chatId,
+      workspaceId,
+      userId,
+      role: 'assistant',
+      content: '',
+      status,
+      metadata: metadata as never,
+    });
+
+  it('insertStep is idempotent per (message, stepIndex) and reads back in order', async () => {
+    const row = await seedRow(stepMarkerMetadata(0), 'streaming');
+    const parts0 = assistantParts([makeStep(0)], '');
+    const parts1 = assistantParts([makeStep(1)], '');
+
+    expect(await stepRepo.insertStep(row.id, workspaceId, 0, parts0)).toBe(true);
+    expect(await stepRepo.insertStep(row.id, workspaceId, 1, parts1)).toBe(true);
+    // A retried persist of the SAME step is a no-op (ON CONFLICT DO NOTHING).
+    expect(await stepRepo.insertStep(row.id, workspaceId, 0, parts0)).toBe(
+      false,
+    );
+
+    const steps = await stepRepo.findByMessage(row.id, workspaceId);
+    expect(steps.map((s) => s.stepIndex)).toEqual([0, 1]);
+
+    // Batch fetch groups by message id in step order.
+    const map = await stepRepo.findByMessageIds([row.id], workspaceId);
+    expect(map.get(row.id)!.map((s) => s.stepIndex)).toEqual([0, 1]);
+  });
+
+  it('a NEW-style (step-table) run reconstructs identically to an OLD-style (inline) run', async () => {
+    const steps = [makeStep(10), makeStep(11)];
+    // The inline parts the OLD full-row flush would have written.
+    const fullParts = assistantParts(steps, '');
+
+    // OLD-style record: full parts inline on the row, NO step rows.
+    const oldRow = await seedRow(
+      { parts: fullParts, toolTraceVersion: 2, stepsPersisted: 2 },
+      'completed',
+    );
+
+    // NEW-style record: only a step marker on the row + per-step rows.
+    const newRow = await seedRow(stepMarkerMetadata(2), 'streaming');
+    for (let i = 0; i < steps.length; i++) {
+      await stepRepo.insertStep(
+        newRow.id,
+        workspaceId,
+        i,
+        assistantParts([steps[i]], ''),
+      );
+    }
+
+    // Re-read both from the DB (proves the jsonb roundtrip).
+    const oldFetched = await msgRepo.findById(oldRow.id, workspaceId);
+    const newFetched = await msgRepo.findById(newRow.id, workspaceId);
+    const oldSteps = await stepRepo.findByMessage(oldRow.id, workspaceId);
+    const newSteps = await stepRepo.findByMessage(newRow.id, workspaceId);
+
+    // The discriminator: the old row carries inline parts, the new one does not.
+    expect(rowHasInlineParts(oldFetched!)).toBe(true);
+    expect(rowHasInlineParts(newFetched!)).toBe(false);
+    expect(oldSteps).toHaveLength(0);
+    expect(newSteps).toHaveLength(2);
+
+    const oldRecon = reconstructRunParts(oldFetched!, oldSteps);
+    const newRecon = reconstructRunParts(newFetched!, newSteps);
+
+    // Both reconstruct to the SAME parts + step count — the era is invisible.
+    expect(newRecon.parts).toEqual(fullParts);
+    expect(oldRecon.parts).toEqual(fullParts);
+    expect(newRecon.parts).toEqual(oldRecon.parts);
+    expect(newRecon.stepsPersisted).toBe(2);
+    expect(oldRecon.stepsPersisted).toBe(2);
+
+    // hydrateAssistantParts fills the new row's metadata.parts to match the old
+    // row's inline parts — so a consumer reading `metadata.parts` off the raw row
+    // (the client seed/poll, export) is unchanged across the era.
+    const map = await stepRepo.findByMessageIds([newRow.id], workspaceId);
+    const [hydrated] = hydrateAssistantParts([newFetched!], map);
+    expect((hydrated.metadata as { parts: unknown }).parts).toEqual(fullParts);
+    // A row that already has inline parts passes through untouched (same ref-shape).
+    const [oldPassThrough] = hydrateAssistantParts([oldFetched!], map);
+    expect((oldPassThrough.metadata as { parts: unknown }).parts).toEqual(
+      fullParts,
+    );
+  });
+});

apps/server/test/integration/ai-chat-run-steps-migration.int-spec.ts

@@ -0,0 +1,63 @@
+import { Kysely, sql } from 'kysely';
+import {
+  up,
+  down,
+} from '../../src/database/migrations/20260708T120000-ai-chat-run-steps';
+import { getTestDb, destroyTestDb } from './db';
+
+/**
+ * #492 migration up/down roundtrip on a LIVE Postgres. global-setup already
+ * migrated docmost_test to latest (so the table exists at start); this drives the
+ * migration's own down()/up() and asserts the table presence toggles, then leaves
+ * it PRESENT (up) so the shared test DB is intact for any spec that runs after.
+ */
+async function tableExists(db: Kysely<any>): Promise<boolean> {
+  const row = (
+    await sql<{ t: string | null }>`select to_regclass('ai_chat_run_steps') as t`.execute(
+      db,
+    )
+  ).rows[0];
+  return row.t !== null;
+}
+
+async function uniqueIndexExists(db: Kysely<any>): Promise<boolean> {
+  const row = (
+    await sql<{
+      t: string | null;
+    }>`select to_regclass('ai_chat_run_steps_message_step_uidx') as t`.execute(db)
+  ).rows[0];
+  return row.t !== null;
+}
+
+describe('20260708 ai_chat_run_steps migration roundtrip [integration]', () => {
+  let db: Kysely<any>;
+
+  beforeAll(() => {
+    db = getTestDb();
+  });
+
+  afterAll(async () => {
+    // Belt-and-suspenders: guarantee the table is present for later specs even if
+    // an assertion threw mid-roundtrip.
+    if (!(await tableExists(db))) await up(db);
+    await destroyTestDb();
+  });
+
+  it('down() drops the table+index and up() recreates them (idempotent)', async () => {
+    // Starts applied (global-setup migrated to latest).
+    expect(await tableExists(db)).toBe(true);
+    expect(await uniqueIndexExists(db)).toBe(true);
+
+    await down(db);
+    expect(await tableExists(db)).toBe(false);
+    expect(await uniqueIndexExists(db)).toBe(false);
+
+    await up(db);
+    expect(await tableExists(db)).toBe(true);
+    expect(await uniqueIndexExists(db)).toBe(true);
+
+    // up() is idempotent (ifNotExists) — a second run is a harmless no-op.
+    await expect(up(db)).resolves.not.toThrow();
+    expect(await tableExists(db)).toBe(true);
+  });
+});

apps/server/test/integration/ai-chat-stream.int-spec.ts

@@ -322,20 +322,21 @@ describe('AiChatService.stream [integration]', () => {
   });
 
   /**
-   * #332 deferred tool loading, the ON path. The riskiest property is that the
-   * per-turn `activatedTools` Set is created FRESH inside each stream() call, so a
-   * tool a previous turn activated via loadTools is NOT still active when the next
-   * turn starts — the new turn begins "cold" (CORE + loadTools only). The unit
-   * tests only exercise pure prepareAgentStep with hand-fed Sets; this pins the
-   * real wiring end-to-end (loadTools.execute -> activatedTools -> prepareStep ->
-   * per-step activeTools) against the real streamText loop, and proves there is no
-   * cross-turn leak. We drive a MockLanguageModelV3 whose step 1 calls
-   * loadTools(['createPage']) and assert, via the model's recorded per-step
-   * CallOptions.tools (the AI SDK filters the provider tool list by activeTools),
-   * that the deferred tool becomes active on the SAME turn's next step but NOT on a
-   * fresh turn's first step.
+   * #332 + #490 deferred tool loading, the ON path. Turn 1 starts COLD (CORE +
+   * loadTools only) and activates a deferred tool via loadTools; that activation
+   * is PERSISTED into the chat's metadata.activatedTools (#490) so the NEXT turn
+   * SEEDS from it and the tool is active from the fresh turn's FIRST step — the
+   * model never re-runs loadTools to re-activate the same tool. The unit tests
+   * only exercise pure prepareAgentStep with hand-fed Sets; this pins the real
+   * wiring end-to-end (loadTools.execute -> activatedTools -> persist -> next-turn
+   * seed -> prepareStep -> per-step activeTools) against the real streamText loop.
+   * We drive a MockLanguageModelV3 whose step 1 calls loadTools(['createPage'])
+   * and assert, via the model's recorded per-step CallOptions.tools (the AI SDK
+   * filters the provider tool list by activeTools), that the deferred tool becomes
+   * active on the SAME turn's next step AND, seeded from metadata, on the next
+   * turn's first step.
    */
-  describe('deferred tool loading ON — per-turn activation, no leak (#332)', () => {
+  describe('deferred tool loading ON — cross-turn activation persistence (#332 + #490)', () => {
     // A stub deferred (non-core) tool the agent can activate. Its execute is never
     // called — the model only needs to SEE it become active — but it must be a
     // valid AI-SDK tool so the SDK includes it in a step's tool list once active.
@@ -451,7 +452,7 @@ describe('AiChatService.stream [integration]', () => {
       } as any);
     }
 
-    it('activates a deferred tool for the SAME turn, and a NEW turn starts cold (no leak)', async () => {
+    it('activates a deferred tool for the SAME turn, and a NEW turn SEEDS it from persisted chat metadata (#490)', async () => {
       const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
 
       // --- Turn 1: loadTools(createPage) on step 1, then answer on step 2. ---
@@ -474,7 +475,7 @@ describe('AiChatService.stream [integration]', () => {
       // Step 2 of the SAME turn sees the just-activated deferred tool.
       expect(step2Tools).toContain('createPage');
 
-      // --- Turn 2 on the SAME chat: must start cold again. ---
+      // --- Turn 2 on the SAME chat: seeds the persisted activation (#490). ---
       const model2 = new MockLanguageModelV3({
         doStream: async () => ({ stream: successStream() }),
       } as any);
@@ -485,9 +486,10 @@ describe('AiChatService.stream [integration]', () => {
 
       const nextTurnFirstStep = toolNames(model2.doStreamCalls[0]);
       expect(nextTurnFirstStep).toContain('loadTools');
-      // The activated set is per-turn: the prior turn's createPage did NOT leak,
-      // so the fresh turn's first step sees it deferred again.
-      expect(nextTurnFirstStep).not.toContain('createPage');
+      // #490: activation PERSISTS across turns — turn 1 wrote createPage into the
+      // chat's metadata.activatedTools, so the next turn seeds from it and the
+      // deferred tool is active from the FIRST step (no need to re-run loadTools).
+      expect(nextTurnFirstStep).toContain('createPage');
     });
   });
 });

packages/mcp/src/lib/drawio-xml.ts

@@ -178,10 +178,11 @@ function sliceModel(xml: string): string | null {
 // --- decode chain ----------------------------------------------------------
 
 /**
- * Read the `content=` attribute out of a `.drawio.svg` string. Docmost stores a
- * base64 payload there (createDrawioSvg); draw.io's own SVG export may store the
- * XML entity-encoded instead. The DOM decodes entities for us, so the caller
- * only has to distinguish "starts with '<'" (raw XML) from base64.
+ * Read the `content=` attribute out of a `.drawio.svg` string. Docmost writes
+ * the mxfile XML entity-encoded there (buildDrawioSvg / createDrawioSvg), which
+ * is also how draw.io's own SVG export stores it; older attachments stored a
+ * base64 payload instead. The DOM decodes entities for us, so the caller only
+ * has to distinguish "starts with '<'" (raw XML) from base64.
  */
 export function extractContentAttr(svg: string): string {
   const { doc, error } = parseXml(svg);
@@ -195,12 +196,23 @@ export function extractContentAttr(svg: string): string {
   // value itself never contains a double-quote (base64 / entity-encoded XML).
   const m = /content="([^"]*)"/.exec(svg);
   if (m) {
-    // Decode the handful of XML entities a raw regex would leave encoded.
+    // Decode the handful of XML entities a raw regex would leave encoded. The
+    // numeric char-refs for tab/newline/CR MUST be decoded here too: the DOM
+    // path above turns them back into the literal control chars, so this
+    // regex fallback has to agree or the two decode paths diverge (#507).
+    // `&amp;` is decoded last so an escaped `&amp;#x9;` reads back as the
+    // literal text `&#x9;`, not a tab.
     return m[1]
       .replace(/&lt;/g, "<")
       .replace(/&gt;/g, ">")
       .replace(/&quot;/g, '"')
       .replace(/&#39;/g, "'")
+      .replace(/&#x9;/gi, "\t")
+      .replace(/&#9;/g, "\t")
+      .replace(/&#xa;/gi, "\n")
+      .replace(/&#10;/g, "\n")
+      .replace(/&#xd;/gi, "\r")
+      .replace(/&#13;/g, "\r")
       .replace(/&amp;/g, "&");
   }
   throw new Error("drawio: SVG has no content= attribute to decode");
@@ -307,9 +319,16 @@ export function encodeDrawioFile(modelXml: string, title = "Page-1"): string {
 /**
  * Build the `diagram.drawio.svg` attachment. Mirrors the import service's
  * createDrawioSvg contract exactly:
- *   <svg xmlns=… xmlns:xlink=… content="${base64(drawioFile)}">${inner}</svg>
+ *   <svg xmlns=… xmlns:xlink=… content="${xmlEscape(drawioFile)}">${inner}</svg>
  * plus width/height/viewBox from the diagram bounding box and the schematic
  * preview as the visible children (`inner`).
+ *
+ * The `content=` value is the mxfile XML XML-entity-escaped (draw.io's own
+ * native form), NOT base64. draw.io's editor decodes a base64 content= via
+ * Latin-1 atob (no UTF-8 step), turning every non-ASCII char (e.g. Cyrillic,
+ * ё, —) into mojibake; the entity-encoded form is decoded by the DOM as UTF-8
+ * and opens intact. Our decoder (decodeDrawioSvg) reads both forms, so old
+ * base64 attachments still round-trip.
  */
 export function buildDrawioSvg(
   modelXml: string,
@@ -318,14 +337,14 @@ export function buildDrawioSvg(
   title = "Page-1",
 ): string {
   const file = encodeDrawioFile(modelXml, title);
-  const base64 = Buffer.from(file, "utf-8").toString("base64");
+  const content = xmlEscape(file);
   const w = Math.max(1, Math.round(bbox.width));
   const h = Math.max(1, Math.round(bbox.height));
   return (
     `<svg xmlns="http://www.w3.org/2000/svg" ` +
     `xmlns:xlink="http://www.w3.org/1999/xlink" ` +
     `width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" ` +
-    `content="${base64}">${inner}</svg>`
+    `content="${content}">${inner}</svg>`
   );
 }
 
@@ -334,7 +353,15 @@ function xmlEscape(s: string): string {
     .replace(/&/g, "&amp;")
     .replace(/</g, "&lt;")
     .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
+    .replace(/"/g, "&quot;")
+    // A literal tab/newline/CR inside an attribute value is collapsed to a
+    // single space by XML attribute-value normalization on DOM read (both jsdom
+    // here and the real draw.io editor), silently flattening multi-line labels
+    // and tab-bearing values. Numeric char-refs survive that normalization, so
+    // emit them the way draw.io's own native export does (#507).
+    .replace(/\t/g, "&#x9;")
+    .replace(/\n/g, "&#xa;")
+    .replace(/\r/g, "&#xd;");
 }
 
 // --- normalization + hash --------------------------------------------------

packages/mcp/test/unit/drawio-xml.test.mjs

@@ -51,6 +51,14 @@ const hasRule = (issues, rule, cellId) =>
     (i) => i.rule === rule && (cellId === undefined || i.cellId === cellId),
   );
 
+// Reverse the attribute-value XML escaping used in the `content=` payload.
+const unescapeAttr = (s) =>
+  s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, "&");
+
 // --- style parsing ---------------------------------------------------------
 
 test("parseStyle: base stylename + key=value pairs", () => {
@@ -335,16 +343,20 @@ test("encode/build: a title with < > \" & round-trips without corrupting the SVG
 
   // The outer content="..." attribute must not be broken by the title: the raw
   // title metacharacters never appear literally in the SVG markup (they are
-  // base64-encoded inside content=, and escaped inside the file XML).
+  // entity-escaped inside content=, doubly so where the file XML already escaped
+  // them inside name="...").
   const contentMatch = /content="([^"]*)"/.exec(svg);
   assert.ok(contentMatch, "SVG has a single well-formed content= attribute");
 
   // The diagram model still decodes losslessly despite the exotic title.
   assert.equal(decodeDrawioSvg(svg), model);
 
+  // content= is now entity-encoded XML (draw.io's native form), never base64.
+  assert.match(contentMatch[1], /^&lt;mxfile/);
+
   // The file XML is well-formed: the title lives in name="..." as escaped
   // entities, so unescaping recovers the original title byte-for-byte.
-  const fileXml = Buffer.from(contentMatch[1], "base64").toString("utf-8");
+  const fileXml = unescapeAttr(contentMatch[1]);
   const nameMatch = /<diagram id="[^"]*" name="([^"]*)">/.exec(fileXml);
   assert.ok(nameMatch, "the diagram name attribute is intact and quote-safe");
   const decodedTitle = nameMatch[1]
@@ -358,3 +370,112 @@ test("encode/build: a title with < > \" & round-trips without corrupting the SVG
   const file = encodeDrawioFile(model, title);
   assert.match(file, /name="A &lt; B &gt; C &quot; D &amp; E">/);
 });
+
+// --- #507: content= is entity-encoded XML, never base64 --------------------
+
+// A model whose cell values carry Cyrillic, ё and an em dash — exactly the
+// characters draw.io's Latin-1 atob mangles when content= is base64.
+const CYRILLIC_MODEL =
+  "<mxGraphModel><root>" +
+  '<mxCell id="0"/><mxCell id="1" parent="0"/>' +
+  '<mxCell id="2" value="Старт-бит — ёж" style="rounded=1;html=1;" vertex="1" parent="1">' +
+  '<mxGeometry x="100" y="100" width="120" height="60" as="geometry"/></mxCell>' +
+  "</root></mxGraphModel>";
+
+test("#507: buildDrawioSvg writes content= as entity-encoded XML (not base64)", () => {
+  const model = normalizeXml(CYRILLIC_MODEL);
+  const svg = buildDrawioSvg(model, "<g/>", { width: 200, height: 120 }, "Диаграмма");
+
+  const contentMatch = /content="([^"]*)"/.exec(svg);
+  assert.ok(contentMatch, "SVG has a single well-formed content= attribute");
+  const content = contentMatch[1];
+
+  // The content= value is the entity-encoded mxfile XML — starts with `&lt;mxfile`.
+  assert.match(content, /^&lt;mxfile/, "content= is entity-encoded mxfile XML");
+  // It must NOT be a base64 blob: base64 has no XML entities and no literal `<`.
+  assert.ok(content.includes("&lt;"), "content= carries XML entities, not base64");
+
+  // Cyrillic / ё / — survive verbatim in the attribute (raw UTF-8, not atob-mangled).
+  assert.ok(content.includes("Старт-бит — ёж"), "non-ASCII value is raw UTF-8 in content=");
+  assert.ok(content.includes("Диаграмма"), "non-ASCII title is raw UTF-8 in content=");
+  // The mojibake that base64+atob would have produced must be absent.
+  assert.ok(!content.includes("Ð"), "no Latin-1 mojibake in content=");
+});
+
+test("#507: Cyrillic model round-trips byte-stable through buildDrawioSvg -> decodeDrawioSvg", () => {
+  const model = normalizeXml(CYRILLIC_MODEL);
+  const svg = buildDrawioSvg(model, "<g/>", { width: 200, height: 120 }, "Заголовок — ё");
+  assert.equal(decodeDrawioSvg(svg), model);
+});
+
+test("#507 back-compat: an OLD base64-form .drawio.svg still decodes losslessly", () => {
+  const model = normalizeXml(CYRILLIC_MODEL);
+  // Reproduce the pre-fix write path: encodeDrawioFile -> base64 in content=.
+  const file = encodeDrawioFile(model, "Старая диаграмма");
+  const base64 = Buffer.from(file, "utf-8").toString("base64");
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" content="${base64}"><g/></svg>`;
+  // No XML entities, purely base64 alphabet — this is the legacy form.
+  assert.ok(!base64.includes("<") && !base64.includes("&"));
+  assert.equal(decodeDrawioSvg(svg), model);
+});
+
+test("#507 negative: non-ASCII in a cell value AND in the title round-trip clean", () => {
+  const model = normalizeXml(CYRILLIC_MODEL);
+  const title = "Тест — ёмкость № 5";
+  const svg = buildDrawioSvg(model, "<g/>", { width: 200, height: 120 }, title);
+
+  // Model recovered byte-for-byte.
+  assert.equal(decodeDrawioSvg(svg), model);
+
+  // Title lands in the <diagram name="..."> of the decoded file XML, intact.
+  const content = /content="([^"]*)"/.exec(svg)[1];
+  const fileXml = unescapeAttr(content);
+  const nameMatch = /<diagram id="[^"]*" name="([^"]*)">/.exec(fileXml);
+  assert.ok(nameMatch, "diagram name attribute present");
+  assert.equal(unescapeAttr(nameMatch[1]), title);
+});
+
+// --- #507 F1: literal tab/newline/CR in an attribute value survive the
+// content= round-trip. The whole mxfile XML lives in one content="..." attr;
+// XML attribute-value normalization collapses a LITERAL tab/newline/CR to a
+// single space on DOM read, so the escape must emit numeric char-refs instead.
+const CTRL_MODEL =
+  "<mxGraphModel><root>" +
+  '<mxCell id="0"/><mxCell id="1" parent="0"/>' +
+  '<mxCell id="2" value="col1\tcol2" style="html=1;\nshadow=0" vertex="1" parent="1">' +
+  '<mxGeometry x="10" y="10" width="120" height="60" as="geometry"/></mxCell>' +
+  '<mxCell id="3" value="Line1\nLine2\rLine3" vertex="1" parent="1">' +
+  '<mxGeometry x="10" y="100" width="120" height="60" as="geometry"/></mxCell>' +
+  "</root></mxGraphModel>";
+
+test("#507 F1: literal tab/newline/CR in a value round-trip byte-stable (DOM decode)", () => {
+  const svg = buildDrawioSvg(CTRL_MODEL, "<g/>", { width: 200, height: 200 });
+  const content = /content="([^"]*)"/.exec(svg)[1];
+  // The tab/newline/CR must be emitted as numeric char-refs, never as literal
+  // control chars (which DOM attribute-value normalization would eat).
+  assert.ok(
+    !/[\t\n\r]/.test(content),
+    "no literal tab/newline/CR survive in the content= attribute",
+  );
+  assert.ok(
+    content.includes("&#x9;") &&
+      content.includes("&#xa;") &&
+      content.includes("&#xd;"),
+    "tab/newline/CR are emitted as numeric char-refs",
+  );
+  // Full DOM decode recovers the model byte-for-byte, control chars intact.
+  assert.equal(decodeDrawioSvg(svg), CTRL_MODEL);
+});
+
+test("#507 F1: regex fallback decodes tab/newline/CR char-refs (agrees with DOM path)", () => {
+  const svg = buildDrawioSvg(CTRL_MODEL, "<g/>", { width: 200, height: 200 });
+  const content = /content="([^"]*)"/.exec(svg)[1];
+  // A bare `&` makes the SVG wrapper malformed, forcing extractContentAttr onto
+  // its regex fallback branch. That branch must decode the tab/newline/CR
+  // char-refs exactly like the DOM path, or the two decoders diverge.
+  const malformedSvg = `<svg content="${content}">&</svg>`;
+  assert.equal(decodeDrawioSvg(malformedSvg), CTRL_MODEL);
+  // The well-formed (DOM) path yields the identical result.
+  assert.equal(decodeDrawioSvg(svg), CTRL_MODEL);
+});

packages/prosemirror-markdown/src/lib/canonicalize.ts

@@ -25,22 +25,13 @@
  * drop any attr whose value equals its known schema default. A non-default
  * value (e.g. `orderedList.start: 5`) is NOT a default, so it is KEPT.
  *
- * Every entry below — with the single documented exception of the `link.internal`
- * marker (see its own bullet) — was read from `packages/docmost-client/src/lib/
+ * Every entry below was read from `packages/docmost-client/src/lib/
  * docmost-schema.ts` (the line refs are the exact `default:` declarations) and
  * confirmed to be materialized by an export→import→export round-trip:
  *   - mark `link`    target / rel  — DocmostAttributes + StarterKit link.
  *       StarterKit's link extension defaults `target: "_blank"` and
  *       `rel: "noopener noreferrer nofollow"`; both materialize on import
  *       (empirically confirmed) even when the source had only `href`.
- *   - mark `link`    internal (#522) — the ONE editor-sourced, NOT-import-
- *       materialized default here. Its source is `editor-ext/src/lib/link.ts`
- *       (default `internal: false`), not docmost-schema, and import does NOT
- *       materialize it (an imported external link leaves `internal` absent/null,
- *       never `false`). It is listed so that the editor's stored `internal:false`
- *       normalizes to the same "external" canon as absent/null (`false ≡ absent`),
- *       keeping a stored external link canonically equal to its re-import. The
- *       load-bearing `internal:true` is NON-default and therefore KEPT.
  *   - mark `comment` resolved      — docmost-schema.ts L213-214 (`default: false`).
  *   - node `orderedList` start     — provided by StarterKit's orderedList
  *       (`default: 1`); materializes on import (empirically confirmed).
@@ -65,14 +56,6 @@ const KNOWN_DEFAULTS: Record<string, Record<string, unknown>> = {
   link: {
     target: "_blank",
     rel: "noopener noreferrer nofollow",
-    // Editor-authored EXTERNAL links store `internal: false` (editor-ext link
-    // default `packages/editor-ext/src/lib/link.ts`), while an imported external
-    // link leaves `internal` absent/null. Both mean "external", so `internal:
-    // false` must normalize away exactly like `null`/absent — otherwise a stored
-    // `internal:false` link diverges from its re-import under
-    // `docsCanonicallyEqual` (false !== null). The internal marker `internal:true`
-    // is NON-default, so it is KEPT and survives canonicalization (#522 §11).
-    internal: false,
   },
   comment: {
     resolved: false,

packages/prosemirror-markdown/src/lib/index.ts

@@ -38,10 +38,6 @@ export {
   normalizeForeignMarkdown,
   normalizeAgentMarkdown,
 } from "./foreign-markdown.js";
-// Pure primitive: detect the unambiguously-internal wiki-page link path
-// (`/s/<space>/p/<slug>`) and promote such link marks to their native internal
-// form during import (#522). A strict subset of the server's INTERNAL_LINK_REGEX.
-export { isInternalPagePath, markInternalLinks } from "./internal-links.js";
 
 // The Docmost tiptap schema mirror. Exposed so consumers (and the sync
 // engine's schema-validity regression tests) can build the exact ProseMirror

packages/prosemirror-markdown/src/lib/internal-links.ts

@@ -1,112 +0,0 @@
-/**
- * Detect and mark unambiguously-internal wiki-page links during markdown import.
- *
- * WHY THIS EXISTS
- * ---------------
- * The markdown converter (`markdownToProseMirrorSync`) materializes every link
- * with StarterKit's external defaults — `internal: null`, `target: "_blank"`,
- * `rel: "noopener noreferrer nofollow"`. A markdown link that points at an
- * internal wiki page written in its host-less, root-relative form
- * (`[text](/s/<space>/p/<slugId>)`) is therefore stored as EXTERNAL: it opens in
- * a new tab, gets no hover-preview, and is invisible to the backlink graph
- * (`extractInternalLinkSlugIds` only counts links whose mark carries
- * `internal: true`). This module supplies the pure primitive that a post-walk in
- * the converter uses to promote such links to their native internal form.
- *
- * WHERE THE CANON LIVES (a strict subset, on purpose)
- * ---------------------------------------------------
- * The authoritative definition of "what is an internal link path" is the
- * server's `INTERNAL_LINK_REGEX`
- * (`apps/server/src/integrations/export/utils.ts`):
- *   /^(https?:\/\/)?([^\/]+)?(\/s\/([^\/]+)\/)?p\/([a-zA-Z0-9-]+)\/?$/
- * This package is a lower layer than the server app and cannot import it, so the
- * matcher below is a DOCUMENTED, STRICT SUBSET of that regex: it accepts only the
- * space-qualified, root-relative page path `/s/<space>/p/<slug>` (with optional
- * trailing slash). Because it is a subset, every link we mark internal here is
- * guaranteed to also satisfy the server regex, hence guaranteed backlink-able and
- * export-rewritable. A unit test pins the exact accept/reject set as the guard
- * against drift.
- *
- * FAIL-TOWARD-EXTERNAL
- * --------------------
- * We mark a link internal ONLY on an unambiguous anchored match. Any ambiguity
- * (a scheme/host, `#anchor`, `?query`, a space-less `/p/<slug>`, a relative
- * `p/<slug>`, a non-string href) leaves the link external. A false-external is a
- * soft degradation (a new tab); a false-internal would produce broken SPA
- * navigation, so "external" is the conservative default.
- *
- * Precedent for the target internal shape: the file importer already promotes
- * internal anchors (`apps/server/src/integrations/import/utils/import-formatter.ts`
- * `$a.attr('data-internal','true')`) and editor-ext reads it
- * (`packages/editor-ext/src/lib/link.ts`).
- */
-
-/**
- * Matches ONLY the space-qualified, root-relative internal page path
- * `/s/<space>/p/<slug>` (with optional trailing slash). A STRICT SUBSET of the
- * server's `INTERNAL_LINK_REGEX`:
- *   - `<space>` = `[^/]+`   (any non-slash segment, as in the server's group 4)
- *   - `<slug>`  = `[a-zA-Z0-9-]+`  (as in the server's group 5 / `extractPageSlugId`)
- * Anchored on both ends so a scheme/host, a trailing `#anchor`/`?query`, or any
- * extra path segment fails to match.
- */
-const INTERNAL_PAGE_PATH = /^\/s\/[^/]+\/p\/[a-zA-Z0-9-]+\/?$/;
-
-/**
- * True iff `href` is the unambiguous, space-qualified, root-relative internal
- * page path. Pure and side-effect-free. Non-string input returns false.
- */
-export function isInternalPagePath(href: unknown): boolean {
-  return typeof href === "string" && INTERNAL_PAGE_PATH.test(href);
-}
-
-/**
- * The native internal-link attribute overrides applied to a link mark whose href
- * is an internal page path. Mirrors the manual JSON-patch form
- * (`{internal:true, target:null, rel:null}`) and the editor-ext/file-importer
- * precedent: internal links carry no `target`/`rel` (same-tab SPA navigation).
- */
-const INTERNAL_LINK_ATTRS = { internal: true, target: null, rel: null } as const;
-
-/**
- * In-place post-walk of a finished ProseMirror doc that promotes every
- * unambiguously-internal link mark to its native internal form.
- *
- * A link that spans several text nodes (e.g. `[**bold** word](/s/x/p/abc)`)
- * stores an equivalent link mark on EACH covered text node — and a covered node
- * may carry nested marks (bold/italic) alongside the link. We therefore walk the
- * entire tree and rewrite EVERY `link` mark whose href passes
- * `isInternalPagePath`, so no covered segment is left external.
- *
- * Pure of external effects and IDEMPOTENT: re-running on an already-marked doc
- * leaves it unchanged (an internal-path href always maps to the same attrs).
- * External links are never touched — their `target:_blank`/`rel:noopener…` stay.
- *
- * The doc is mutated in place (the converter owns the freshly-built doc and
- * returns it directly); the same node reference is returned for convenience.
- */
-export function markInternalLinks<T>(node: T): T {
-  walk(node);
-  return node;
-}
-
-function walk(node: any): void {
-  if (!node || typeof node !== "object") return;
-  if (Array.isArray(node)) {
-    for (const child of node) walk(child);
-    return;
-  }
-  if (Array.isArray(node.marks)) {
-    for (const mark of node.marks) {
-      if (
-        mark &&
-        mark.type === "link" &&
-        mark.attrs &&
-        isInternalPagePath(mark.attrs.href)
-      ) {
-        mark.attrs = { ...mark.attrs, ...INTERNAL_LINK_ATTRS };
-      }
-    }
-  }
-  if (Array.isArray(node.content)) walk(node.content);
-}

packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts

@@ -12,7 +12,6 @@ import { parseHtmlDocument, generateJsonWith } from "./dom-parser.js";
 import type { TokenizerExtension, RendererExtension } from "marked";
 import { docmostExtensions } from "./docmost-schema.js";
 import { parseAttachedComment } from "./attached-comment.js";
-import { markInternalLinks } from "./internal-links.js";
 import { splitFootnoteParagraphs } from "./footnote.js";
 import {
   decodeInlineMathLatex,
@@ -1095,12 +1094,7 @@ export function markdownToProseMirrorSync(markdownContent: string): any {
   const withFootnotes = assembleFootnotes(withAttrs);
   const bridged = bridgeTaskLists(withFootnotes);
   const doc = generateJsonWith(bridged, docmostExtensions);
-  // Promote unambiguously-internal wiki-page links (`[t](/s/<space>/p/<slug>)`)
-  // to their native internal form (`internal:true, target:null, rel:null`) so
-  // they get same-tab SPA navigation, hover-preview, and backlink participation.
-  // Every markdown import path funnels through here, so all of them are fixed at
-  // once; external links are left untouched (#522).
-  return markInternalLinks(stripEmptyParagraphs(doc));
+  return stripEmptyParagraphs(doc);
 }
 
 /**

packages/prosemirror-markdown/test/internal-links.test.ts

@@ -1,345 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  isInternalPagePath,
-  markInternalLinks,
-} from '../src/lib/internal-links.js';
-import { markdownToProseMirrorSync } from '../src/lib/markdown-to-prosemirror.js';
-import {
-  canonicalizeContent,
-  docsCanonicallyEqual,
-} from '../src/lib/canonicalize.js';
-
-// A LOCAL, illustrative copy of the server's INTERNAL_LINK_REGEX
-// (apps/server/src/integrations/export/utils.ts) used only to document the
-// subset boundary WITHIN this package (this layer cannot import the server).
-// It is NOT the cross-package drift guard: a hand copy can silently go stale if
-// the server regex is later narrowed. The real, mechanical drift guard lives in
-// the top layer, `apps/server/src/integrations/export/internal-link-parity.spec.ts`,
-// which imports BOTH the LIVE server `INTERNAL_LINK_REGEX` and the LIVE
-// `isInternalPagePath` and reddens if the client ever ceases to be a subset.
-const SERVER_INTERNAL_LINK_REGEX =
-  /^(https?:\/\/)?([^\/]+)?(\/s\/([^\/]+)\/)?p\/([a-zA-Z0-9-]+)\/?$/;
-
-// Walk a doc collecting every link mark (across all text nodes).
-const linkMarks = (doc: any): any[] => {
-  const out: any[] = [];
-  const walk = (n: any): void => {
-    if (!n || typeof n !== 'object') return;
-    if (Array.isArray(n)) return n.forEach(walk);
-    if (Array.isArray(n.marks))
-      for (const m of n.marks) if (m?.type === 'link') out.push(m);
-    if (Array.isArray(n.content)) walk(n.content);
-  };
-  walk(doc);
-  return out;
-};
-
-describe('isInternalPagePath', () => {
-  const ACCEPT = [
-    '/s/eng/p/abc123',
-    '/s/eng/p/abc123/', // trailing slash
-    '/s/My-Space/p/A-b-C-9', // hyphens + mixed case in both segments
-    '/s/x/p/z',
-  ];
-  const REJECT = [
-    'https://example.com/p/x', // scheme + host
-    'http://host/s/eng/p/abc', // scheme + host, even on the internal shape
-    '//host/s/eng/p/abc', // protocol-relative host
-    '/p/abc123', // space-less form (server does NOT backlink it)
-    'p/abc123', // relative
-    's/eng/p/abc123', // missing leading slash
-    '/s/eng/p/abc#section', // anchor
-    '/s/eng/p/abc?q=1', // query
-    '/s/eng/p/abc/extra', // extra segment
-    '/s//p/abc', // empty space segment
-    '/s/eng/p/', // empty slug
-    '/s/eng/p', // no slug at all
-    '/api/pages/abc', // other internal route
-    '/s/eng/x/abc', // wrong middle segment
-    '/s/a/b/p/abc', // space contains slash -> extra segment
-    '',
-  ];
-  // Structurally VALID `/s/<space>/p/<slug>` shapes whose ONLY defect is a
-  // forbidden character in the slug segment. These pin the slug charset
-  // `[a-zA-Z0-9-]` itself (not just the surrounding structure): drop them and a
-  // mutation widening the charset (e.g. adding `.`) survives the suite. Each is
-  // ALSO rejected by the server regex — documenting that the subset boundary
-  // holds precisely on the charset, not just on structure.
-  const REJECT_SLUG_CHARSET = [
-    '/s/eng/p/abc.def', // dot
-    '/s/eng/p/abc_def', // underscore
-    '/s/eng/p/abc%20', // percent-encoded space
-    '/s/eng/p/abc~x', // tilde
-  ];
-
-  it('accepts the space-qualified root-relative page path (+trailing slash)', () => {
-    for (const href of ACCEPT)
-      expect(isInternalPagePath(href), href).toBe(true);
-  });
-
-  it('rejects external URLs, ambiguous, and non-page forms', () => {
-    for (const href of REJECT)
-      expect(isInternalPagePath(href), href).toBe(false);
-  });
-
-  it('rejects a correctly-shaped path with a forbidden slug character', () => {
-    // Pins the slug charset itself: a mutation widening `[a-zA-Z0-9-]` reddens.
-    for (const href of REJECT_SLUG_CHARSET)
-      expect(isInternalPagePath(href), href).toBe(false);
-  });
-
-  it('the forbidden-slug-char paths are rejected by the server regex too', () => {
-    // The subset boundary holds on the charset, not just the structure: none of
-    // these match the server regex, so the client must not accept them either.
-    for (const href of REJECT_SLUG_CHARSET)
-      expect(SERVER_INTERNAL_LINK_REGEX.test(href), href).toBe(false);
-  });
-
-  it('rejects non-string input (fail-toward-external)', () => {
-    for (const v of [null, undefined, 123, {}, [], true])
-      expect(isInternalPagePath(v as unknown)).toBe(false);
-  });
-
-  it('is a STRICT SUBSET of the server INTERNAL_LINK_REGEX', () => {
-    // Every accepted href must also satisfy the server regex (so it is
-    // guaranteed backlink-able / export-rewritable).
-    for (const href of ACCEPT)
-      expect(SERVER_INTERNAL_LINK_REGEX.test(href), href).toBe(true);
-  });
-});
-
-describe('markInternalLinks', () => {
-  const linkNode = (text: string, href: string, extraMarks: any[] = []) => ({
-    type: 'text',
-    text,
-    marks: [
-      {
-        type: 'link',
-        attrs: {
-          href,
-          internal: null,
-          title: null,
-          target: '_blank',
-          rel: 'noopener noreferrer nofollow',
-          class: null,
-        },
-      },
-      ...extraMarks,
-    ],
-  });
-
-  it('marks an internal-path link internal:true, target:null, rel:null', () => {
-    const doc = {
-      type: 'doc',
-      content: [
-        { type: 'paragraph', content: [linkNode('hi', '/s/eng/p/abc123')] },
-      ],
-    };
-    markInternalLinks(doc);
-    const m = linkMarks(doc)[0];
-    expect(m.attrs.internal).toBe(true);
-    expect(m.attrs.target).toBeNull();
-    expect(m.attrs.rel).toBeNull();
-    expect(m.attrs.href).toBe('/s/eng/p/abc123'); // href untouched
-  });
-
-  it('leaves external links untouched', () => {
-    const doc = {
-      type: 'doc',
-      content: [
-        {
-          type: 'paragraph',
-          content: [linkNode('ext', 'https://example.com/p/x')],
-        },
-      ],
-    };
-    markInternalLinks(doc);
-    const m = linkMarks(doc)[0];
-    expect(m.attrs.internal).toBeNull();
-    expect(m.attrs.target).toBe('_blank');
-    expect(m.attrs.rel).toBe('noopener noreferrer nofollow');
-  });
-
-  it('marks EVERY text node a multi-node link spans (incl. nested bold/italic)', () => {
-    // A link `[**bold** plain *ital*](/s/x/p/abc)` stores the link mark on each
-    // covered text node; some also carry bold/italic. All must become internal.
-    const bold = { type: 'bold' };
-    const italic = { type: 'italic' };
-    const doc = {
-      type: 'doc',
-      content: [
-        {
-          type: 'paragraph',
-          content: [
-            linkNode('bold', '/s/x/p/abc', [bold]),
-            linkNode(' plain ', '/s/x/p/abc'),
-            linkNode('ital', '/s/x/p/abc', [italic]),
-          ],
-        },
-      ],
-    };
-    markInternalLinks(doc);
-    const marks = linkMarks(doc);
-    expect(marks).toHaveLength(3);
-    for (const m of marks) {
-      expect(m.attrs.internal).toBe(true);
-      expect(m.attrs.target).toBeNull();
-      expect(m.attrs.rel).toBeNull();
-    }
-    // Nested bold/italic marks are preserved alongside the promoted link.
-    const nested = doc.content[0].content;
-    expect(nested[0].marks.some((m: any) => m.type === 'bold')).toBe(true);
-    expect(nested[2].marks.some((m: any) => m.type === 'italic')).toBe(true);
-  });
-
-  it('is idempotent', () => {
-    const doc = {
-      type: 'doc',
-      content: [
-        { type: 'paragraph', content: [linkNode('hi', '/s/eng/p/abc')] },
-      ],
-    };
-    markInternalLinks(doc);
-    const once = JSON.stringify(doc);
-    markInternalLinks(doc);
-    expect(JSON.stringify(doc)).toBe(once);
-  });
-});
-
-describe('markdown import (full converter) — #522 acceptance', () => {
-  it('promotes an internal link and leaves an external one external', () => {
-    const doc = markdownToProseMirrorSync(
-      '[t](/s/eng/p/abc123) and [ext](https://example.com/p/x)',
-    );
-    const marks = linkMarks(doc);
-    const internal = marks.find((m) => m.attrs.href === '/s/eng/p/abc123');
-    const external = marks.find(
-      (m) => m.attrs.href === 'https://example.com/p/x',
-    );
-    expect(internal.attrs).toMatchObject({
-      internal: true,
-      target: null,
-      rel: null,
-    });
-    expect(external.attrs).toMatchObject({
-      internal: null,
-      target: '_blank',
-      rel: 'noopener noreferrer nofollow',
-    });
-  });
-
-  it('does NOT promote the space-less /p/<slug> form (documented limit)', () => {
-    const doc = markdownToProseMirrorSync('[t](/p/abc123)');
-    const m = linkMarks(doc)[0];
-    expect(m.attrs.internal).toBeNull();
-    expect(m.attrs.target).toBe('_blank');
-  });
-
-  it('the promoted link is backlink-extractable (matches server regex + true)', () => {
-    // Mirrors extractInternalLinkSlugIds: internal flag AND server-regex match.
-    const doc = markdownToProseMirrorSync('[t](/s/eng/p/my-page-abc123)');
-    const m = linkMarks(doc)[0];
-    expect(m.attrs.internal).toBe(true);
-    const match = m.attrs.href.match(SERVER_INTERNAL_LINK_REGEX);
-    expect(match).not.toBeNull();
-    // group 5 is the slug segment the server feeds to extractPageSlugId.
-    expect(match![5]).toBe('my-page-abc123');
-  });
-
-  it('comment-body markdown gets the same treatment (shared converter path)', () => {
-    // Comment bodies go through the same markdownToProseMirrorSync; a spot-check
-    // that the shared path (not a comment-only branch) does the promotion.
-    const doc = markdownToProseMirrorSync('see [here](/s/team/p/xyz789)');
-    const m = linkMarks(doc).find((x) => x.attrs.href === '/s/team/p/xyz789');
-    expect(m.attrs.internal).toBe(true);
-  });
-});
-
-describe('canonicalize — internal:false ≡ external (#522 §11)', () => {
-  it('drops editor-authored internal:false so external stays canonically equal', () => {
-    // Editor stores external links with internal:false; import leaves it absent.
-    const stored = {
-      type: 'doc',
-      content: [
-        {
-          type: 'paragraph',
-          content: [
-            {
-              type: 'text',
-              text: 'x',
-              marks: [
-                {
-                  type: 'link',
-                  attrs: {
-                    href: 'https://example.com',
-                    internal: false,
-                    target: '_blank',
-                    rel: 'noopener noreferrer nofollow',
-                  },
-                },
-              ],
-            },
-          ],
-        },
-      ],
-    };
-    const reimport = {
-      type: 'doc',
-      content: [
-        {
-          type: 'paragraph',
-          content: [
-            {
-              type: 'text',
-              text: 'x',
-              marks: [
-                {
-                  type: 'link',
-                  attrs: {
-                    href: 'https://example.com',
-                    internal: null, // import default
-                    target: '_blank',
-                    rel: 'noopener noreferrer nofollow',
-                  },
-                },
-              ],
-            },
-          ],
-        },
-      ],
-    };
-    expect(docsCanonicallyEqual(stored, reimport)).toBe(true);
-    // internal:false / target / rel all drop as defaults; only the non-default
-    // href survives.
-    const canon = canonicalizeContent(stored);
-    const mark = canon.content[0].content[0].marks[0];
-    expect(mark.attrs).toEqual({ href: 'https://example.com' });
-  });
-
-  it('keeps internal:true through canonicalization (non-default, load-bearing)', () => {
-    const doc = {
-      type: 'doc',
-      content: [
-        {
-          type: 'paragraph',
-          content: [
-            {
-              type: 'text',
-              text: 'x',
-              marks: [
-                {
-                  type: 'link',
-                  attrs: { href: '/s/x/p/abc', internal: true },
-                },
-              ],
-            },
-          ],
-        },
-      ],
-    };
-    const canon = canonicalizeContent(doc);
-    const mark = canon.content[0].content[0].marks[0];
-    expect(mark.attrs.internal).toBe(true);
-    expect(mark.attrs.href).toBe('/s/x/p/abc');
-  });
-});