fix(page,ai-chat): address PR #200 review — canonical lock UUIDs, changelog, tests

- page.service: lock concurrent re-parents by canonical row UUIDs (`movedPage.id`, not the raw client `dto.pageId` which may be a slugId) so two opposing moves passing slugIds can't sort into different FOR UPDATE orders and deadlock (#159). - CHANGELOG: add [Unreleased] entries — Fixed #159 (serialized concurrent moves + in-tx cycle re-check), Added #190 (model-friendly tool-input errors). - page.service.spec: hoist the duplicated `makeChain` trx-stub Proxy into one module-level helper (was 3 copies); add a move-to-root test covering the unlocked else-branch (no transaction opened, updatePage called without a trx). - model-friendly-input.spec: cover the duplicate-path dedup branch in formatIssues — a single param with two zod issues is named only once. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
fix(page): serialize concurrent moves so opposing re-parents can't form a cycle (#159 )
2026-06-26 16:59:23 +03:00 · 2026-06-25 22:42:15 +03:00 · 2026-06-25 22:30:24 +03:00
36 changed files with 531 additions and 2289 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,16 +12,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ### Added

- **Custom pretty-links for shared pages (`/l/:alias`).** A page editor can give
-  any publicly shared page a short, memorable, workspace-scoped vanity address
-  backed by a new `share_aliases` table. Hitting `/l/<alias>` issues a `302`
-  (never `301`, since the target is retargetable) to the canonical
-  `/share/<key>/p/<slug>` page; an unknown, dangling, or no-longer-readable alias
-  serves the plain SPA index so that the existence of a name never leaks. An
-  alias can be moved to another page (with a confirm-reassign guard) and the
-  foreign key is `ON DELETE SET NULL`, so deleting the target leaves a dangling
-  alias any workspace member can reclaim. (#205)
-
 - **Persistent AI-chat history as the source of truth + server-side export.**
  An assistant turn is now persisted to the database step by step: the row is
  inserted upfront as `streaming` and updated as each agent step finishes, then
@@ -62,6 +52,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Footnote multi-backlinks.** A footnote referenced more than once now shows a
  back-link per reference (↩ a b c …), each scrolling to its own occurrence, like
  Pandoc/Wikipedia; a single-reference footnote keeps the plain ↩. (#168)
+- **Model-friendly AI-chat tool-input errors.** When the model calls an in-app
+  AI tool with bad arguments, the validation failure is now a concise,
+  human-readable message that NAMES each offending parameter (by its dotted
+  path) and appends a fixed retry hint ("include every REQUIRED parameter…, do
+  not drop ids like `pageId`"), instead of the raw zod text. This nudges the
+  model to re-issue the call correctly — particularly in parallel tool-call
+  batches where it tends to drop a repeated id. The required/optional contract
+  and unknown-key stripping are unchanged. (#190)

 ### Changed

@@ -102,6 +100,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  no longer froze on the previous step's authoritative usage; the current step's
  estimate is combined per-component with `max`, so the count rises smoothly and
  never jumps backwards. (#163)
+- **Concurrent page moves can no longer lose a subtree to a cycle.** Two
+  opposing re-parents racing each other (A: X under Y, B: Y under X) could each
+  pass a cycle check built from a stale snapshot and commit a cycle, orphaning a
+  subtree. A genuine re-parent under a concrete parent now serializes: it locks
+  the moved page and the destination parent `FOR UPDATE` in a canonical
+  (UUID-sorted) order — so opposing moves can't deadlock — and re-runs the cycle
+  check INSIDE the transaction against the now-committed state. Same-parent
+  reorders and moves to root keep the lock-free path. (#159)

 ## [0.93.0] - 2026-06-21

--- a/apps/client/public/locales/en-US/translation.json
+++ b/apps/client/public/locales/en-US/translation.json
@@ -1315,15 +1315,5 @@
  "Protocol": "Protocol",
  "How chat requests are sent and how reasoning is surfaced": "How chat requests are sent and how reasoning is surfaced",
  "OpenAI-compatible (surfaces reasoning)": "OpenAI-compatible (surfaces reasoning)",
-  "OpenAI (official)": "OpenAI (official)",
-  "Custom address": "Custom address",
-  "A short, memorable link you can point at any shared page.": "A short, memorable link you can point at any shared page.",
-  "Use 2-60 lowercase letters, digits and hyphens": "Use 2-60 lowercase letters, digits and hyphens",
-  "This address is already in use": "This address is already in use",
-  "Move custom address?": "Move custom address?",
-  "Move here": "Move here",
-  "The address \"{{alias}}\" currently points to \"{{title}}\". Move it to this page?": "The address \"{{alias}}\" currently points to \"{{title}}\". Move it to this page?",
-  "The address \"{{alias}}\" is already in use. Move it to this page?": "The address \"{{alias}}\" is already in use. Move it to this page?",
-  "Failed to set custom address": "Failed to set custom address",
-  "Failed to remove custom address": "Failed to remove custom address"
+  "OpenAI (official)": "OpenAI (official)"
 }
--- a/apps/client/public/locales/ru-RU/translation.json
+++ b/apps/client/public/locales/ru-RU/translation.json
@@ -1169,15 +1169,5 @@
  "Protocol": "Протокол",
  "How chat requests are sent and how reasoning is surfaced": "Как отправляются запросы чата и как показывается reasoning",
  "OpenAI-compatible (surfaces reasoning)": "OpenAI-совместимый (показывает reasoning)",
-  "OpenAI (official)": "OpenAI (официальный)",
-  "Custom address": "Пользовательский адрес",
-  "A short, memorable link you can point at any shared page.": "Короткая запоминающаяся ссылка, которую можно направить на любую опубликованную страницу.",
-  "Use 2-60 lowercase letters, digits and hyphens": "Используйте 2–60 строчных букв, цифр и дефисов",
-  "This address is already in use": "Этот адрес уже занят",
-  "Move custom address?": "Переместить пользовательский адрес?",
-  "Move here": "Переместить сюда",
-  "The address \"{{alias}}\" currently points to \"{{title}}\". Move it to this page?": "Адрес «{{alias}}» сейчас указывает на «{{title}}». Переместить его на эту страницу?",
-  "The address \"{{alias}}\" is already in use. Move it to this page?": "Адрес «{{alias}}» уже используется. Переместить его на эту страницу?",
-  "Failed to set custom address": "Не удалось задать пользовательский адрес",
-  "Failed to remove custom address": "Не удалось удалить пользовательский адрес"
+  "OpenAI (official)": "OpenAI (официальный)"
 }
--- a/apps/client/src/features/share/components/share-alias-section.tsx
+++ b/apps/client/src/features/share/components/share-alias-section.tsx
@@ -1,237 +0,0 @@
-import {
-  ActionIcon,
-  Button,
-  Group,
-  Modal,
-  Text,
-  TextInput,
-} from "@mantine/core";
-import { IconExternalLink } from "@tabler/icons-react";
-import { useEffect, useMemo, useRef, useState } from "react";
-import { useTranslation } from "react-i18next";
-import CopyTextButton from "@/components/common/copy.tsx";
-import { getAppUrl } from "@/lib/config.ts";
-import {
-  useRemoveShareAliasMutation,
-  useSetShareAliasMutation,
-  useShareAliasForPageQuery,
-} from "@/features/share/queries/share-query.ts";
-import { checkShareAliasAvailability } from "@/features/share/services/share-service.ts";
-import {
-  isValidShareAlias,
-  normalizeShareAlias,
-} from "@/features/share/share-alias.util.ts";
-
-interface ShareAliasSectionProps {
-  pageId: string;
-  readOnly: boolean;
-}
-
-// The prefix label shown next to the slug input, e.g. "docs.example.com/l/".
-function aliasPrefixLabel(): string {
-  const url = getAppUrl();
-  const host = url.replace(/^https?:\/\//, "").replace(/\/+$/, "");
-  return `${host}/l/`;
-}
-
-export default function ShareAliasSection({
-  pageId,
-  readOnly,
-}: ShareAliasSectionProps) {
-  const { t } = useTranslation();
-  const { data: currentAlias } = useShareAliasForPageQuery(pageId);
-  const setAliasMutation = useSetShareAliasMutation();
-  const removeAliasMutation = useRemoveShareAliasMutation();
-
-  const [value, setValue] = useState("");
-  const [availability, setAvailability] = useState<{
-    valid: boolean;
-    available: boolean;
-    currentPageId: string | null;
-  } | null>(null);
-  const [reassign, setReassign] = useState<{
-    alias: string;
-    currentPageTitle: string | null;
-  } | null>(null);
-
-  // Seed the input from the page's current alias (if any).
-  useEffect(() => {
-    setValue(currentAlias?.alias ?? "");
-  }, [currentAlias?.alias, pageId]);
-
-  const normalized = useMemo(() => normalizeShareAlias(value), [value]);
-  const isValid = isValidShareAlias(normalized);
-  const unchanged = currentAlias?.alias === normalized;
-
-  // Debounced availability probe (skips when invalid or unchanged).
-  const debounceRef = useRef<ReturnType<typeof setTimeout>>();
-  useEffect(() => {
-    setAvailability(null);
-    if (!isValid || unchanged) return;
-    debounceRef.current && clearTimeout(debounceRef.current);
-    debounceRef.current = setTimeout(async () => {
-      try {
-        const res = await checkShareAliasAvailability(normalized);
-        setAvailability({
-          valid: res.valid,
-          available: res.available,
-          currentPageId: res.currentPageId,
-        });
-      } catch {
-        setAvailability(null);
-      }
-    }, 400);
-    return () => {
-      debounceRef.current && clearTimeout(debounceRef.current);
-    };
-  }, [normalized, isValid, unchanged]);
-
-  const prettyLink = currentAlias?.alias
-    ? `${getAppUrl()}/l/${currentAlias.alias}`
-    : null;
-
-  const handleSave = async (confirmReassign = false) => {
-    try {
-      await setAliasMutation.mutateAsync({
-        pageId,
-        alias: normalized,
-        confirmReassign,
-      });
-      setReassign(null);
-    } catch (error: any) {
-      // The address already points at another page: prompt to move it here.
-      if (error?.status === 409 || error?.response?.status === 409) {
-        const data = error?.response?.data;
-        if (data?.code === "ALIAS_REASSIGN_REQUIRED") {
-          setReassign({
-            alias: normalized,
-            currentPageTitle: data?.currentPageTitle ?? null,
-          });
-        }
-      }
-    }
-  };
-
-  const handleRemove = async () => {
-    if (!currentAlias?.id) return;
-    await removeAliasMutation.mutateAsync(currentAlias.id);
-    setValue("");
-  };
-
-  const showInvalid = normalized.length > 0 && !isValid;
-  const showTaken =
-    isValid && !unchanged && availability && !availability.available;
-
-  return (
-    <>
-      <Text size="sm" fw={500} mt="md">
-        {t("Custom address")}
-      </Text>
-      <Text size="xs" c="dimmed" mb={4}>
-        {t("A short, memorable link you can point at any shared page.")}
-      </Text>
-
-      {prettyLink && (
-        <Group my="xs" gap={4} wrap="nowrap">
-          <TextInput
-            variant="filled"
-            value={prettyLink}
-            readOnly
-            rightSection={<CopyTextButton text={prettyLink} />}
-            style={{ width: "100%" }}
-          />
-          <ActionIcon
-            component="a"
-            variant="default"
-            target="_blank"
-            href={prettyLink}
-            size="sm"
-          >
-            <IconExternalLink size={16} />
-          </ActionIcon>
-        </Group>
-      )}
-
-      <TextInput
-        value={value}
-        onChange={(e) => setValue(e.currentTarget.value)}
-        // Show the canonical form once the user pauses so what they type maps
-        // visibly to what gets stored.
-        onBlur={() => setValue(normalized)}
-        leftSection={
-          <Text size="xs" c="dimmed" pl={4} style={{ whiteSpace: "nowrap" }}>
-            {aliasPrefixLabel()}
-          </Text>
-        }
-        leftSectionWidth={Math.min(aliasPrefixLabel().length * 7 + 12, 180)}
-        placeholder={t("my-page")}
-        disabled={readOnly}
-        error={
-          showInvalid
-            ? t("Use 2-60 lowercase letters, digits and hyphens")
-            : showTaken
-              ? t("This address is already in use")
-              : undefined
-        }
-      />
-
-      <Group mt="xs" gap="xs">
-        <Button
-          size="compact-sm"
-          onClick={() => handleSave(false)}
-          loading={setAliasMutation.isPending}
-          disabled={readOnly || !isValid || unchanged}
-        >
-          {t("Save")}
-        </Button>
-        {currentAlias?.id && (
-          <Button
-            size="compact-sm"
-            variant="default"
-            color="red"
-            onClick={handleRemove}
-            loading={removeAliasMutation.isPending}
-            disabled={readOnly}
-          >
-            {t("Remove")}
-          </Button>
-        )}
-      </Group>
-
-      <Modal
-        opened={!!reassign}
-        onClose={() => setReassign(null)}
-        title={t("Move custom address?")}
-        centered
-        size="sm"
-      >
-        <Text size="sm">
-          {reassign?.currentPageTitle
-            ? t(
-                'The address "{{alias}}" currently points to "{{title}}". Move it to this page?',
-                {
-                  alias: reassign?.alias,
-                  title: reassign?.currentPageTitle,
-                },
-              )
-            : t(
-                'The address "{{alias}}" is already in use. Move it to this page?',
-                { alias: reassign?.alias },
-              )}
-        </Text>
-        <Group justify="flex-end" mt="md">
-          <Button variant="default" onClick={() => setReassign(null)}>
-            {t("Cancel")}
-          </Button>
-          <Button
-            color="red"
-            onClick={() => handleSave(true)}
-            loading={setAliasMutation.isPending}
-          >
-            {t("Move here")}
-          </Button>
-        </Group>
-      </Modal>
-    </>
-  );
-}
--- a/apps/client/src/features/share/components/share-modal.tsx
+++ b/apps/client/src/features/share/components/share-modal.tsx
@@ -25,7 +25,6 @@ import CopyTextButton from "@/components/common/copy.tsx";
 import { getAppUrl } from "@/lib/config.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import classes from "@/features/share/components/share.module.css";
-import ShareAliasSection from "@/features/share/components/share-alias-section.tsx";
 import { useAtom } from "jotai";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { useSpaceQuery } from "@/features/space/queries/space-query.ts";
@@ -254,9 +253,6 @@ export default function ShareModal({ readOnly }: ShareModalProps) {
                    disabled={readOnly}
                  />
                </Group>
-                {pageId && (
-                  <ShareAliasSection pageId={pageId} readOnly={readOnly} />
-                )}
              </>
            )}
          </>
--- a/apps/client/src/features/share/queries/share-query.ts
+++ b/apps/client/src/features/share/queries/share-query.ts
@@ -10,8 +10,6 @@ import { useTranslation } from "react-i18next";
 import {
  ICreateShare,
  IShare,
-  IShareAlias,
-  ISetShareAlias,
  ISharedItem,
  ISharedPage,
  ISharedPageTree,
@@ -22,14 +20,11 @@ import {
 import {
  createShare,
  deleteShare,
-  getShareAliasForPage,
  getSharedPageTree,
  getShareForPage,
  getShareInfo,
  getSharePageInfo,
  getShares,
-  removeShareAlias,
-  setShareAlias,
  updateShare,
 } from "@/features/share/services/share-service.ts";
 import { IPagination, QueryParams } from "@/lib/types.ts";
@@ -175,72 +170,6 @@ export function useDeleteShareMutation() {
  });
 }

-export function useShareAliasForPageQuery(
-  pageId: string,
-): UseQueryResult<IShareAlias | null, Error> {
-  return useQuery({
-    // The endpoint resolves to null when the page has no alias; normalize the
-    // absence so React Query never sees `undefined`.
-    queryKey: ["share-alias-for-page", pageId],
-    queryFn: async () => (await getShareAliasForPage(pageId)) ?? null,
-    enabled: !!pageId,
-    staleTime: 60 * 1000,
-    retry: false,
-  });
-}
-
-export function useSetShareAliasMutation() {
-  const { t } = useTranslation();
-  const queryClient = useQueryClient();
-
-  return useMutation<IShareAlias, Error, ISetShareAlias>({
-    mutationFn: (data) => setShareAlias(data),
-    onSuccess: () => {
-      queryClient.invalidateQueries({
-        predicate: (item) =>
-          ["share-alias-for-page", "share-list"].includes(
-            item.queryKey[0] as string,
-          ),
-      });
-    },
-    onError: (error) => {
-      // A 409 reassign-required is handled inline by the modal (it shows the
-      // "move address here?" confirmation), so don't surface a generic toast.
-      if (error?.["status"] === 409) return;
-      notifications.show({
-        message:
-          error?.["response"]?.data?.message || t("Failed to set custom address"),
-        color: "red",
-      });
-    },
-  });
-}
-
-export function useRemoveShareAliasMutation() {
-  const { t } = useTranslation();
-  const queryClient = useQueryClient();
-
-  return useMutation<void, Error, string>({
-    mutationFn: (aliasId) => removeShareAlias(aliasId),
-    onSuccess: () => {
-      queryClient.invalidateQueries({
-        predicate: (item) =>
-          ["share-alias-for-page", "share-list"].includes(
-            item.queryKey[0] as string,
-          ),
-      });
-    },
-    onError: (error) => {
-      notifications.show({
-        message:
-          error?.["response"]?.data?.message ||
-          t("Failed to remove custom address"),
-        color: "red",
-      });
-    },
-  });
-}
-
 export function useGetSharedPageTreeQuery(
  shareId: string,
 ): UseQueryResult<ISharedPageTree, Error> {
--- a/apps/client/src/features/share/services/share-service.ts
+++ b/apps/client/src/features/share/services/share-service.ts
@@ -4,9 +4,6 @@ import { IPage } from "@/features/page/types/page.types";
 import {
  ICreateShare,
  IShare,
-  IShareAlias,
-  IShareAliasAvailability,
-  ISetShareAlias,
  ISharedItem,
  ISharedPage,
  ISharedPageTree,
@@ -60,33 +57,3 @@ export async function getSharedPageTree(
  const req = await api.post<ISharedPageTree>("/shares/tree", { shareId });
  return req.data;
 }
-
-export async function getShareAliasForPage(
-  pageId: string,
-): Promise<IShareAlias | null> {
-  const req = await api.post<IShareAlias | null>("/share-aliases/for-page", {
-    pageId,
-  });
-  return req.data;
-}
-
-export async function setShareAlias(
-  data: ISetShareAlias,
-): Promise<IShareAlias> {
-  const req = await api.post<IShareAlias>("/share-aliases/set", data);
-  return req.data;
-}
-
-export async function removeShareAlias(aliasId: string): Promise<void> {
-  await api.post("/share-aliases/remove", { aliasId });
-}
-
-export async function checkShareAliasAvailability(
-  alias: string,
-): Promise<IShareAliasAvailability> {
-  const req = await api.post<IShareAliasAvailability>(
-    "/share-aliases/availability",
-    { alias },
-  );
-  return req.data;
-}
--- a/apps/client/src/features/share/share-alias.util.test.ts
+++ b/apps/client/src/features/share/share-alias.util.test.ts
@@ -1,32 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  isValidShareAlias,
-  normalizeShareAlias,
-} from "@/features/share/share-alias.util.ts";
-
-// Mirrors the server-side util so the modal's live feedback matches what the
-// server will accept/store.
-describe("normalizeShareAlias", () => {
-  it("lowercases, trims and maps separators to single hyphens", () => {
-    expect(normalizeShareAlias("  My  Cool_Page ")).toBe("my-cool-page");
-  });
-
-  it("collapses repeated hyphens and trims edges", () => {
-    expect(normalizeShareAlias("--a---b--")).toBe("a-b");
-  });
-});
-
-describe("isValidShareAlias", () => {
-  it("accepts ascii hyphen-separated slugs of length 2..60", () => {
-    expect(isValidShareAlias("hello-world")).toBe(true);
-    expect(isValidShareAlias("a".repeat(60))).toBe(true);
-  });
-
-  it("rejects too short, edge/double hyphens, uppercase and non-ascii", () => {
-    expect(isValidShareAlias("a")).toBe(false);
-    expect(isValidShareAlias("-a")).toBe(false);
-    expect(isValidShareAlias("a--b")).toBe(false);
-    expect(isValidShareAlias("Hello")).toBe(false);
-    expect(isValidShareAlias("привет")).toBe(false);
-  });
-});
--- a/apps/client/src/features/share/share-alias.util.ts
+++ b/apps/client/src/features/share/share-alias.util.ts
@@ -1,26 +0,0 @@
-/**
- * Client copy of the vanity share-alias helpers. Kept in sync with the server
- * (`apps/server/src/core/share/share-alias.util.ts`) so live input feedback
- * matches what the server will store/accept. ASCII-only, lowercase, hyphen
- * separated, length 2..60.
- */
-
-// Normalize a user-provided vanity alias into canonical ASCII storage form.
-export function normalizeShareAlias(raw: string): string {
-  return (raw ?? "")
-    .trim()
-    .toLowerCase()
-    .replace(/[\s_]+/g, "-")
-    .replace(/-{2,}/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
-const ALIAS_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-export function isValidShareAlias(alias: string): boolean {
-  return (
-    typeof alias === "string" &&
-    alias.length >= 2 &&
-    alias.length <= 60 &&
-    ALIAS_RE.test(alias)
-  );
-}
--- a/apps/client/src/features/share/types/share.types.ts
+++ b/apps/client/src/features/share/types/share.types.ts
@@ -75,30 +75,6 @@ export interface IShareInfoInput {
  pageId: string;
 }

-// Vanity /l/:alias pointer.
-export interface IShareAlias {
-  id: string;
-  workspaceId: string;
-  alias: string;
-  pageId: string | null;
-  creatorId: string | null;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface ISetShareAlias {
-  pageId: string;
-  alias: string;
-  confirmReassign?: boolean;
-}
-
-export interface IShareAliasAvailability {
-  alias: string;
-  valid: boolean;
-  available: boolean;
-  currentPageId: string | null;
-}
-
 export interface ISharedPageTree {
  share: IShare;
  pageTree: Partial<IPage[]>;
--- a/apps/server/src/core/ai-chat/tools/ai-chat-tools.service.spec.ts
+++ b/apps/server/src/core/ai-chat/tools/ai-chat-tools.service.spec.ts
@@ -120,21 +120,26 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {
    const tools = await buildTools();
    const deletePage = tools.deletePage;

-    // The Zod input schema only allows `pageId`; parsing strips/ignores extra
-    // keys, so a permanent/force flag is never part of the validated input.
+    // inputSchema is now an AI SDK `Schema` (not a raw zod object). Its
+    // `validate` runs the same zod safeParse and forwards the STRIPPED data, so
+    // a permanent/force flag is never part of the validated input the SDK then
+    // hands to execute.
    const schema = (deletePage as unknown as { inputSchema: unknown })
      .inputSchema as {
-      parse: (v: unknown) => Record<string, unknown>;
+      validate: (
+        v: unknown,
+      ) => Promise<{ success: boolean; value?: Record<string, unknown> }>;
    };
-    const parsed = schema.parse({
+    const result = await schema.validate({
      pageId: 'page-789',
      permanentlyDelete: true,
      forceDelete: true,
    });

-    expect(parsed).toHaveProperty('pageId', 'page-789');
-    expect(parsed).not.toHaveProperty('permanentlyDelete');
-    expect(parsed).not.toHaveProperty('forceDelete');
+    expect(result.success).toBe(true);
+    expect(result.value).toHaveProperty('pageId', 'page-789');
+    expect(result.value).not.toHaveProperty('permanentlyDelete');
+    expect(result.value).not.toHaveProperty('forceDelete');
  });
 });

@@ -207,21 +212,25 @@ describe('AiChatToolsService expanded toolset guardrails', () => {
    const tools = await buildTools();
    const transformPage = tools.transformPage;

-    // The Zod input schema only allows pageId/transformJs/dryRun; parsing
-    // strips unknown keys, so deleteComments can never reach the client.
+    // inputSchema is now an AI SDK `Schema`; its `validate` runs the same zod
+    // safeParse, which only allows pageId/transformJs/dryRun and strips unknown
+    // keys — so deleteComments can never reach the client.
    const schema = (transformPage as unknown as { inputSchema: unknown })
      .inputSchema as {
-      parse: (v: unknown) => Record<string, unknown>;
+      validate: (
+        v: unknown,
+      ) => Promise<{ success: boolean; value?: Record<string, unknown> }>;
    };
-    const parsed = schema.parse({
+    const result = await schema.validate({
      pageId: 'p',
      transformJs: '(d)=>d',
      dryRun: true,
      deleteComments: true,
    });

-    expect(parsed).toHaveProperty('pageId', 'p');
-    expect(parsed).not.toHaveProperty('deleteComments');
+    expect(result.success).toBe(true);
+    expect(result.value).toHaveProperty('pageId', 'p');
+    expect(result.value).not.toHaveProperty('deleteComments');
  });
 });

--- a/apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts
+++ b/apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts
@@ -15,6 +15,7 @@ import {
 } from './docmost-client.loader';
 import { resolveCurrentPageResult } from './current-page.util';
 import { parseNodeArg } from './parse-node-arg';
+import { modelFriendlyInput } from './model-friendly-input';

 /**
 * Per-user, per-request adapter that exposes Docmost READ operations to the
@@ -102,9 +103,9 @@ export class AiChatToolsService {
    ): Tool =>
      tool({
        description: spec.description,
-        inputSchema: spec.buildShape
-          ? z.object(spec.buildShape(z) as z.ZodRawShape)
-          : z.object({}),
+        inputSchema: modelFriendlyInput(
+          spec.buildShape ? (spec.buildShape(z) as z.ZodRawShape) : {},
+        ),
        execute,
      });

@@ -118,7 +119,7 @@ export class AiChatToolsService {
          'and entities), not a full sentence. If the first results look weak ' +
          'or incomplete, search again with different wording or synonyms ' +
          'before answering.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          query: z.string().describe('The search query.'),
          limit: z
            .number()
@@ -227,7 +228,7 @@ export class AiChatToolsService {
          '"the current page", or "here" refers to. Returns the page id and title, ' +
          'or null if the user is not currently on a page. Call this first whenever ' +
          'the user refers to the current page without giving an explicit id.',
-        inputSchema: z.object({}),
+        inputSchema: modelFriendlyInput({}),
        execute: async () => resolveCurrentPageResult(openedPage),
      }),

@@ -235,7 +236,7 @@ export class AiChatToolsService {
        description:
          'Fetch a single page as Markdown by its page id. Returns the page ' +
          'title and its Markdown content.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id (or slugId) of the page.'),
        }),
        execute: async ({ pageId }) => {
@@ -259,7 +260,7 @@ export class AiChatToolsService {
          'Create a new page with a Markdown body in a space, optionally under ' +
          'a parent page. Returns the new page id and title. Reversible: a page ' +
          'can be moved to trash later.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          title: z.string().describe('The title of the new page.'),
          content: z
            .string()
@@ -294,7 +295,7 @@ export class AiChatToolsService {
        description:
          "Replace a page's body with new Markdown content (and optionally its " +
          'title). Reversible: the previous version is kept in page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page to update.'),
          content: z.string().describe('The new page body as Markdown.'),
          title: z
@@ -316,7 +317,7 @@ export class AiChatToolsService {
        description:
          "Rename a page (change its title only; the body is untouched). " +
          'Reversible: rename back at any time.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page to rename.'),
          title: z.string().describe('The new title.'),
        }),
@@ -331,7 +332,7 @@ export class AiChatToolsService {
        description:
          'Move a page under a new parent page, or to the space root when no ' +
          'parent is given. Reversible: move it back at any time.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page to move.'),
          parentPageId: z
            .string()
@@ -353,7 +354,7 @@ export class AiChatToolsService {
        description:
          'Move a page to the trash (SOFT delete only — fully reversible; the ' +
          'page can be restored from trash). This NEVER permanently deletes.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page to move to trash.'),
        }),
        // GUARDRAIL (§14 H4): the only field ever passed to the client is
@@ -379,7 +380,7 @@ export class AiChatToolsService {
          '"selection not found" error, retry with a corrected EXACT selection ' +
          'copied verbatim from a single paragraph/block. Reversible via the ' +
          'comment UI.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page to comment on.'),
          content: z.string().describe('The comment body as Markdown.'),
          selection: z
@@ -428,7 +429,7 @@ export class AiChatToolsService {
        description:
          'Resolve or reopen a top-level comment thread (reversible — toggle ' +
          'the resolved flag). Only top-level comments can be resolved.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          commentId: z
            .string()
            .describe('The id of the top-level comment to resolve/reopen.'),
@@ -460,7 +461,7 @@ export class AiChatToolsService {
          'List the most recent pages, optionally scoped to a single space. ' +
          'Returns a bounded list (default 50, max 100). Pass tree:true (with ' +
          "spaceId) to instead get the space's full page hierarchy as a nested tree.",
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          spaceId: z
            .string()
            .optional()
@@ -488,7 +489,7 @@ export class AiChatToolsService {
          'List sidebar pages for a space. With no pageId, returns the ' +
          "space's ROOT pages; with a pageId, returns that page's direct " +
          'CHILDREN.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          spaceId: z.string().describe('The id of the space.'),
          pageId: z
            .string()
@@ -520,7 +521,7 @@ export class AiChatToolsService {
        description:
          'Read a table as a matrix of cell texts (plus a parallel cellIds ' +
          'matrix so cells can be addressed for rich edits).',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page.'),
          tableRef: z
            .string()
@@ -536,7 +537,7 @@ export class AiChatToolsService {
      listComments: tool({
        description:
          'List all comments on a page (content as Markdown).',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page.'),
        }),
        execute: async ({ pageId }) => await client.listComments(pageId),
@@ -544,7 +545,7 @@ export class AiChatToolsService {

      getComment: tool({
        description: 'Fetch a single comment by id (content as Markdown).',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          commentId: z.string().describe('The id of the comment.'),
        }),
        execute: async ({ commentId }) => await client.getComment(commentId),
@@ -554,7 +555,7 @@ export class AiChatToolsService {
        description:
          'Find new comments across a space (optionally scoped to a subtree) ' +
          'created after a given timestamp.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          spaceId: z.string().describe('The id of the space to scan.'),
          since: z
            .string()
@@ -586,7 +587,7 @@ export class AiChatToolsService {
        description:
          'Fetch a single page-history version including its lossless ' +
          'ProseMirror content.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          historyId: z.string().describe('The id of the history version.'),
        }),
        execute: async ({ historyId }) =>
@@ -604,7 +605,7 @@ export class AiChatToolsService {
          'Export a page to a single self-contained Docmost-flavoured ' +
          'Markdown file (meta + body + comment threads). Lossless round-trip ' +
          'with importPageMarkdown.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page to export.'),
        }),
        execute: async ({ pageId }) => {
@@ -630,7 +631,7 @@ export class AiChatToolsService {
          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
          'may be a JSON object or a JSON string (both accepted). Reversible: ' +
          'the previous version is kept in page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page.'),
          nodeId: z
            .string()
@@ -663,7 +664,7 @@ export class AiChatToolsService {
          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
          'may be a JSON object or a JSON string (both accepted). Reversible ' +
          'via page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page.'),
          node: z
            .any()
@@ -722,7 +723,7 @@ export class AiChatToolsService {
          'object or a JSON string (both accepted). Omit content for a ' +
          'title-only update. Reversible: the previous version is kept in page ' +
          'history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page to update.'),
          content: z
            .any()
@@ -753,7 +754,7 @@ export class AiChatToolsService {
        description:
          'Insert a row of plain-text cells into a table. Reversible via ' +
          'page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page.'),
          tableRef: z
            .string()
@@ -772,7 +773,7 @@ export class AiChatToolsService {
      tableDeleteRow: tool({
        description:
          'Delete a table row at a 0-based index. Reversible via page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page.'),
          tableRef: z
            .string()
@@ -787,7 +788,7 @@ export class AiChatToolsService {
        description:
          'Set the plain-text content of a table cell at [row, col] (0-based). ' +
          'Reversible via page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page.'),
          tableRef: z
            .string()
@@ -817,7 +818,7 @@ export class AiChatToolsService {
          'Make a page PUBLICLY accessible and return its public URL. ' +
          'Reversible via unsharePage. Only share when the user explicitly ' +
          'asked, since this exposes the page to anyone with the link.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page to share.'),
          searchIndexing: z
            .boolean()
@@ -844,7 +845,7 @@ export class AiChatToolsService {
          "page's ProseMirror document for complex/scripted rewrites. dryRun " +
          '(default true) previews a diff WITHOUT writing; set dryRun:false to ' +
          'apply. Reversible: applying creates a new page-history snapshot.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page to transform.'),
          transformJs: z
            .string()
--- a/apps/server/src/core/ai-chat/tools/model-friendly-input.spec.ts
+++ b/apps/server/src/core/ai-chat/tools/model-friendly-input.spec.ts
@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { modelFriendlyInput } from './model-friendly-input';
+
+/**
+ * Unit tests for the model-friendly input wrapper (issue #190): validation
+ * failures must report a human-readable, parameter-naming message (not the raw
+ * zod text), successful validation must strip unknown keys (preserving the
+ * strip guardrails), and the JSON schema handed to the model must keep the
+ * required/optional contract and field descriptions intact.
+ */
+describe('modelFriendlyInput', () => {
+  // A representative shape: a required id + description, plus an optional field.
+  const shape = {
+    pageId: z.string().describe('The id of the page to comment on.'),
+    content: z.string(),
+    limit: z.number().int().optional(),
+  };
+
+  // The AI SDK `Schema` exposes a `validate` callback and a `jsonSchema` field;
+  // type them loosely for the test.
+  type SchemaLike = {
+    validate?: (
+      v: unknown,
+    ) =>
+      | { success: boolean; value?: Record<string, unknown>; error?: Error }
+      | PromiseLike<{
+          success: boolean;
+          value?: Record<string, unknown>;
+          error?: Error;
+        }>;
+    jsonSchema: unknown;
+  };
+
+  it('reports a model-friendly error naming the missing REQUIRED param + retry hint', async () => {
+    const schema = modelFriendlyInput(shape) as unknown as SchemaLike;
+    // Drop the required `pageId` (the parallel-batch failure mode).
+    const result = await schema.validate!({ content: 'hi' });
+
+    expect(result.success).toBe(false);
+    const message = result.error?.message ?? '';
+    // Names the offending parameter by name.
+    expect(message).toContain('pageId');
+    // Carries the fixed actionable retry hint.
+    expect(message).toContain('Include every REQUIRED parameter and retry');
+    expect(message).toContain('do not drop ids like "pageId"');
+    // It must NOT be the bare raw zod text alone — our wrapper prefix is present.
+    expect(message).toContain('Invalid tool input');
+  });
+
+  it('accepts valid input and STRIPS unknown keys (keeps declared ones)', async () => {
+    const schema = modelFriendlyInput(shape) as unknown as SchemaLike;
+    const result = await schema.validate!({
+      pageId: 'p-1',
+      content: 'hello',
+      // An extra unknown key a (compromised) model might emit.
+      permanentlyDelete: true,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.value).toEqual({ pageId: 'p-1', content: 'hello' });
+    expect(result.value).not.toHaveProperty('permanentlyDelete');
+  });
+
+  it('produces a draft-07 JSON schema that preserves required + descriptions', async () => {
+    const schema = modelFriendlyInput(shape) as unknown as SchemaLike;
+    // jsonSchema may be a value or a promise; await either way.
+    const json = (await Promise.resolve(schema.jsonSchema)) as {
+      required?: string[];
+      properties?: Record<string, { description?: string }>;
+    };
+
+    // Required contract preserved: pageId + content required, limit optional.
+    expect(json.required).toEqual(expect.arrayContaining(['pageId', 'content']));
+    expect(json.required).not.toContain('limit');
+    // Field description preserved.
+    expect(json.properties?.pageId?.description).toBe(
+      'The id of the page to comment on.',
+    );
+  });
+
+  it('de-duplicates a parameter that produces MULTIPLE issues on the same path', async () => {
+    // A single field can fail several zod checks at once (here min-length AND a
+    // regex), yielding two issues with the SAME path. The friendly message must
+    // name that parameter only once (the `seen` dedup branch).
+    const multiIssueShape = {
+      code: z
+        .string()
+        .min(5)
+        .regex(/^[0-9]+$/),
+    };
+    const schema = modelFriendlyInput(
+      multiIssueShape,
+    ) as unknown as SchemaLike;
+    // "ab" violates BOTH the min(5) and the digit-only regex.
+    const result = await schema.validate!({ code: 'ab' });
+
+    expect(result.success).toBe(false);
+    const message = result.error?.message ?? '';
+    // The parameter name appears exactly once despite two underlying issues.
+    const occurrences = message.split('parameter "code"').length - 1;
+    expect(occurrences).toBe(1);
+  });
+
+  it('handles a root-level type error with a "(root)" parameter name', async () => {
+    const schema = modelFriendlyInput(shape) as unknown as SchemaLike;
+    // Passing a non-object yields an issue with an empty path.
+    const result = await schema.validate!('not an object');
+
+    expect(result.success).toBe(false);
+    expect(result.error?.message).toContain('(root)');
+  });
+});
--- a/apps/server/src/core/ai-chat/tools/model-friendly-input.ts
+++ b/apps/server/src/core/ai-chat/tools/model-friendly-input.ts
@@ -0,0 +1,72 @@
+import { jsonSchema, type JSONSchema7, type Schema } from 'ai';
+import { z } from 'zod';
+
+// Centralized input-schema wrapper for in-app AI tools. The JSON schema handed
+// to the model is derived from the same zod shape (so `required`/`description`/
+// constraints are unchanged), but validation failures are reported with a
+// human-readable message that NAMES the offending parameter(s) and asks the
+// model to retry with every required field — instead of the raw zod text. This
+// matters for parallel tool-call batches where the model tends to drop a
+// repeated id like `pageId`.
+
+// Fixed, actionable hint appended to every validation error. Kept as a constant
+// so the message stays deterministic and the spec can assert on it verbatim.
+const RETRY_HINT =
+  'Include every REQUIRED parameter and retry; when issuing parallel tool ' +
+  'calls, do not drop ids like "pageId".';
+
+/**
+ * Turn a zod validation error into a concise, model-friendly message that names
+ * each offending parameter (by its dotted path; the root object is "(root)"),
+ * gives a short reason, and ends with the fixed retry hint. Repeated parameter
+ * names are de-duplicated and the output is deterministic.
+ */
+export function formatIssues(error: z.ZodError): string {
+  const seen = new Set<string>();
+  const parts: string[] = [];
+  for (const issue of error.issues) {
+    const name =
+      Array.isArray(issue.path) && issue.path.length > 0
+        ? issue.path.join('.')
+        : '(root)';
+    if (seen.has(name)) continue;
+    seen.add(name);
+    // Prefer zod's own message (e.g. "Invalid input: expected string, received
+    // undefined"); fall back to a generic reason when it is missing.
+    const reason = issue.message ? issue.message : 'missing or invalid';
+    parts.push(`parameter "${name}": ${reason}`);
+  }
+  const summary = parts.length > 0 ? parts.join('; ') : 'invalid tool input';
+  return `Invalid tool input — ${summary}. ${RETRY_HINT}`;
+}
+
+/**
+ * Build an AI SDK `Schema` from a zod raw shape. The JSON schema exposed to the
+ * model is derived from the zod object (preserving `required`, `description`,
+ * and field constraints), so the required/optional contract is UNCHANGED. On a
+ * validation failure we return a model-friendly error (see `formatIssues`); on
+ * success we return the PARSED data, which has unknown keys stripped by zod —
+ * this preserves the existing strip guardrails (e.g. deletePage never forwards
+ * permanentlyDelete/forceDelete; transformPage never forwards deleteComments).
+ */
+export function modelFriendlyInput<Shape extends z.ZodRawShape>(
+  shape: Shape,
+): Schema<z.infer<z.ZodObject<Shape>>> {
+  const object = z.object(shape);
+  // draft-07 JSON schema for the model (keeps required/description/constraints).
+  const schema = z.toJSONSchema(object, { target: 'draft-7' }) as JSONSchema7;
+  return jsonSchema<z.infer<typeof object>>(schema, {
+    validate: (value: unknown) => {
+      const result = object.safeParse(value);
+      if (result.success) {
+        // Return the PARSED (unknown-key-stripped) data so the SDK forwards a
+        // clean object to execute — preserves the existing strip guardrails.
+        return { success: true as const, value: result.data };
+      }
+      return {
+        success: false as const,
+        error: new Error(formatIssues(result.error)),
+      };
+    },
+  });
+}
--- a/apps/server/src/core/ai-chat/tools/public-share-chat-tools.service.ts
+++ b/apps/server/src/core/ai-chat/tools/public-share-chat-tools.service.ts
@@ -5,6 +5,7 @@ import { ShareService } from '../../share/share.service';
 import { SearchService } from '../../search/search.service';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { jsonToMarkdown } from '../../../collaboration/collaboration.util';
+import { modelFriendlyInput } from './model-friendly-input';

 /**
 * Isolated, READ-ONLY toolset for the ANONYMOUS public-share assistant.
@@ -52,7 +53,7 @@ export class PublicShareChatToolsService {
          '(key terms and entities), not a full sentence. If the first ' +
          'results look weak, search again with different wording before ' +
          'answering. Only pages inside this share are ever returned.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          query: z.string().describe('The search query.'),
          limit: z
            .number()
@@ -87,7 +88,7 @@ export class PublicShareChatToolsService {
          'Markdown, by its page id. Returns the page title and its Markdown ' +
          'content. Only pages inside this share can be read; reading any ' +
          'other page fails.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
          pageId: z
            .string()
            .describe('The id (or slugId) of a page within this share.'),
@@ -142,7 +143,7 @@ export class PublicShareChatToolsService {
          'List the pages (titles + ids) that make up THIS published ' +
          'documentation share, so you can orient yourself before reading or ' +
          'searching. Only pages inside this share are listed.',
-        inputSchema: z.object({}),
+        inputSchema: modelFriendlyInput({}),
        execute: async () => {
          // Reuse the same share-tree logic the public /shares/tree route uses:
          // it validates the share + workspace, excludes restricted subtrees,
--- a/apps/server/src/core/page/services/page.service.spec.ts
+++ b/apps/server/src/core/page/services/page.service.spec.ts
@@ -3,6 +3,22 @@ import { PageService } from './page.service';
 import { MovePageDto } from '../dto/move-page.dto';
 import { Page } from '@docmost/db/types/entity.types';

+// A permissive chainable Proxy stands in for the locked Kysely trx so the
+// FOR-UPDATE lock query chains inside executeTx(this.db, ...) resolve. Shared by
+// every spec that drives a transactional write (movePage cycle guard, movePage
+// provenance, movePageToSpace).
+const makeChain = () => {
+  const c: any = new Proxy(function () {}, {
+    get: (_t, p) =>
+      p === 'then'
+        ? undefined
+        : p === 'execute' || p === 'executeTakeFirst'
+          ? () => Promise.resolve([])
+          : () => c,
+  });
+  return c;
+};
+
 // Direct instantiation with stub deps. The Test.createTestingModule form failed
 // to resolve the @InjectKysely()/@InjectQueue() tokens at compile(), and this
 // smoke test only needs the service to construct.
@@ -39,12 +55,14 @@ describe('PageService', () => {
    // Build a PageService whose pageRepo (findById/updatePage) and own
    // getPageBreadCrumbs are mockable, while every other collaborator stays a
    // bare stub. We only need to drive the three cycle-guard branches, so we
-    // mock minimally rather than standing up the whole DI graph.
+    // mock minimally rather than standing up the whole DI graph. The trx stub
+    // comes from the shared module-level `makeChain` helper.
    const makeService = (overrides?: {
      breadcrumbs?: Array<{ id: string }>;
    }) => {
      const pageRepo = {
-        // Destination parent lookup: a valid, non-deleted, same-space page.
+        // Destination parent lookup: a valid, non-deleted, same-space page. Also
+        // serves the FOR-UPDATE lock reads inside the transaction.
        findById: jest.fn().mockResolvedValue({
          id: 'dest-parent',
          deletedAt: null,
@@ -57,11 +75,19 @@ describe('PageService', () => {

      const eventEmitter = { emit: jest.fn() };

+      // Re-parenting under a concrete parent now runs through
+      // executeTx(this.db, ...), which calls db.transaction().execute(fn). The
+      // trxStub is the value handed to the callback (the locked transaction).
+      const trxStub = makeChain();
+      const db = {
+        transaction: jest.fn(() => ({ execute: (fn: any) => fn(trxStub) })),
+      };
+
      const svc = new PageService(
        pageRepo as any, // pageRepo
        {} as any, // pagePermissionRepo
        {} as any, // attachmentRepo
-        {} as any, // db
+        db as any, // db
        {} as any, // storageService
        {} as any, // attachmentQueue
        {} as any, // aiQueue
@@ -79,7 +105,7 @@ describe('PageService', () => {
        .spyOn(svc, 'getPageBreadCrumbs')
        .mockResolvedValue((overrides?.breadcrumbs ?? []) as any);

-      return { svc, pageRepo, eventEmitter };
+      return { svc, pageRepo, eventEmitter, trxStub, db };
    };

    // movePage takes `movedPage` as a param. Keep its parentPageId distinct from
@@ -146,6 +172,65 @@ describe('PageService', () => {
      await expect(svc.movePage(dto, makeMovedPage())).resolves.not.toThrow();
      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
    });
+
+    it('serializes a legitimate re-parent under FOR UPDATE in canonical lock order (#159 #9)', async () => {
+      // Destination's ancestor chain does NOT contain the moved page -> no cycle.
+      const { svc, pageRepo, trxStub } = makeService({
+        breadcrumbs: [{ id: 'dest-parent' }, { id: 'root' }],
+      });
+      const getBreadcrumbsSpy = jest.spyOn(svc, 'getPageBreadCrumbs');
+      const dto: MovePageDto = {
+        pageId: 'page-1',
+        position: VALID_POSITION,
+        parentPageId: 'dest-parent',
+      };
+
+      await expect(svc.movePage(dto, makeMovedPage())).resolves.not.toThrow();
+
+      // Both rows are locked FOR UPDATE inside the transaction: findById is
+      // called with { withLock: true, trx: <the locked tx> } for the moved page
+      // and the destination parent.
+      const lockCalls = pageRepo.findById.mock.calls.filter(
+        (c: any[]) => c[1]?.withLock === true,
+      );
+      expect(lockCalls).toHaveLength(2);
+      for (const call of lockCalls) {
+        expect(call[1].withLock).toBe(true);
+        expect(call[1].trx).toBe(trxStub);
+      }
+
+      // Locks are acquired in a canonical (id-sorted) order so the two opposing
+      // moves serialize without deadlocking.
+      const lockedIds = lockCalls.map((c: any[]) => c[0]);
+      expect(lockedIds).toEqual(['page-1', 'dest-parent'].sort());
+
+      // The cycle re-check runs inside the locked transaction (trx passed).
+      expect(getBreadcrumbsSpy).toHaveBeenCalledWith('dest-parent', trxStub);
+
+      // The update is written inside the same transaction (trx is the 3rd arg).
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      expect(pageRepo.updatePage.mock.calls[0][2]).toBe(trxStub);
+    });
+
+    it('moves a page to root WITHOUT a transaction (no cycle possible)', async () => {
+      // A move-to-root (parentPageId === null) can never create a cycle, so it
+      // takes the unlocked else-branch: updatePage runs with NO trx and the
+      // db.transaction() serialization path is skipped entirely.
+      const { svc, pageRepo, db } = makeService();
+      const dto: MovePageDto = {
+        pageId: 'page-1',
+        position: VALID_POSITION,
+        parentPageId: null,
+      };
+
+      await expect(svc.movePage(dto, makeMovedPage())).resolves.not.toThrow();
+
+      // No FOR-UPDATE serialization: the transaction was never opened.
+      expect(db.transaction).not.toHaveBeenCalled();
+      // The update is written outside any transaction (3rd arg is undefined).
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      expect(pageRepo.updatePage.mock.calls[0][2]).toBeUndefined();
+    });
  });

  describe('agent provenance stamping (#143)', () => {
@@ -259,6 +344,8 @@ describe('PageService', () => {

    describe('movePage() → updatePage', () => {
      const VALID_POSITION = 'a0';
+      // Re-parenting under a concrete parent runs through executeTx(this.db, ...);
+      // the shared `makeChain` helper stands in for the locked Kysely trx.
      const run = async (provenance: any) => {
        const pageRepo = {
          findById: jest.fn().mockResolvedValue({
@@ -268,9 +355,12 @@ describe('PageService', () => {
          }),
          updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
        };
+        const trxStub = makeChain();
        const svc = makeSvc({
          pageRepo,
-          db: {} as any,
+          db: {
+            transaction: () => ({ execute: (fn: any) => fn(trxStub) }),
+          } as any,
        });
        // Legitimate move: destination ancestors do NOT include the moved page.
        jest
@@ -316,20 +406,9 @@ describe('PageService', () => {

    describe('movePageToSpace() → root-page updatePage', () => {
      // movePageToSpace runs its writes inside executeTx(this.db, cb), which
-      // calls this.db.transaction().execute(fn => fn(trx)). A permissive
-      // chainable Proxy stands in for the Kysely trx so arbitrary chains resolve.
-      const makeChain = () => {
-        const c: any = new Proxy(function () {}, {
-          get: (_t, p) =>
-            p === 'then'
-              ? undefined
-              : p === 'execute' || p === 'executeTakeFirst'
-                ? () => Promise.resolve([])
-                : () => c,
-        });
-        return c;
-      };
-
+      // calls this.db.transaction().execute(fn => fn(trx)). The shared
+      // `makeChain` helper stands in for the Kysely trx so arbitrary chains
+      // resolve.
      const run = async (provenance: any) => {
        const trxStub = makeChain();
        const db = {
--- a/apps/server/src/core/page/services/page.service.ts
+++ b/apps/server/src/core/page/services/page.service.ts
@@ -15,13 +15,13 @@ import {
  executeWithCursorPagination,
 } from '@docmost/db/pagination/cursor-pagination';
 import { InjectKysely } from 'nestjs-kysely';
-import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
 import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
 import { MovePageDto } from '../dto/move-page.dto';
 import { shapeSidebarPagesTree } from './sidebar-pages-tree.util';
 import { generateSlugId } from '../../../common/helpers';
 import { getPageTitle } from '../../../common/helpers';
-import { executeTx } from '@docmost/db/utils';
+import { executeTx, dbOrTx } from '@docmost/db/utils';
 import { AttachmentRepo } from '@docmost/db/repos/attachment/attachment.repo';
 import { v7 as uuid7 } from 'uuid';
 import {
@@ -915,34 +915,53 @@ export class PageService {
      }
    }

-    // Server-side cycle guard: a page may not be moved into itself or into any
-    // page within its own subtree. Without this, an MCP/REST/agent caller (or a
-    // fast drag racing the client check) could persist a cycle and broadcast it.
-    // Only relevant when re-parenting under a concrete parent; moving to root
-    // (parentPageId null/undefined) can never create a cycle.
-    if (dto.parentPageId) {
-      if (dto.parentPageId === dto.pageId) {
-        throw new BadRequestException('Cannot move a page into its own subtree');
-      }
-      // Walk the destination parent's ancestor chain (reusing the breadcrumb
-      // ancestor CTE). If the page being moved appears among those ancestors,
-      // the destination lives inside the moved page's subtree -> cycle.
-      const destAncestors = await this.getPageBreadCrumbs(dto.parentPageId);
-      if (destAncestors.some((ancestor) => ancestor.id === dto.pageId)) {
-        throw new BadRequestException('Cannot move a page into its own subtree');
-      }
+    // Cheap self-move guard (no DB) — keep before the transaction.
+    if (dto.parentPageId && dto.parentPageId === dto.pageId) {
+      throw new BadRequestException('Cannot move a page into its own subtree');
    }

-    const updateResult = await this.pageRepo.updatePage(
-      {
-        position: dto.position,
-        parentPageId: parentPageId,
-        // Agent-edit provenance: annotate the source on an agent move. A normal
-        // user request leaves the existing source value unchanged.
-        ...agentSourceFields(provenance, 'lastUpdatedSource', 'lastUpdatedAiChatId'),
-      },
-      dto.pageId,
-    );
+    const updateValues = {
+      position: dto.position,
+      parentPageId: parentPageId,
+      // Agent-edit provenance: annotate the source on an agent move. A normal
+      // user request leaves the existing source value unchanged.
+      ...agentSourceFields(provenance, 'lastUpdatedSource', 'lastUpdatedAiChatId'),
+    };
+
+    let updateResult;
+    if (typeof parentPageId === 'string') {
+      // Genuine re-parent under a concrete parent: the ONLY path that can create
+      // a cycle. Two opposing moves (A: X under Y, B: Y under X) racing each
+      // other could each pass a cycle check built from a stale snapshot and
+      // persist a cycle (#159 finding #9). Serialize them: lock the moved page
+      // and the destination parent FOR UPDATE in a canonical (id-sorted) order
+      // so they cannot deadlock, then run the cycle check INSIDE the transaction
+      // against the now-committed state.
+      updateResult = await executeTx(this.db, async (trx) => {
+        // Both opposing moves touch the same two rows {pageId, parentPageId};
+        // a fixed lock order forces one to wait for the other to commit. Lock by
+        // canonical UUIDs — `dto.pageId` can be a slugId (MovePageDto.pageId is a
+        // bare @IsString), so two opposing moves passing slugIds could sort into
+        // different lock orders and deadlock (AB-BA). `movedPage.id` is the
+        // resolved row UUID, matching `parentPageId`.
+        const lockIds = [movedPage.id, parentPageId].sort();
+        for (const id of lockIds) {
+          await this.pageRepo.findById(id, { withLock: true, trx });
+        }
+        // Re-read the destination's ancestor chain within the locked tx: it now
+        // reflects any concurrent re-parent that committed before we got the lock.
+        const destAncestors = await this.getPageBreadCrumbs(parentPageId, trx);
+        if (destAncestors.some((ancestor) => ancestor.id === dto.pageId)) {
+          throw new BadRequestException(
+            'Cannot move a page into its own subtree',
+          );
+        }
+        return this.pageRepo.updatePage(updateValues, dto.pageId, trx);
+      });
+    } else {
+      // Same-parent reorder or move-to-root: no cycle possible, no lock needed.
+      updateResult = await this.pageRepo.updatePage(updateValues, dto.pageId);
+    }

    // Guard against a phantom broadcast: if the row was concurrently deleted or
    // otherwise not updated, skip the PAGE_MOVED event so we don't replay a move
@@ -981,8 +1000,8 @@ export class PageService {
    });
  }

-  async getPageBreadCrumbs(childPageId: string) {
-    const ancestors = await this.db
+  async getPageBreadCrumbs(childPageId: string, trx?: KyselyTransaction) {
+    const ancestors = await dbOrTx(this.db, trx)
      .withRecursive('page_ancestors', (db) =>
        db
          .selectFrom('pages')
--- a/apps/server/src/core/share/dto/share-alias.dto.ts
+++ b/apps/server/src/core/share/dto/share-alias.dto.ts
@@ -1,44 +0,0 @@
-import {
-  IsBoolean,
-  IsNotEmpty,
-  IsOptional,
-  IsString,
-} from 'class-validator';
-
-/**
- * Create/retarget a vanity alias for a page. `confirmReassign` is the
- * two-step guard for the "address already points at another page" case: the
- * first call without it gets a 409 carrying the current target, the client
- * confirms, and retries with `confirmReassign: true`.
- */
-export class SetShareAliasDto {
-  @IsString()
-  @IsNotEmpty()
-  pageId: string;
-
-  @IsString()
-  @IsNotEmpty()
-  alias: string;
-
-  @IsBoolean()
-  @IsOptional()
-  confirmReassign?: boolean;
-}
-
-export class RemoveShareAliasDto {
-  @IsString()
-  @IsNotEmpty()
-  aliasId: string;
-}
-
-export class ShareAliasAvailabilityDto {
-  @IsString()
-  @IsNotEmpty()
-  alias: string;
-}
-
-export class ShareAliasForPageDto {
-  @IsString()
-  @IsNotEmpty()
-  pageId: string;
-}
--- a/apps/server/src/core/share/share-alias-redirect.controller.spec.ts
+++ b/apps/server/src/core/share/share-alias-redirect.controller.spec.ts
@@ -1,252 +0,0 @@
-import * as fs from 'node:fs';
-
-// `@sindresorhus/slugify` is ESM-only and not in jest's transformIgnorePatterns,
-// so the real module fails to parse under ts-jest. Stub it with a minimal,
-// deterministic slugifier — this spec asserts the controller's slug *assembly*
-// (`<title-slug>-<slugId>`, 70-char clamp, `untitled` fallback), not the upstream
-// slug algorithm. The factory keeps the real ESM module from ever being loaded.
-jest.mock('@sindresorhus/slugify', () => ({
-  __esModule: true,
-  default: (input: string) =>
-    String(input)
-      .toLowerCase()
-      .trim()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, ''),
-}));
-
-import { ShareAliasRedirectController } from './share-alias-redirect.controller';
-
-/**
- * Routing/leak guard for the PUBLIC `GET /l/:alias` resolver.
- *
- * This is the most security-sensitive surface of the alias feature: an
- * unauthenticated route that MUST serve the plain SPA index (exactly like any
- * unknown path) for an unknown / dangling / no-longer-readable alias so that the
- * existence of a name never leaks. Only a resolvable, still-readable alias may
- * 302 to the canonical `/share/<key>/p/<title-slug>-<slugId>` page (302 — never
- * 301 — because the target is retargetable). These tests pin that routing and
- * the defensive percent-decoding, mirroring `share-seo.controller.routing.spec`.
- */
-
-const STREAM_SENTINEL = { __isStream: true } as unknown as fs.ReadStream;
-
-// Stub fs at CALL time (jest.spyOn), NOT module load (jest.mock): the controller
-// transitively pulls bcrypt, whose native module is located by node-gyp-build
-// reading the filesystem at import time — a module-level fs mock breaks that.
-beforeEach(() => {
-  jest.spyOn(fs, 'existsSync').mockReturnValue(true);
-  jest.spyOn(fs, 'createReadStream').mockReturnValue(STREAM_SENTINEL);
-});
-afterEach(() => jest.restoreAllMocks());
-
-function makeRes() {
-  const res: any = {
-    sent: undefined as unknown,
-    statusCode: undefined as number | undefined,
-    redirectUrl: undefined as string | undefined,
-    type: jest.fn(() => res),
-    status: jest.fn((code: number) => {
-      res.statusCode = code;
-      return res;
-    }),
-    send: jest.fn((v: unknown) => {
-      res.sent = v;
-      return res;
-    }),
-    redirect: jest.fn((url: string, code: number) => {
-      res.redirectUrl = url;
-      res.statusCode = code;
-      return res;
-    }),
-  };
-  return res;
-}
-
-function makeController(opts: {
-  resolved?: { share: any; page: any } | null;
-  selfHosted?: boolean;
-}) {
-  const shareAliasService = {
-    resolveReadableTarget: jest.fn(async () => opts.resolved ?? null),
-  };
-  const workspaceRepo = {
-    findFirst: jest.fn(async () => ({ id: 'ws-self' })),
-    findByHostname: jest.fn(async (sub: string) =>
-      sub === 'acme' ? { id: 'ws-acme' } : null,
-    ),
-  };
-  const environmentService = {
-    isSelfHosted: jest.fn(() => opts.selfHosted ?? true),
-  };
-  const controller = new ShareAliasRedirectController(
-    shareAliasService as any,
-    workspaceRepo as any,
-    environmentService as any,
-  );
-  return { controller, shareAliasService, workspaceRepo, environmentService };
-}
-
-const selfReq: any = { raw: { headers: { host: 'self' } } };
-
-describe('ShareAliasRedirectController.resolve', () => {
-  it('302-redirects a resolvable alias to the canonical share page', async () => {
-    const { controller, shareAliasService } = makeController({
-      resolved: {
-        share: { key: 'SHAREKEY' },
-        page: { slugId: 'abc123', title: 'Quarterly Report' },
-      },
-    });
-    const res = makeRes();
-
-    await controller.resolve('promo', selfReq, res);
-
-    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
-      'promo',
-      'ws-self',
-    );
-    expect(res.redirect).toHaveBeenCalledWith(
-      '/share/SHAREKEY/p/quarterly-report-abc123',
-      302,
-    );
-    // No index stream was served on a hit.
-    expect(res.sent).toBeUndefined();
-  });
-
-  it('falls back to "untitled" in the slug when the target has no title', async () => {
-    const { controller } = makeController({
-      resolved: { share: { key: 'K' }, page: { slugId: 'sid', title: '' } },
-    });
-    const res = makeRes();
-
-    await controller.resolve('promo', selfReq, res);
-
-    expect(res.redirect).toHaveBeenCalledWith('/share/K/p/untitled-sid', 302);
-  });
-
-  it('clamps the title-slug to the first 70 characters of the page title', async () => {
-    // 119-char title; only the first 70 chars must reach the slug. The 70-char
-    // boundary deliberately falls mid-word ("Entire" -> "entir") so the clamp is
-    // unambiguous: anything past char 70 ("...e Fiscal Year...") must be dropped.
-    const longTitle =
-      'The Comprehensive Quarterly Financial Performance Report For The Entire Fiscal Year Two Thousand Twenty Five And Beyond';
-    const { controller } = makeController({
-      resolved: {
-        share: { key: 'K' },
-        page: { slugId: 'sid', title: longTitle },
-      },
-    });
-    const res = makeRes();
-
-    await controller.resolve('promo', selfReq, res);
-
-    expect(res.redirect).toHaveBeenCalledWith(
-      '/share/K/p/the-comprehensive-quarterly-financial-performance-report-for-the-entir-sid',
-      302,
-    );
-  });
-
-  it('streams the SPA index WITHOUT a 302 for an unknown/dangling/unreadable alias (no leak)', async () => {
-    const { controller, shareAliasService } = makeController({ resolved: null });
-    const res = makeRes();
-
-    await controller.resolve('does-not-exist', selfReq, res);
-
-    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalled();
-    // The plain index stream was served and no redirect leaked alias existence.
-    expect(res.redirect).not.toHaveBeenCalled();
-    expect(res.sent).toBe(STREAM_SENTINEL);
-    expect(res.type).toHaveBeenCalledWith('text/html');
-  });
-
-  it('streams the SPA index without even resolving when the workspace is null', async () => {
-    // Subdomain host that maps to no workspace => workspace === null.
-    const { controller, shareAliasService, workspaceRepo } = makeController({
-      selfHosted: false,
-    });
-    const res = makeRes();
-    const req: any = { raw: { headers: { host: 'unknown.example.com' } } };
-
-    await controller.resolve('promo', req, res);
-
-    expect(workspaceRepo.findByHostname).toHaveBeenCalledWith('unknown');
-    // Never even attempts to resolve (alias existence cannot leak per-host).
-    expect(shareAliasService.resolveReadableTarget).not.toHaveBeenCalled();
-    expect(res.redirect).not.toHaveBeenCalled();
-    expect(res.sent).toBe(STREAM_SENTINEL);
-  });
-
-  it('defensively decodes broken percent-encoding and treats it as unknown', async () => {
-    const { controller, shareAliasService } = makeController({ resolved: null });
-    const res = makeRes();
-
-    // '%E0%A4%A' is invalid -> decodeURIComponent throws -> raw value is used,
-    // and the alias resolves to nothing (no crash, served as index).
-    await controller.resolve('%E0%A4%A', selfReq, res);
-
-    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
-      '%E0%A4%A',
-      'ws-self',
-    );
-    expect(res.redirect).not.toHaveBeenCalled();
-    expect(res.sent).toBe(STREAM_SENTINEL);
-  });
-
-  it('decodes a valid percent-encoded alias before resolving', async () => {
-    const { controller, shareAliasService } = makeController({ resolved: null });
-    const res = makeRes();
-
-    await controller.resolve('my%2Dlink', selfReq, res);
-
-    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
-      'my-link',
-      'ws-self',
-    );
-  });
-
-  it('resolves the workspace via findFirst on the self-hosted path', async () => {
-    const { controller, workspaceRepo, shareAliasService } = makeController({
-      selfHosted: true,
-      resolved: null,
-    });
-    const res = makeRes();
-
-    await controller.resolve('promo', selfReq, res);
-
-    expect(workspaceRepo.findFirst).toHaveBeenCalled();
-    expect(workspaceRepo.findByHostname).not.toHaveBeenCalled();
-    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
-      'promo',
-      'ws-self',
-    );
-  });
-
-  it('resolves the workspace via findByHostname (subdomain) on the cloud path', async () => {
-    const { controller, workspaceRepo, shareAliasService } = makeController({
-      selfHosted: false,
-      resolved: null,
-    });
-    const res = makeRes();
-    const req: any = { raw: { headers: { host: 'acme.example.com' } } };
-
-    await controller.resolve('promo', req, res);
-
-    expect(workspaceRepo.findByHostname).toHaveBeenCalledWith('acme');
-    expect(workspaceRepo.findFirst).not.toHaveBeenCalled();
-    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
-      'promo',
-      'ws-acme',
-    );
-  });
-
-  it('serves a 404 when no built client index exists', async () => {
-    jest.spyOn(fs, 'existsSync').mockReturnValue(false);
-    const { controller } = makeController({ resolved: null });
-    const res = makeRes();
-
-    await controller.resolve('promo', selfReq, res);
-
-    expect(res.status).toHaveBeenCalledWith(404);
-    expect(res.redirect).not.toHaveBeenCalled();
-  });
-});
--- a/apps/server/src/core/share/share-alias-redirect.controller.ts
+++ b/apps/server/src/core/share/share-alias-redirect.controller.ts
@@ -1,95 +0,0 @@
-import { Controller, Get, Param, Req, Res } from '@nestjs/common';
-import { FastifyReply, FastifyRequest } from 'fastify';
-import { join } from 'path';
-import * as fs from 'node:fs';
-import slugify from '@sindresorhus/slugify';
-import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
-import { EnvironmentService } from '../../integrations/environment/environment.service';
-import { Workspace } from '@docmost/db/types/entity.types';
-import { ShareAliasService } from './share-alias.service';
-
-/**
- * Public resolver for vanity links `GET /l/:alias`. Excluded from the global
- * `/api` prefix (see main.ts) and parallel to ShareSeoController.
- *
- * On a hit it issues a 302 (NEVER 301) to the canonical
- * `/share/:key/p/:slug` page, so:
- *   - the existing share render + SSR meta is reused verbatim (crawlers follow
- *     the 302 and get the correct preview);
- *   - because the alias target is mutable, a temporary redirect is always
- *     re-resolved — a cached 301 would pin clients to the pre-swap page.
- *
- * Any unknown / dangling / no-longer-readable alias serves the plain SPA index
- * (same as any unknown path) so the existence of a name never leaks.
- */
-@Controller('l')
-export class ShareAliasRedirectController {
-  constructor(
-    private readonly shareAliasService: ShareAliasService,
-    private readonly workspaceRepo: WorkspaceRepo,
-    private readonly environmentService: EnvironmentService,
-  ) {}
-
-  @Get(':alias')
-  async resolve(
-    @Param('alias') rawAlias: string,
-    @Req() req: FastifyRequest,
-    @Res({ passthrough: false }) res: FastifyReply,
-  ) {
-    // NestJS does not apply middlewares to paths excluded from the global /api
-    // prefix, so the DomainMiddleware workspace resolution is duplicated here
-    // (same workaround as ShareSeoController).
-    let workspace: Workspace = null;
-    if (this.environmentService.isSelfHosted()) {
-      workspace = await this.workspaceRepo.findFirst();
-    } else {
-      const header = req.raw.headers.host;
-      const subdomain = header?.split('.')[0];
-      workspace = subdomain
-        ? await this.workspaceRepo.findByHostname(subdomain)
-        : null;
-    }
-
-    const clientDistPath = join(__dirname, '..', '..', '..', '..', 'client/dist');
-    const indexFilePath = join(clientDistPath, 'index.html');
-
-    let decoded = rawAlias;
-    try {
-      decoded = decodeURIComponent(rawAlias);
-    } catch {
-      // Malformed percent-encoding -> treat as unknown alias.
-    }
-
-    const resolved = workspace
-      ? await this.shareAliasService.resolveReadableTarget(
-          decoded,
-          workspace.id,
-        )
-      : null;
-
-    if (!resolved) {
-      return this.sendIndex(indexFilePath, res);
-    }
-
-    const slug = buildPageSlug(resolved.page.slugId, resolved.page.title);
-    // 302, NOT 301: the alias is retargetable, so the redirect must always be
-    // re-resolved by clients/crawlers.
-    return res.redirect(`/share/${resolved.share.key}/p/${slug}`, 302);
-  }
-
-  private sendIndex(indexFilePath: string, res: FastifyReply) {
-    if (!fs.existsSync(indexFilePath)) {
-      // No built client (e.g. API-only dev): nothing to serve.
-      res.status(404).send('Not found');
-      return;
-    }
-    const stream = fs.createReadStream(indexFilePath);
-    res.type('text/html').send(stream);
-  }
-}
-
-/** Canonical share page slug: `<title-slug>-<slugId>` (mirrors the client). */
-function buildPageSlug(slugId: string, title?: string): string {
-  const titleSlug = slugify(title?.substring(0, 70) || 'untitled');
-  return `${titleSlug}-${slugId}`;
-}
--- a/apps/server/src/core/share/share-alias.controller.spec.ts
+++ b/apps/server/src/core/share/share-alias.controller.spec.ts
@@ -1,260 +0,0 @@
-import {
-  BadRequestException,
-  ForbiddenException,
-  NotFoundException,
-} from '@nestjs/common';
-import { ShareAliasController } from './share-alias.controller';
-
-/**
- * Authz-gate tests for the authenticated alias management controller. The access
- * decisions for creating/retargeting/removing an alias live in THIS controller
- * (the service spec delegates authorization to the caller), so each gate is
- * pinned here against mocked PageRepo / ShareService / ShareAliasService /
- * PageAccessService. A regression that drops any gate must fail here.
- */
-describe('ShareAliasController authz gates', () => {
-  function makeController() {
-    const shareAliasService = {
-      setAlias: jest.fn(async () => ({ id: 'alias-1' })),
-      removeAlias: jest.fn(async () => undefined),
-      getAliasById: jest.fn(),
-      getAliasForPage: jest.fn(),
-      checkAvailability: jest.fn(),
-    };
-    const shareService = {
-      resolveReadableSharePage: jest.fn(),
-      isSharingAllowed: jest.fn(),
-    };
-    const pageRepo = { findById: jest.fn() };
-    const pageAccessService = {
-      validateCanEdit: jest.fn(async () => undefined),
-      validateCanView: jest.fn(async () => undefined),
-    };
-    const controller = new ShareAliasController(
-      shareAliasService as any,
-      shareService as any,
-      pageRepo as any,
-      pageAccessService as any,
-    );
-    return {
-      controller,
-      shareAliasService,
-      shareService,
-      pageRepo,
-      pageAccessService,
-    };
-  }
-
-  const user: any = { id: 'u-1' };
-  const workspace: any = { id: 'ws-1' };
-
-  describe('set', () => {
-    it('throws NotFoundException for a nonexistent page', async () => {
-      const { controller, pageRepo, pageAccessService } = makeController();
-      pageRepo.findById.mockResolvedValue(null);
-
-      await expect(
-        controller.set({ pageId: 'p-x', alias: 'promo' } as any, user, workspace),
-      ).rejects.toBeInstanceOf(NotFoundException);
-      expect(pageAccessService.validateCanEdit).not.toHaveBeenCalled();
-    });
-
-    it('throws NotFoundException for a page in another workspace', async () => {
-      const { controller, pageRepo } = makeController();
-      pageRepo.findById.mockResolvedValue({
-        id: 'p-1',
-        workspaceId: 'ws-OTHER',
-      });
-
-      await expect(
-        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
-      ).rejects.toBeInstanceOf(NotFoundException);
-    });
-
-    it('enforces validateCanEdit before setting the alias', async () => {
-      const { controller, pageRepo, pageAccessService, shareService } =
-        makeController();
-      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
-      pageAccessService.validateCanEdit.mockRejectedValue(
-        new ForbiddenException('no edit'),
-      );
-
-      await expect(
-        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
-      ).rejects.toBeInstanceOf(ForbiddenException);
-      // Gate short-circuits before any share resolution.
-      expect(shareService.resolveReadableSharePage).not.toHaveBeenCalled();
-    });
-
-    it('throws BadRequestException when the page is not publicly shared', async () => {
-      const { controller, pageRepo, shareService } = makeController();
-      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
-      shareService.resolveReadableSharePage.mockResolvedValue(null);
-
-      await expect(
-        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
-      ).rejects.toThrow('Page is not publicly shared');
-      await expect(
-        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
-      ).rejects.toBeInstanceOf(BadRequestException);
-    });
-
-    it('throws ForbiddenException when public sharing is disabled', async () => {
-      const { controller, pageRepo, shareService } = makeController();
-      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
-      shareService.resolveReadableSharePage.mockResolvedValue({
-        share: { spaceId: 'sp-1' },
-      });
-      shareService.isSharingAllowed.mockResolvedValue(false);
-
-      await expect(
-        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
-      ).rejects.toBeInstanceOf(ForbiddenException);
-    });
-
-    it('delegates to setAlias on the happy path with all gates passed', async () => {
-      const { controller, pageRepo, shareService, shareAliasService } =
-        makeController();
-      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
-      shareService.resolveReadableSharePage.mockResolvedValue({
-        share: { spaceId: 'sp-1' },
-      });
-      shareService.isSharingAllowed.mockResolvedValue(true);
-
-      const result = await controller.set(
-        { pageId: 'p-1', alias: 'promo', confirmReassign: true } as any,
-        user,
-        workspace,
-      );
-
-      expect(shareAliasService.setAlias).toHaveBeenCalledWith({
-        workspaceId: 'ws-1',
-        pageId: 'p-1',
-        creatorId: 'u-1',
-        alias: 'promo',
-        confirmReassign: true,
-      });
-      expect(result).toEqual({ id: 'alias-1' });
-    });
-  });
-
-  describe('remove', () => {
-    it('throws NotFoundException for an unknown alias', async () => {
-      const { controller, shareAliasService } = makeController();
-      shareAliasService.getAliasById.mockResolvedValue(null);
-
-      await expect(
-        controller.remove({ aliasId: 'a-x' } as any, user, workspace),
-      ).rejects.toBeInstanceOf(NotFoundException);
-      expect(shareAliasService.removeAlias).not.toHaveBeenCalled();
-    });
-
-    it('requires validateCanEdit on the current target before removing', async () => {
-      const { controller, shareAliasService, pageRepo, pageAccessService } =
-        makeController();
-      shareAliasService.getAliasById.mockResolvedValue({
-        id: 'a-1',
-        pageId: 'p-1',
-      });
-      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
-      pageAccessService.validateCanEdit.mockRejectedValue(
-        new ForbiddenException('no edit'),
-      );
-
-      await expect(
-        controller.remove({ aliasId: 'a-1' } as any, user, workspace),
-      ).rejects.toBeInstanceOf(ForbiddenException);
-      expect(shareAliasService.removeAlias).not.toHaveBeenCalled();
-    });
-
-    it('removes a dangling alias (pageId null) WITHOUT an edit check', async () => {
-      const { controller, shareAliasService, pageRepo, pageAccessService } =
-        makeController();
-      shareAliasService.getAliasById.mockResolvedValue({
-        id: 'a-1',
-        pageId: null,
-      });
-
-      await controller.remove({ aliasId: 'a-1' } as any, user, workspace);
-
-      expect(pageRepo.findById).not.toHaveBeenCalled();
-      expect(pageAccessService.validateCanEdit).not.toHaveBeenCalled();
-      expect(shareAliasService.removeAlias).toHaveBeenCalledWith('a-1', 'ws-1');
-    });
-
-    it('removes when the editor can edit the current target', async () => {
-      const { controller, shareAliasService, pageRepo, pageAccessService } =
-        makeController();
-      shareAliasService.getAliasById.mockResolvedValue({
-        id: 'a-1',
-        pageId: 'p-1',
-      });
-      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
-
-      await controller.remove({ aliasId: 'a-1' } as any, user, workspace);
-
-      expect(pageAccessService.validateCanEdit).toHaveBeenCalled();
-      expect(shareAliasService.removeAlias).toHaveBeenCalledWith('a-1', 'ws-1');
-    });
-
-    it('removes even if the recorded target page no longer exists', async () => {
-      const { controller, shareAliasService, pageRepo, pageAccessService } =
-        makeController();
-      shareAliasService.getAliasById.mockResolvedValue({
-        id: 'a-1',
-        pageId: 'p-gone',
-      });
-      pageRepo.findById.mockResolvedValue(null);
-
-      await controller.remove({ aliasId: 'a-1' } as any, user, workspace);
-
-      expect(pageAccessService.validateCanEdit).not.toHaveBeenCalled();
-      expect(shareAliasService.removeAlias).toHaveBeenCalledWith('a-1', 'ws-1');
-    });
-  });
-
-  describe('forPage', () => {
-    it('throws NotFoundException for a cross-workspace/nonexistent page', async () => {
-      const { controller, pageRepo, pageAccessService } = makeController();
-      pageRepo.findById.mockResolvedValue({
-        id: 'p-1',
-        workspaceId: 'ws-OTHER',
-      });
-
-      await expect(
-        controller.forPage({ pageId: 'p-1' } as any, user, workspace),
-      ).rejects.toBeInstanceOf(NotFoundException);
-      expect(pageAccessService.validateCanView).not.toHaveBeenCalled();
-    });
-
-    it('requires validateCanView and returns the alias (or null)', async () => {
-      const { controller, pageRepo, pageAccessService, shareAliasService } =
-        makeController();
-      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
-      shareAliasService.getAliasForPage.mockResolvedValue({ id: 'a-1' });
-
-      const result = await controller.forPage(
-        { pageId: 'p-1' } as any,
-        user,
-        workspace,
-      );
-
-      expect(pageAccessService.validateCanView).toHaveBeenCalled();
-      expect(result).toEqual({ id: 'a-1' });
-    });
-
-    it('returns null when the page has no alias', async () => {
-      const { controller, pageRepo, shareAliasService } = makeController();
-      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
-      shareAliasService.getAliasForPage.mockResolvedValue(undefined);
-
-      const result = await controller.forPage(
-        { pageId: 'p-1' } as any,
-        user,
-        workspace,
-      );
-
-      expect(result).toBeNull();
-    });
-  });
-});
--- a/apps/server/src/core/share/share-alias.controller.ts
+++ b/apps/server/src/core/share/share-alias.controller.ts
@@ -1,139 +0,0 @@
-import {
-  BadRequestException,
-  Body,
-  Controller,
-  ForbiddenException,
-  HttpCode,
-  HttpStatus,
-  NotFoundException,
-  Post,
-  UseGuards,
-} from '@nestjs/common';
-import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
-import { AuthUser } from '../../common/decorators/auth-user.decorator';
-import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
-import { User, Workspace } from '@docmost/db/types/entity.types';
-import { PageRepo } from '@docmost/db/repos/page/page.repo';
-import { PageAccessService } from '../page/page-access/page-access.service';
-import { ShareService } from './share.service';
-import { ShareAliasService } from './share-alias.service';
-import {
-  RemoveShareAliasDto,
-  SetShareAliasDto,
-  ShareAliasAvailabilityDto,
-  ShareAliasForPageDto,
-} from './dto/share-alias.dto';
-
-/**
- * Authenticated management of vanity `/l/:alias` links. The PUBLIC resolve path
- * lives in `ShareAliasRedirectController` (`/l/:alias`); this controller only
- * creates/retargets/removes/looks-up aliases for editors.
- */
-@UseGuards(JwtAuthGuard)
-@Controller('share-aliases')
-export class ShareAliasController {
-  constructor(
-    private readonly shareAliasService: ShareAliasService,
-    private readonly shareService: ShareService,
-    private readonly pageRepo: PageRepo,
-    private readonly pageAccessService: PageAccessService,
-  ) {}
-
-  @HttpCode(HttpStatus.OK)
-  @Post('set')
-  async set(
-    @Body() dto: SetShareAliasDto,
-    @AuthUser() user: User,
-    @AuthWorkspace() workspace: Workspace,
-  ) {
-    const page = await this.pageRepo.findById(dto.pageId);
-    if (!page || page.workspaceId !== workspace.id) {
-      throw new NotFoundException('Page not found');
-    }
-
-    // Editing the page is required to point an address at it.
-    await this.pageAccessService.validateCanEdit(page, user);
-
-    // The page must currently be publicly readable through the share graph; an
-    // alias to a non-shared page would only ever 404.
-    const resolved = await this.shareService.resolveReadableSharePage(
-      undefined,
-      page.id,
-      workspace.id,
-    );
-    if (!resolved) {
-      throw new BadRequestException('Page is not publicly shared');
-    }
-
-    const sharingAllowed = await this.shareService.isSharingAllowed(
-      workspace.id,
-      resolved.share.spaceId,
-    );
-    if (!sharingAllowed) {
-      throw new ForbiddenException('Public sharing is disabled');
-    }
-
-    return this.shareAliasService.setAlias({
-      workspaceId: workspace.id,
-      pageId: page.id,
-      creatorId: user.id,
-      alias: dto.alias,
-      confirmReassign: dto.confirmReassign,
-    });
-  }
-
-  @HttpCode(HttpStatus.OK)
-  @Post('remove')
-  async remove(
-    @Body() dto: RemoveShareAliasDto,
-    @AuthUser() user: User,
-    @AuthWorkspace() workspace: Workspace,
-  ) {
-    const alias = await this.shareAliasService.getAliasById(
-      dto.aliasId,
-      workspace.id,
-    );
-    if (!alias) {
-      throw new NotFoundException('Alias not found');
-    }
-
-    // Only someone who can edit the (current) target page may free the address.
-    // A dangling alias (page deleted) can be removed by any workspace member.
-    if (alias.pageId) {
-      const page = await this.pageRepo.findById(alias.pageId);
-      if (page) {
-        await this.pageAccessService.validateCanEdit(page, user);
-      }
-    }
-
-    await this.shareAliasService.removeAlias(alias.id, workspace.id);
-  }
-
-  @HttpCode(HttpStatus.OK)
-  @Post('availability')
-  async availability(
-    @Body() dto: ShareAliasAvailabilityDto,
-    @AuthWorkspace() workspace: Workspace,
-  ) {
-    return this.shareAliasService.checkAvailability(dto.alias, workspace.id);
-  }
-
-  @HttpCode(HttpStatus.OK)
-  @Post('for-page')
-  async forPage(
-    @Body() dto: ShareAliasForPageDto,
-    @AuthUser() user: User,
-    @AuthWorkspace() workspace: Workspace,
-  ) {
-    const page = await this.pageRepo.findById(dto.pageId);
-    if (!page || page.workspaceId !== workspace.id) {
-      throw new NotFoundException('Page not found');
-    }
-    await this.pageAccessService.validateCanView(page, user);
-
-    return (
-      (await this.shareAliasService.getAliasForPage(page.id, workspace.id)) ??
-      null
-    );
-  }
-}
--- a/apps/server/src/core/share/share-alias.service.spec.ts
+++ b/apps/server/src/core/share/share-alias.service.spec.ts
@@ -1,252 +0,0 @@
-import { BadRequestException, ConflictException } from '@nestjs/common';
-import { ShareAliasService } from './share-alias.service';
-
-/**
- * Behaviour tests for the alias write/resolve semantics: create vs no-op vs the
- * 409 reassign guard, uniqueness-race handling, availability probe, and the
- * request-time readable-target resolution (which re-runs the share boundary).
- */
-describe('ShareAliasService', () => {
-  function makeService() {
-    const shareAliasRepo = {
-      findByAliasAndWorkspace: jest.fn(),
-      findByPageId: jest.fn(),
-      findById: jest.fn(),
-      insert: jest.fn(),
-      updatePageId: jest.fn(),
-      delete: jest.fn(),
-    };
-    const pageRepo = { findById: jest.fn() };
-    const shareService = {
-      resolveReadableSharePage: jest.fn(),
-      isSharingAllowed: jest.fn(),
-    };
-    const service = new ShareAliasService(
-      shareAliasRepo as any,
-      pageRepo as any,
-      shareService as any,
-    );
-    return { service, shareAliasRepo, pageRepo, shareService };
-  }
-
-  describe('setAlias', () => {
-    it('rejects an invalid alias before touching the db', async () => {
-      const { service, shareAliasRepo } = makeService();
-      await expect(
-        service.setAlias({
-          workspaceId: 'ws-1',
-          pageId: 'p-1',
-          creatorId: 'u-1',
-          alias: 'A', // too short + uppercase
-        }),
-      ).rejects.toBeInstanceOf(BadRequestException);
-      expect(shareAliasRepo.findByAliasAndWorkspace).not.toHaveBeenCalled();
-    });
-
-    it('normalizes then inserts a brand-new alias', async () => {
-      const { service, shareAliasRepo } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
-      shareAliasRepo.insert.mockResolvedValue({ id: 'a-1', alias: 'my-page' });
-
-      const res = await service.setAlias({
-        workspaceId: 'ws-1',
-        pageId: 'p-1',
-        creatorId: 'u-1',
-        alias: '  My Page ',
-      });
-
-      expect(shareAliasRepo.findByAliasAndWorkspace).toHaveBeenCalledWith(
-        'my-page',
-        'ws-1',
-      );
-      expect(shareAliasRepo.insert).toHaveBeenCalledWith({
-        workspaceId: 'ws-1',
-        alias: 'my-page',
-        pageId: 'p-1',
-        creatorId: 'u-1',
-      });
-      expect(res).toMatchObject({ id: 'a-1' });
-    });
-
-    it('is a no-op when the alias already points at the same page', async () => {
-      const { service, shareAliasRepo } = makeService();
-      const existing = { id: 'a-1', alias: 'foo', pageId: 'p-1' };
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(existing);
-
-      const res = await service.setAlias({
-        workspaceId: 'ws-1',
-        pageId: 'p-1',
-        creatorId: 'u-1',
-        alias: 'foo',
-      });
-
-      expect(res).toBe(existing);
-      expect(shareAliasRepo.insert).not.toHaveBeenCalled();
-      expect(shareAliasRepo.updatePageId).not.toHaveBeenCalled();
-    });
-
-    it('throws 409 with current target when name is taken and not confirmed', async () => {
-      const { service, shareAliasRepo, pageRepo } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
-        id: 'a-1',
-        alias: 'foo',
-        pageId: 'p-other',
-      });
-      pageRepo.findById.mockResolvedValue({ id: 'p-other', title: 'Other' });
-
-      try {
-        await service.setAlias({
-          workspaceId: 'ws-1',
-          pageId: 'p-1',
-          creatorId: 'u-1',
-          alias: 'foo',
-        });
-        fail('expected ConflictException');
-      } catch (err) {
-        expect(err).toBeInstanceOf(ConflictException);
-        expect((err as ConflictException).getResponse()).toMatchObject({
-          code: 'ALIAS_REASSIGN_REQUIRED',
-          currentPageId: 'p-other',
-          currentPageTitle: 'Other',
-        });
-      }
-      expect(shareAliasRepo.updatePageId).not.toHaveBeenCalled();
-    });
-
-    it('retargets (UPDATE page_id) when confirmReassign is set', async () => {
-      const { service, shareAliasRepo } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
-        id: 'a-1',
-        alias: 'foo',
-        pageId: 'p-other',
-      });
-      shareAliasRepo.updatePageId.mockResolvedValue({ id: 'a-1', pageId: 'p-1' });
-
-      const res = await service.setAlias({
-        workspaceId: 'ws-1',
-        pageId: 'p-1',
-        creatorId: 'u-1',
-        alias: 'foo',
-        confirmReassign: true,
-      });
-
-      expect(shareAliasRepo.updatePageId).toHaveBeenCalledWith(
-        'a-1',
-        'p-1',
-        'ws-1',
-      );
-      expect(res).toMatchObject({ pageId: 'p-1' });
-    });
-
-    it('maps a unique-violation race to 409', async () => {
-      const { service, shareAliasRepo } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
-      shareAliasRepo.insert.mockRejectedValue({ code: '23505' });
-
-      await expect(
-        service.setAlias({
-          workspaceId: 'ws-1',
-          pageId: 'p-1',
-          creatorId: 'u-1',
-          alias: 'foo',
-        }),
-      ).rejects.toBeInstanceOf(ConflictException);
-    });
-  });
-
-  describe('checkAvailability', () => {
-    it('reports invalid for a bad slug without a db hit', async () => {
-      const { service, shareAliasRepo } = makeService();
-      const res = await service.checkAvailability('Bad Slug!', 'ws-1');
-      expect(res).toMatchObject({ valid: false, available: false });
-      expect(shareAliasRepo.findByAliasAndWorkspace).not.toHaveBeenCalled();
-    });
-
-    it('reports available when no row exists', async () => {
-      const { service, shareAliasRepo } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
-      const res = await service.checkAvailability('free-name', 'ws-1');
-      expect(res).toMatchObject({
-        alias: 'free-name',
-        valid: true,
-        available: true,
-        currentPageId: null,
-      });
-    });
-
-    it('reports taken with the current target page', async () => {
-      const { service, shareAliasRepo } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
-        id: 'a-1',
-        pageId: 'p-9',
-      });
-      const res = await service.checkAvailability('taken', 'ws-1');
-      expect(res).toMatchObject({ available: false, currentPageId: 'p-9' });
-    });
-  });
-
-  describe('resolveReadableTarget', () => {
-    it('returns null for an invalid alias', async () => {
-      const { service } = makeService();
-      expect(await service.resolveReadableTarget('!!', 'ws-1')).toBeNull();
-    });
-
-    it('returns null for an unknown or dangling alias', async () => {
-      const { service, shareAliasRepo } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValueOnce(undefined);
-      expect(await service.resolveReadableTarget('foo', 'ws-1')).toBeNull();
-
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValueOnce({
-        id: 'a-1',
-        pageId: null,
-      });
-      expect(await service.resolveReadableTarget('foo', 'ws-1')).toBeNull();
-    });
-
-    it('returns null when the page is no longer publicly readable', async () => {
-      const { service, shareAliasRepo, shareService } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
-        id: 'a-1',
-        pageId: 'p-1',
-      });
-      shareService.resolveReadableSharePage.mockResolvedValue(null);
-      expect(await service.resolveReadableTarget('foo', 'ws-1')).toBeNull();
-    });
-
-    it('returns null when sharing is disabled for the space', async () => {
-      const { service, shareAliasRepo, shareService } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
-        id: 'a-1',
-        pageId: 'p-1',
-      });
-      shareService.resolveReadableSharePage.mockResolvedValue({
-        share: { key: 'k', spaceId: 's-1' },
-        page: { slugId: 'sid', title: 'T' },
-      });
-      shareService.isSharingAllowed.mockResolvedValue(false);
-      expect(await service.resolveReadableTarget('foo', 'ws-1')).toBeNull();
-    });
-
-    it('returns the resolved share+page on success', async () => {
-      const { service, shareAliasRepo, shareService } = makeService();
-      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
-        id: 'a-1',
-        pageId: 'p-1',
-      });
-      const resolved = {
-        share: { key: 'k', spaceId: 's-1' },
-        page: { slugId: 'sid', title: 'T' },
-      };
-      shareService.resolveReadableSharePage.mockResolvedValue(resolved);
-      shareService.isSharingAllowed.mockResolvedValue(true);
-
-      const res = await service.resolveReadableTarget('FOO', 'ws-1');
-      expect(res).toBe(resolved);
-      // alias was normalized to lowercase before lookup
-      expect(shareAliasRepo.findByAliasAndWorkspace).toHaveBeenCalledWith(
-        'foo',
-        'ws-1',
-      );
-    });
-  });
-});
--- a/apps/server/src/core/share/share-alias.service.ts
+++ b/apps/server/src/core/share/share-alias.service.ts
@@ -1,187 +0,0 @@
-import {
-  BadRequestException,
-  ConflictException,
-  Injectable,
-  Logger,
-} from '@nestjs/common';
-import { ShareAliasRepo } from '@docmost/db/repos/share-alias/share-alias.repo';
-import { PageRepo } from '@docmost/db/repos/page/page.repo';
-import { ShareService } from './share.service';
-import { Page, ShareAlias } from '@docmost/db/types/entity.types';
-import { isValidShareAlias, normalizeShareAlias } from './share-alias.util';
-
-/** Postgres unique_violation; the (workspace_id, alias) constraint races here. */
-const PG_UNIQUE_VIOLATION = '23505';
-
-export interface ResolvedAliasTarget {
-  share: NonNullable<
-    Awaited<ReturnType<ShareService['resolveReadableSharePage']>>
-  >['share'];
-  page: Page;
-}
-
-@Injectable()
-export class ShareAliasService {
-  private readonly logger = new Logger(ShareAliasService.name);
-
-  constructor(
-    private readonly shareAliasRepo: ShareAliasRepo,
-    private readonly pageRepo: PageRepo,
-    private readonly shareService: ShareService,
-  ) {}
-
-  /**
-   * Create or retarget a vanity alias. The alias is workspace-scoped:
-   *   - no row for this name        -> INSERT a new pointer
-   *   - row already points at pageId -> no-op (idempotent)
-   *   - row points elsewhere         -> the "swap". Without confirmReassign we
-   *     throw 409 carrying the current target so the client can confirm; with
-   *     it we UPDATE the single row's page_id (every /l/<alias> link follows the
-   *     302 to the new page instantly — no stale 301 cache).
-   *
-   * Caller is responsible for authorizing the page (edit rights + public
-   * readability); this method owns only the alias-name semantics.
-   */
-  async setAlias(opts: {
-    workspaceId: string;
-    pageId: string;
-    creatorId: string;
-    alias: string;
-    confirmReassign?: boolean;
-  }): Promise<ShareAlias> {
-    const { workspaceId, pageId, creatorId, confirmReassign } = opts;
-    const alias = normalizeShareAlias(opts.alias);
-    if (!isValidShareAlias(alias)) {
-      throw new BadRequestException(
-        'Invalid alias. Use 2-60 lowercase letters, digits and hyphens.',
-      );
-    }
-
-    const existing = await this.shareAliasRepo.findByAliasAndWorkspace(
-      alias,
-      workspaceId,
-    );
-
-    if (!existing) {
-      try {
-        return await this.shareAliasRepo.insert({
-          workspaceId,
-          alias,
-          pageId,
-          creatorId,
-        });
-      } catch (err: any) {
-        // Lost a uniqueness race: another request claimed the name first.
-        if (err?.code === PG_UNIQUE_VIOLATION) {
-          throw new ConflictException({ message: 'Alias already taken' });
-        }
-        this.logger.error(err);
-        throw new BadRequestException('Failed to set alias');
-      }
-    }
-
-    // Already points at this page -> nothing to do.
-    if (existing.pageId === pageId) {
-      return existing;
-    }
-
-    // Name occupied by a different (or dangling) target: require confirmation.
-    if (!confirmReassign) {
-      const currentPage = existing.pageId
-        ? await this.pageRepo.findById(existing.pageId)
-        : null;
-      throw new ConflictException({
-        message: 'Alias already in use',
-        code: 'ALIAS_REASSIGN_REQUIRED',
-        currentPageId: existing.pageId,
-        currentPageTitle: currentPage?.title ?? null,
-      });
-    }
-
-    return this.shareAliasRepo.updatePageId(existing.id, pageId, workspaceId);
-  }
-
-  /** Free a vanity name (no history kept). */
-  async removeAlias(aliasId: string, workspaceId: string): Promise<void> {
-    await this.shareAliasRepo.delete(aliasId, workspaceId);
-  }
-
-  /** Debounced availability probe for the modal. */
-  async checkAvailability(
-    rawAlias: string,
-    workspaceId: string,
-  ): Promise<{
-    alias: string;
-    valid: boolean;
-    available: boolean;
-    currentPageId: string | null;
-  }> {
-    const alias = normalizeShareAlias(rawAlias);
-    if (!isValidShareAlias(alias)) {
-      return { alias, valid: false, available: false, currentPageId: null };
-    }
-    const existing = await this.shareAliasRepo.findByAliasAndWorkspace(
-      alias,
-      workspaceId,
-    );
-    return {
-      alias,
-      valid: true,
-      available: !existing,
-      currentPageId: existing?.pageId ?? null,
-    };
-  }
-
-  /** A single alias row scoped to the workspace, or undefined. */
-  getAliasById(
-    aliasId: string,
-    workspaceId: string,
-  ): Promise<ShareAlias | undefined> {
-    return this.shareAliasRepo.findById(aliasId, workspaceId);
-  }
-
-  /** The alias currently targeting a page (modal display), or undefined. */
-  getAliasForPage(
-    pageId: string,
-    workspaceId: string,
-  ): Promise<ShareAlias | undefined> {
-    return this.shareAliasRepo.findByPageId(pageId, workspaceId);
-  }
-
-  /**
-   * Resolve a vanity alias to the canonical, publicly-READABLE share page, or
-   * null. This re-runs the authoritative share boundary at request time (so a
-   * later-unshared / restricted / sharing-disabled target collapses to null and
-   * the caller serves the generic SPA 404 — no existence leak). The alias row
-   * itself is just a pointer; this is where access is actually decided.
-   */
-  async resolveReadableTarget(
-    rawAlias: string,
-    workspaceId: string,
-  ): Promise<ResolvedAliasTarget | null> {
-    const alias = normalizeShareAlias(rawAlias);
-    if (!isValidShareAlias(alias)) return null;
-
-    const aliasRow = await this.shareAliasRepo.findByAliasAndWorkspace(
-      alias,
-      workspaceId,
-    );
-    // Unknown name or a dangling alias (target page deleted) -> not resolvable.
-    if (!aliasRow?.pageId) return null;
-
-    const resolved = await this.shareService.resolveReadableSharePage(
-      undefined,
-      aliasRow.pageId,
-      workspaceId,
-    );
-    if (!resolved) return null;
-
-    const sharingAllowed = await this.shareService.isSharingAllowed(
-      workspaceId,
-      resolved.share.spaceId,
-    );
-    if (!sharingAllowed) return null;
-
-    return resolved;
-  }
-}
--- a/apps/server/src/core/share/share-alias.util.spec.ts
+++ b/apps/server/src/core/share/share-alias.util.spec.ts
@@ -1,60 +0,0 @@
-import { isValidShareAlias, normalizeShareAlias } from './share-alias.util';
-
-describe('normalizeShareAlias', () => {
-  it('lowercases and trims', () => {
-    expect(normalizeShareAlias('  HelloWorld  ')).toBe('helloworld');
-  });
-
-  it('converts spaces and underscores to single hyphens', () => {
-    expect(normalizeShareAlias('my cool   page')).toBe('my-cool-page');
-    expect(normalizeShareAlias('my_cool_page')).toBe('my-cool-page');
-  });
-
-  it('collapses repeated hyphens and trims edge hyphens', () => {
-    expect(normalizeShareAlias('--a---b--')).toBe('a-b');
-  });
-
-  it('handles null/undefined defensively', () => {
-    expect(normalizeShareAlias(undefined as unknown as string)).toBe('');
-  });
-});
-
-describe('isValidShareAlias', () => {
-  it('accepts ascii lowercase hyphen-separated slugs', () => {
-    expect(isValidShareAlias('hello')).toBe(true);
-    expect(isValidShareAlias('hello-world-2')).toBe(true);
-    expect(isValidShareAlias('a1')).toBe(true);
-  });
-
-  it('rejects too short / too long', () => {
-    expect(isValidShareAlias('a')).toBe(false);
-    expect(isValidShareAlias('a'.repeat(61))).toBe(false);
-    expect(isValidShareAlias('a'.repeat(60))).toBe(true);
-  });
-
-  it('rejects leading/trailing/double hyphens', () => {
-    expect(isValidShareAlias('-abc')).toBe(false);
-    expect(isValidShareAlias('abc-')).toBe(false);
-    expect(isValidShareAlias('a--b')).toBe(false);
-  });
-
-  it('rejects uppercase, cyrillic and other non-ascii', () => {
-    expect(isValidShareAlias('Hello')).toBe(false);
-    expect(isValidShareAlias('привет')).toBe(false);
-    expect(isValidShareAlias('a b')).toBe(false);
-    expect(isValidShareAlias('a_b')).toBe(false);
-    expect(isValidShareAlias('a.b')).toBe(false);
-  });
-
-  it('normalize + validate round-trips a messy input to a valid slug', () => {
-    const alias = normalizeShareAlias('  My  Cool_Page!! ');
-    // "!!" is not stripped by normalize (only case/separators), so the result
-    // still fails validation — the charset gate is intentionally separate.
-    expect(alias).toBe('my-cool-page!!');
-    expect(isValidShareAlias(alias)).toBe(false);
-
-    const ok = normalizeShareAlias('  My  Cool Page ');
-    expect(ok).toBe('my-cool-page');
-    expect(isValidShareAlias(ok)).toBe(true);
-  });
-});
--- a/apps/server/src/core/share/share-alias.util.ts
+++ b/apps/server/src/core/share/share-alias.util.ts
@@ -1,30 +0,0 @@
-/**
- * Vanity share-alias helpers shared by the write path (set/availability) and the
- * `/l/:alias` resolve path. Aliases are ASCII-only, lowercase, hyphen-separated
- * slugs — deliberately no Cyrillic / transliteration: the user types the exact
- * canonical form. Keep this in sync with the client copy in
- * `apps/client/src/features/share/share-alias.util.ts`.
- */
-
-// Normalize a user-provided vanity alias into canonical ASCII storage form.
-// This only canonicalizes shape (case, separators); it does NOT enforce the
-// charset — call isValidShareAlias afterwards to reject anything illegal.
-export function normalizeShareAlias(raw: string): string {
-  return (raw ?? '')
-    .trim()
-    .toLowerCase()
-    .replace(/[\s_]+/g, '-') // spaces/underscores -> single hyphen
-    .replace(/-{2,}/g, '-') // collapse repeated hyphens
-    .replace(/^-+|-+$/g, ''); // trim leading/trailing hyphens
-}
-
-// ASCII only: lowercase letters/digits in hyphen-separated groups, length 2..60.
-const ALIAS_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-export function isValidShareAlias(alias: string): boolean {
-  return (
-    typeof alias === 'string' &&
-    alias.length >= 2 &&
-    alias.length <= 60 &&
-    ALIAS_RE.test(alias)
-  );
-}
--- a/apps/server/src/core/share/share.module.ts
+++ b/apps/server/src/core/share/share.module.ts
@@ -5,22 +5,13 @@ import { TokenModule } from '../auth/token.module';
 import { ShareSeoController } from './share-seo.controller';
 import { TransclusionModule } from '../page/transclusion/transclusion.module';
 import { AiModule } from '../../integrations/ai/ai.module';
