@@ -1,5 +1,6 @@
 import {
   createWorkspaceFileContract,
+  DEFAULT_WORKSPACE_FILE_PAGE_SIZE,
   listWorkspaceFilesContract,
   WORKSPACE_FILE_PAGE_PARAMS,
 } from '@/lib/api/contracts/workspace-files'
@@ -24,8 +25,6 @@ import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { MAX_WORKSPACE_FILE_INLINE_BODY_BYTES } from '@/lib/workspace-files/orchestration'
 import { readSortedCursor, writeSortedCursor } from '@/app/api/v2/lib/response'
 
-const DEFAULT_WORKSPACE_FILE_PAGE_SIZE = 100
-
 export const dynamic = 'force-dynamic'
 
 /** Every param that changes which files, in which order, a page walk returns. */
@@ -35,7 +34,7 @@ function fileCursorFilters(
 ) {
   return cursorScopeKey(cursorRoute(listWorkspaceFilesContract, { id: workspaceId }), {
     scope: query.scope,
-    folderId: query.folderId === null ? 'root' : query.folderId,
+    folderId: query.folderId,
   })
 }
 
@@ -47,6 +46,8 @@ export const GET = defineInternalJsonRoute({
   contract: listWorkspaceFilesContract,
   auth: internalSessionAuth,
   operation: fileOperations.list,
+  // One policy per route: paged requests share the unpaged list's exemption until the builder
+  // can choose a policy per request.
   rateLimit: internalRateLimits.none({ reason: 'Preserve existing internal file-list behavior' }),
   errorPolicy: internalFileErrorPolicies.default,
   mapInput: ({ params, query }) => {
 
@@ -10,6 +10,9 @@ import { fileOperations } from '@/lib/workspace-files/application/operations'
 
 export const dynamic = 'force-dynamic'
 
+/** Sized for debounced type-ahead: a burst while typing, about two searches a second sustained. */
+const SEARCH_TYPE_AHEAD_LIMIT = { maxTokens: 120, refillRate: 120, refillIntervalMs: 60_000 }
+
 /**
  * GET /api/workspaces/[id]/files/search — live files whose name contains `q`, by name, each
  * carrying its `folderPath`; within `folderId` (and, by default, its subfolders) when given.
@@ -18,7 +21,10 @@ export const GET = defineInternalJsonRoute({
   contract: searchWorkspaceFilesContract,
   auth: internalSessionAuth,
   operation: fileOperations.list,
-  rateLimit: internalRateLimits.user({ bucketName: 'workspace-files.read' }),
+  rateLimit: internalRateLimits.user({
+    bucketName: 'workspace-files.search',
+    config: SEARCH_TYPE_AHEAD_LIMIT,
+  }),
   errorPolicy: internalFileErrorPolicies.default,
   mapInput: ({ params, query }) => ({
     workspaceId: params.id,
 
@@ -10,7 +10,7 @@ import {
 } from '@/lib/api/contracts/primitives'
 import { shareRecordSchema } from '@/lib/api/contracts/public-shares'
 import { defineRouteContract } from '@/lib/api/contracts/types'
-import { V2_SEARCH_MAX_LENGTH } from '@/lib/api/contracts/v2/shared'
+import { V2_SEARCH_MAX_LENGTH, v2LimitSchema } from '@/lib/api/contracts/v2/shared'
 import { LIST_SORT_ORDERS } from '@/lib/api/list-query'
 
 /**
@@ -35,6 +35,9 @@ const WORKSPACE_FILE_SORT_FIELDS = ['name', 'size', 'uploadedAt', 'updatedAt'] a
 /** The largest page `GET /api/workspaces/[id]/files` serves when paging. */
 const MAX_WORKSPACE_FILE_PAGE_SIZE = 500
 
+/** The page size a paged list request that omits `limit` gets. */
+export const DEFAULT_WORKSPACE_FILE_PAGE_SIZE = 100
+
 /** A folder filter in the browser's addressing: `root` for the workspace root, else a folder id. */
 const workspaceFileFolderFilterSchema = z
   .union([z.literal('root'), folderIdSchema])
@@ -209,8 +212,12 @@ const workspaceFileSuccessSchema = z.object({
   success: z.boolean(),
 })
 
-const listWorkspaceFilesResponseSchema = workspaceFileSuccessSchema.extend({
+/** The body every file-list read answers with. */
+const workspaceFilesResponseSchema = workspaceFileSuccessSchema.extend({
   files: z.array(workspaceFileRecordSchema),
+})
+
+const listWorkspaceFilesResponseSchema = workspaceFilesResponseSchema.extend({
   /** Present only on a paged request: the next page's cursor, `null` on the last page. */
   nextCursor: z.string().nullable().optional(),
 })
@@ -234,41 +241,33 @@ export const listWorkspaceFilesContract = defineRouteContract({
   },
 })
 
-const MAX_WORKSPACE_FILE_SEARCH_RESULTS = 50
-
 const searchWorkspaceFilesQuerySchema = z.object({
+  /**
+   * A term of one or two characters holds no trigram, so it cannot use the name index and
+   * scans the workspace's live files; three or more probe `workspace_files_workspace_name_trgm_idx`.
+   */
   q: z.string().trim().min(1, 'q cannot be empty').max(V2_SEARCH_MAX_LENGTH, 'q is too long'),
   /** Confine the search to this folder (`root` for the workspace root). Omit to search everywhere. */
   folderId: workspaceFileFolderFilterSchema.optional(),
   /** Whether the folder's subfolders are searched too. Ignored without `folderId`. */
   recursive: booleanQueryFlagSchema.default(true),
-  limit: z.coerce
-    .number({ error: 'limit must be a number' })
-    .int('limit must be a whole number')
-    .min(1, 'limit must be at least 1')
-    .max(
-      MAX_WORKSPACE_FILE_SEARCH_RESULTS,
-      `limit cannot exceed ${MAX_WORKSPACE_FILE_SEARCH_RESULTS}`
-    )
-    .default(20),
+  limit: v2LimitSchema({ max: 50, fallback: 20, description: 'Maximum files to return.' }),
 })
 
-const searchWorkspaceFilesResponseSchema = workspaceFileSuccessSchema.extend({
-  /** Live files whose name contains `q` (case-insensitive), by name; each carries `folderPath`. */
-  files: z.array(workspaceFileRecordSchema),
-})
-
-/** GET — case-insensitive file-name search within a workspace, optionally within one folder. */
+/**
+ * GET — case-insensitive file-name search within a workspace, optionally within one folder:
+ * live files whose name contains `q`, by name, each carrying `folderPath`.
+ */
 export const searchWorkspaceFilesContract = defineRouteContract({
   method: 'GET',
   path: '/api/workspaces/[id]/files/search',
   params: workspaceFilesParamsSchema,
   query: searchWorkspaceFilesQuerySchema,
-  response: { mode: 'json', schema: searchWorkspaceFilesResponseSchema },
+  response: { mode: 'json', schema: workspaceFilesResponseSchema },
 })
 
 /** The most entries each of a lookup's `ids`, `keys`, and `references` may carry. */
-export const MAX_WORKSPACE_FILE_LOOKUP_ENTRIES = 100
+const MAX_WORKSPACE_FILE_LOOKUP_ENTRIES = 100
 
 const lookupEntriesSchema = (field: string) =>
   z
@@ -296,9 +295,8 @@ const lookupWorkspaceFilesBodySchema = z
     { message: 'Provide at least one id, key, or reference' }
   )
 
-const lookupWorkspaceFilesResponseSchema = workspaceFileSuccessSchema.extend({
-  /** Every live file any id, key, or reference resolved to, once each. Misses are absent. */
-  files: z.array(workspaceFileRecordSchema),
+/** `files` holds every live file any id, key, or reference resolved to, once each. */
+const lookupWorkspaceFilesResponseSchema = workspaceFilesResponseSchema.extend({
   /** Per requested reference, in request order (deduplicated): the file it resolved to, or `null`. */
   references: z.array(z.object({ reference: z.string(), fileId: z.string().nullable() })),
 })
 
@@ -235,6 +235,28 @@ export function preciseTimestampKey<Row>(
   }
 }
 
+/**
+ * A `timestamp` key that orders on the raw column, so an index on `(…, <column>, id)` serves
+ * both the order and the cursor seek, while still finishing a walk begun before that.
+ *
+ * A cursor minted under the millisecond {@link timestampKey} carries a date rather than the
+ * precise form (see {@link classifyTimestampCursor}) and was read under truncated ordering,
+ * where rows sharing a millisecond fall in `id` order rather than stored order. Resuming one
+ * under the raw ordering would skip or repeat rows inside that millisecond, so it keeps the
+ * truncated key it was minted under, and so does every cursor that page mints, until the walk
+ * ends. `readCursor` returns the row's {@link preciseTimestampText}.
+ */
+export function resumableTimestampKey<Row>(
+  column: Column,
+  read: (row: Row) => Date,
+  readCursor: (row: Row) => string,
+  cursorKeys: CursorKey[] | undefined
+): KeysetKey<Row> {
+  return cursorKeys !== undefined && classifyTimestampCursor(cursorKeys[0]) === 'date'
+    ? timestampKey(column, read)
+    : preciseTimestampKey(column, readCursor)
+}
+
 export function sortDirection(order: ListSortOrder): typeof asc {
   return order === 'asc' ? asc : desc
 }
 
@@ -23,11 +23,10 @@ import {
   type ListSortOrder,
   listOrderBy,
   numberKey,
-  preciseTimestampKey,
   preciseTimestampText,
+  resumableTimestampKey,
   resumeKeyset,
   textKey,
-  timestampKey,
 } from '@/lib/api/list-query'
 import { MATERIALIZE_CONCURRENCY } from '@/lib/core/utils/concurrency'
 import { MAX_DURABLE_LARGE_VALUE_BYTES } from '@/lib/execution/payloads/limits'
@@ -250,27 +249,22 @@ type PublicLogKeysetRow = Pick<
  * Both log tables are ordered by it, and both spell it identically, so the
  * merged sequence a unioned page returns resumes from one set of cursor keys.
  *
- * It orders on the raw column so the `(workspace_id, started_at)` and
- * `(workflow_id, started_at)` indexes serve the sort and a page reads only its
- * own rows. A cursor minted before that carries a date rather than the precise
- * form (see {@link classifyTimestampCursor}) and was read under
- * millisecond-truncated ordering, where rows sharing a millisecond
- * fall in `id` order rather than stored order. Resuming one under the raw
- * ordering would skip or repeat rows inside that millisecond, so it keeps the
- * truncated keyset it was minted under, and so does every cursor that page
- * mints, until the walk ends.
+ * It orders on the raw column (see {@link resumableTimestampKey}) so the
+ * `(workspace_id, started_at)` and `(workflow_id, started_at)` indexes serve the
+ * sort and a page reads only its own rows.
  */
 function startedAtKeyset<Row extends { id: string; startedAt: Date; startedAtCursor: string }>(
   startedAtColumn: Column,
   idColumn: Column,
   cursorKeys: CursorKey[] | undefined
 ): KeysetKey<Row>[] {
-  const resumesDateCursor =
-    cursorKeys !== undefined && classifyTimestampCursor(cursorKeys[0]) === 'date'
   return [
-    resumesDateCursor
-      ? timestampKey<Row>(startedAtColumn, (row) => row.startedAt)
-      : preciseTimestampKey<Row>(startedAtColumn, (row) => row.startedAtCursor),
+    resumableTimestampKey<Row>(
+      startedAtColumn,
+      (row) => row.startedAt,
+      (row) => row.startedAtCursor,
+      cursorKeys
+    ),
     textKey<Row>(idColumn, (row) => row.id),
   ]
 }
 
@@ -0,0 +1,9 @@
+import type { ShareRecord } from '@/lib/api/contracts/public-shares'
+
+/** Each item with its public share state, `null` when it was never shared. */
+export function attachShares<T extends { id: string }>(
+  items: readonly T[],
+  shares: ReadonlyMap<string, ShareRecord>
+): (T & { share: ShareRecord | null })[] {
+  return items.map((item) => ({ ...item, share: shares.get(item.id) ?? null }))
+}