@agent-native/core-corpus 0.201.0-nightly-20261005153421 → 0.201.0

package/corpus/templates/content/actions/_database-navigation.ts

@@ -24,11 +24,12 @@ import { getDb, schema } from "../server/db/index.js";
 import type {
   ContentDatabaseFilter,
   ContentDatabaseFilterMode,
+  ContentDatabaseNavigationPage,
   ContentDatabaseNavigationPageResponse,
   ContentDatabaseNavigationSort,
+  ContentDatabasePersonalViewOverrides,
 } from "../shared/api.js";
-import { readPersonalDatabaseViewOverrides } from "./_content-database-personal-view.js";
-import { favoriteDocumentIds } from "./_content-favorites.js";
+import { favoritesSystemIds } from "./_content-favorites.js";
 import { softDeletedDatabaseDocumentExclusions } from "./_document-discovery-query.js";
 import { parseDatabaseViewConfig } from "./_property-utils.js";
 
@@ -309,14 +310,21 @@ function combineRevisions(parts: NavigationRevision[]) {
   )}`;
 }
 
+// Expanded branches one read returns with its page, and how many expanded
+// document IDs it accepts.
+export const MAX_NAVIGATION_EXPANDED_BRANCHES = 32;
+export const MAX_NAVIGATION_EXPAND_IDS = 100;
+
 export async function getContentDatabaseNavigationPage(args: {
   database: typeof schema.contentDatabases.$inferSelect;
   userEmail: string;
+  overrides: ContentDatabasePersonalViewOverrides | null;
   parentId: string | null;
   sort: ContentDatabaseNavigationSort;
   viewId?: string;
   limit: number;
   cursor?: string;
+  expand?: readonly string[];
 }): Promise<ContentDatabaseNavigationPageResponse> {
   if (args.database.systemRole !== "files" || !args.database.spaceId) {
     fail("Navigation mode is only available for a Files database.", {
@@ -331,33 +339,7 @@ export async function getContentDatabaseNavigationPage(args: {
     userEmail: args.userEmail,
     orgId: args.database.orgId ?? undefined,
   };
-  const [overrides, parentRows] = await Promise.all([
-    readPersonalDatabaseViewOverrides(args.userEmail, args.database.id),
-    args.parentId === null
-      ? null
-      : db
-          .select({ id: schema.documents.id })
-          .from(schema.contentDatabaseItems)
-          .innerJoin(
-            schema.documents,
-            eq(schema.documents.id, schema.contentDatabaseItems.documentId),
-          )
-          .where(
-            and(
-              eq(schema.contentDatabaseItems.databaseId, args.database.id),
-              eq(schema.documents.id, args.parentId),
-              eq(schema.documents.spaceId, args.database.spaceId),
-              isNull(schema.documents.trashedAt),
-              accessFilter(
-                schema.documents,
-                schema.documentShares,
-                accessContext,
-              ),
-              ...softDeletedDatabaseDocumentExclusions(schema.documents.id),
-            ),
-          )
-          .limit(1),
-  ]);
+  const overrides = args.overrides;
   const sharedConfig = parseDatabaseViewConfig(args.database.viewConfigJson);
   const viewId =
     args.viewId ?? overrides?.activeViewId ?? sharedConfig.activeViewId;
@@ -411,11 +393,16 @@ export async function getContentDatabaseNavigationPage(args: {
       descending,
     }),
   ]);
-  if (parentRows && parentRows.length === 0) {
-    fail("The Files navigation parent is unavailable.", {
-      errorCode: "invalid_navigation_parent",
-      statusCode: 400,
-    });
+  if (
+    cursor &&
+    (cursor.databaseId !== args.database.id ||
+      cursor.parentId !== args.parentId ||
+      cursor.sort !== effectiveSort ||
+      cursor.viewId !== viewId ||
+      cursor.orderHash !== orderHash ||
+      cursor.configHash !== configHash)
+  ) {
+    invalidCursor();
   }
 
   const definitionById = await navigationFilterDefinitions(
@@ -435,37 +422,32 @@ export async function getContentDatabaseNavigationPage(args: {
       updatedAt: sql`${schema.documents.updatedAt}`,
     },
   });
-  if (
-    cursor &&
-    (cursor.databaseId !== args.database.id ||
-      cursor.parentId !== args.parentId ||
-      cursor.sort !== effectiveSort ||
-      cursor.viewId !== viewId ||
-      cursor.orderHash !== orderHash ||
-      cursor.configHash !== configHash)
-  ) {
-    invalidCursor();
-  }
 
   const childDocuments = alias(schema.documents, "navigation_child_documents");
   const childItems = alias(
     schema.contentDatabaseItems,
     "navigation_child_memberships",
   );
+  const favoriteItems = alias(
+    schema.contentDatabaseItems,
+    "navigation_favorite_memberships",
+  );
+  const roleShares = alias(schema.documentShares, "navigation_role_shares");
   const databaseDocuments = alias(
     schema.contentDatabases,
     "navigation_database_documents",
   );
-  const siblingFilter = and(
-    eq(schema.contentDatabaseItems.databaseId, args.database.id),
-    args.parentId === null
-      ? isNull(schema.documents.parentId)
-      : eq(schema.documents.parentId, args.parentId),
-    isNull(schema.documents.trashedAt),
-    accessFilter(schema.documents, schema.documentShares, accessContext),
-    ...softDeletedDatabaseDocumentExclusions(schema.documents.id),
-    effectiveFilter,
-  );
+  const siblingsOf = (parentId: string | null) =>
+    and(
+      eq(schema.contentDatabaseItems.databaseId, args.database.id),
+      parentId === null
+        ? isNull(schema.documents.parentId)
+        : eq(schema.documents.parentId, parentId),
+      isNull(schema.documents.trashedAt),
+      accessFilter(schema.documents, schema.documentShares, accessContext),
+      ...softDeletedDatabaseDocumentExclusions(schema.documents.id),
+      effectiveFilter,
+    );
   const accessRevision = sql<string>`coalesce((
     SELECT string_agg(ds.role || ':' || ds.principal_type || ':' || ds.principal_id, ',' ORDER BY ds.role, ds.principal_type, ds.principal_id)
     FROM document_shares ds
@@ -490,6 +472,72 @@ export async function getContentDatabaseNavigationPage(args: {
         isNull(databaseDocuments.deletedAt),
       ),
     );
+  const visibleChild = db
+    .select({ id: childItems.id })
+    .from(childItems)
+    .innerJoin(childDocuments, eq(childDocuments.id, childItems.documentId))
+    .where(
+      and(
+        eq(childItems.databaseId, args.database.id),
+        eq(childDocuments.parentId, schema.documents.id),
+        isNull(childDocuments.trashedAt),
+        accessFilter(childDocuments, schema.documentShares, accessContext),
+        ...softDeletedDatabaseDocumentExclusions(childDocuments.id),
+        navigationFilterSql({
+          filters: effectiveFilters,
+          filterMode: effectiveFilterMode,
+          definitionById,
+          document: {
+            id: sql`${childDocuments.id}`,
+            title: sql`${childDocuments.title}`,
+            parentId: sql`${childDocuments.parentId}`,
+            ownerEmail: sql`${childDocuments.ownerEmail}`,
+            createdAt: sql`${childDocuments.createdAt}`,
+            updatedAt: sql`${childDocuments.updatedAt}`,
+          },
+        }),
+      ),
+    );
+  const favoriteMembership = db
+    .select({ id: favoriteItems.id })
+    .from(favoriteItems)
+    .where(
+      and(
+        eq(
+          favoriteItems.databaseId,
+          favoritesSystemIds(args.userEmail).databaseId,
+        ),
+        eq(favoriteItems.documentId, schema.documents.id),
+      ),
+    );
+  const sharedWithRole = (roles: Array<"admin" | "editor">) =>
+    db
+      .select({ id: roleShares.id })
+      .from(roleShares)
+      .where(
+        and(
+          eq(roleShares.resourceId, schema.documents.id),
+          or(
+            inArray(roleShares.role, roles),
+            // Legacy share rows can carry `owner` even though new writes use ShareRole.
+            sql`${roleShares.role} = 'owner'`,
+          ),
+          or(
+            and(
+              eq(roleShares.principalType, "user"),
+              eq(roleShares.principalId, args.userEmail),
+            ),
+            args.database.orgId
+              ? and(
+                  eq(roleShares.principalType, "org"),
+                  eq(roleShares.principalId, args.database.orgId),
+                )
+              : undefined,
+          ),
+        ),
+      );
+  // The per-row lookups below are subqueries in the select list, so Postgres
+  // runs them only for the rows the page returns, after its sort and limit.
   const rowFields = {
     membershipId: schema.contentDatabaseItems.id,
     membershipPosition: schema.contentDatabaseItems.position,
@@ -505,25 +553,125 @@ export async function getContentDatabaseNavigationPage(args: {
     type: sql<"page" | "database">`CASE WHEN ${exists(
       activeDatabaseDocument,
     )} THEN 'database' ELSE 'page' END`,
+    hasChildren: sql<boolean>`${exists(visibleChild)}`,
+    isFavorite: sql<boolean>`${exists(favoriteMembership)}`,
+    sharedEditor: sql<boolean>`${exists(sharedWithRole(["admin", "editor"]))}`,
+    sharedManager: sql<boolean>`${exists(sharedWithRole(["admin"]))}`,
     rowHash: sql<string>`${rowHash}::text`,
   };
+  const membershipRows = (where: SQL | undefined) =>
+    db
+      .select(rowFields)
+      .from(schema.contentDatabaseItems)
+      .innerJoin(
+        schema.documents,
+        eq(schema.documents.id, schema.contentDatabaseItems.documentId),
+      )
+      .where(where);
+  type NavigationRow = Awaited<ReturnType<typeof membershipRows>>[number] & {
+    sortValue: string | number;
+  };
+
+  // A cursor stays valid while every visible sibling up to it is unchanged:
+  // rows after it are read fresh by the next page anyway. The revision is the
+  // count and hash sum of that prefix, so it grows with the pages read, not
+  // with the workspace.
+  const revisionOf = async (
+    query: Promise<Array<{ count: number; checksum: string }>>,
+  ): Promise<NavigationRevision> => {
+    const [row] = await query;
+    return { count: row?.count ?? 0, checksum: BigInt(row?.checksum ?? "0") };
+  };
+  const revisionFields = {
+    count: sql<number>`count(*)::int`,
+    checksum: sql<string>`coalesce(sum((${rowHash})::numeric), 0)::text`,
+  };
+  const membershipRevision = (where: SQL | undefined) =>
+    db
+      .select(revisionFields)
+      .from(schema.contentDatabaseItems)
+      .innerJoin(
+        schema.documents,
+        eq(schema.documents.id, schema.contentDatabaseItems.documentId),
+      )
+      .where(where);
+
+  type NavigationOrder = {
+    page: (
+      siblings: SQL | undefined,
+      after: NavigationCursor | null,
+    ) => Promise<NavigationRow[]>;
+    through: (
+      siblings: SQL | undefined,
+      cursor: NavigationCursor,
+    ) => Promise<NavigationRevision[]>;
+  };
+
+  const sortValue: SQL<string> =
+    effectiveSort === "name"
+      ? sql<string>`${schema.documents.title}`
+      : effectiveSort === "created"
+        ? sql<string>`${schema.documents.createdAt}`
+        : sql<string>`${schema.documents.updatedAt}`;
+  const ascending = !descending;
+  const sortedAfter = (key: { sortValue: string | number; itemId: string }) =>
+    or(
+      ascending ? gt(sortValue, key.sortValue) : lt(sortValue, key.sortValue),
+      and(
+        eq(sortValue, key.sortValue),
+        gt(schema.contentDatabaseItems.id, key.itemId),
+      ),
+    );
+  const sortedOrder: NavigationOrder = {
+    page: (siblings, after) =>
+      db
+        .select({ ...rowFields, sortValue })
+        .from(schema.contentDatabaseItems)
+        .innerJoin(
+          schema.documents,
+          eq(schema.documents.id, schema.contentDatabaseItems.documentId),
+        )
+        .where(and(siblings, after ? sortedAfter(after) : undefined))
+        .orderBy(
+          ascending ? asc(sortValue) : desc(sortValue),
+          asc(schema.contentDatabaseItems.id),
+        )
+        .limit(args.limit + 1),
+    through: (siblings, cursor) =>
+      Promise.all([
+        revisionOf(
+          membershipRevision(
+            and(
+              siblings,
+              ascending
+                ? lte(sortValue, cursor.sortValue)
+                : gte(sortValue, cursor.sortValue),
+              sql`not (${sortedAfter(cursor)!})`,
+            ),
+          ),
+        ),
+      ]),
+  };
 
   // Custom order puts the saved item IDs first, in saved order, and the rest
-  // after them by position. The ranked page walks the saved list in order
-  // through primary-key lookups; the unranked page walks the
-  // (database_id, position, id) index. Neither sorts the whole Files database.
+  // after them by position.
   const rankById = new Map<string, number>();
   itemIds.forEach((itemId, index) => {
     if (!rankById.has(itemId)) rankById.set(itemId, index + 1);
   });
   const unrankedValue = itemIds.length + 1;
+  const allRanks = [...rankById];
+
+  // The root holds most of a workspace, and a saved order mostly lists root
+  // items, so the root walks the saved list in order through primary-key
+  // lookups and the unranked rest through the (database_id, position, id)
+  // index. Neither sorts the whole Files database.
   const savedRanks = (ranks: Array<[string, number]>) =>
     sql`jsonb_to_recordset(${JSON.stringify(
       ranks.map(([itemId, rank]) => ({ item_id: itemId, rank })),
     )}::jsonb) as saved_rank(item_id text, rank integer)`;
   const rankedSource = (ranks: Array<[string, number]>) =>
     sql`(select item_id, rank from ${savedRanks(ranks)} order by rank) as navigation_rank`;
-  const allRanks = [...rankById];
   // NOT IN over a subquery is a hashed lookup; NOT EXISTS here would rescan
   // the saved list for every candidate row.
   const notRanked = allRanks.length
@@ -541,117 +689,133 @@ export async function getContentDatabaseNavigationPage(args: {
         schema.documents,
         eq(schema.documents.id, schema.contentDatabaseItems.documentId),
       );
-  const unrankedRows = () =>
-    db
-      .select(rowFields)
-      .from(schema.contentDatabaseItems)
-      .innerJoin(
-        schema.documents,
-        eq(schema.documents.id, schema.contentDatabaseItems.documentId),
-      );
-  const sortValue: SQL<string> =
-    effectiveSort === "name"
-      ? sql<string>`${schema.documents.title}`
-      : effectiveSort === "created"
-        ? sql<string>`${schema.documents.createdAt}`
-        : sql<string>`${schema.documents.updatedAt}`;
-  const ascending = !descending;
-  const sortedAfter = (key: { sortValue: string | number; itemId: string }) =>
-    or(
-      ascending ? gt(sortValue, key.sortValue) : lt(sortValue, key.sortValue),
-      and(
-        eq(sortValue, key.sortValue),
-        gt(schema.contentDatabaseItems.id, key.itemId),
-      ),
-    );
+  const positionAfter = (key: { position?: number; itemId: string }) =>
+    sql`(${schema.contentDatabaseItems.position}, ${schema.contentDatabaseItems.id}) > (${key.position!}, ${key.itemId})`;
   const positionThrough = (key: { position?: number; itemId: string }) =>
     sql`(${schema.contentDatabaseItems.position}, ${schema.contentDatabaseItems.id}) <= (${key.position!}, ${key.itemId})`;
-
-  let rows: Array<
-    Awaited<ReturnType<typeof unrankedRows>>[number] & {
-      sortValue: string | number;
-    }
-  >;
-  if (effectiveSort === "custom") {
-    const cursorRank = cursor ? Number(cursor.sortValue) : 0;
-    const rankedAfterCursor = allRanks.filter(([, rank]) => rank > cursorRank);
-    const rankedPage = (ranks: Array<[string, number]>) =>
-      ranks.length
-        ? rankedRows(ranks)
-            .where(siblingFilter)
-            .orderBy(sql`navigation_rank.rank`)
-            .limit(args.limit + 1)
-        : Promise.resolve([]);
-    // A saved order can hold thousands of IDs, but a page usually fills from
-    // the first few, so the whole list is only sent when that window falls
-    // short. Rows past the last saved sibling come from the unranked side.
-    const window = rankedAfterCursor.slice(0, (args.limit + 1) * 4);
-    let ranked = await rankedPage(window);
-    let unranked: Awaited<ReturnType<typeof unrankedRows>> = [];
-    if (ranked.length <= args.limit) {
-      const [rest, tail] = await Promise.all([
-        rankedPage(rankedAfterCursor.slice(window.length)),
-        unrankedRows()
-          .where(
+  const savedListOrder: NavigationOrder = {
+    page: async (siblings, after) => {
+      const cursorRank = after ? Number(after.sortValue) : 0;
+      const rankedAfterCursor = allRanks.filter(
+        ([, rank]) => rank > cursorRank,
+      );
+      const rankedPage = (ranks: Array<[string, number]>) =>
+        ranks.length
+          ? rankedRows(ranks)
+              .where(siblings)
+              .orderBy(sql`navigation_rank.rank`)
+              .limit(args.limit + 1)
+          : Promise.resolve([]);
+      // A saved order can hold thousands of IDs, but a page usually fills
+      // from the first few, so the whole list is only sent when that window
+      // falls short. Rows past the last saved sibling come from the unranked
+      // side.
+      const window = rankedAfterCursor.slice(0, (args.limit + 1) * 4);
+      let ranked = await rankedPage(window);
+      let unranked: Awaited<ReturnType<typeof membershipRows>> = [];
+      if (ranked.length <= args.limit) {
+        const [rest, tail] = await Promise.all([
+          rankedPage(rankedAfterCursor.slice(window.length)),
+          membershipRows(
             and(
-              siblingFilter,
+              siblings,
               notRanked,
-              cursor && cursorRank === unrankedValue
-                ? sql`(${schema.contentDatabaseItems.position}, ${schema.contentDatabaseItems.id}) > (${cursor.position!}, ${cursor.itemId})`
+              after && cursorRank === unrankedValue
+                ? positionAfter(after)
                 : undefined,
             ),
           )
-          .orderBy(
-            asc(schema.contentDatabaseItems.position),
-            asc(schema.contentDatabaseItems.id),
-          )
-          .limit(args.limit + 1),
+            .orderBy(
+              asc(schema.contentDatabaseItems.position),
+              asc(schema.contentDatabaseItems.id),
+            )
+            .limit(args.limit + 1),
+        ]);
+        ranked = [...ranked, ...rest].slice(0, args.limit + 1);
+        unranked = tail.slice(0, args.limit + 1 - ranked.length);
+      }
+      return [
+        ...ranked,
+        ...unranked.map((row) => ({ ...row, sortValue: unrankedValue })),
+      ];
+    },
+    through: (siblings, cursor) => {
+      const cursorRank = Number(cursor.sortValue);
+      const ranksThrough = allRanks.filter(([, rank]) => rank <= cursorRank);
+      return Promise.all([
+        ...(ranksThrough.length
+          ? [
+              revisionOf(
+                db
+                  .select(revisionFields)
+                  .from(rankedSource(ranksThrough))
+                  .innerJoin(
+                    schema.contentDatabaseItems,
+                    eq(
+                      schema.contentDatabaseItems.id,
+                      sql`navigation_rank.item_id`,
+                    ),
+                  )
+                  .innerJoin(
+                    schema.documents,
+                    eq(
+                      schema.documents.id,
+                      schema.contentDatabaseItems.documentId,
+                    ),
+                  )
+                  .where(siblings),
+              ),
+            ]
+          : []),
+        ...(cursorRank === unrankedValue
+          ? [
+              revisionOf(
+                membershipRevision(
+                  and(siblings, notRanked, positionThrough(cursor)),
+                ),
+              ),
+            ]
+          : []),
       ]);
-      ranked = [...ranked, ...rest].slice(0, args.limit + 1);
-      unranked = tail.slice(0, args.limit + 1 - ranked.length);
-    }
-    rows = [
-      ...ranked,
-      ...unranked.map((row) => ({ ...row, sortValue: unrankedValue })),
-    ];
-  } else {
-    rows = await db
-      .select({ ...rowFields, sortValue })
-      .from(schema.contentDatabaseItems)
-      .innerJoin(
-        schema.documents,
-        eq(schema.documents.id, schema.contentDatabaseItems.documentId),
-      )
-      .where(and(siblingFilter, cursor ? sortedAfter(cursor) : undefined))
-      .orderBy(
-        ascending ? asc(sortValue) : desc(sortValue),
-        asc(schema.contentDatabaseItems.id),
-      )
-      .limit(args.limit + 1);
-  }
-
-  const hasMore = rows.length > args.limit;
-  const pageRows = rows.slice(0, args.limit);
-  const pageDocumentIds = pageRows.map((row) => row.documentId);
-
-  // A cursor stays valid while every visible sibling up to it is unchanged:
-  // rows after it are read fresh by the next page anyway. The revision is the
-  // count and hash sum of that prefix, so it grows with the pages read, not
-  // with the workspace.
-  const revisionOf = async (
-    query: Promise<Array<{ count: number; checksum: string }>>,
-  ): Promise<NavigationRevision> => {
-    const [row] = await query;
-    return { count: row?.count ?? 0, checksum: BigInt(row?.checksum ?? "0") };
-  };
-  const revisionFields = {
-    count: sql<number>`count(*)::int`,
-    checksum: sql<string>`coalesce(sum((${rowHash})::numeric), 0)::text`,
+    },
   };
-  const cursorPrefixRevision = (): Promise<NavigationRevision[]> => {
-    if (!cursor) return Promise.resolve([]);
-    if (effectiveSort !== "custom") {
-      return Promise.all([
+
+  // A folder's own children are found through the parent_id index, so a
+  // child branch ranks just those rows by looking each one up in the saved
+  // order, instead of walking a saved list that mostly holds other branches.
+  // The order is one jsonb object bound once; a joined set of saved IDs would
+  // be estimated at 100 rows and planned as a rescan per sibling.
+  const savedOrder = sql`(select ${JSON.stringify(
+    Object.fromEntries(rankById),
+  )}::jsonb as ranks) as navigation_saved_order`;
+  const siblingRank = sql<number>`coalesce((navigation_saved_order.ranks ->> ${schema.contentDatabaseItems.id})::int, ${unrankedValue})`;
+  const siblingKey = sql`(${siblingRank}, ${schema.contentDatabaseItems.position}, ${schema.contentDatabaseItems.id})`;
+  const cursorKey = (key: NavigationCursor) =>
+    sql`(${Number(key.sortValue)}, ${key.position!}, ${key.itemId})`;
+  const siblingRankOrder: NavigationOrder = {
+    page: (siblings, after) =>
+      db
+        .select({ ...rowFields, sortValue: siblingRank })
+        .from(schema.contentDatabaseItems)
+        .innerJoin(
+          schema.documents,
+          eq(schema.documents.id, schema.contentDatabaseItems.documentId),
+        )
+        .innerJoin(savedOrder, sql`true`)
+        .where(
+          and(
+            siblings,
+            after ? sql`${siblingKey} > ${cursorKey(after)}` : undefined,
+          ),
+        )
+        .orderBy(
+          siblingRank,
+          asc(schema.contentDatabaseItems.position),
+          asc(schema.contentDatabaseItems.id),
+        )
+        .limit(args.limit + 1),
+    through: (siblings, cursor) =>
+      Promise.all([
         revisionOf(
           db
             .select(revisionFields)
@@ -660,195 +824,210 @@ export async function getContentDatabaseNavigationPage(args: {
               schema.documents,
               eq(schema.documents.id, schema.contentDatabaseItems.documentId),
             )
-            .where(
-              and(
-                siblingFilter,
-                ascending
-                  ? lte(sortValue, cursor.sortValue)
-                  : gte(sortValue, cursor.sortValue),
-                sql`not (${sortedAfter(cursor)!})`,
-              ),
-            ),
+            .innerJoin(savedOrder, sql`true`)
+            .where(and(siblings, sql`${siblingKey} <= ${cursorKey(cursor)}`)),
         ),
-      ]);
-    }
-    const cursorRank = Number(cursor.sortValue);
-    const ranksThrough = allRanks.filter(([, rank]) => rank <= cursorRank);
-    return Promise.all([
-      ...(ranksThrough.length
-        ? [
-            revisionOf(
-              db
-                .select(revisionFields)
-                .from(rankedSource(ranksThrough))
-                .innerJoin(
-                  schema.contentDatabaseItems,
-                  eq(
-                    schema.contentDatabaseItems.id,
-                    sql`navigation_rank.item_id`,
-                  ),
-                )
-                .innerJoin(
-                  schema.documents,
-                  eq(
-                    schema.documents.id,
-                    schema.contentDatabaseItems.documentId,
-                  ),
-                )
-                .where(siblingFilter),
-            ),
-          ]
-        : []),
-      ...(cursorRank === unrankedValue
-        ? [
-            revisionOf(
-              db
-                .select(revisionFields)
-                .from(schema.contentDatabaseItems)
-                .innerJoin(
-                  schema.documents,
-                  eq(
-                    schema.documents.id,
-                    schema.contentDatabaseItems.documentId,
-                  ),
-                )
-                .where(and(siblingFilter, notRanked, positionThrough(cursor))),
-            ),
-          ]
-        : []),
-    ]);
+      ]),
   };
 
-  const [favoriteIds, shareRows, parentsWithChildren, prefixRevision] =
-    await Promise.all([
-      favoriteDocumentIds(db, args.userEmail, pageDocumentIds),
-      pageRows.length
-        ? db
-            .select({
-              resourceId: schema.documentShares.resourceId,
-              role: schema.documentShares.role,
-            })
-            .from(schema.documentShares)
-            .where(
-              and(
-                inArray(schema.documentShares.resourceId, pageDocumentIds),
-                or(
-                  and(
-                    eq(schema.documentShares.principalType, "user"),
-                    eq(schema.documentShares.principalId, args.userEmail),
-                  ),
-                  ...(args.database.orgId
-                    ? [
-                        and(
-                          eq(schema.documentShares.principalType, "org"),
-                          eq(
-                            schema.documentShares.principalId,
-                            args.database.orgId,
-                          ),
-                        ),
-                      ]
-                    : []),
-                ),
-              ),
-            )
-        : [],
-      pageRows.length
-        ? db
-            .selectDistinct({ parentId: childDocuments.parentId })
-            .from(childItems)
-            .innerJoin(
-              childDocuments,
-              eq(childDocuments.id, childItems.documentId),
-            )
-            .where(
-              and(
-                eq(childItems.databaseId, args.database.id),
-                inArray(childDocuments.parentId, pageDocumentIds),
-                isNull(childDocuments.trashedAt),
-                accessFilter(
-                  childDocuments,
-                  schema.documentShares,
-                  accessContext,
-                ),
-                ...softDeletedDatabaseDocumentExclusions(childDocuments.id),
-                navigationFilterSql({
-                  filters: effectiveFilters,
-                  filterMode: effectiveFilterMode,
-                  definitionById,
-                  document: {
-                    id: sql`${childDocuments.id}`,
-                    title: sql`${childDocuments.title}`,
-                    parentId: sql`${childDocuments.parentId}`,
-                    ownerEmail: sql`${childDocuments.ownerEmail}`,
-                    createdAt: sql`${childDocuments.createdAt}`,
-                    updatedAt: sql`${childDocuments.updatedAt}`,
+  const readBranch = async (
+    parentId: string | null,
+    after: NavigationCursor | null,
+  ): Promise<ContentDatabaseNavigationPage> => {
+    const order =
+      effectiveSort !== "custom"
+        ? sortedOrder
+        : parentId === null
+          ? savedListOrder
+          : siblingRankOrder;
+    const siblings = siblingsOf(parentId);
+    const [rows, prefixRevision] = await Promise.all([
+      order.page(siblings, after),
+      after ? order.through(siblings, after) : [],
+    ]);
+    if (after && combineRevisions(prefixRevision) !== after.revision) {
+      invalidCursor();
+    }
+    const hasMore = rows.length > args.limit;
+    const pageRows = rows.slice(0, args.limit);
+    const last = pageRows[pageRows.length - 1];
+    return {
+      items: pageRows.map(
+        ({
+          sortValue: _sortValue,
+          rowHash: _rowHash,
+          ownerEmail,
+          sharedEditor,
+          sharedManager,
+          ...row
+        }) => {
+          const isOwner =
+            ownerEmail.toLowerCase() === args.userEmail.toLowerCase();
+          return {
+            ...row,
+            canEdit: isOwner || sharedEditor,
+            canManage: isOwner || sharedManager,
+          };
+        },
+      ),
+      pagination: {
+        limit: args.limit,
+        hasMore,
+        nextCursor:
+          hasMore && last
+            ? encodeCursor({
+                version: CURSOR_VERSION,
+                databaseId: args.database.id,
+                parentId,
+                sort: effectiveSort,
+                viewId,
+                orderHash,
+                revision: combineRevisions([
+                  ...prefixRevision,
+                  {
+                    count: pageRows.length,
+                    checksum: pageRows.reduce(
+                      (total, row) => total + BigInt(row.rowHash),
+                      0n,
+                    ),
                   },
-                }),
+                ]),
+                configHash,
+                sortValue: last.sortValue,
+                position:
+                  effectiveSort === "custom"
+                    ? last.membershipPosition
+                    : undefined,
+                itemId: last.membershipId,
+              })
+            : null,
+      },
+    };
+  };
+
+  // The requested parent and the expanded folders pass the same access,
+  // trash, and deletion checks before any of their children are read.
+  const checkedIds = [
+    ...(args.parentId === null ? [] : [args.parentId]),
+    ...new Set(args.expand),
+  ];
+  const checked =
+    checkedIds.length === 0
+      ? Promise.resolve([])
+      : db
+          .select({
+            id: schema.documents.id,
+            parentId: schema.documents.parentId,
+          })
+          .from(schema.contentDatabaseItems)
+          .innerJoin(
+            schema.documents,
+            eq(schema.documents.id, schema.contentDatabaseItems.documentId),
+          )
+          .where(
+            and(
+              eq(schema.contentDatabaseItems.databaseId, args.database.id),
+              inArray(schema.documents.id, checkedIds),
+              eq(schema.documents.spaceId, args.database.spaceId),
+              isNull(schema.documents.trashedAt),
+              accessFilter(
+                schema.documents,
+                schema.documentShares,
+                accessContext,
               ),
-            )
-        : [],
-      cursorPrefixRevision(),
-    ]);
-  if (cursor && combineRevisions(prefixRevision) !== cursor.revision) {
-    invalidCursor();
+              ...softDeletedDatabaseDocumentExclusions(schema.documents.id),
+            ),
+          );
+  const pageRead = readBranch(args.parentId, cursor);
+  const parentFound = (rows: Array<{ id: string }>) =>
+    args.parentId === null || rows.some((row) => row.id === args.parentId);
+
+  // Expanded folders under the requested parent return their first pages
+  // with it. Which ones open follows from the checked parent links alone, so
+  // every branch reads alongside the page instead of one level per query. A
+  // first page also opens expanded folders that are not on it: the sidebar
+  // shows the open page's ancestors under their parent's first page wherever
+  // they sort.
+  const branchReads = checked.then(async (rows) => {
+    if (!parentFound(rows)) return { branches: [], truncated: false };
+    const expand = new Set(args.expand);
+    const parentOf = new Map<string, string | null>();
+    const expandedChildren = new Map<string | null, string[]>();
+    for (const row of rows) {
+      if (!expand.has(row.id)) continue;
+      parentOf.set(row.id, row.parentId);
+      const siblings = expandedChildren.get(row.parentId) ?? [];
+      siblings.push(row.id);
+      expandedChildren.set(row.parentId, siblings);
+    }
+    let level = expandedChildren.get(args.parentId) ?? [];
+    if (cursor && level.length > 0) {
+      const listed = new Set(
+        (await pageRead).items.map((item) => item.documentId),
+      );
+      level = level.filter((documentId) => listed.has(documentId));
+    }
+    // Stored parent links can form a cycle through the requested parent, so
+    // a folder is reached once and the parent itself never opens.
+    const reachable = new Set<string>();
+    while (level.length > 0) {
+      for (const documentId of level) reachable.add(documentId);
+      level = level.flatMap((documentId) =>
+        (expandedChildren.get(documentId) ?? []).filter(
+          (child) => child !== args.parentId && !reachable.has(child),
+        ),
+      );
+    }
+    // The cap keeps folders in the order the caller asked for them, each with
+    // the open folders above it, so the open page's ancestors, asked for
+    // first, are not cut for breadth.
+    const opened = new Set<string>();
+    for (const documentId of args.expand ?? []) {
+      const chain: string[] = [];
+      for (
+        let id: string | null | undefined = documentId;
+        typeof id === "string" && reachable.has(id) && !opened.has(id);
+        id = parentOf.get(id)
+      ) {
+        chain.push(id);
+      }
+      if (opened.size + chain.length > MAX_NAVIGATION_EXPANDED_BRANCHES) {
+        continue;
+      }
+      for (const id of chain) opened.add(id);
+    }
+    const openedIds = [...opened];
+    const pages = await Promise.all(
+      openedIds.map((documentId) => readBranch(documentId, null)),
+    );
+    return {
+      // A folder with no children the caller can see draws no branch.
+      branches: openedIds.flatMap((documentId, index) =>
+        pages[index]!.items.length > 0
+          ? [[documentId, pages[index]!] as const]
+          : [],
+      ),
+      truncated: opened.size < reachable.size,
+    };
+  });
+
+  const [checkedRows, page, expanded] = await Promise.all([
+    checked,
+    pageRead,
+    branchReads,
+  ]);
+  if (!parentFound(checkedRows)) {
+    fail("The Files navigation parent is unavailable.", {
+      errorCode: "invalid_navigation_parent",
+      statusCode: 400,
+    });
   }
-  const withChildren = new Set(parentsWithChildren.map((row) => row.parentId));
-  const editableIds = new Set(
-    shareRows
-      .filter((row) => ["owner", "admin", "editor"].includes(row.role))
-      .map((row) => row.resourceId),
-  );
-  const manageableIds = new Set(
-    shareRows
-      .filter((row) => ["owner", "admin"].includes(row.role))
-      .map((row) => row.resourceId),
-  );
-  const last = pageRows[pageRows.length - 1];
+  if (!args.expand?.length) return page;
   return {
-    items: pageRows.map(
-      ({ sortValue: _sortValue, rowHash: _rowHash, ownerEmail, ...row }) => {
-        const isOwner =
-          ownerEmail.toLowerCase() === args.userEmail.toLowerCase();
-        return {
-          ...row,
-          hasChildren: withChildren.has(row.documentId),
-          isFavorite: favoriteIds.has(row.documentId),
-          canEdit: isOwner || editableIds.has(row.documentId),
-          canManage: isOwner || manageableIds.has(row.documentId),
-        };
-      },
-    ),
-    pagination: {
-      limit: args.limit,
-      hasMore,
-      nextCursor:
-        hasMore && last
-          ? encodeCursor({
-              version: CURSOR_VERSION,
-              databaseId: args.database.id,
-              parentId: args.parentId,
-              sort: effectiveSort,
-              viewId,
-              orderHash,
-              revision: combineRevisions([
-                ...prefixRevision,
-                {
-                  count: pageRows.length,
-                  checksum: pageRows.reduce(
-                    (total, row) => total + BigInt(row.rowHash),
-                    0n,
-                  ),
-                },
-              ]),
-              configHash,
-              sortValue: last.sortValue,
-              position:
-                effectiveSort === "custom"
-                  ? last.membershipPosition
-                  : undefined,
-              itemId: last.membershipId,
-            })
-          : null,
-    },
+    ...page,
+    ...(expanded.branches.length > 0
+      ? { branches: Object.fromEntries(expanded.branches) }
+      : {}),
+    branchesTruncated: expanded.truncated,
   };
 }