-import { ShareAliasService } from './share-alias.service';
-import { ShareAliasController } from './share-alias.controller';
-import { ShareAliasRedirectController } from './share-alias-redirect.controller';

@Module({
  // AiModule (AiSettingsService) is used by the page-info route to surface
  // whether the anonymous public-share assistant is enabled for the workspace.
  imports: [TokenModule, TransclusionModule, AiModule],
-  controllers: [
-    ShareController,
-    ShareSeoController,
-    // Vanity /l/:alias: authenticated management + public 302 resolver.
-    ShareAliasController,
-    ShareAliasRedirectController,
-  ],
-  providers: [ShareService, ShareAliasService],
-  exports: [ShareService, ShareAliasService],
+  controllers: [ShareController, ShareSeoController],
+  providers: [ShareService],
+  exports: [ShareService],
 })
 export class ShareModule {}
--- a/apps/server/src/database/database.module.ts
+++ b/apps/server/src/database/database.module.ts
@@ -23,7 +23,6 @@ import { UserTokenRepo } from './repos/user-token/user-token.repo';
 import { UserSessionRepo } from '@docmost/db/repos/session/user-session.repo';
 import { BacklinkRepo } from '@docmost/db/repos/backlink/backlink.repo';
 import { ShareRepo } from '@docmost/db/repos/share/share.repo';
