fix(#342 review round-2 F5-F6): drop the posthog re-render remount + test chunk detector

- F5 [stability/regression]: the round-1 F2 fix re-rendered the root with
  <PostHogProvider><App/></PostHogProvider> after the analytics chunk loaded. In
  the ChunkLoadErrorBoundary child slot the element TYPE changes App ->
  PostHogProvider, so React does NOT reconcile in place — it REMOUNTS the whole
  App: every mount effect runs twice (websocket connect/disconnect, origin
  tracking, subscriptions) and local state / focus / scroll / in-progress input is
  lost on cloud cold-load (e.g. typing in /login before analytics loads). And it
  was USELESS: the app has ZERO consumers of the PostHog React context (no
  usePostHog / useFeatureFlag* / PostHogFeature), and PostHogProvider given an
  initialized client is a no-op — all capture goes through the posthog singleton.
  Fix: initAnalytics now inits the posthog SINGLETON only (no posthog-js/react
  import, no second render); renderApp() renders <App/> once. First paint stays
  instant, cloud analytics behavior unchanged, no remount.
- F6 [test]: exported isChunkLoadError + chunk-load-error-boundary.test.ts —
  pins the detector (ChunkLoadError name + the 3 dynamic-import failure messages,
  case-insensitive → true; null/undefined/ordinary errors → false) so a
  false-negative that re-blanks the app on a real chunk-404 is caught.

Gate: client tsc 0, chunk-load + sanitize tests 14 passed. Entry chunk unchanged.

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

apps/client/package.json

@@ -13,6 +13,7 @@
   },
   "dependencies": {
     "@ai-sdk/react": "^3.0.208",
+    "@braintree/sanitize-url": "7.1.2",
     "@atlaskit/pragmatic-drag-and-drop": "1.8.1",
     "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "2.1.5",
     "@atlaskit/pragmatic-drag-and-drop-flourish": "2.0.15",

apps/client/src/App.tsx

@@ -1,38 +1,72 @@
+import { lazy, Suspense } from "react";
 import { Navigate, Route, Routes } from "react-router-dom";
+import { Center, Loader } from "@mantine/core";
+import { Error404 } from "@/components/ui/error-404.tsx";
+import Layout from "@/components/layouts/global/layout.tsx";
+import { useTrackOrigin } from "@/hooks/use-track-origin";
+
+// ShareLayout is route-split: its ShareShell chrome pulls in the table of
+// contents (and thus TipTap), so keeping it out of the eager graph removes the
+// editor engine from startup for authenticated users too.
+const ShareLayout = lazy(
+  () => import("@/features/share/components/share-layout.tsx"),
+);
+
+// Auth / entry pages stay eager: they are the first paint for an unauthenticated
+// visitor (e.g. /login) and are already small, so code-splitting them would only
+// add a cold-chunk round trip to the most common cold-start path.
 import SetupWorkspace from "@/pages/auth/setup-workspace.tsx";
 import LoginPage from "@/pages/auth/login";
-import Home from "@/pages/dashboard/home";
-import Page from "@/pages/page/page";
-import AccountSettings from "@/pages/settings/account/account-settings";
-import WorkspaceMembers from "@/pages/settings/workspace/workspace-members";
-import WorkspaceSettings from "@/pages/settings/workspace/workspace-settings";
-import AiSettings from "@/pages/settings/workspace/ai-settings";
-import Groups from "@/pages/settings/group/groups";
-import GroupInfo from "./pages/settings/group/group-info";
-import Spaces from "@/pages/settings/space/spaces.tsx";
-import { Error404 } from "@/components/ui/error-404.tsx";
-import AccountPreferences from "@/pages/settings/account/account-preferences.tsx";
-import SpaceHome from "@/pages/space/space-home.tsx";
-import PageRedirect from "@/pages/page/page-redirect.tsx";
-import Layout from "@/components/layouts/global/layout.tsx";
 import InviteSignup from "@/pages/auth/invite-signup.tsx";
 import ForgotPassword from "@/pages/auth/forgot-password.tsx";
 import PasswordReset from "./pages/auth/password-reset";
-import SharedPage from "@/pages/share/shared-page.tsx";
-import Shares from "@/pages/settings/shares/shares.tsx";
-import ShareLayout from "@/features/share/components/share-layout.tsx";
+import PageRedirect from "@/pages/page/page-redirect.tsx";
 import ShareRedirect from "@/pages/share/share-redirect.tsx";
-import { useTrackOrigin } from "@/hooks/use-track-origin";
-import SpacesPage from "@/pages/spaces/spaces.tsx";
-import SpaceTrash from "@/pages/space/space-trash.tsx";
-import FavoritesPage from "@/pages/favorites/favorites-page";
-import LabelPage from "@/pages/label/label-page";
+
+// Heavy / leaf pages are route-split with React.lazy so their code (most
+// importantly the whole TipTap editor + KaTeX + lowlight grammars + drawio that
+// the page editor and the readonly share editor pull in) is fetched only when
+// the matching route is actually visited. The <Suspense> boundaries live inside
+// each Layout (around its <Outlet/>), so the app shell stays mounted while a
+// route chunk loads.
+const Home = lazy(() => import("@/pages/dashboard/home"));
+const Page = lazy(() => import("@/pages/page/page"));
+const SpaceHome = lazy(() => import("@/pages/space/space-home.tsx"));
+const SpaceTrash = lazy(() => import("@/pages/space/space-trash.tsx"));
+const SpacesPage = lazy(() => import("@/pages/spaces/spaces.tsx"));
+const FavoritesPage = lazy(() => import("@/pages/favorites/favorites-page"));
+const LabelPage = lazy(() => import("@/pages/label/label-page"));
+const SharedPage = lazy(() => import("@/pages/share/shared-page.tsx"));
+
+const AccountSettings = lazy(
+  () => import("@/pages/settings/account/account-settings"),
+);
+const AccountPreferences = lazy(
+  () => import("@/pages/settings/account/account-preferences.tsx"),
+);
+const WorkspaceSettings = lazy(
+  () => import("@/pages/settings/workspace/workspace-settings"),
+);
+const AiSettings = lazy(() => import("@/pages/settings/workspace/ai-settings"));
+const WorkspaceMembers = lazy(
+  () => import("@/pages/settings/workspace/workspace-members"),
+);
+const Groups = lazy(() => import("@/pages/settings/group/groups"));
+const GroupInfo = lazy(() => import("./pages/settings/group/group-info"));
+const Spaces = lazy(() => import("@/pages/settings/space/spaces.tsx"));
+const Shares = lazy(() => import("@/pages/settings/shares/shares.tsx"));
 
 export default function App() {
   useTrackOrigin();
 
   return (
-    <>
+    <Suspense
+      fallback={
+        <Center h="100vh">
+          <Loader size="sm" />
+        </Center>
+      }
+    >
       <Routes>
         <Route index element={<Navigate to="/home" />} />
         <Route path={"/login"} element={<LoginPage />} />
@@ -83,6 +117,6 @@ export default function App() {
 
         <Route path="*" element={<Error404 />} />
       </Routes>
-    </>
+    </Suspense>
   );
 }

apps/client/src/components/chunk-load-error-boundary.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { isChunkLoadError } from "./chunk-load-error-boundary";
+
+// The detector decides whether a caught render error is a stale-deploy chunk-404
+// (→ auto-reload to fetch the new manifest) vs a genuine app error (→ generic
+// recovery UI, no reload). A false negative on a real chunk failure re-blanks the
+// app; a false positive would auto-reload on an ordinary error. Pin both sides.
+describe("isChunkLoadError", () => {
+  it("detects the ChunkLoadError name", () => {
+    expect(isChunkLoadError({ name: "ChunkLoadError", message: "x" })).toBe(true);
+  });
+
+  it.each([
+    "Failed to fetch dynamically imported module: https://x/assets/index-abc.js",
+    "error loading dynamically imported module",
+    "Importing a module script failed.",
+  ])("detects the dynamic-import failure message %#", (message) => {
+    expect(isChunkLoadError({ name: "TypeError", message })).toBe(true);
+  });
+
+  it("is case-insensitive on the message", () => {
+    expect(
+      isChunkLoadError({ message: "FAILED TO FETCH DYNAMICALLY IMPORTED MODULE" }),
+    ).toBe(true);
+  });
+
+  it.each([
+    null,
+    undefined,
+    {},
+    { name: "TypeError", message: "Cannot read properties of undefined" },
+    { message: "Network request failed" },
+    new Error("some ordinary render error"),
+  ])("returns false for a non-chunk error %#", (err) => {
+    expect(isChunkLoadError(err)).toBe(false);
+  });
+});

apps/client/src/components/chunk-load-error-boundary.tsx

@@ -0,0 +1,71 @@
+import { ReactNode } from "react";
+import { ErrorBoundary } from "react-error-boundary";
+import { Button, Center, Stack, Text } from "@mantine/core";
+
+const RELOAD_FLAG = "chunk-reload-attempted";
+
+// Heuristic detection of a failed dynamic import. Since the code-splitting work,
+// every route (plus Aside / AiChatWindow) is React.lazy: when a new deploy
+// replaces the hashed chunks, a tab left open on the old index.html requests a
+// chunk URL that now 404s, and React.lazy rejects. Browsers / Vite surface these
+// with a ChunkLoadError name or one of these messages.
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error) return false;
+  const name = (error as { name?: string }).name ?? "";
+  const message = (error as { message?: string }).message ?? "";
+  return (
+    name === "ChunkLoadError" ||
+    /Failed to fetch dynamically imported module/i.test(message) ||
+    /error loading dynamically imported module/i.test(message) ||
+    /Importing a module script failed/i.test(message)
+  );
+}
+
+function handleError(error: unknown) {
+  if (!isChunkLoadError(error)) return;
+  // A stale-chunk 404 is cured by a full reload that re-fetches index.html and
+  // the new chunk manifest. Auto-reload once, guarding against a reload loop
+  // (e.g. a genuinely missing chunk) with a one-shot sessionStorage flag. If the
+  // flag is already set we fall through to the manual recovery UI below.
+  try {
+    if (sessionStorage.getItem(RELOAD_FLAG)) return;
+    sessionStorage.setItem(RELOAD_FLAG, "1");
+  } catch {
+    // sessionStorage unavailable (private mode / disabled): skip the automatic
+    // reload rather than risk an unguarded loop; the fallback UI still recovers.
+    return;
+  }
+  window.location.reload();
+}
+
+// Root-level boundary that sits ABOVE every route-level Suspense boundary so a
+// lazy route/component chunk failure is caught here instead of unmounting the
+// whole tree into a blank white screen. Per-feature ErrorBoundaries (page.tsx,
+// transclusion, page-embed) remain in place underneath for their local errors.
+export function ChunkLoadErrorBoundary({ children }: { children: ReactNode }) {
+  return (
+    <ErrorBoundary
+      onError={handleError}
+      fallbackRender={({ error }) => {
+        const chunk = isChunkLoadError(error);
+        return (
+          <Center h="100vh" p="md">
+            <Stack align="center" gap="sm" maw={420}>
+              <Text fw={600}>
+                {chunk ? "A new version is available" : "Something went wrong"}
+              </Text>
+              <Text size="sm" c="dimmed" ta="center">
+                {chunk
+                  ? "Please reload the page to load the latest version."
+                  : "An unexpected error occurred. Reloading the page may help."}
+              </Text>
+              <Button onClick={() => window.location.reload()}>Reload</Button>
+            </Stack>
+          </Center>
+        );
+      }}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}

apps/client/src/components/layouts/global/global-app-shell.tsx

@@ -1,9 +1,10 @@
 import { AppShell, Container } from "@mantine/core";
-import React, { useEffect, useRef, useState } from "react";
+import React, { Suspense, useEffect, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import SettingsSidebar from "@/components/settings/settings-sidebar.tsx";
-import { useAtom } from "jotai";
+import { useAtom, useAtomValue } from "jotai";
+import { aiChatWindowOpenAtom } from "@/features/ai-chat/atoms/ai-chat-atom.ts";
 import {
   APP_NAVBAR_ID,
   NAVBAR_COLLAPSE_BREAKPOINT,
@@ -14,8 +15,6 @@ import {
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
 import { SpaceSidebar } from "@/features/space/components/sidebar/space-sidebar.tsx";
 import { AppHeader } from "@/components/layouts/global/app-header.tsx";
-import Aside from "@/components/layouts/global/aside.tsx";
-import AiChatWindow from "@/features/ai-chat/components/ai-chat-window.tsx";
 import GitmostGlobalBridge from "@/features/editor/gitmost/gitmost-global-bridge.tsx";
 import classes from "./app-shell.module.css";
 import { useToggleSidebar } from "@/components/layouts/global/hooks/hooks/use-toggle-sidebar.ts";
@@ -23,6 +22,21 @@ import GlobalSidebar from "@/components/layouts/global/global-sidebar.tsx";
 import { ASIDE_PANEL_ID } from "@/hooks/use-toggle-aside.tsx";
 import { MAIN_CONTENT_ID, SkipToMain } from "@/components/ui/skip-to-main.tsx";
 
+// Lazily load the AI chat window so the AI SDK runtime it pulls in is fetched
+// only after the user first opens the chat, instead of for every authenticated
+// user on load. The window itself renders null while closed, so there is no
+// behavior difference — it simply is not mounted until first opened.
+const AiChatWindow = React.lazy(
+  () => import("@/features/ai-chat/components/ai-chat-window.tsx"),
+);
+
+// The right aside hosts the comment panel and table of contents, both of which
+// pull in TipTap. It only ever renders on page routes, so lazy-loading it keeps
+// the whole editor engine out of the eager global-shell startup graph.
+const Aside = React.lazy(
+  () => import("@/components/layouts/global/aside.tsx"),
+);
+
 export default function GlobalAppShell({
   children,
 }: {
@@ -37,6 +51,15 @@ export default function GlobalAppShell({
   const [isResizing, setIsResizing] = useState(false);
   const sidebarRef = useRef(null);
 
+  // Latch: once the AI chat window has been opened, keep it mounted so an
+  // in-flight stream is never torn down. Before the first open the AI chat chunk
+  // is never fetched.
+  const aiChatOpen = useAtomValue(aiChatWindowOpenAtom);
+  const [aiChatEverOpened, setAiChatEverOpened] = useState(false);
+  useEffect(() => {
+    if (aiChatOpen) setAiChatEverOpened(true);
+  }, [aiChatOpen]);
+
   const startResizing = React.useCallback((mouseDownEvent) => {
     mouseDownEvent.preventDefault();
     setIsResizing(true);
@@ -160,13 +183,21 @@ export default function GlobalAppShell({
                   : undefined
           }
         >
-          <Aside />
+          <Suspense fallback={null}>
+            <Aside />
+          </Suspense>
         </AppShell.Aside>
       )}
     </AppShell>
-    {/* Floating AI chat window. Mounted once globally; it is position: fixed
-        and self-hides when closed, so its place in the tree is not critical. */}
-    <AiChatWindow />
+    {/* Floating AI chat window. Mounted once globally on first open; it is
+        position: fixed and self-hides when closed, so its place in the tree is
+        not critical. Kept mounted after the first open so a live stream is not
+        aborted. */}
+    {aiChatEverOpened && (
+      <Suspense fallback={null}>
+        <AiChatWindow />
+      </Suspense>
+    )}
       {/* Global gitmost native bridge: registers listSpaces / listPages /
           createPageWithRecording on window.gitmost so the native host can
           create a page with a recording even when no page editor is open. */}

apps/client/src/components/layouts/global/layout.tsx

@@ -1,5 +1,7 @@
+import { Suspense, useEffect } from "react";
 import { UserProvider } from "@/features/user/user-provider.tsx";
 import { Outlet, useParams } from "react-router-dom";
+import { Center, Loader } from "@mantine/core";
 import GlobalAppShell from "@/components/layouts/global/global-app-shell.tsx";
 import { SearchSpotlight } from "@/features/search/components/search-spotlight.tsx";
 import { useGetSpaceBySlugQuery } from "@/features/space/queries/space-query.ts";
@@ -8,10 +10,39 @@ export default function Layout() {
   const { spaceSlug } = useParams();
   const { data: space } = useGetSpaceBySlugQuery(spaceSlug);
 
+  // Warm the (now route-split) editor chunk during idle time on authenticated
+  // routes, so the first navigation to a page renders from cache instead of a
+  // cold chunk fetch. Best-effort: gated on requestIdleCallback and never blocks
+  // startup — the dynamic import mirrors the App.tsx route lazy loader so both
+  // resolve to the same chunk.
+  useEffect(() => {
+    const ric =
+      typeof window !== "undefined" && (window as any).requestIdleCallback;
+    const warm = () => {
+      // Best-effort prefetch: a failed warm-up (offline, stale 404) is harmless
+      // and must not surface as an unhandledrejection.
+      void import("@/pages/page/page").catch(() => {});
+    };
+    if (ric) {
+      const id = ric(warm);
+      return () => (window as any).cancelIdleCallback?.(id);
+    }
+    const timer = setTimeout(warm, 2000);
+    return () => clearTimeout(timer);
+  }, []);
+
   return (
     <UserProvider>
       <GlobalAppShell>
-        <Outlet />
+        <Suspense
+          fallback={
+            <Center h="60vh">
+              <Loader size="sm" />
+            </Center>
+          }
+        >
+          <Outlet />
+        </Suspense>
       </GlobalAppShell>
       <SearchSpotlight spaceId={space?.id} />
     </UserProvider>

apps/client/src/features/editor/atoms/editor-atoms.ts

@@ -1,5 +1,8 @@
 import { atom } from "jotai";
-import { Editor } from "@tiptap/core";
+// Type-only: these atoms only hold an Editor reference for typing. A value
+// import would drag the whole @tiptap/core engine into the eager graph of every
+// shell component that reads one of these atoms.
+import type { Editor } from "@tiptap/core";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";
 

apps/client/src/features/editor/components/drawio/drawio-menu-lazy.tsx

@@ -0,0 +1,16 @@
+import { lazy, Suspense } from "react";
+import { EditorMenuProps } from "@/features/editor/components/table/types/types.ts";
+
+// Lazily load the drawio bubble menu so it is split out of the editor chunk and
+// fetched only when an editable editor is mounted (mirrors excalidraw-menu-lazy).
+const DrawioMenu = lazy(
+  () => import("@/features/editor/components/drawio/drawio-menu.tsx"),
+);
+
+export default function DrawioMenuLazy(props: EditorMenuProps) {
+  return (
+    <Suspense fallback={null}>
+      <DrawioMenu {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/drawio/drawio-view-lazy.tsx

@@ -0,0 +1,17 @@
+import { lazy, Suspense } from "react";
+import { NodeViewProps } from "@tiptap/react";
+
+// Lazily load the drawio node view so the heavy react-drawio embed runtime is
+// split into its own chunk and fetched only when a drawio diagram is actually
+// rendered (mirrors excalidraw-view-lazy).
+const DrawioView = lazy(
+  () => import("@/features/editor/components/drawio/drawio-view.tsx"),
+);
+
+export default function DrawioViewLazy(props: NodeViewProps) {
+  return (
+    <Suspense fallback={null}>
+      <DrawioView {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/math/math-block-lazy.tsx

@@ -0,0 +1,19 @@
+import { lazy, Suspense } from "react";
+import { NodeViewProps } from "@tiptap/react";
+
+// Lazily load the KaTeX-backed block math view so the katex chunk is fetched
+// only when a document actually contains a math node (mirrors the mermaid/
+// excalidraw lazy pattern). The local Suspense keeps a slow katex chunk from
+// crashing or blocking the whole editor: while it loads we render the raw
+// LaTeX source as a node-sized placeholder.
+const MathBlockView = lazy(
+  () => import("@/features/editor/components/math/math-block.tsx"),
+);
+
+export default function MathBlockViewLazy(props: NodeViewProps) {
+  return (
+    <Suspense fallback={<div data-katex="true">{props.node.attrs.text}</div>}>
+      <MathBlockView {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/math/math-inline-lazy.tsx

@@ -0,0 +1,19 @@
+import { lazy, Suspense } from "react";
+import { NodeViewProps } from "@tiptap/react";
+
+// Lazily load the KaTeX-backed inline math view so the katex chunk is fetched
+// only when a document actually contains a math node (mirrors the mermaid/
+// excalidraw lazy pattern). The local Suspense keeps a slow katex chunk from
+// crashing or blocking the whole editor: while it loads we render the raw
+// LaTeX source as a node-sized placeholder.
+const MathInlineView = lazy(
+  () => import("@/features/editor/components/math/math-inline.tsx"),
+);
+
+export default function MathInlineViewLazy(props: NodeViewProps) {
+  return (
+    <Suspense fallback={<span data-katex="true">{props.node.attrs.text}</span>}>
+      <MathInlineView {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/extensions/extensions.ts

@@ -81,8 +81,8 @@ import {
   createResizeHandle,
   buildResizeClasses,
 } from "@/features/editor/components/common/node-resize-handles.ts";
-import MathInlineView from "@/features/editor/components/math/math-inline.tsx";
-import MathBlockView from "@/features/editor/components/math/math-block.tsx";
+import MathInlineView from "@/features/editor/components/math/math-inline-lazy.tsx";
+import MathBlockView from "@/features/editor/components/math/math-block-lazy.tsx";
 import ImageView from "@/features/editor/components/image/image-view.tsx";
 import CalloutView from "@/features/editor/components/callout/callout-view.tsx";
 import StatusView from "@/features/editor/components/status/status-view.tsx";
@@ -90,7 +90,7 @@ import VideoView from "@/features/editor/components/video/video-view.tsx";
 import AudioView from "@/features/editor/components/audio/audio-view.tsx";
 import AttachmentView from "@/features/editor/components/attachment/attachment-view.tsx";
 import CodeBlockView from "@/features/editor/components/code-block/code-block-view.tsx";
-import DrawioView from "../components/drawio/drawio-view";
+import DrawioView from "../components/drawio/drawio-view-lazy.tsx";
 import ExcalidrawView from "@/features/editor/components/excalidraw/excalidraw-view-lazy.tsx";
 import EmbedView from "@/features/editor/components/embed/embed-view.tsx";
 import HtmlEmbedView from "@/features/editor/components/html-embed/html-embed-view.tsx";

apps/client/src/features/editor/gitmost/gitmost-global-bridge.tsx

@@ -1,8 +1,17 @@
 import { useEffect, useRef } from "react";
 import { useNavigate } from "react-router-dom";
 import { getDefaultStore } from "jotai";
-import { WebSocketStatus } from "@hocuspocus/provider";
-import { Editor } from "@tiptap/core";
+
+// Literal value of WebSocketStatus.Connected from @hocuspocus/provider. Inlined
+// so this always-mounted global bridge does not statically import
+// @hocuspocus/provider — that import pulls Yjs (and, through a shared chunk, the
+// whole TipTap engine) into the eager startup graph. yjsConnectionStatusAtom
+// already stores these raw status strings.
+const YJS_STATUS_CONNECTED = "connected";
+// Type-only: importing Editor as a type keeps @tiptap/core (the whole editor
+// engine) out of the eager global-shell graph — the bridge only uses it for
+// annotations/casts, never as a runtime value.
+import type { Editor } from "@tiptap/core";
 import {
   pageEditorAtom,
   yjsConnectionStatusAtom,
@@ -16,16 +25,19 @@ import {
   getSidebarPages,
 } from "@/features/page/services/page-service.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
-import {
+// Types are erased at build time, so importing them does not pull the module's
+// runtime (which drags in @tiptap + the editor-ext barrel). The actual recording
+// helpers are dynamically imported at call time inside createPageWithRecording,
+// keeping the editor engine out of the eager global-shell startup graph — the
+// bridge is mounted for every authenticated user but recording is a rare,
+// native-host-driven action.
+import type {
   GitmostBridge,
   GitmostCreatePagePayload,
   GitmostCreatePageResult,
   GitmostListPagesPayload,
   GitmostListPagesResult,
   GitmostListSpacesResult,
-  gitmostDecodePayloadToFile,
-  gitmostInsertTranscriptIntoEditor,
-  gitmostUploadFileToEditor,
 } from "@/features/editor/gitmost/gitmost-recording.ts";
 
 // How long to wait for a freshly-navigated page's editor to mount, become
@@ -58,7 +70,7 @@ function gitmostWaitForEditor(
         !editor.isDestroyed &&
         editor.isEditable &&
         editorPageId === pageId &&
-        yjsStatus === WebSocketStatus.Connected;
+        yjsStatus === YJS_STATUS_CONNECTED;
       if (ready) {
         resolve(editor);
         return;
@@ -172,6 +184,15 @@ export default function GitmostGlobalBridge() {
           };
         }
 
+        // Load the recording helpers on demand (see the import note above). This
+        // is the only place they are needed, so the @tiptap/editor-ext code they
+        // pull in stays out of the eager startup graph.
+        const {
+          gitmostDecodePayloadToFile,
+          gitmostUploadFileToEditor,
+          gitmostInsertTranscriptIntoEditor,
+        } = await import("@/features/editor/gitmost/gitmost-recording.ts");
+
         // Validate/decode the recording BEFORE creating the page so a bad
         // payload never leaves an empty junk page behind. Per the createPage
         // error contract, any decode failure collapses to "insert-failed" (the

apps/client/src/features/editor/page-editor.tsx

@@ -59,7 +59,7 @@ import {
   handlePaste,
 } from "@/features/editor/components/common/editor-paste-handler.tsx";
 import ExcalidrawMenu from "./components/excalidraw/excalidraw-menu-lazy";
-import DrawioMenu from "./components/drawio/drawio-menu";
+import DrawioMenu from "./components/drawio/drawio-menu-lazy";
 import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import SearchAndReplaceDialog from "@/features/editor/components/search-and-replace/search-and-replace-dialog.tsx";
 import { useDebouncedCallback, useDocumentVisibility } from "@mantine/hooks";

apps/client/src/features/share/components/share-layout.tsx

@@ -1,10 +1,20 @@
+import { Suspense } from "react";
 import { Outlet } from "react-router-dom";
+import { Center, Loader } from "@mantine/core";
 import ShareShell from "@/features/share/components/share-shell.tsx";
 
 export default function ShareLayout() {
   return (
     <ShareShell>
-      <Outlet />
+      <Suspense
+        fallback={
+          <Center h="60vh">
+            <Loader size="sm" />
+          </Center>
+        }
+      >
+        <Outlet />
+      </Suspense>
     </ShareShell>
   );
 }

apps/client/src/hooks/use-clipboard.ts

@@ -1,7 +1,7 @@
 // Source: https://github.com/mantinedev/mantine/blob/master/packages/@mantine/hooks/src/use-clipboard/use-clipboard.ts
 // polyfilled to support execCommand fallback
 import { useState } from "react";
-import { execCommandCopy } from "@docmost/editor-ext";
+import { execCommandCopy } from "@/lib/copy-to-clipboard.ts";
 
 export type UseClipboardOptions = {
   timeout?: number;

apps/client/src/lib/config.ts

@@ -1,7 +1,7 @@
 import bytes from "bytes";
 import { castToBoolean } from "@/lib/utils.tsx";
 import { AvatarIconType } from "@/features/attachments/types/attachment.types.ts";
-import { sanitizeUrl } from "@docmost/editor-ext";
+import { sanitizeUrl } from "@/lib/sanitize-url.ts";
 
 declare global {
   interface Window {

apps/client/src/lib/copy-to-clipboard.ts

@@ -0,0 +1,16 @@
+// Client-local execCommand copy fallback (previously imported from
+// @docmost/editor-ext). It lives here so the ubiquitous useClipboard / CopyButton
+// path does not pull in the editor-ext barrel — and with it the whole TipTap
+// engine — through the eager startup graph. Behavior is identical to the
+// editor-ext helper it replaces.
+export function execCommandCopy(text: string): void {
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.style.position = "fixed";
+  textarea.style.left = "-9999px";
+  textarea.style.top = "-9999px";
+  document.body.appendChild(textarea);
+  textarea.select();
+  document.execCommand("copy");
+  document.body.removeChild(textarea);
+}

apps/client/src/lib/sanitize-url.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { sanitizeUrl } from "./sanitize-url";
+
+// `sanitizeUrl` is a byte-identical client-local copy of editor-ext's wrapper
+// around @braintree/sanitize-url: it maps the sanitizer's "about:blank" XSS
+// sentinel to "". These assertions mirror editor-ext's own security-contract
+// test so the extracted copy keeps the same guarantees.
+describe("sanitizeUrl", () => {
+  it("blocks dangerous schemes (returns empty string)", () => {
+    expect(sanitizeUrl("javascript:alert(1)")).toBe("");
+    expect(sanitizeUrl("data:text/html,<script>alert(1)</script>")).toBe("");
+    expect(sanitizeUrl("vbscript:msgbox(1)")).toBe("");
+    // Case / whitespace obfuscation must not slip past the sanitizer.
+    expect(sanitizeUrl("  JaVaScRiPt:alert(1)")).toBe("");
+  });
+
+  it("returns empty string for empty / undefined input", () => {
+    expect(sanitizeUrl(undefined)).toBe("");
+    expect(sanitizeUrl("")).toBe("");
+  });
+
+  it("allows safe https, relative file and mailto URLs", () => {
+    expect(sanitizeUrl("https://example.com/page")).toMatch(
+      /^https:\/\/example\.com\/page/,
+    );
+    expect(sanitizeUrl("/api/files/abc-123")).toBe("/api/files/abc-123");
+    expect(sanitizeUrl("mailto:user@example.com")).toBe(
+      "mailto:user@example.com",
+    );
+  });
+});

apps/client/src/lib/sanitize-url.ts

@@ -0,0 +1,15 @@
+import { sanitizeUrl as braintreeSanitizeUrl } from "@braintree/sanitize-url";
+
+// Client-local copy of editor-ext's sanitizeUrl wrapper. Importing it from the
+// editor-ext barrel dragged the whole TipTap engine into the eager startup graph
+// via the app-wide config module (getFileUrl). This keeps the exact same
+// behavior (braintree sanitize + normalize "about:blank" -> "") without that
+// dependency.
+export function sanitizeUrl(url: string | undefined): string {
+  if (!url) return "";
+
+  const sanitized = braintreeSanitizeUrl(url);
+
+  // Return an empty string instead of "about:blank".
+  return sanitized === "about:blank" ? "" : sanitized;
+}

apps/client/src/main.tsx

@@ -13,15 +13,14 @@ import { ModalsProvider } from "@mantine/modals";
 import { Notifications } from "@mantine/notifications";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { HelmetProvider } from "react-helmet-async";
+import { ChunkLoadErrorBoundary } from "@/components/chunk-load-error-boundary.tsx";
 import "./i18n";
-import { PostHogProvider } from "posthog-js/react";
 import {
   getPostHogHost,
   getPostHogKey,
   isCloud,
   isPostHogEnabled,
 } from "@/lib/config.ts";
-import posthog from "posthog-js";
 import { initVitals } from "@/lib/telemetry/vitals";
 
 export const queryClient = new QueryClient({
@@ -35,15 +34,6 @@ export const queryClient = new QueryClient({
   },
 });
 
-if (isCloud() && isPostHogEnabled) {
-  posthog.init(getPostHogKey(), {
-    api_host: getPostHogHost(),
-    defaults: "2025-05-24",
-    disable_session_recording: true,
-    capture_pageleave: false,
-  });
-}
-
 // #355 — client perf-telemetry. Decides sampling ONCE (25%/session) before
 // subscribing to any observer; non-sampled sessions send nothing.
 initVitals();
@@ -51,19 +41,62 @@ initVitals();
 const container = document.getElementById("root") as HTMLElement;
 const root = (container as any).__reactRoot ??= ReactDOM.createRoot(container);
 
-root.render(
-  <BrowserRouter>
-    <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
-      <ModalsProvider>
-        <QueryClientProvider client={queryClient}>
-          <Notifications position="bottom-center" limit={3} zIndex={10000} />
-          <HelmetProvider>
-            <PostHogProvider client={posthog}>
-              <App />
-            </PostHogProvider>
-          </HelmetProvider>
-        </QueryClientProvider>
-      </ModalsProvider>
-    </MantineProvider>
-  </BrowserRouter>,
-);
+function renderApp() {
+  root.render(
+    <BrowserRouter>
+      <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
+        <ModalsProvider>
+          <QueryClientProvider client={queryClient}>
+            <Notifications position="bottom-center" limit={3} zIndex={10000} />
+            <HelmetProvider>
+              {/* Root boundary above every lazy route's Suspense: a stale-chunk
+                  404 after a deploy is caught and recovered here instead of
+                  blanking the whole app. */}
+              <ChunkLoadErrorBoundary>
+                <App />
+              </ChunkLoadErrorBoundary>
+            </HelmetProvider>
+          </QueryClientProvider>
+        </ModalsProvider>
+      </MantineProvider>
+    </BrowserRouter>,
+  );
+}
+
+async function initAnalytics() {
+  // posthog-js is only pulled in for cloud deployments with analytics enabled, so
+  // self-hosted builds never download it. The gate is kept identical to the
+  // previous eager code so cloud analytics behavior is unchanged; the import is
+  // simply deferred behind it.
+  //
+  // Crucially this runs AFTER the immediate first render below, so first paint is
+  // never gated on the analytics chunk. Any failure (network, stale 404, or an
+  // ad-blocker blocking a chunk named "posthog") is swallowed so the user keeps a
+  // working app without analytics instead of a permanently blank page.
+  //
+  // NOTE: we init the posthog SINGLETON only and do NOT wrap the tree in
+  // <PostHogProvider>. The app has zero consumers of the PostHog React context
+  // (no usePostHog / useFeatureFlag* / PostHogFeature), and PostHogProvider given
+  // an already-initialized `client` is a no-op — all capture goes through the
+  // singleton. Re-rendering to attach the provider would only REMOUNT the whole
+  // App (running every mount effect twice and dropping local state / focus /
+  // in-progress input on cloud cold-load) for no functional gain.
+  if (!(isCloud() && isPostHogEnabled)) return;
+  try {
+    const { default: posthog } = await import("posthog-js");
+    posthog.init(getPostHogKey(), {
+      api_host: getPostHogHost(),
+      defaults: "2025-05-24",
+      disable_session_recording: true,
+      capture_pageleave: false,
+    });
+  } catch {
+    // Analytics failed to load — degrade gracefully; the app already rendered.
+  }
+}
+
+// Paint immediately for everyone (self-hosted stays exactly as instant as before,
+// cloud no longer blocks on the analytics import). The posthog singleton is
+// initialized after, without re-rendering the tree.
+renderApp();
+void initAnalytics();

apps/client/vite.config.ts

@@ -63,6 +63,20 @@ export default defineConfig(({ mode }) => {
                 name: "vendor-mantine",
                 test: /[\\/]node_modules[\\/]@mantine[\\/]/,
               },
+              // NOTE: TipTap/ProseMirror/Yjs are intentionally NOT force-grouped
+              // into a single vendor chunk. Doing so backfires: rolldown co-locates
+              // a small module shared with the (eager) react-i18next runtime into
+              // that group chunk, which then drags the whole ~590KB editor engine
+              // into the eager modulepreload graph. Left to the default splitting,
+              // the editor engine stays in lazily-loaded chunks pulled only by the
+              // route-split editor/share pages. KaTeX is safe to group (nothing
+              // eager references it).
+              // KaTeX in its own stable chunk; loaded on demand by the lazy math
+              // node views (never in the startup path).
+              {
+                name: "vendor-katex",
+                test: /[\\/]node_modules[\\/]katex[\\/]/,
+              },
             ],
           },
         },

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

@@ -1,329 +0,0 @@
-import { Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
-
-/**
- * In-memory run-stream registry (#184 phase 1.5). A durable agent run tees its
- * SSE frames here (via `pipeUIMessageStreamToResponse({ consumeSseStream })`)
- * so a LATE tab — one that reloaded, or opened after the starter dropped — can
- * attach through `GET /ai-chat/runs/:chatId/stream`, replay the frames buffered
- * so far, and then follow the live tail as a normal streamer.
- *
- * This is deliberately single-process and best-effort: it holds nothing the DB
- * does not (the run + assistant row are the source of truth), so a process
- * restart simply drops in-flight entries and the client falls back to its
- * restore + degraded-poll path. The async `attach` return type is the seam for a
- * future phase-2 cross-process backend (Redis) — the interface does not change.
- */
-
-/** How long a finished entry is retained for late attach (replay + immediate end). */
-export const RUN_STREAM_RETAIN_FINISHED_MS = 30_000;
-
-/** Per-run replay buffer cap. Past this the buffer is dropped (attach -> 204). */
-export const RUN_STREAM_MAX_BUFFER_BYTES = 4 * 1024 * 1024;
-
-// 2x the replay cap: a just-written 4MB replay burst alone can never trip the
-// per-subscriber cap (see controller); only a genuinely stalled socket can.
-export const SUBSCRIBER_MAX_BUFFERED_BYTES = 2 * RUN_STREAM_MAX_BUFFER_BYTES;
-
-export interface RunStreamCallbacks {
-  onFrame: (frame: string) => void;
-  onEnd: () => void;
-}
-
-export interface RunStreamAttachment {
-  replay: string[];
-  finished: boolean;
-  start(): void; // drain pending frames (order preserved) and go live
-  unsubscribe(): void; // safe to call at any point, idempotent
-}
-
-interface Subscriber extends RunStreamCallbacks {
-  started: boolean;
-  pending: string[];
-  // Byte size of `pending`, capped at SUBSCRIBER_MAX_BUFFERED_BYTES. `start()` is
-  // called in the SAME tick as `attach()` today (see attach), so `pending` never
-  // holds more than one microtask of frames — but the async `attach` signature is
-  // a phase-2 seam: an await between attach and start would let a stalled paused
-  // subscriber buffer the WHOLE run here. The cap is the structural backstop.
-  pendingBytes: number;
-  overflowed: boolean;
-  pendingEnd: boolean;
-}
-
-interface Entry {
-  runId: string;
-  // The persisted assistant row id of this run (set at bind; undefined if the
-  // seed failed). Used by the attach anchor check (invariant 6).
-  assistantMessageId?: string;
-  frames: string[];
-  bytes: number;
-  overflowed: boolean;
-  finished: boolean;
-  subscribers: Set<Subscriber>;
-  retainTimer?: NodeJS.Timeout;
-}
-
-@Injectable()
-export class AiChatStreamRegistryService implements OnModuleDestroy {
-  private readonly logger = new Logger(AiChatStreamRegistryService.name);
-  private readonly entries = new Map<string, Entry>(); // key: chatId
-
-  /**
-   * Register a fresh entry at the START of a run (before any frame), so a tab
-   * that attaches in the begin->seed window finds an entry to wait on. If an
-   * entry already exists for this chat (a previous, possibly still-live run whose
-   * tee loop is draining), it is terminated MIRRORING the done-path (invariant 3)
-   * so its subscribers are released and its retention timer is cleared; a late
-   * `done` from that old tee then fires against the closed-over old reference and,
-   * thanks to identity checks, never touches this new entry.
-   */
-  open(chatId: string, runId: string): void {
-    const existing = this.entries.get(chatId);
-    if (existing) {
-      if (existing.retainTimer) {
-        clearTimeout(existing.retainTimer);
-        existing.retainTimer = undefined;
-      }
-      // Started subscribers get exactly one onEnd() and are removed; paused ones
-      // are marked pendingEnd (their start() will end them). finished=true guards
-      // any later done from the old tee loop from double-notifying.
-      this.terminateSubscribers(existing);
-    }
-    this.entries.set(chatId, {
-      runId,
-      frames: [],
-      bytes: 0,
-      overflowed: false,
-      finished: false,
-      subscribers: new Set<Subscriber>(),
-    });
-  }
-
-  /**
-   * Tee a run's SSE frame stream into its entry (called from consumeSseStream).
-   * No-op with a warning when there is no entry or the entry belongs to a
-   * different run (invariant 1). The reader loop is fire-and-forget: the tee
-   * branch outlives the client socket by design.
-   */
-  bind(
-    chatId: string,
-    runId: string,
-    assistantMessageId: string | undefined,
-    stream: ReadableStream<string>,
-  ): void {
-    const entry = this.entries.get(chatId);
-    if (!entry || entry.runId !== runId) {
-      // Invariant 1: only the matching run may mutate the entry.
-      this.logger.warn(
-        `bind: no matching run-stream entry for chat=${chatId} run=${runId}`,
-      );
-      return;
-    }
-    entry.assistantMessageId = assistantMessageId;
-    const reader = stream.getReader();
-    const pump = async (): Promise<void> => {
-      try {
-        for (;;) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          this.ingestFrame(entry, value);
-        }
-        this.finalizeEntry(chatId, entry);
-      } catch {
-        // A read error is a terminal event too — release subscribers.
-        this.finalizeEntry(chatId, entry);
-      }
-    };
-    void pump();
-  }
-
-  /**
-   * Terminate a run's entry from the OUTER catch of the stream method (a failure
-   * before/while wiring the pipe, so `done` will never arrive). Identity-checked
-   * on runId (invariant 1); the shared terminal path is idempotent.
-   */
-  abortEntry(chatId: string, runId: string): void {
-    const entry = this.entries.get(chatId);
-    if (!entry || entry.runId !== runId) return;
-    this.finalizeEntry(chatId, entry);
-  }
-
-  /**
-   * Attach to a run's stream. Async only for the phase-2 Redis seam — the body
-   * runs synchronously so the replay snapshot and the subscriber registration
-   * happen in ONE tick with no await between them (invariant 4): a frame ingested
-   * concurrently cannot slip into the gap and be lost or duplicated.
-   *
-   * Returns null (-> the caller answers 204) when:
-   *  - there is no entry, or it overflowed (replay is gone);
-   *  - expect=live with an anchor that does not match this run's assistant id
-   *    (invariant 6: a stripped tab must never replay a FOREIGN run's transcript);
-   *  - the run finished and the caller did not expect a live tail.
-   * A finished run with expect=live yields a replay-only attachment (no
-   * subscriber registered). Otherwise a paused subscriber is registered and the
-   * caller replays `replay`, then calls start() to drain and go live.
-   */
-  async attach(
-    chatId: string,
-    expectLive: boolean,
-    anchor: string | undefined,
-    cb: RunStreamCallbacks,
-  ): Promise<RunStreamAttachment | null> {
-    const entry = this.entries.get(chatId);
-    if (!entry || entry.overflowed) return null;
-    // Invariant 6: cross-run replay is forbidden. Before bind, assistantMessageId
-    // is undefined and mismatches any anchor -> 204 -> client restore+poll path.
-    if (expectLive && anchor && entry.assistantMessageId !== anchor) return null;
-    if (entry.finished && !expectLive) return null;
-    if (entry.finished && expectLive) {
-      // Replay-only: the run is done, no subscriber is registered.
-      return {
-        replay: entry.frames.slice(),
-        finished: true,
-        start: () => undefined,
-        unsubscribe: () => undefined,
-      };
-    }
-
-    const sub: Subscriber = {
-      onFrame: cb.onFrame,
-      onEnd: cb.onEnd,
-      started: false,
-      pending: [],
-      pendingBytes: 0,
-      overflowed: false,
-      pendingEnd: false,
-    };
-    entry.subscribers.add(sub);
-    // Snapshot in the SAME synchronous block as the registration (invariant 4).
-    const replay = entry.frames.slice();
-    // CONTRACT: the caller MUST call start() in the SAME tick as this attach()
-    // returns — no await between them. While a subscriber is paused, every frame
-    // is buffered in sub.pending; a delayed start() lets a whole run accumulate
-    // there. The pendingBytes cap (see ingestFrame) is the structural backstop if
-    // that contract is ever broken (e.g. the phase-2 Redis await seam).
-    return {
-      replay,
-      finished: false,
-      start: () => {
-        if (sub.overflowed) {
-          // The pending buffer overflowed while paused: end the stream instead of
-          // replaying a partial (a 204-equivalent post-attach degrade).
-          try {
-            sub.onEnd();
-          } catch {
-            // The socket is gone; nothing to end.
-          }
-          entry.subscribers.delete(sub);
-          return;
-        }
-        // Deliver frames buffered while paused, in order, then go live.
-        for (const frame of sub.pending) {
-          try {
-            sub.onFrame(frame);
-          } catch {
-            entry.subscribers.delete(sub);
-            return;
-          }
-        }
-        sub.pending = [];
-        sub.started = true;
-        if (sub.pendingEnd) {
-          try {
-            sub.onEnd();
-          } catch {
-            // The socket is gone; nothing to end.
-          }
-          entry.subscribers.delete(sub);
-        }
-      },
-      unsubscribe: () => {
-        entry.subscribers.delete(sub);
-      },
-    };
-  }
-
-  onModuleDestroy(): void {
-    for (const entry of this.entries.values()) {
-      if (entry.retainTimer) clearTimeout(entry.retainTimer);
-    }
-    this.entries.clear();
-  }
-
-  /** Buffer + fan-out a single frame. See invariant/overflow semantics inline. */
-  private ingestFrame(entry: Entry, frame: string): void {
-    entry.bytes += Buffer.byteLength(frame);
-    if (!entry.overflowed) {
-      entry.frames.push(frame);
-      if (entry.bytes > RUN_STREAM_MAX_BUFFER_BYTES) {
-        // The crossing frame was already counted AND (below) fanned out; only the
-        // replay buffer is dropped. After overflow no more frames are buffered,
-        // but live fan-out continues.
-        entry.overflowed = true;
-        entry.frames = [];
-        this.logger.warn(
-          `run-stream buffer overflow for run=${entry.runId}; ` +
-            `late attach will 204 until the run ends`,
-        );
-      }
-    }
-    for (const sub of entry.subscribers) {
-      if (sub.started) {
-        try {
-          sub.onFrame(frame);
-        } catch {
-          entry.subscribers.delete(sub);
-        }
-      } else {
-        sub.pending.push(frame);
-        sub.pendingBytes += Buffer.byteLength(frame);
-        if (sub.pendingBytes > SUBSCRIBER_MAX_BUFFERED_BYTES) {
-          // The paused subscriber's buffer overflowed — only possible if start()
-          // was delayed past the same-tick contract (the phase-2 await seam).
-          // Drop it rather than buffer the whole run; on start() it degrades to an
-          // immediate end (a 204-equivalent) instead of replaying a partial.
-          sub.overflowed = true;
-          sub.pending = [];
-          entry.subscribers.delete(sub);
-        }
-      }
-    }
-  }
-
-  /**
-   * Shared terminal path for done / read-error / external-abort. Idempotent: a
-   * second call (already finished) is a no-op, so an open()-replaced or
-   * abort-then-done entry is never double-armed or double-ended.
-   */
-  private finalizeEntry(chatId: string, entry: Entry): void {
-    if (entry.finished) return;
-    this.terminateSubscribers(entry);
-    const timer = setTimeout(() => {
-      // Invariant 2: only delete OUR entry (a replacement may already own the key).
-      if (this.entries.get(chatId) === entry) this.entries.delete(chatId);
-    }, RUN_STREAM_RETAIN_FINISHED_MS);
-    timer.unref?.();
-    entry.retainTimer = timer;
-  }
-
-  /**
-   * Mark the entry finished and release its subscribers, mirroring the done-path:
-   * started subscribers get exactly one onEnd() and are removed; paused ones are
-   * flagged pendingEnd so their start() ends them. Deleting the current element
-   * during Set iteration is safe.
-   */
-  private terminateSubscribers(entry: Entry): void {
-    entry.finished = true;
-    for (const sub of entry.subscribers) {
-      if (sub.started) {
-        try {
-          sub.onEnd();
-        } catch {
-          // The socket is gone; nothing to end.
-        }
-        entry.subscribers.delete(sub);
-      } else {
-        sub.pendingEnd = true;
-      }
-    }
-  }
-}

apps/server/src/core/ai-chat/ai-chat-stream-registry.spec.ts

@@ -1,388 +0,0 @@
-import {
-  AiChatStreamRegistryService,
-  RUN_STREAM_MAX_BUFFER_BYTES,
-  RUN_STREAM_RETAIN_FINISHED_MS,
-  RunStreamCallbacks,
-} from './ai-chat-stream-registry.service';
-
-/**
- * Unit tests for the in-memory run-stream registry (#184 phase 1.5). The registry
- * is the whole of the resumable-transport contract: replay ordering, paused ->
- * live hand-off, overflow, retention, the anchor check (invariant 6), and the
- * mirror-the-done-path replace semantics (invariant 3). Every enumerated case in
- * the issue's task 1.5 has a test here.
- */
-
-// A ReadableStream whose frames the test pushes explicitly, plus close/error.
-function makePushStream(): {
-  stream: ReadableStream<string>;
-  push: (f: string) => void;
-  close: () => void;
-  error: (e?: unknown) => void;
-} {
-  let controller!: ReadableStreamDefaultController<string>;
-  const stream = new ReadableStream<string>({
-    start(c) {
-      controller = c;
-    },
-  });
-  return {
-    stream,
-    push: (f) => controller.enqueue(f),
-    close: () => controller.close(),
-    error: (e) => controller.error(e ?? new Error('read error')),
-  };
-}
-
-// Let the fire-and-forget pump drain queued frames (reader.read() resolves on a
-// macrotask boundary for an already-enqueued value).
-const flush = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
-
-function collector(): {
-  cb: RunStreamCallbacks;
-  frames: string[];
-  ended: () => number;
-} {
-  const frames: string[] = [];
-  let ends = 0;
-  return {
-    frames,
-    ended: () => ends,
-    cb: {
-      onFrame: (f) => frames.push(f),
-      onEnd: () => {
-        ends += 1;
-      },
-    },
-  };
-}
-
-describe('AiChatStreamRegistryService', () => {
-  const CHAT = 'chat-1';
-  let registry: AiChatStreamRegistryService;
-
-  beforeEach(() => {
-    registry = new AiChatStreamRegistryService();
-    jest.spyOn((registry as any).logger, 'warn').mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    registry.onModuleDestroy();
-  });
-
-  it('replays frames in arrival order (live attach)', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    src.push('b');
-    src.push('c');
-    await flush();
-
-    const c = collector();
-    const att = await registry.attach(CHAT, false, undefined, c.cb);
-    expect(att).not.toBeNull();
-    expect(att!.replay).toEqual(['a', 'b', 'c']);
-    expect(att!.finished).toBe(false);
-  });
-
-  it('late attach gets the full prefix as replay plus the live tail', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    src.push('b');
-    await flush();
-
-    const c = collector();
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
-    expect(att.replay).toEqual(['a', 'b']);
-    att.start();
-    // Live tail arrives after start().
-    src.push('c');
-    src.push('d');
-    await flush();
-    expect(c.frames).toEqual(['c', 'd']);
-  });
-
-  it('a paused subscriber receives frames buffered during pause in order, then live (no loss/reorder)', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    await flush();
-
-    const c = collector();
-    // Attach (paused). Frames that arrive BEFORE start() must queue, not drop.
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
-    expect(att.replay).toEqual(['a']);
-    src.push('b'); // arrives while paused -> pending
-    src.push('c');
-    await flush();
-    expect(c.frames).toEqual([]); // nothing delivered yet (paused)
-    att.start(); // drains pending in order
-    expect(c.frames).toEqual(['b', 'c']);
-    src.push('d'); // now live
-    await flush();
-    expect(c.frames).toEqual(['b', 'c', 'd']);
-  });
-
-  it('a run that finishes while a subscriber is paused ends it on start()', async () => {
-    registry.open(CHAT, 'run-1');
-    const c = collector();
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
-    // Terminate the run while the subscriber is still paused.
-    registry.abortEntry(CHAT, 'run-1');
-    expect(c.ended()).toBe(0); // paused: not ended yet
-    att.start();
-    expect(c.ended()).toBe(1); // start() drains + ends
-  });
-
-  it('finished + expect=live returns a replay WITHOUT registering a subscriber', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    src.push('b');
-    src.close();
-    await flush();
-
-    const c = collector();
-    const att = (await registry.attach(CHAT, true, undefined, c.cb))!;
-    expect(att.finished).toBe(true);
-    expect(att.replay).toEqual(['a', 'b']);
-    // No subscriber registered: start()/unsubscribe are no-ops and the entry has
-    // zero subscribers.
-    const entry = (registry as any).entries.get(CHAT);
-    expect(entry.subscribers.size).toBe(0);
-    att.start();
-    expect(c.frames).toEqual([]);
-  });
-
-  it('finished WITHOUT expect=live returns null', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    src.close();
-    await flush();
-
-    const c = collector();
-    expect(await registry.attach(CHAT, false, undefined, c.cb)).toBeNull();
-  });
-
-  it('anchor mismatch with expect=live returns null (and null before bind sets assistantMessageId)', async () => {
-    registry.open(CHAT, 'run-1');
-    const c = collector();
-    // Before bind: assistantMessageId is undefined -> mismatches any anchor.
-    expect(
-      await registry.attach(CHAT, true, 'assist-1', c.cb),
-    ).toBeNull();
-
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    await flush();
-    // Wrong anchor -> null (cross-run replay forbidden, invariant 6).
-    expect(await registry.attach(CHAT, true, 'other-id', c.cb)).toBeNull();
-  });
-
-  it('matching anchor with expect=live attaches', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    await flush();
-
-    const c = collector();
-    const att = await registry.attach(CHAT, true, 'assist-1', c.cb);
-    expect(att).not.toBeNull();
-    expect(att!.replay).toEqual(['a']);
-  });
-
-  it('overflow: attach returns null, but the LIVE subscriber keeps receiving (incl. the crossing frame)', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-
-    // A live (started) subscriber attached before the flood.
-    const c = collector();
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
-    att.start();
-
-    const oneMb = 'x'.repeat(1024 * 1024);
-    // 5 x 1MB = 5MB > 4MB cap; the 5th frame is the one that crosses.
-    for (let i = 0; i < 5; i++) src.push(oneMb + i);
-    await flush();
-
-    const entry = (registry as any).entries.get(CHAT);
-    expect(entry.overflowed).toBe(true);
-    expect(entry.bytes).toBeGreaterThan(RUN_STREAM_MAX_BUFFER_BYTES);
-    // The live subscriber received ALL 5 frames, including the crossing one.
-    expect(c.frames).toHaveLength(5);
-    expect(c.frames[4]).toBe(oneMb + 4);
-
-    // A NEW attach after overflow gets null (replay buffer is gone).
-    const c2 = collector();
-    expect(await registry.attach(CHAT, false, undefined, c2.cb)).toBeNull();
-  });
-
-  it('a paused subscriber whose pending buffer overflows is dropped and ends on start(); other subscribers keep receiving', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-
-    // A: paused (start() deliberately delayed to simulate the phase-2 await seam).
-    const a = collector();
-    const attA = (await registry.attach(CHAT, false, undefined, a.cb))!;
-    // B: live (started) — its delivery must be unaffected by A's overflow.
-    const b = collector();
-    const attB = (await registry.attach(CHAT, false, undefined, b.cb))!;
-    attB.start();
-
-    const oneMb = 'x'.repeat(1024 * 1024);
-    // 9 x 1MB = 9MB > 8MB per-subscriber cap; A's pending overflows, B streams live.
-    for (let i = 0; i < 9; i++) src.push(oneMb + i);
-    await flush();
-
-    const entry = (registry as any).entries.get(CHAT);
-    // A was dropped from the subscriber set on overflow; B (started) remains.
-    expect(entry.subscribers.size).toBe(1);
-    expect(a.frames).toEqual([]); // paused + overflowed: nothing was delivered
-    // B received every frame live (delivery unaffected by A's overflow).
-    expect(b.frames).toHaveLength(9);
-
-    // A's start() (arriving late) degrades to an immediate end, not a partial replay.
-    attA.start();
-    expect(a.frames).toEqual([]);
-    expect(a.ended()).toBe(1);
-  });
-
-  it('open() over a LIVE entry ends started subscribers exactly once and a late done does not touch the new entry (invariant 3)', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    await flush();
-
-    const c = collector();
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
-    att.start(); // started subscriber on run-1
-
-    // run-2 starts on the same chat while run-1's tee is still reading.
-    registry.open(CHAT, 'run-2');
-    expect(c.ended()).toBe(1); // exactly one onEnd from the replace
-
-    const newEntry = (registry as any).entries.get(CHAT);
-    expect(newEntry.runId).toBe('run-2');
-    expect(newEntry.finished).toBe(false);
-
-    // The old tee now completes: its late done must NOT double-end nor delete the
-    // new entry.
-    src.push('b');
-    src.close();
-    await flush();
-    expect(c.ended()).toBe(1); // still exactly one
-    const still = (registry as any).entries.get(CHAT);
-    expect(still).toBe(newEntry);
-    expect(still.runId).toBe('run-2');
-  });
-
-  it('bind with a foreign runId is a no-op (invariant 1)', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'WRONG-run', 'assist-x', src.stream);
-    src.push('a');
-    await flush();
-    const entry = (registry as any).entries.get(CHAT);
-    // Frames were NOT ingested (bind bailed), assistantMessageId untouched.
-    expect(entry.frames).toEqual([]);
-    expect(entry.assistantMessageId).toBeUndefined();
-  });
-
-  it('abortEntry with a foreign runId is a no-op (invariant 1)', async () => {
-    registry.open(CHAT, 'run-1');
-    registry.abortEntry(CHAT, 'WRONG-run');
-    const entry = (registry as any).entries.get(CHAT);
-    expect(entry.finished).toBe(false);
-  });
-
-  it('a throwing onFrame ejects only that subscriber; the ingest loop stays alive', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-
-    const bad = collector();
-    const badAtt = (await registry.attach(CHAT, false, undefined, {
-      onFrame: () => {
-        throw new Error('boom');
-      },
-      onEnd: bad.cb.onEnd,
-    }))!;
-    badAtt.start();
-
-    const good = collector();
-    const goodAtt = (await registry.attach(CHAT, false, undefined, good.cb))!;
-    goodAtt.start();
-
-    src.push('a'); // bad throws on this frame -> ejected
-    src.push('b'); // good still receives both
-    await flush();
-
-    const entry = (registry as any).entries.get(CHAT);
-    expect(entry.subscribers.size).toBe(1); // bad ejected, good remains
-    expect(good.frames).toEqual(['a', 'b']);
-  });
-});
-
-/**
- * Retention + replace timer behavior. Fake timers, and entries are finalized via
- * the synchronous abortEntry() path so no stream pump / microtask juggling is
- * needed.
- */
-describe('AiChatStreamRegistryService retention timers', () => {
-  const CHAT = 'chat-r';
-  let registry: AiChatStreamRegistryService;
-
-  beforeEach(() => {
-    jest.useFakeTimers();
-    registry = new AiChatStreamRegistryService();
-    jest.spyOn((registry as any).logger, 'warn').mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    registry.onModuleDestroy();
-    jest.useRealTimers();
-  });
-
-  it('a finished entry is removed after the retention window', () => {
-    registry.open(CHAT, 'run-1');
-    registry.abortEntry(CHAT, 'run-1'); // finalize -> retention armed
-    expect((registry as any).entries.get(CHAT)).toBeDefined();
-    jest.advanceTimersByTime(RUN_STREAM_RETAIN_FINISHED_MS + 1);
-    expect((registry as any).entries.get(CHAT)).toBeUndefined();
-  });
-
-  it('retention deletes ONLY its own entry (invariant 2)', () => {
-    registry.open(CHAT, 'run-1');
-    registry.abortEntry(CHAT, 'run-1'); // arm retention for entry A
-    // Simulate the race where the key was replaced without clearing A's timer.
-    const sentinel = { marker: true };
-    (registry as any).entries.set(CHAT, sentinel);
-    jest.advanceTimersByTime(RUN_STREAM_RETAIN_FINISHED_MS + 1);
-    // A's timer saw entries.get(CHAT) !== A, so it did NOT delete the successor.
-    expect((registry as any).entries.get(CHAT)).toBe(sentinel);
-  });
-
-  it('open() over a retained entry clears its timer and the successor survives', () => {
-    registry.open(CHAT, 'run-1');
-    registry.abortEntry(CHAT, 'run-1'); // retained, timer armed
-    const clearSpy = jest.spyOn(global, 'clearTimeout');
-    registry.open(CHAT, 'run-2'); // must clear run-1's retain timer
-    expect(clearSpy).toHaveBeenCalled();
-    jest.advanceTimersByTime(RUN_STREAM_RETAIN_FINISHED_MS + 1);
-    const entry = (registry as any).entries.get(CHAT);
-    expect(entry).toBeDefined();
-    expect(entry.runId).toBe('run-2');
-  });
-});

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

@@ -1,423 +0,0 @@
-import { ForbiddenException } from '@nestjs/common';
-import { AiChatController } from './ai-chat.controller';
-import type {
-  RunStreamAttachment,
-  RunStreamCallbacks,
-} from './ai-chat-stream-registry.service';
-import { SUBSCRIBER_MAX_BUFFERED_BYTES } from './ai-chat-stream-registry.service';
-import type { User, Workspace } from '@docmost/db/types/entity.types';
-
-/**
- * Wiring spec for the #184 phase 1.5 attach endpoint
- * (`GET /ai-chat/runs/:chatId/stream`). Owner-gated via assertOwnedChat; the
- * registry is mocked so this exercises ONLY the controller's replay/live/204/
- * cleanup wiring against a fake raw socket. Constructor order is (aiChatService,
- * aiChatRunService, aiChatRepo, aiChatMessageRepo, aiTranscription, pageRepo,
- * streamRegistry, environment).
- */
-describe('AiChatController attach endpoint (#184 phase 1.5)', () => {
-  const user = { id: 'u1' } as User;
-  const workspace = { id: 'ws1' } as Workspace;
-
-  function makeRawRes() {
-    const raw: any = {
-      writableEnded: false,
-      writableLength: 0,
-      destroyed: false,
-      written: [] as string[],
-      head: null as any,
-      write: jest.fn((f: string) => {
-        raw.written.push(f);
-        return true;
-      }),
-      writeHead: jest.fn((code: number, headers: any) => {
-        raw.head = { code, headers };
-        return raw;
-      }),
-      flushHeaders: jest.fn(),
-      end: jest.fn(() => {
-        raw.writableEnded = true;
-      }),
-      destroy: jest.fn(() => {
-        raw.destroyed = true;
-      }),
-      on: jest.fn(),
-      once: jest.fn(),
-    };
-    const res: any = {
-      raw,
-      status: jest.fn(() => res),
-      send: jest.fn(),
-      hijack: jest.fn(),
-    };
-    return { res, raw };
-  }
-
-  function makeReq(destroyed = false) {
-    const handlers: Record<string, () => void> = {};
-    const raw: any = {
-      destroyed,
-      once: jest.fn((ev: string, fn: () => void) => {
-        handlers[ev] = fn;
-      }),
-    };
-    return { req: { raw } as any, raw, fireClose: () => handlers['close']?.() };
-  }
-
-  function makeAttachment(
-    over: Partial<RunStreamAttachment> = {},
-  ): RunStreamAttachment {
-    return {
-      replay: [],
-      finished: false,
-      start: jest.fn(),
-      unsubscribe: jest.fn(),
-      ...over,
-    };
-  }
-
-  function makeController(opts: {
-    chat?: unknown;
-    attachment?: RunStreamAttachment | null;
-  }) {
-    const aiChatRepo = { findById: jest.fn().mockResolvedValue(opts.chat) };
-    let capturedCb: RunStreamCallbacks | undefined;
-    const streamRegistry = {
-      attach: jest.fn(
-        (
-          _chatId: string,
-          _live: boolean,
-          _anchor: string | undefined,
-          cb: RunStreamCallbacks,
-        ) => {
-          capturedCb = cb;
-          return Promise.resolve(
-            opts.attachment === undefined ? makeAttachment() : opts.attachment,
-          );
-        },
-      ),
-    };
-    const environment = { isAiChatResumableStreamEnabled: () => true };
-    const controller = new AiChatController(
-      {} as never, // aiChatService
-      {} as never, // aiChatRunService
-      aiChatRepo as never,
-      {} as never, // aiChatMessageRepo
-      {} as never, // aiTranscription
-      {} as never, // pageRepo
-      streamRegistry as never,
-      environment as never,
-    );
-    return {
-      controller,
-      aiChatRepo,
-      streamRegistry,
-      getCb: () => capturedCb!,
-    };
-  }
-
-  const owned = { id: 'c1', creatorId: 'u1' };
-
-  it('owner-gates: a foreign chat throws ForbiddenException and never attaches', async () => {
-    const { controller, streamRegistry } = makeController({
-      chat: { id: 'c1', creatorId: 'someone-else' },
-    });
-    const { res } = makeRawRes();
-    const { req } = makeReq();
-    await expect(
-      controller.attachRunStream(
-        'c1',
-        undefined,
-        undefined,
-        req,
-        res,
-        user,
-        workspace,
-      ),
-    ).rejects.toBeInstanceOf(ForbiddenException);
-    expect(streamRegistry.attach).not.toHaveBeenCalled();
-  });
-
-  it('answers 204 when the registry has nothing to resume (no entry / finished / anchor-mismatch)', async () => {
-    const { controller } = makeController({ chat: owned, attachment: null });
-    const { res } = makeRawRes();
-    const { req } = makeReq();
-    await controller.attachRunStream(
-      'c1',
-      undefined,
-      undefined,
-      req,
-      res,
-      user,
-      workspace,
-    );
-    expect(res.status).toHaveBeenCalledWith(204);
-    expect(res.send).toHaveBeenCalled();
-    expect(res.hijack).not.toHaveBeenCalled();
-  });
-
-  it('threads expect=live and anchor through to the registry', async () => {
-    const { controller, streamRegistry } = makeController({
-      chat: owned,
-      attachment: null,
-    });
-    const { res } = makeRawRes();
-    const { req } = makeReq();
-    await controller.attachRunStream(
-      'c1',
-      'live',
-      'anchor-1',
-      req,
-      res,
-      user,
-      workspace,
-    );
-    expect(streamRegistry.attach).toHaveBeenCalledWith(
-      'c1',
-      true,
-      'anchor-1',
-      expect.anything(),
-    );
-  });
-
-  it('passes expect=false when the query is absent', async () => {
-    const { controller, streamRegistry } = makeController({
-      chat: owned,
-      attachment: null,
-    });
-    const { res } = makeRawRes();
-    const { req } = makeReq();
-    await controller.attachRunStream(
-      'c1',
-      undefined,
-      undefined,
-      req,
-      res,
-      user,
-      workspace,
-    );
-    expect(streamRegistry.attach).toHaveBeenCalledWith(
-      'c1',
-      false,
-      undefined,
-      expect.anything(),
-    );
-  });
-
-  it('hijacks, writes headers + replay, registers a close cleanup, then goes live', async () => {
-    const start = jest.fn();
-    const attachment = makeAttachment({
-      replay: ['f1', 'f2'],
-      finished: false,
-      start,
-    });
-    const { controller } = makeController({ chat: owned, attachment });
-    const { res, raw } = makeRawRes();
-    const { req } = makeReq();
-    await controller.attachRunStream(
-      'c1',
-      undefined,
-      undefined,
-      req,
-      res,
-      user,
-      workspace,
-    );
-    expect(res.hijack).toHaveBeenCalled();
-    expect(raw.writeHead).toHaveBeenCalledWith(
-      200,
-      expect.objectContaining({ 'content-type': 'text/event-stream' }),
-    );
-    expect(raw.written).toEqual(['f1', 'f2']); // replay
-    expect(start).toHaveBeenCalled(); // go live after replay
-    expect(req.raw.once).toHaveBeenCalledWith('close', expect.any(Function));
-  });
-
-  it('finished replay ends the response immediately without going live', async () => {
-    const start = jest.fn();
-    const attachment = makeAttachment({
-      replay: ['f1'],
-      finished: true,
-      start,
-    });
-    const { controller } = makeController({ chat: owned, attachment });
-    const { res, raw } = makeRawRes();
-    const { req } = makeReq();
-    await controller.attachRunStream(
-      'c1',
-      'live',
-      'a1',
-      req,
-      res,
-      user,
-      workspace,
-    );
-    expect(raw.written).toEqual(['f1']);
-    expect(raw.end).toHaveBeenCalled();
-    expect(start).not.toHaveBeenCalled(); // finished -> returns before start()
-  });
-
-  it('a close during the awaits (req.raw.destroyed) unsubscribes and writes nothing', async () => {
-    const attachment = makeAttachment({ replay: ['f1'] });
-    const { controller } = makeController({ chat: owned, attachment });
-    const { res, raw } = makeRawRes();
-    const { req } = makeReq(true); // destroyed already at registration time
-    await controller.attachRunStream(
-      'c1',
-      undefined,
-      undefined,
-      req,
-      res,
-      user,
-      workspace,
-    );
-    expect(attachment.unsubscribe).toHaveBeenCalled();
-    expect(raw.writeHead).not.toHaveBeenCalled();
-    expect(raw.written).toEqual([]);
-  });
-
-  it('the registered close handler unsubscribes the attachment', async () => {
-    const attachment = makeAttachment({ replay: [] });
-    const { controller } = makeController({ chat: owned, attachment });
-    const { res } = makeRawRes();
-    const { req, fireClose } = makeReq();
-    await controller.attachRunStream(
-      'c1',
-      undefined,
-      undefined,
-      req,
-      res,
-      user,
-      workspace,
-    );
-    expect(attachment.unsubscribe).not.toHaveBeenCalled();
-    fireClose(); // socket closed
-    expect(attachment.unsubscribe).toHaveBeenCalled();
-  });
-
-  it('onFrame destroys the socket when the buffered length exceeds the cap', async () => {
-    const attachment = makeAttachment({ replay: [] });
-    const { controller, getCb } = makeController({ chat: owned, attachment });
-    const { res, raw } = makeRawRes();
-    const { req } = makeReq();
-    await controller.attachRunStream(
-      'c1',
-      undefined,
-      undefined,
-      req,
-      res,
-      user,
-      workspace,
-    );
-    const cb = getCb();
-    // Normal live frame writes.
-    raw.writableLength = 0;
-    cb.onFrame('live-1');
-    expect(raw.written).toContain('live-1');
-    // A stalled socket over the cap is destroyed instead of buffering.
-    raw.writableLength = SUBSCRIBER_MAX_BUFFERED_BYTES + 1;
-    raw.write.mockClear();
-    cb.onFrame('too-much');
-    expect(raw.destroy).toHaveBeenCalled();
-    expect(raw.write).not.toHaveBeenCalled();
-  });
-});
-
-/**
- * The begin-hook `open()` flag gate (#184 phase 1.5). `open()` lives ONLY in the
- * stream() begin-hook, gated on the resumable flag. If it regressed, a flag-off
- * turn would create an EMPTY registry entry (never bound, never finished) and a
- * later attach would find a non-null paused attachment -> a hung SSE that never
- * gets a frame and never ends, instead of a clean 204. These drive stream() only
- * far enough to capture the runHooks it hands to the service, then invoke the
- * begin-hook and assert whether the registry was opened.
- */
-describe('AiChatController begin-hook open() flag gate (#184 phase 1.5)', () => {
-  const user = { id: 'u1' } as User;
-  const workspace = {
-    id: 'ws1',
-    settings: { ai: { chat: true, autonomousRuns: true } },
-  } as unknown as Workspace;
-
-  function makeController(opts: { resumable: boolean }) {
-    let capturedArgs: any;
-    const aiChatService = {
-      resolveRoleForRequest: jest.fn(async () => null),
-      getChatModel: jest.fn(async () => ({})),
-      stream: jest.fn(async (args: any) => {
-        capturedArgs = args;
-      }),
-    };
-    const aiChatRunService = {
-      getActiveForChat: jest.fn(async () => undefined),
-      beginRun: jest.fn(async () => ({
-        runId: 'run-1',
-        signal: new AbortController().signal,
-      })),
-    };
-    const streamRegistry = { open: jest.fn(), attach: jest.fn() };
-    const environment = {
-      isAiChatResumableStreamEnabled: () => opts.resumable,
-    };
-    const controller = new AiChatController(
-      aiChatService as never,
-      aiChatRunService as never,
-      {} as never, // aiChatRepo
-      {} as never, // aiChatMessageRepo
-      {} as never, // aiTranscription
-      {} as never, // pageRepo
-      streamRegistry as never,
-      environment as never,
-    );
-    return {
-      controller,
-      streamRegistry,
-      aiChatRunService,
-      getRunHooks: () => capturedArgs?.runHooks,
-    };
-  }
-
-  function makeReqRes() {
-    const req: any = {
-      raw: { sessionId: 'sess-1', once: jest.fn() },
-      body: {
-        messages: [
-          { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
-        ],
-      },
-    };
-    const res: any = {
-      raw: { once: jest.fn(), on: jest.fn(), headersSent: false, writableEnded: false },
-      hijack: jest.fn(),
-    };
-    return { req, res };
-  }
-
-  it('flag OFF: the begin-hook does NOT open a registry entry (no hung empty entry)', async () => {
-    const { controller, streamRegistry, aiChatRunService, getRunHooks } =
-      makeController({ resumable: false });
-    const { req, res } = makeReqRes();
-    await controller.stream(req, res, user, workspace);
-
-    const runHooks = getRunHooks();
-    expect(runHooks).toBeDefined();
-    const handle = await runHooks.begin('chat-1');
-    // The run still begins (the durable-run feature is independent of resume)...
-    expect(aiChatRunService.beginRun).toHaveBeenCalled();
-    expect(handle).toEqual({ runId: 'run-1', signal: expect.anything() });
-    // ...but with the flag off the registry entry is NEVER opened.
-    expect(streamRegistry.open).not.toHaveBeenCalled();
-  });
-
-  it('flag ON: the begin-hook opens the registry entry with (chatId, runId)', async () => {
-    const { controller, streamRegistry, getRunHooks } = makeController({
-      resumable: true,
-    });
-    const { req, res } = makeReqRes();
-    await controller.stream(req, res, user, workspace);
-
-    const runHooks = getRunHooks();
-    await runHooks.begin('chat-1');
-    expect(streamRegistry.open).toHaveBeenCalledWith('chat-1', 'run-1');
-  });
-});

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

@@ -4,15 +4,11 @@ import {
   ConflictException,
   Controller,
   ForbiddenException,
-  Get,
   HttpCode,
   HttpException,
   HttpStatus,
   Logger,
-  Param,
-  ParseUUIDPipe,
   Post,
-  Query,
   Req,
   Res,
   ServiceUnavailableException,
@@ -58,12 +54,6 @@ import {
 } from './dto/ai-chat.dto';
 import { describeProviderError } from '../../integrations/ai/ai-error.util';
 import { buildChatMarkdown } from './chat-markdown.util';
-import {
-  AiChatStreamRegistryService,
-  SUBSCRIBER_MAX_BUFFERED_BYTES,
-} from './ai-chat-stream-registry.service';
-import { startSseHeartbeat } from './sse-resilience';
-import { EnvironmentService } from '../../integrations/environment/environment.service';
 
 /**
  * Per-user AI chat API (§6.1). Routes are POST to match this codebase's
@@ -82,11 +72,6 @@ export class AiChatController {
     private readonly aiChatMessageRepo: AiChatMessageRepo,
     private readonly aiTranscription: AiTranscriptionService,
     private readonly pageRepo: PageRepo,
-    // #184 phase 1.5. OPTIONAL so existing positional constructions (controller
-    // specs) compile unchanged; Nest always injects the real providers in
-    // production. Only touched on the resumable-stream (flag-on) path.
-    private readonly streamRegistry?: AiChatStreamRegistryService,
-    private readonly environment?: EnvironmentService,
   ) {}
 
   /** List the requesting user's chats in this workspace (paginated). */
@@ -248,102 +233,6 @@ export class AiChatController {
     return { stopped };
   }
 
-  /**
-   * Attach to a chat's live run stream (#184 phase 1.5). A late/reloaded tab
-   * replays the frames buffered so far and then follows the live tail as a normal
-   * streamer. Owner-gated via assertOwnedChat (same gate as getRun). When there is
-   * nothing to resume — no entry, a finished run without expect=live, an
-   * overflowed buffer, or an anchor that pins a DIFFERENT run — the endpoint
-   * answers 204, the ONLY "nothing to resume" signal the AI SDK's reconnect
-   * accepts (it maps 204 to a silent no-op). With AI_CHAT_RESUMABLE_STREAM off the
-   * registry is never populated, so attach always 204s.
-   *
-   * `expect=live` opts into replaying a finished-but-retained run (safe only when
-   * the client stripped the streaming tail); `anchor` is the client's assistant
-   * row id, which must match this run's (invariant 6) or a foreign run's
-   * transcript would be replayed into the store.
-   */
-  @SkipTransform()
-  @UseGuards(JwtAuthGuard, UserThrottlerGuard)
-  @Throttle({ [AI_CHAT_THROTTLER]: { limit: 60, ttl: 60000 } })
-  @Get('runs/:chatId/stream')
-  async attachRunStream(
-    @Param('chatId', new ParseUUIDPipe()) chatId: string,
-    @Query('expect') expect: string | undefined,
-    @Query('anchor') anchor: string | undefined,
-    @Req() req: FastifyRequest,
-    @Res() res: FastifyReply,
-    @AuthUser() user: User,
-    @AuthWorkspace() workspace: Workspace,
-  ): Promise<void> {
-    await this.assertOwnedChat(chatId, user, workspace); // same gate as getRun
-    let stopHeartbeat: () => void = () => undefined;
-    const attachment = await this.streamRegistry?.attach(
-      chatId,
-      expect === 'live',
-      anchor,
-      {
-        onFrame: (frame) => {
-          // Backpressure guard: 2x the replay cap, so the initial replay burst
-          // alone can never trip it; only a genuinely stalled socket can.
-          try {
-            if (res.raw.writableLength > SUBSCRIBER_MAX_BUFFERED_BYTES) {
-              res.raw.destroy(); // 'close' fires -> unsubscribe below
-              return;
-            }
-            if (!res.raw.writableEnded) res.raw.write(frame);
-          } catch {
-            res.raw.destroy();
-          }
-        },
-        onEnd: () => {
-          stopHeartbeat();
-          if (!res.raw.writableEnded) res.raw.end();
-        },
-      },
-    );
-    if (!attachment) {
-      res.status(204).send(); // the ONLY "nothing to resume" signal the SDK accepts
-      return;
-    }
-    res.hijack();
-    // Cleanup BEFORE any write (invariant 5): a torn-down socket must not orphan
-    // a paused subscriber whose pending queue would buffer the whole run.
-    req.raw.once('close', () => {
-      attachment.unsubscribe();
-      stopHeartbeat();
-    });
-    // A close emitted DURING the awaits above was missed by the listener — check.
-    // (Healthy pending GETs have req.raw.destroyed === false, so no false
-    // positives; returning without end() is fine — the socket is gone.)
-    if (req.raw.destroyed) {
-      attachment.unsubscribe();
-      return;
-    }
-    res.raw.on('error', () => undefined);
-    try {
-      res.raw.writeHead(200, {
-        'content-type': 'text/event-stream',
-        'cache-control': 'no-cache',
-        'x-vercel-ai-ui-message-stream': 'v1',
-        'x-accel-buffering': 'no',
-        // deliberately NO Connection/Keep-Alive (hop-by-hop; Safari/HTTP2)
-      });
-      res.raw.flushHeaders?.();
-      for (const frame of attachment.replay) res.raw.write(frame);
-      if (attachment.finished) {
-        res.raw.end();
-        return;
-      }
-      stopHeartbeat = startSseHeartbeat(res.raw, 15_000);
-      attachment.start(); // drain pending accumulated during replay, go live
-    } catch {
-      attachment.unsubscribe();
-      stopHeartbeat();
-      res.raw.destroy();
-    }
-  }
-
   /** Rename a chat. */
   @HttpCode(HttpStatus.OK)
   @Post('rename')
@@ -455,25 +344,13 @@ export class AiChatController {
     // its progress, and settle its terminal status — see AiChatRunService.
     const runHooks: AiChatRunHooks | undefined = autonomousRuns
       ? {
-          begin: async (chatId) => {
-            const handle = await this.aiChatRunService.beginRun({
+          begin: (chatId) =>
+            this.aiChatRunService.beginRun({
               chatId,
               workspaceId: workspace.id,
               userId: user.id,
               trigger: 'user',
-            });
-            // #184 phase 1.5: register the run-stream entry at BEGIN (before any
-            // frame) so a tab that attaches in the begin->seed window finds an
-            // entry to wait on. Gated on AI_CHAT_RESUMABLE_STREAM: with the flag
-            // off nothing is registered and attach always 204s.
-            if (
-              handle?.runId &&
-              this.environment?.isAiChatResumableStreamEnabled?.()
-            ) {
-              this.streamRegistry?.open(chatId, handle.runId);
-            }
-            return handle;
-          },
+            }),
           onAssistantSeeded: (runId, messageId) =>
             this.aiChatRunService.linkAssistantMessage(
               runId,

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

@@ -4,7 +4,6 @@ import { TokenModule } from '../auth/token.module';
 import { AiChatController } from './ai-chat.controller';
 import { AiChatService } from './ai-chat.service';
 import { AiChatRunService } from './ai-chat-run.service';
-import { AiChatStreamRegistryService } from './ai-chat-stream-registry.service';
 import { AiTranscriptionService } from './ai-transcription.service';
 import { AiChatToolsService } from './tools/ai-chat-tools.service';
 import { EmbeddingModule } from './embedding/embedding.module';
@@ -45,7 +44,6 @@ import { PublicShareChatToolsService } from './tools/public-share-chat-tools.ser
   providers: [
     AiChatService,
     AiChatRunService,
-    AiChatStreamRegistryService,
     AiTranscriptionService,
     AiChatToolsService,
     PublicShareChatService,

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

@@ -1,13 +1,4 @@
-import { ForbiddenException, Logger } from '@nestjs/common';
-// Mock ONLY streamText so a driven stream() call can capture the pipe-options
-// object (consumeSseStream / generateMessageId). Everything else in the AI SDK
-// stays REAL (requireActual), so the pure-helper suites in this file are
-// unaffected — none of them call stream()/streamText.
-jest.mock('ai', () => ({
-  ...jest.requireActual('ai'),
-  streamText: jest.fn(),
-}));
-import { streamText } from 'ai';
+import { ForbiddenException } from '@nestjs/common';
 import {
   AiChatService,
   compactToolOutput,
@@ -1068,181 +1059,3 @@ describe('isInterruptResume', () => {
     expect(isInterruptResume(withPrev(null), true)).toBe(false);
   });
 });
-
-/**
- * #184 phase 1.5 — the run-wrapped pipe options (unit). Drives stream() to the
- * pipe call with streamText mocked, capturing the options object, and asserts:
- *  - flag OFF while a runId IS present -> the LEGACY option shape (no
- *    consumeSseStream, no generateMessageId), and the registry is never touched.
- *    This is the exact dormancy guarantee this PR rests on.
- *  - flag ON + runId -> consumeSseStream tees into the registry and
- *    generateMessageId returns the seeded assistant DB row id.
- *  - flag ON but no runHooks (runId undefined) -> legacy (the runId gate).
- *  - flag ON + runId -> the outer catch releases the entry via abortEntry.
- */
-describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', () => {
-  const streamTextMock = streamText as unknown as jest.Mock;
-  let pipeMock: jest.Mock;
-
-  beforeEach(() => {
-    streamTextMock.mockReset();
-    pipeMock = jest.fn();
-    streamTextMock.mockReturnValue({
-      consumeStream: jest.fn(),
-      pipeUIMessageStreamToResponse: pipeMock,
-    });
-    // Silence the service's diagnostic logging for a clean test run.
-    jest.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined as never);
-    jest
-      .spyOn(Logger.prototype, 'error')
-      .mockImplementation(() => undefined as never);
-    jest
-      .spyOn(Logger.prototype, 'warn')
-      .mockImplementation(() => undefined as never);
-  });
-
-  afterEach(() => jest.restoreAllMocks());
-
-  // A raw-response stub sufficient for the post-streamText wiring.
-  function makeRes() {
-    return {
-      raw: {
-        writeHead: jest.fn(),
-        write: jest.fn(),
-        once: jest.fn(),
-        on: jest.fn(),
-        flushHeaders: jest.fn(),
-        writableEnded: false,
-        destroyed: false,
-      },
-    };
-  }
-
-  // Wire only the deps reached on the way to the pipe call, plus a spy registry.
-  function makeService(opts: { resumable: boolean }) {
-    const aiChatRepo = {
-      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
-      insert: jest.fn(),
-    };
-    const aiChatMessageRepo = {
-      // Both the user insert and the assistant seed return the same row id.
-      insert: jest.fn(async () => ({ id: 'msg-1' })),
-      findAllByChat: jest.fn(async () => []),
-      update: jest.fn(async () => ({ id: 'msg-1' })),
-    };
-    const aiSettings = { resolve: jest.fn(async () => ({})) };
-    const tools = { forUser: jest.fn(async () => ({})) };
-    const mcpClients = {
-      toolsFor: jest.fn(async () => ({
-        tools: {},
-        clients: [],
-        outcomes: [],
-        instructions: [],
-      })),
-    };
-    const streamRegistry = {
-      open: jest.fn(),
-      bind: jest.fn(),
-      abortEntry: jest.fn(),
-    };
-    const svc = new AiChatService(
-      {} as never, // ai (model is injected)
-      aiChatRepo as never,
-      aiChatMessageRepo as never,
-      {} as never, // aiChatPageSnapshotRepo
-      aiSettings as never,
-      tools as never,
-      mcpClients as never,
-      {} as never, // aiAgentRoleRepo
-      {} as never, // pageRepo (openPage undefined -> never touched)
-      {} as never, // pageAccess
-      {
-        isAiChatDeferredToolsEnabled: () => false,
-        isAiChatResumableStreamEnabled: () => opts.resumable,
-      } as never,
-      streamRegistry as never,
-    );
-    return { svc, streamRegistry };
-  }
-
-  const body = {
-    chatId: 'chat-1',
-    messages: [
-      { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
-    ],
-  };
-
-  const makeRunHooks = () => ({
-    begin: jest.fn(async () => ({
-      runId: 'run-1',
-      signal: new AbortController().signal,
-    })),
-    onAssistantSeeded: jest.fn(),
-    onStep: jest.fn(),
-    onSettled: jest.fn(),
-  });
-
-  async function drive(svc: AiChatService, hooks: unknown): Promise<void> {
-    await svc.stream({
-      user: { id: 'u1' } as never,
-      workspace: { id: 'ws-1' } as never,
-      sessionId: 's1',
-      body: body as never,
-      res: makeRes() as never,
-      signal: new AbortController().signal,
-      model: {} as never,
-      role: null,
-      runHooks: hooks as never,
-    });
-  }
-
-  it('flag OFF + runId present: LEGACY option shape (no consumeSseStream / generateMessageId); registry untouched', async () => {
-    const { svc, streamRegistry } = makeService({ resumable: false });
-    await drive(svc, makeRunHooks());
-    expect(pipeMock).toHaveBeenCalledTimes(1);
-    const options = pipeMock.mock.calls[0][1];
-    // The dormancy guarantee: a live run with the flag off tees NOTHING and does
-    // not stamp a message id — byte-for-byte the pre-1.5 wire.
-    expect(options.consumeSseStream).toBeUndefined();
-    expect(options.generateMessageId).toBeUndefined();
-    expect(streamRegistry.bind).not.toHaveBeenCalled();
-    expect(streamRegistry.abortEntry).not.toHaveBeenCalled();
-  });
-
-  it('flag ON + runId: consumeSseStream tees into the registry; generateMessageId returns the seeded row id', async () => {
-    const { svc, streamRegistry } = makeService({ resumable: true });
-    await drive(svc, makeRunHooks());
-    const options = pipeMock.mock.calls[0][1];
-    expect(typeof options.consumeSseStream).toBe('function');
-    expect(typeof options.generateMessageId).toBe('function');
-    // generateMessageId stamps the seeded assistant DB row id.
-    expect(options.generateMessageId()).toBe('msg-1');
-    // consumeSseStream binds the tee: (chatId, runId, assistantId, stream).
-    const fakeStream = {} as ReadableStream<string>;
-    options.consumeSseStream({ stream: fakeStream });
-    expect(streamRegistry.bind).toHaveBeenCalledWith(
-      'chat-1',
-      'run-1',
-      'msg-1',
-      fakeStream,
-    );
-  });
-
-  it('flag ON but NO runHooks (runId undefined): pipe options stay legacy (the runId gate)', async () => {
-    const { svc, streamRegistry } = makeService({ resumable: true });
-    await drive(svc, undefined);
-    const options = pipeMock.mock.calls[0][1];
-    expect(options.consumeSseStream).toBeUndefined();
-    expect(options.generateMessageId).toBeUndefined();
-    expect(streamRegistry.bind).not.toHaveBeenCalled();
-  });
-
-  it('flag ON + runId: the outer catch calls abortEntry when the stream throws', async () => {
-    const { svc, streamRegistry } = makeService({ resumable: true });
-    streamTextMock.mockImplementation(() => {
-      throw new Error('boom');
-    });
-    await expect(drive(svc, makeRunHooks())).rejects.toThrow('boom');
-    expect(streamRegistry.abortEntry).toHaveBeenCalledWith('chat-1', 'run-1');
-  });
-});

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

@@ -32,7 +32,6 @@ import {
 import { AiChatToolsService } from './tools/ai-chat-tools.service';
 import { McpClientsService } from './external-mcp/mcp-clients.service';
 import { EnvironmentService } from '../../integrations/environment/environment.service';
-import { AiChatStreamRegistryService } from './ai-chat-stream-registry.service';
 import { buildSystemPrompt } from './ai-chat.prompt';
 import {
   CORE_TOOL_KEYS,
@@ -277,10 +276,6 @@ export class AiChatService implements OnModuleInit {
     // Reads the AI_CHAT_DEFERRED_TOOLS toggle (#332). Injected last so existing
     // positional constructor callers (tests) only append one stub.
     private readonly environment: EnvironmentService,
-    // #184 phase 1.5 run-stream registry. OPTIONAL so existing positional
-    // constructions (int-specs) compile unchanged; Nest always injects the real
-    // provider in production. Only ever touched on the run-wrapped + flag-on path.
-    private readonly streamRegistry?: AiChatStreamRegistryService,
   ) {}
 
   /**
@@ -1179,35 +1174,6 @@ export class AiChatService implements OnModuleInit {
         // as the cumulative authoritative usage so the client never jumps DOWN.
         let cumulativeStepUsage: ChatStreamUsage | undefined;
         result.pipeUIMessageStreamToResponse(res.raw, {
-          // #184 phase 1.5: run-wrapped mode only — the legacy path (flag off) stays
-          // byte-for-byte identical, including the absence of start.messageId. Both
-          // fields are gated on `runId` (present only for a durable run) AND the
-          // AI_CHAT_RESUMABLE_STREAM flag; the seed `assistantId` is unconditional,
-          // so gating on `assistantId` alone would change the legacy wire.
-          ...(runId && this.environment?.isAiChatResumableStreamEnabled?.()
-            ? {
-                // Tee the SSE frames into the run-stream registry so late tabs can
-                // attach (replay + live tail).
-                consumeSseStream: ({
-                  stream,
-                }: {
-                  stream: ReadableStream<string>;
-                }) =>
-                  this.streamRegistry?.bind(
-                    chatId,
-                    runId!,
-                    assistantId,
-                    stream,
-                  ),
-                // Stamp the persisted assistant row's DB id onto the streamed
-                // message so every tab renders the SAME id as the DB row (id-based
-                // reconciliation). Seeding is best-effort: when it failed, let the
-                // client generate the id.
-                ...(assistantId
-                  ? { generateMessageId: () => assistantId }
-                  : {}),
-              }
-            : {}),
           headers: { 'X-Accel-Buffering': 'no' },
           // Surface the authoritative chatId on the streamed assistant UI message so
           // the client adopts the REAL id of the row we created, instead of guessing
@@ -1273,12 +1239,6 @@ export class AiChatService implements OnModuleInit {
       // finalizeRun (onSettled) is idempotent — a settle here and a settle from a
       // streamText callback collapse to a single terminal write.
       if (runId) {
-        // #184 phase 1.5: a failure here means the tee `done` will never arrive,
-        // so release the registry entry's subscribers explicitly — otherwise an
-        // attached tab hangs forever. Same flag gate as the tee wiring above.
-        if (this.environment?.isAiChatResumableStreamEnabled?.()) {
-          this.streamRegistry?.abortEntry(chatId, runId);
-        }
         await runHooks?.onSettled?.(
           runId,
           'error',

apps/server/src/integrations/environment/environment.service.ts

@@ -292,23 +292,6 @@ export class EnvironmentService {
     return enabled === 'true';
   }
 
-  /**
-   * Resumable SSE transport for durable agent runs (#184 phase 1.5). When
-   * enabled, a run tees its SSE frames into the in-memory run-stream registry so
-   * a late/reloaded tab can attach (replay + live tail) via
-   * `GET /ai-chat/runs/:chatId/stream`. Defaults to DISABLED: PR 1 ships the
-   * server code dormant — with the flag off, `open`/`bind`/`generateMessageId`
-   * are never called and attach always answers 204, so the legacy and #184
-   * phase-1 wire paths stay byte-for-byte identical. Set
-   * AI_CHAT_RESUMABLE_STREAM=true to activate it (paired with the PR 2 client).
-   */
-  isAiChatResumableStreamEnabled(): boolean {
-    const enabled = this.configService
-      .get<string>('AI_CHAT_RESUMABLE_STREAM', 'false')
-      .toLowerCase();
-    return enabled === 'true';
-  }
-
   getPostHogHost(): string {
     return this.configService.get<string>('POSTHOG_HOST');
   }

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

@@ -1,564 +0,0 @@
-import * as http from 'node:http';
-import { Kysely } from 'kysely';
-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 { AiChatRunRepo } from '@docmost/db/repos/ai-chat/ai-chat-run.repo';
-import { AiChatService } from 'src/core/ai-chat/ai-chat.service';
-import { AiChatRunService } from 'src/core/ai-chat/ai-chat-run.service';
-import {
-  AiChatStreamRegistryService,
-  RunStreamCallbacks,
-} from 'src/core/ai-chat/ai-chat-stream-registry.service';
-import {
-  getTestDb,
-  destroyTestDb,
-  createWorkspace,
-  createUser,
-  createChat,
-} from './db';
-
-/**
- * #184 phase 1.5 — the resumable transport end to end against REAL Postgres,
- * the REAL `streamText` (seeded via MockLanguageModelV3) and a REAL Node
- * ServerResponse, driving the REAL `AiChatService.stream` run-wrapped path with a
- * REAL `AiChatStreamRegistryService`. The run-hooks mirror the controller: they
- * begin a durable run and `open()` the registry entry at begin, and the service
- * tees the SSE frames into it via `consumeSseStream` while stamping the DB row id
- * via `generateMessageId` (both gated on runId + the resumable flag).
- *
- * Proven here: a finished run's replay is the full frame sequence incl `[DONE]`
- * with `start.messageId` == the seeded DB row id; the anchor check (invariant 6);
- * an attach opened BEFORE the first frame follows the live stream from frame 0; an
- * explicit stop surfaces `{"type":"abort"}` + `[DONE]` + end to the subscriber;
- * and the legacy (non-run) path tees nothing.
- */
-
-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 (as in the stream int-spec).
-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();
-    });
-  });
-}
-
-// A full, 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 stream the test feeds chunk by chunk (to attach mid-flight / drive a stop).
-function makeControlledStream() {
-  let controller!: ReadableStreamDefaultController<any>;
-  const stream = new ReadableStream<any>({
-    start(c) {
-      controller = c;
-    },
-  });
-  return {
-    stream,
-    emit: (chunk: any) => controller.enqueue(chunk),
-    close: () => controller.close(),
-  };
-}
-
-// Collect replay + live frames from an attachment.
-function liveSink(): {
-  cb: RunStreamCallbacks;
-  frames: string[];
-  ended: () => boolean;
-} {
-  const frames: string[] = [];
-  let ended = false;
-  return {
-    frames,
-    ended: () => ended,
-    cb: {
-      onFrame: (f) => frames.push(f),
-      onEnd: () => {
-        ended = true;
-      },
-    },
-  };
-}
-
-// The SSE `start` frame carries the message id; pull it out of a `data: {...}`.
-function parseStartMessageId(frames: string[]): string | undefined {
-  for (const f of frames) {
-    const m = /^data: (\{.*\})\s*$/m.exec(f.trim());
-    if (!m) continue;
-    try {
-      const json = JSON.parse(m[1]);
-      if (json.type === 'start') return json.messageId;
-    } catch {
-      /* not this frame */
-    }
-  }
-  return undefined;
-}
-
-describe('AiChatService run-stream attach [integration]', () => {
-  let db: Kysely<any>;
-  let aiChatRepo: AiChatRepo;
-  let msgRepo: AiChatMessageRepo;
-  let runRepo: AiChatRunRepo;
-  let workspaceId: string;
-  let userId: string;
-
-  const mcpClients = {
-    toolsFor: async () => ({
-      tools: {},
-      clients: [],
-      outcomes: [],
-      instructions: [],
-    }),
-  };
-
-  // Build the service with the run-stream registry wired and the resumable flag
-  // ON (the property under test). Deferred tools OFF (irrelevant here).
-  function buildService(registry: AiChatStreamRegistryService): AiChatService {
-    return new AiChatService(
-      { getChatModel: async () => null } as any,
-      aiChatRepo,
-      msgRepo,
-      {} as any,
-      { resolve: async () => null } as any,
-      { forUser: async () => ({}) } as any,
-      mcpClients as any,
-      {} as any,
-      {} as any,
-      {} as any,
-      {
-        isAiChatDeferredToolsEnabled: () => false,
-        isAiChatResumableStreamEnabled: () => true,
-      } as any,
-      registry,
-    );
-  }
-
-  // Run-hooks mirroring the controller: begin the durable run AND open() the
-  // registry entry at begin. Captures the runId so a test can stop it.
-  function makeRunHooks(
-    runService: AiChatRunService,
-    registry: AiChatStreamRegistryService,
-    box: { runId?: string },
-  ) {
-    return {
-      begin: async (chatId: string) => {
-        const handle = await runService.beginRun({
-          chatId,
-          workspaceId,
-          userId,
-          trigger: 'user',
-        });
-        box.runId = handle.runId;
-        registry.open(chatId, handle.runId);
-        return handle;
-      },
-      onAssistantSeeded: (runId: string, messageId: string) =>
-        runService.linkAssistantMessage(runId, workspaceId, messageId),
-      onStep: (runId: string, n: number) =>
-        void runService.recordStep(runId, workspaceId, n),
-      onSettled: (runId: string, status: any, error?: string) =>
-        runService.finalizeRun(runId, workspaceId, status, error),
-    };
-  }
-
-  function userUiMessage(text: string) {
-    return {
-      id: `u-${Math.random()}`,
-      role: 'user',
-      parts: [{ type: 'text', text }],
-    };
-  }
-
-  async function startRun(opts: {
-    registry: AiChatStreamRegistryService;
-    runService?: AiChatRunService;
-    model: MockLanguageModelV3;
-    chatId: string;
-    body: any;
-    box?: { runId?: string };
-  }): Promise<{ res: http.ServerResponse; cleanup: () => Promise<void> }> {
-    const service = buildService(opts.registry);
-    const { res, cleanup } = await makeRealResponse();
-    const runHooks = opts.runService
-      ? makeRunHooks(opts.runService, opts.registry, opts.box ?? {})
-      : undefined;
-    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,
-      runHooks,
-    } as any);
-    return { res, cleanup };
-  }
-
-  async function assistantRowId(chatId: string): Promise<string> {
-    const rows = await msgRepo.findAllByChat(chatId, workspaceId);
-    const row = rows.find((r: any) => r.role === 'assistant');
-    return row!.id as string;
-  }
-
-  beforeAll(async () => {
-    db = getTestDb();
-    aiChatRepo = new AiChatRepo(db as any);
-    msgRepo = new AiChatMessageRepo(db as any);
-    runRepo = new AiChatRunRepo(db as any);
-    workspaceId = (await createWorkspace(db)).id;
-    userId = (await createUser(db, workspaceId)).id;
-  });
-
-  afterAll(async () => {
-    await destroyTestDb();
-  });
-
-  it('run-wrapped: replay is the full frame sequence incl [DONE], start.messageId == the seeded DB row id', async () => {
-    const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
-    const registry = new AiChatStreamRegistryService();
-    const runService = new AiChatRunService(runRepo, {
-      isCloud: () => false,
-    } as never);
-    const model = new MockLanguageModelV3({
-      doStream: async () => ({ stream: successStream() }),
-    } as any);
-
-    const box: { runId?: string } = {};
-    const { cleanup } = await startRun({
-      registry,
-      runService,
-      model,
-      chatId,
-      body: { chatId, messages: [userUiMessage('Hi')] },
-      box,
-    });
-    try {
-      // Wait for the assistant row to settle (terminal callbacks run async).
-      await waitFor(async () => {
-        const rows = await msgRepo.findAllByChat(chatId, workspaceId);
-        return rows.some(
-          (r: any) =>
-            r.role === 'assistant' &&
-            ['completed', 'error', 'aborted'].includes(r.status),
-        );
-      });
-      const rowId = await assistantRowId(chatId);
-
-      // Finished-run replay with expect=live + the correct anchor.
-      const sink = liveSink();
-      const att = await registry.attach(chatId, true, rowId, sink.cb);
-      expect(att).not.toBeNull();
-      expect(att!.finished).toBe(true);
-      // The tee captured frames (consumeSseStream was wired).
-      expect(att!.replay.length).toBeGreaterThan(0);
-      // generateMessageId stamped the DB row id onto the streamed start frame.
-      expect(parseStartMessageId(att!.replay)).toBe(rowId);
-      // The full sequence includes the streamed text and the terminal marker.
-      const joined = att!.replay.join('');
-      expect(joined).toContain('Hello');
-      expect(att!.replay.some((f) => f.includes('[DONE]'))).toBe(true);
-    } finally {
-      registry.onModuleDestroy();
-      await cleanup();
-    }
-  });
-
-  it('anchor mismatch with expect=live returns null (invariant 6)', async () => {
-    const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
-    const registry = new AiChatStreamRegistryService();
-    const runService = new AiChatRunService(runRepo, {
-      isCloud: () => false,
-    } as never);
-    const model = new MockLanguageModelV3({
-      doStream: async () => ({ stream: successStream() }),
-    } as any);
-
-    const { cleanup } = await startRun({
-      registry,
-      runService,
-      model,
-      chatId,
-      body: { chatId, messages: [userUiMessage('Hi')] },
-    });
-    try {
-      await waitFor(async () => {
-        const rows = await msgRepo.findAllByChat(chatId, workspaceId);
-        return rows.some(
-          (r: any) => r.role === 'assistant' && r.status === 'completed',
-        );
-      });
-      const sink = liveSink();
-      // A foreign anchor must NOT replay this run's transcript.
-      expect(
-        await registry.attach(chatId, true, 'a-different-run-row', sink.cb),
-      ).toBeNull();
-    } finally {
-      registry.onModuleDestroy();
-      await cleanup();
-    }
-  });
-
-  it('an attach opened BEFORE the first frame follows the live stream from frame 0', async () => {
-    const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
-    const registry = new AiChatStreamRegistryService();
-    const runService = new AiChatRunService(runRepo, {
-      isCloud: () => false,
-    } as never);
-    const controlled = makeControlledStream();
-    const model = new MockLanguageModelV3({
-      doStream: async () => ({ stream: controlled.stream }),
-    } as any);
-
-    const { cleanup } = await startRun({
-      registry,
-      runService,
-      model,
-      chatId,
-      body: { chatId, messages: [userUiMessage('Slow please')] },
-    });
-    try {
-      // Attach while the entry exists (opened at begin) but before any frame.
-      const sink = liveSink();
-      const att = (await registry.attach(chatId, false, undefined, sink.cb))!;
-      expect(att.replay).toEqual([]); // nothing streamed yet -> replay from 0
-      att.start(); // go live (drains nothing, then follows)
-
-      // Now emit the whole turn.
-      controlled.emit({ type: 'stream-start', warnings: [] });
-      controlled.emit({ type: 'text-start', id: 't1' });
-      controlled.emit({ type: 'text-delta', id: 't1', delta: 'Zero' });
-      controlled.emit({ type: 'text-end', id: 't1' });
-      controlled.emit({
-        type: 'finish',
-        finishReason: 'stop',
-        usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
-      });
-      controlled.close();
-
-      await waitFor(() => sink.frames.some((f) => f.includes('[DONE]')));
-      // The subscriber saw the stream from the very first frame (`start`) through
-      // the terminal marker, with the streamed text present.
-      expect(sink.frames.some((f) => f.includes('"type":"start"'))).toBe(true);
-      expect(sink.frames.join('')).toContain('Zero');
-      expect(sink.frames[sink.frames.length - 1]).toContain('[DONE]');
-      expect(sink.ended()).toBe(true);
-    } finally {
-      registry.onModuleDestroy();
-      await cleanup();
-    }
-  });
-
-  it('requestStop surfaces {"type":"abort"} + [DONE] + end to the attached subscriber', async () => {
-    const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
-    const registry = new AiChatStreamRegistryService();
-    const runService = new AiChatRunService(runRepo, {
-      isCloud: () => false,
-    } as never);
-    // An abort-AWARE model: it streams some partial output, then errors the model
-    // stream with an AbortError when the run signal aborts — exactly as a real
-    // provider network stream is torn down on abort (a plain in-memory stream
-    // would just stall, so streamText would never observe the stop).
-    const model = new MockLanguageModelV3({
-      doStream: async ({ abortSignal }: any) => {
-        const stream = new ReadableStream<any>({
-          start(controller) {
-            controller.enqueue({ type: 'stream-start', warnings: [] });
-            controller.enqueue({ type: 'text-start', id: 't1' });
-            controller.enqueue({ type: 'text-delta', id: 't1', delta: 'partial' });
-            abortSignal?.addEventListener('abort', () => {
-              try {
-                controller.error(
-                  new DOMException('Aborted', 'AbortError'),
-                );
-              } catch {
-                /* already errored/closed */
-              }
-            });
-          },
-        });
-        return { stream };
-      },
-    } as any);
-
-    const box: { runId?: string } = {};
-    const { cleanup } = await startRun({
-      registry,
-      runService,
-      model,
-      chatId,
-      body: { chatId, messages: [userUiMessage('Start then stop')] },
-      box,
-    });
-    try {
-      const sink = liveSink();
-      const att = (await registry.attach(chatId, false, undefined, sink.cb))!;
-      att.start();
-
-      // Give streamText a beat to begin consuming the partial output.
-      await sleep(250);
-      // User presses Stop -> the run signal aborts -> the SDK emits an abort chunk.
-      await runService.requestStop(box.runId!, workspaceId);
-
-      await waitFor(() => sink.ended());
-      expect(sink.frames.some((f) => f.includes('"type":"abort"'))).toBe(true);
-      expect(sink.frames.some((f) => f.includes('[DONE]'))).toBe(true);
-      expect(sink.ended()).toBe(true);
-    } finally {
-      registry.onModuleDestroy();
-      await cleanup();
-    }
-  });
-
-  it('the outer catch calls abortEntry so an open entry is released (finished)', async () => {
-    const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
-    const registry = new AiChatStreamRegistryService();
-    const runService = new AiChatRunService(runRepo, {
-      isCloud: () => false,
-    } as never);
-    const model = new MockLanguageModelV3({
-      doStream: async () => ({ stream: successStream() }),
-    } as any);
-
-    // A msgRepo whose user-row insert throws: the turn fails AFTER begin (the
-    // entry is already open) but BEFORE the pipe, exercising the outer catch.
-    const throwingMsgRepo = {
-      insert: async () => {
-        throw new Error('db boom');
-      },
-      findAllByChat: (...a: any[]) => (msgRepo as any).findAllByChat(...a),
-      update: (...a: any[]) => (msgRepo as any).update(...a),
-      findById: (...a: any[]) => (msgRepo as any).findById(...a),
-    };
-    const service = new AiChatService(
-      { getChatModel: async () => null } as any,
-      aiChatRepo,
-      throwingMsgRepo as any,
-      {} as any,
-      { resolve: async () => null } as any,
-      { forUser: async () => ({}) } as any,
-      mcpClients as any,
-      {} as any,
-      {} as any,
-      {} as any,
-      {
-        isAiChatDeferredToolsEnabled: () => false,
-        isAiChatResumableStreamEnabled: () => true,
-      } as any,
-      registry,
-    );
-    const { res, cleanup } = await makeRealResponse();
-    const box: { runId?: string } = {};
-    try {
-      await expect(
-        service.stream({
-          user: { id: userId, workspaceId } as any,
-          workspace: { id: workspaceId, name: 'WS' } as any,
-          sessionId: 'sess-1',
-          body: { chatId, messages: [userUiMessage('will throw')] },
-          res: { raw: res } as any,
-          signal: new AbortController().signal,
-          model: model as any,
-          role: null,
-          runHooks: makeRunHooks(runService, registry, box),
-        } as any),
-      ).rejects.toThrow();
-      // The entry opened at begin was terminated by abortEntry (from the catch),
-      // so it is finished and a plain attach returns null instead of hanging.
-      const entry = (registry as any).entries.get(chatId);
-      expect(entry).toBeDefined();
-      expect(entry.finished).toBe(true);
-      const sink = liveSink();
-      expect(await registry.attach(chatId, false, undefined, sink.cb)).toBeNull();
-    } finally {
-      registry.onModuleDestroy();
-      await cleanup();
-    }
-  });
-
-  it('legacy (no run-hooks): the registry is never populated', async () => {
-    const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
-    const registry = new AiChatStreamRegistryService();
-    const model = new MockLanguageModelV3({
-      doStream: async () => ({ stream: successStream() }),
-    } as any);
-
-    // No runHooks -> runId undefined -> the run-wrapped tee is never wired.
-    const { cleanup } = await startRun({
-      registry,
-      model,
-      chatId,
-      body: { chatId, messages: [userUiMessage('Legacy hi')] },
-    });
-    try {
-      await waitFor(async () => {
-        const rows = await msgRepo.findAllByChat(chatId, workspaceId);
-        return rows.some(
-          (r: any) => r.role === 'assistant' && r.status === 'completed',
-        );
-      });
-      const sink = liveSink();
-      // No entry was ever opened; attach always yields null.
-      expect(await registry.attach(chatId, false, undefined, sink.cb)).toBeNull();
-      expect(await registry.attach(chatId, true, 'anything', sink.cb)).toBeNull();
-    } finally {
-      registry.onModuleDestroy();
-      await cleanup();
-    }
-  });
-});

pnpm-lock.yaml

@@ -272,6 +272,9 @@ importers:
       '@atlaskit/pragmatic-drag-and-drop-live-region':
         specifier: 1.3.4
         version: 1.3.4
+      '@braintree/sanitize-url':
+        specifier: 7.1.2
+        version: 7.1.2
       '@casl/react':
         specifier: 5.0.1
         version: 5.0.1(@casl/ability@6.8.0)(react@18.3.1)