-import { ShareAliasRepo } from '@docmost/db/repos/share-alias/share-alias.repo';
 import { NotificationRepo } from '@docmost/db/repos/notification/notification.repo';
 import { WatcherRepo } from '@docmost/db/repos/watcher/watcher.repo';
 import { LabelRepo } from '@docmost/db/repos/label/label.repo';
@@ -97,7 +96,6 @@ import { normalizePostgresUrl } from '../common/helpers';
    UserSessionRepo,
    BacklinkRepo,
    ShareRepo,
-    ShareAliasRepo,
    NotificationRepo,
    WatcherRepo,
    LabelRepo,
@@ -130,7 +128,6 @@ import { normalizePostgresUrl } from '../common/helpers';
    UserSessionRepo,
    BacklinkRepo,
    ShareRepo,
-    ShareAliasRepo,
    NotificationRepo,
    WatcherRepo,
    LabelRepo,
--- a/apps/server/src/database/migrations/20260626T130000-share-aliases.ts
+++ b/apps/server/src/database/migrations/20260626T130000-share-aliases.ts
@@ -1,54 +0,0 @@
-import { type Kysely, sql } from 'kysely';
-
-/**
- * Vanity share aliases: a retargetable, human-readable pointer (`/l/<alias>`)
- * that lives independently of any single `shares` row. The alias belongs to the
- * WORKSPACE (stable address), and `page_id` is nullable with ON DELETE SET NULL
- * so the address survives deletion of its current target (it 404s until
- * retargeted) rather than disappearing with the page.
- */
-export async function up(db: Kysely<any>): Promise<void> {
-  await db.schema
-    .createTable('share_aliases')
-    .addColumn('id', 'uuid', (col) =>
-      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
-    )
-    .addColumn('workspace_id', 'uuid', (col) =>
-      col.references('workspaces.id').onDelete('cascade').notNull(),
-    )
-    // Normalized ASCII, lowercase. Uniqueness is enforced per-workspace below.
-    .addColumn('alias', 'varchar', (col) => col.notNull())
-    // Nullable + SET NULL: the address outlives its target page.
-    .addColumn('page_id', 'uuid', (col) =>
-      col.references('pages.id').onDelete('set null'),
-    )
-    .addColumn('creator_id', 'uuid', (col) =>
-      col.references('users.id').onDelete('set null'),
-    )
-    .addColumn('created_at', 'timestamptz', (col) =>
-      col.notNull().defaultTo(sql`now()`),
-    )
-    .addColumn('updated_at', 'timestamptz', (col) =>
-      col.notNull().defaultTo(sql`now()`),
-    )
-    .execute();
-
-  // The vanity name is unique within a workspace (mirrors shares.key scoping).
-  await db.schema
-    .createIndex('share_aliases_workspace_id_alias_unique')
-    .on('share_aliases')
-    .columns(['workspace_id', 'alias'])
-    .unique()
-    .execute();
-
-  // "Which alias targets this page?" lookup for the share modal.
-  await db.schema
-    .createIndex('share_aliases_page_id_idx')
-    .on('share_aliases')
-    .column('page_id')
-    .execute();
-}
-
-export async function down(db: Kysely<any>): Promise<void> {
-  await db.schema.dropTable('share_aliases').execute();
-}
--- a/apps/server/src/database/migrations/share-aliases.migration.spec.ts
+++ b/apps/server/src/database/migrations/share-aliases.migration.spec.ts
@@ -1,94 +0,0 @@
-import * as migration from './20260626T130000-share-aliases';
-import type {
-  InsertableShareAlias,
-  ShareAlias,
-  UpdatableShareAlias,
-} from '../types/entity.types';
-
-/**
- * Sanity checks for the share_aliases migration + entity types. We don't run a
- * live Postgres here (that's the integration suite); instead we assert the
- * migration exposes the expected up/down contract and creates the table with
- * the unique (workspace_id, alias) constraint and the page_id index, and that
- * the generated entity types line up with the column set.
- */
-describe('share-aliases migration', () => {
-  it('up creates the table, the unique index and the page_id index', async () => {
-    const calls: string[] = [];
-
-    const tableBuilder: any = new Proxy(
-      {},
-      {
-        get(_t, prop: string) {
-          if (prop === 'execute') return async () => undefined;
-          // addColumn/addConstraint/etc. are chainable no-ops.
-          return () => tableBuilder;
-        },
-      },
-    );
-
-    const indexBuilder: any = new Proxy(
-      {},
-      {
-        get(_t, prop: string) {
-          if (prop === 'execute') return async () => undefined;
-          return () => indexBuilder;
-        },
-      },
-    );
-
-    const schema = {
-      createTable: (name: string) => {
-        calls.push(`createTable:${name}`);
-        return tableBuilder;
-      },
-      createIndex: (name: string) => {
-        calls.push(`createIndex:${name}`);
-        return indexBuilder;
-      },
-    };
-
-    await migration.up({ schema } as any);
-
-    expect(calls).toContain('createTable:share_aliases');
-    expect(calls).toContain(
-      'createIndex:share_aliases_workspace_id_alias_unique',
-    );
-    expect(calls).toContain('createIndex:share_aliases_page_id_idx');
-  });
-
-  it('down drops the table', async () => {
-    const calls: string[] = [];
-    const dropBuilder: any = { execute: async () => undefined };
-    const schema = {
-      dropTable: (name: string) => {
-        calls.push(`dropTable:${name}`);
-        return dropBuilder;
-      },
-    };
-    await migration.down({ schema } as any);
-    expect(calls).toContain('dropTable:share_aliases');
-  });
-
-  it('entity types expose the alias columns', () => {
-    // Compile-time only: these typed declarations fail `tsc` if the entity types
-    // drift (missing/renamed columns, wrong nullability). The runtime assertions
-    // would be tautological, so the value is purely in the type-check.
-    const row: ShareAlias = {
-      id: 'a-1',
-      workspaceId: 'ws-1',
-      alias: 'foo',
-      pageId: 'p-1',
-      creatorId: 'u-1',
-      createdAt: new Date(),
-      updatedAt: new Date(),
-    };
-    const insert: InsertableShareAlias = {
-      workspaceId: 'ws-1',
-      alias: 'foo',
-    };
-    const update: UpdatableShareAlias = { pageId: null };
-
-    expect([row, insert, update]).toHaveLength(3);
-  });
-});
--- a/apps/server/src/database/repos/share-alias/share-alias.repo.spec.ts
+++ b/apps/server/src/database/repos/share-alias/share-alias.repo.spec.ts
@@ -1,120 +0,0 @@
-import { ShareAliasRepo } from './share-alias.repo';
-import type { KyselyDB } from '../../types/kysely.types';
-
-/**
- * SQL-shape unit tests for ShareAliasRepo. A live Postgres is out of scope;
- * instead we spy on the Kysely builder to assert each method pins the
- * workspace scope (so a name in one workspace can never resolve another's
- * page) and threads the right columns.
- */
-describe('ShareAliasRepo', () => {
-  function makeSelectRepo(result: unknown) {
-    const where = jest.fn();
-    const builder: any = {
-      select: jest.fn(() => builder),
-      where: jest.fn((...args: unknown[]) => {
-        where(...args);
-        return builder;
-      }),
-      executeTakeFirst: jest.fn().mockResolvedValue(result),
-    };
-    const db = { selectFrom: jest.fn(() => builder) } as unknown as KyselyDB;
-    return { repo: new ShareAliasRepo(db), db, where, builder };
-  }
-
-  it('findByAliasAndWorkspace scopes by alias AND workspace', async () => {
-    const row = { id: 'a-1', alias: 'foo', workspaceId: 'ws-1' };
-    const { repo, db, where } = makeSelectRepo(row);
-
-    const res = await repo.findByAliasAndWorkspace('foo', 'ws-1');
-
-    expect(res).toBe(row);
-    expect(db.selectFrom).toHaveBeenCalledWith('shareAliases');
-    expect(where).toHaveBeenCalledWith('alias', '=', 'foo');
-    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
-  });
-
-  it('findByPageId scopes by page AND workspace', async () => {
-    const { repo, where } = makeSelectRepo(undefined);
-    await repo.findByPageId('p-1', 'ws-1');
-    expect(where).toHaveBeenCalledWith('pageId', '=', 'p-1');
-    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
-  });
-
-  it('insert writes the provided columns and returns the row', async () => {
-    const values = jest.fn();
-    const inserted = { id: 'a-1' };
-    const builder: any = {
-      values: jest.fn((v: unknown) => {
-        values(v);
-        return builder;
-      }),
-      returning: jest.fn(() => builder),
-      executeTakeFirst: jest.fn().mockResolvedValue(inserted),
-    };
-    const db = { insertInto: jest.fn(() => builder) } as unknown as KyselyDB;
-    const repo = new ShareAliasRepo(db);
-
-    const res = await repo.insert({
-      workspaceId: 'ws-1',
-      alias: 'foo',
-      pageId: 'p-1',
-      creatorId: 'u-1',
-    });
-
-    expect(db.insertInto).toHaveBeenCalledWith('shareAliases');
-    expect(values).toHaveBeenCalledWith({
-      workspaceId: 'ws-1',
-      alias: 'foo',
-      pageId: 'p-1',
-      creatorId: 'u-1',
-    });
-    expect(res).toBe(inserted);
-  });
-
-  it('updatePageId retargets a single row scoped by id + workspace', async () => {
-    const set = jest.fn();
-    const where = jest.fn();
-    const builder: any = {
-      set: jest.fn((s: unknown) => {
-        set(s);
-        return builder;
-      }),
-      where: jest.fn((...args: unknown[]) => {
-        where(...args);
-        return builder;
-      }),
-      returning: jest.fn(() => builder),
-      executeTakeFirst: jest.fn().mockResolvedValue({ id: 'a-1' }),
-    };
-    const db = { updateTable: jest.fn(() => builder) } as unknown as KyselyDB;
-    const repo = new ShareAliasRepo(db);
-
-    await repo.updatePageId('a-1', 'p-2', 'ws-1');
-
-    expect(db.updateTable).toHaveBeenCalledWith('shareAliases');
-    expect(set.mock.calls[0][0].pageId).toBe('p-2');
-    expect(set.mock.calls[0][0].updatedAt).toBeInstanceOf(Date);
-    expect(where).toHaveBeenCalledWith('id', '=', 'a-1');
-    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
-  });
-
-  it('delete scopes by id + workspace', async () => {
-    const where = jest.fn();
-    const builder: any = {
-      where: jest.fn((...args: unknown[]) => {
-        where(...args);
-        return builder;
-      }),
-      execute: jest.fn().mockResolvedValue(undefined),
-    };
-    const db = { deleteFrom: jest.fn(() => builder) } as unknown as KyselyDB;
-    const repo = new ShareAliasRepo(db);
-
-    await repo.delete('a-1', 'ws-1');
-
-    expect(db.deleteFrom).toHaveBeenCalledWith('shareAliases');
-    expect(where).toHaveBeenCalledWith('id', '=', 'a-1');
-    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
-  });
-});
--- a/apps/server/src/database/repos/share-alias/share-alias.repo.ts
+++ b/apps/server/src/database/repos/share-alias/share-alias.repo.ts
@@ -1,109 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { InjectKysely } from 'nestjs-kysely';
-import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
-import { dbOrTx } from '../../utils';
-import {
-  InsertableShareAlias,
-  ShareAlias,
-} from '@docmost/db/types/entity.types';
-
-/**
- * Repository for vanity share aliases (`/l/:alias`). An alias is a long-lived,
- * workspace-scoped pointer to a page; retargeting is a single UPDATE of
- * `page_id`. All lookups are workspace-scoped so a name in one workspace can
- * never resolve a page in another.
- */
-@Injectable()
-export class ShareAliasRepo {
-  constructor(@InjectKysely() private readonly db: KyselyDB) {}
-
-  private baseFields: Array<keyof ShareAlias> = [
-    'id',
-    'workspaceId',
-    'alias',
-    'pageId',
-    'creatorId',
-    'createdAt',
-    'updatedAt',
-  ];
-
-  /** Resolve a (normalized) alias within a workspace, or undefined. */
-  async findByAliasAndWorkspace(
-    alias: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<ShareAlias | undefined> {
-    return dbOrTx(this.db, trx)
-      .selectFrom('shareAliases')
-      .select(this.baseFields)
-      .where('alias', '=', alias)
-      .where('workspaceId', '=', workspaceId)
-      .executeTakeFirst();
-  }
-
-  /** The alias currently pointing at a page (for the share modal). */
-  async findByPageId(
-    pageId: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<ShareAlias | undefined> {
-    return dbOrTx(this.db, trx)
-      .selectFrom('shareAliases')
-      .select(this.baseFields)
-      .where('pageId', '=', pageId)
-      .where('workspaceId', '=', workspaceId)
-      .executeTakeFirst();
-  }
-
-  async findById(
-    id: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<ShareAlias | undefined> {
-    return dbOrTx(this.db, trx)
-      .selectFrom('shareAliases')
-      .select(this.baseFields)
-      .where('id', '=', id)
-      .where('workspaceId', '=', workspaceId)
-      .executeTakeFirst();
-  }
-
-  async insert(
-    insertable: InsertableShareAlias,
-    trx?: KyselyTransaction,
-  ): Promise<ShareAlias> {
-    return dbOrTx(this.db, trx)
-      .insertInto('shareAliases')
-      .values(insertable)
-      .returning(this.baseFields)
-      .executeTakeFirst();
-  }
-
-  /** Retarget an existing alias to a new page (the "swap" operation). */
-  async updatePageId(
-    id: string,
-    pageId: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<ShareAlias> {
-    return dbOrTx(this.db, trx)
-      .updateTable('shareAliases')
-      .set({ pageId, updatedAt: new Date() })
-      .where('id', '=', id)
-      .where('workspaceId', '=', workspaceId)
-      .returning(this.baseFields)
-      .executeTakeFirst();
-  }
-
-  async delete(
-    id: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<void> {
-    await dbOrTx(this.db, trx)
-      .deleteFrom('shareAliases')
-      .where('id', '=', id)
-      .where('workspaceId', '=', workspaceId)
-      .execute();
-  }
-}
--- a/apps/server/src/database/types/db.d.ts
+++ b/apps/server/src/database/types/db.d.ts
@@ -305,16 +305,6 @@ export interface Pages {
  ydoc: Buffer | null;
 }

-export interface ShareAliases {
-  alias: string;
-  createdAt: Generated<Timestamp>;
-  creatorId: string | null;
-  id: Generated<string>;
-  pageId: string | null;
-  updatedAt: Generated<Timestamp>;
-  workspaceId: string;
-}
-
 export interface Shares {
  createdAt: Generated<Timestamp>;
  creatorId: string | null;
@@ -684,7 +674,6 @@ export interface DB {
  pageVerifiers: PageVerifiers;
  pages: Pages;
  scimTokens: ScimTokens;
-  shareAliases: ShareAliases;
  shares: Shares;
  spaceMembers: SpaceMembers;
  spaces: Spaces;
--- a/apps/server/src/database/types/entity.types.ts
+++ b/apps/server/src/database/types/entity.types.ts
@@ -30,7 +30,6 @@ import {
  AuthProviders,
  AuthAccounts,
  Shares,
-  ShareAliases,
  Favorites,
  FileTasks,
  UserMfa as _UserMFA,
@@ -173,11 +172,6 @@ export type Share = Selectable<Shares>;
 export type InsertableShare = Insertable<Shares>;
 export type UpdatableShare = Updateable<Omit<Shares, 'id'>>;

-// Share alias (vanity /l/:alias pointer)
-export type ShareAlias = Selectable<ShareAliases>;
-export type InsertableShareAlias = Insertable<ShareAliases>;
-export type UpdatableShareAlias = Updateable<Omit<ShareAliases, 'id'>>;
-
 // Favorite
 export type Favorite = Selectable<Favorites>;
 export type InsertableFavorite = Insertable<Favorites>;
--- a/apps/server/src/main.ts
+++ b/apps/server/src/main.ts
@@ -40,14 +40,7 @@ async function bootstrap() {
  app.useLogger(app.get(PinoLogger));

  app.setGlobalPrefix('api', {
-    exclude: [
-      'robots.txt',
-      'share/:shareId/p/:pageSlug',
-      // Vanity link resolver lives outside /api so /l/<alias> is a clean
-      // public URL that 302s to the canonical share page.
-      'l/:alias',
-      'mcp',
-    ],
+    exclude: ['robots.txt', 'share/:shareId/p/:pageSlug', 'mcp'],
  });

  const reflector = app.get(Reflector);
--- a/apps/server/test/integration/page-move-cycle-concurrency.int-spec.ts
+++ b/apps/server/test/integration/page-move-cycle-concurrency.int-spec.ts
@@ -0,0 +1,122 @@
+import { Kysely } from 'kysely';
+import { BadRequestException } from '@nestjs/common';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { PageService } from '../../src/core/page/services/page.service';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createSpace,
+  createPage,
+} from './db';
+
+/**
+ * #159 finding #9 — concurrent opposing page moves must not create a cycle.
+ *
+ * User A drags X under Y while user B simultaneously drags Y under X. Before the
+ * fix, the cycle guard (a breadcrumb/ancestor read) and the parent-update write
+ * were NOT in a transaction, so both moves ran against a stale snapshot, both
+ * passed their cycle check, and both committed -> X.parent=Y AND Y.parent=X: a
+ * cycle with no path to root, which breaks the recursive ancestor CTEs and makes
+ * both subtrees vanish from the sidebar.
+ *
+ * The fix wraps the cycle check + update in one READ COMMITTED transaction and
+ * locks the two involved rows FOR UPDATE in a canonical (id-sorted) order, then
+ * re-runs the cycle check inside the lock. One move wins; the loser sees the
+ * committed re-parent and trips the "own subtree" guard.
+ *
+ * NOTE: this runs against real Postgres in CI (the integration suite). There is
+ * no local Postgres in dev, so it is not expected to run locally.
+ */
+describe('movePage concurrent opposing moves do not create a cycle [integration]', () => {
+  let db: Kysely<any>;
+  let workspaceId: string;
+  let spaceId: string;
+
+  beforeAll(async () => {
+    db = getTestDb();
+    workspaceId = (await createWorkspace(db)).id;
+    spaceId = (await createSpace(db, workspaceId)).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  it('lets exactly one opposing move win and never persists a cycle', async () => {
+    // Real collaborators against the test DB. movePage only touches db-backed
+    // methods on pageRepo plus the db itself and the event emitter (stubbed).
+    const pageRepo = new PageRepo(
+      db as any,
+      {} as any,
+      { emit: () => undefined } as any,
+    );
+    const svc = new PageService(
+      pageRepo as any, // pageRepo
+      {} as any, // pagePermissionRepo
+      {} as any, // attachmentRepo
+      db as any, // db
+      {} as any, // storageService
+      {} as any, // attachmentQueue
+      {} as any, // aiQueue
+      {} as any, // generalQueue
+      { emit: () => undefined } as any, // eventEmitter
+      {} as any, // collaborationGateway
+      {} as any, // watcherService
+      {} as any, // transclusionService
+    );
+
+    // Seed R (root), X and Y as children of R.
+    const root = await createPage(db, { workspaceId, spaceId, title: 'R' });
+    const pageX = await createPage(db, { workspaceId, spaceId, title: 'X' });
+    const pageY = await createPage(db, { workspaceId, spaceId, title: 'Y' });
+
+    // createPage does not set parentPageId; wire X.parent=R and Y.parent=R and
+    // give each a valid fractional-index position.
+    await db
+      .updateTable('pages')
+      .set({ parentPageId: root.id, position: 'a0' })
+      .where('id', 'in', [pageX.id, pageY.id])
+      .execute();
+
+    // The Page snapshots movePage receives (parentPageId must be R so each move
+    // is a genuine re-parent rather than a same-parent reorder).
+    const movedX = await pageRepo.findById(pageX.id);
+    const movedY = await pageRepo.findById(pageY.id);
+
+    // Two opposing moves racing: A moves X under Y, B moves Y under X.
+    const results = await Promise.allSettled([
+      svc.movePage(
+        { pageId: pageX.id, parentPageId: pageY.id, position: 'a1' },
+        movedX,
+      ),
+      svc.movePage(
+        { pageId: pageY.id, parentPageId: pageX.id, position: 'a1' },
+        movedY,
+      ),
+    ]);
+
+    // Exactly one fulfilled and one rejected; the rejection is the cycle guard.
+    const fulfilled = results.filter((r) => r.status === 'fulfilled');
+    const rejected = results.filter((r) => r.status === 'rejected');
+    expect(fulfilled).toHaveLength(1);
+    expect(rejected).toHaveLength(1);
+
+    const reason = (rejected[0] as PromiseRejectedResult).reason;
+    expect(reason).toBeInstanceOf(BadRequestException);
+    expect(String(reason?.message)).toContain('own subtree');
+
+    // No cycle persisted: re-fetch X and Y and assert NOT (X->Y AND Y->X).
+    const xNow = await pageRepo.findById(pageX.id);
+    const yNow = await pageRepo.findById(pageY.id);
+    const isCycle =
+      xNow.parentPageId === pageY.id && yNow.parentPageId === pageX.id;
+    expect(isCycle).toBe(false);
+
+    // Exactly one re-parent took effect: one of X/Y still points at R, the other
+    // points at its sibling.
+    const xWon = xNow.parentPageId === pageY.id && yNow.parentPageId === root.id;
+    const yWon = yNow.parentPageId === pageX.id && xNow.parentPageId === root.id;
+    expect(xWon || yWon).toBe(true);
+  });
+});