@byline/host-tanstack-start 3.20.4 → 4.0.0

package/src/server-fns/collections/delete-outcome.test.node.ts

@@ -0,0 +1,72 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { DeleteDocumentResult, DeleteDocumentSideEffectPhase } from '@byline/core'
+import { describe, expect, it } from 'vitest'
+
+import { hasDeleteSideEffectFailures, toDeleteDocumentResponse } from './delete-outcome.js'
+
+describe('delete outcome transport and admin interpretation', () => {
+  it('returns only allowlisted phase/code data for a committed warning', () => {
+    // Simulate malformed runtime data from an older or compromised source. The
+    // core type rejects this shape, but the transport still sanitizes it.
+    const unsafeResult = {
+      deletedVersionCount: 2,
+      outcome: 'committed-with-side-effect-failures',
+      sideEffectFailures: [
+        { phase: 'afterDelete', message: 'secret hook details', code: 'ERR_SEARCH' },
+        { phase: 'storageCleanup', message: 'private/path.pdf', code: 'ERR_STORAGE' },
+        {
+          phase: 'internalOnly' as DeleteDocumentSideEffectPhase,
+          message: 'internal phase details',
+          code: 'ERR_INTERNAL',
+        },
+      ],
+    } as unknown as DeleteDocumentResult
+    const response = toDeleteDocumentResponse(unsafeResult)
+
+    expect(response).toEqual({
+      status: 'ok',
+      deletedVersionCount: 2,
+      outcome: 'committed-with-side-effect-failures',
+      sideEffectFailures: [
+        { phase: 'afterDelete', code: 'ERR_UNHANDLED' },
+        { phase: 'storageCleanup', code: 'ERR_STORAGE' },
+        { phase: 'unknown', code: 'ERR_UNHANDLED' },
+      ],
+    })
+    expect(JSON.parse(JSON.stringify(response))).toEqual(response)
+    expect(JSON.stringify(response)).not.toContain('secret hook details')
+    expect(JSON.stringify(response)).not.toContain('private/path.pdf')
+    expect(JSON.stringify(response)).not.toContain('internal phase details')
+    expect(hasDeleteSideEffectFailures(response)).toBe(true)
+  })
+
+  it('preserves the committed success discriminant and empty failures', () => {
+    const response = toDeleteDocumentResponse({
+      deletedVersionCount: 2,
+      outcome: 'committed',
+      sideEffectFailures: [],
+    })
+
+    expect(response).toEqual({
+      status: 'ok',
+      deletedVersionCount: 2,
+      outcome: 'committed',
+      sideEffectFailures: [],
+    })
+    expect(hasDeleteSideEffectFailures(response)).toBe(false)
+  })
+
+  it('classifies only committed side-effect failures as an admin warning', () => {
+    expect(hasDeleteSideEffectFailures({ outcome: 'committed' })).toBe(false)
+    expect(hasDeleteSideEffectFailures({ outcome: 'committed-with-side-effect-failures' })).toBe(
+      true
+    )
+  })
+})

package/src/server-fns/collections/delete-outcome.ts

@@ -0,0 +1,80 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type {
+  DeleteDocumentResult,
+  DeleteDocumentSideEffectCode,
+  DeleteDocumentSideEffectPhase,
+} from '@byline/core'
+import { ErrorCodes } from '@byline/core'
+
+export type DeleteDocumentPublicSideEffectPhase = DeleteDocumentSideEffectPhase | 'unknown'
+export type DeleteDocumentPublicSideEffectCode = DeleteDocumentSideEffectCode
+
+export interface DeleteDocumentPublicSideEffectFailure {
+  phase: DeleteDocumentPublicSideEffectPhase
+  code: DeleteDocumentPublicSideEffectCode
+}
+
+export type DeleteDocumentResponse =
+  | {
+      status: 'ok'
+      deletedVersionCount: number
+      outcome: 'committed'
+      sideEffectFailures: []
+    }
+  | {
+      status: 'ok'
+      deletedVersionCount: number
+      outcome: 'committed-with-side-effect-failures'
+      sideEffectFailures: [
+        DeleteDocumentPublicSideEffectFailure,
+        ...DeleteDocumentPublicSideEffectFailure[],
+      ]
+    }
+
+function sanitizePhase(phase: DeleteDocumentSideEffectPhase): DeleteDocumentPublicSideEffectPhase {
+  if (phase === 'storageCleanup' || phase === 'afterTreeChange' || phase === 'afterDelete') {
+    return phase
+  }
+  return 'unknown'
+}
+
+function sanitizeCode(code: string): DeleteDocumentPublicSideEffectCode {
+  return code === ErrorCodes.STORAGE ? ErrorCodes.STORAGE : ErrorCodes.UNHANDLED
+}
+
+function sanitizeFailure({
+  phase,
+  code,
+}: {
+  phase: DeleteDocumentSideEffectPhase
+  code: string
+}): DeleteDocumentPublicSideEffectFailure {
+  return { phase: sanitizePhase(phase), code: sanitizeCode(code) }
+}
+
+export function toDeleteDocumentResponse(result: DeleteDocumentResult): DeleteDocumentResponse {
+  if (result.outcome === 'committed') {
+    return { status: 'ok', ...result }
+  }
+
+  const [firstFailure, ...remainingFailures] = result.sideEffectFailures
+  return {
+    status: 'ok',
+    deletedVersionCount: result.deletedVersionCount,
+    outcome: result.outcome,
+    sideEffectFailures: [sanitizeFailure(firstFailure), ...remainingFailures.map(sanitizeFailure)],
+  }
+}
+
+export function hasDeleteSideEffectFailures(
+  result: Pick<DeleteDocumentResult, 'outcome'>
+): boolean {
+  return result.outcome === 'committed-with-side-effect-failures'
+}

package/src/server-fns/collections/delete.ts

@@ -14,6 +14,7 @@ import { deleteDocument as deleteDocumentService } from '@byline/core/services'
 
 import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { toDeleteDocumentResponse } from './delete-outcome.js'
 
 // ---------------------------------------------------------------------------
 // Delete document (soft-delete — marks all versions as deleted)
@@ -58,5 +59,5 @@ export const deleteDocument = createServerFn({ method: 'POST' })
     }
 
     const result = await deleteDocumentService(ctx, { documentId: id })
-    return { status: 'ok' as const, deletedVersionCount: result.deletedVersionCount }
+    return toDeleteDocumentResponse(result)
   })

package/src/server-fns/collections/get.ts

@@ -197,6 +197,8 @@ const getDocumentByVersionFn = createServerFn({ method: 'GET' })
       }).log(logger)
     }
 
+    // The client binds the historical row to `path` and applies its beforeRead
+    // predicate; unknown and cross-collection version ids both resolve null.
     const document = await getAdminBylineClient()
       .collection(path)
       .findByVersion(versionId, { locale: resolvedLocale })

package/src/server-fns/collections/index.ts

@@ -10,6 +10,7 @@ export * from './copy-to-locale'
 export * from './create'
 export * from './delete'
 export * from './delete-locale'
+export * from './delete-outcome'
 export * from './duplicate'
 export * from './get'
 export * from './history'

package/src/server-fns/collections/tree-mutation.test.node.ts

@@ -0,0 +1,225 @@
+import { TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER } from '@byline/core'
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  createAdminTreeMoveController,
+  executeAdminTreeMove,
+  getAdminTreeMoveUiEffects,
+  isCommittedTreeHookFailure,
+  isTreeMutationConflict,
+  placeAdminTreeNode,
+  removeAdminTreeNode,
+  shouldSyncAdminTreeRows,
+} from './tree-mutation.js'
+
+describe('admin tree mutations', () => {
+  it('recognises a coded stale-tree conflict', () => {
+    expect(isTreeMutationConflict({ code: 'ERR_CONFLICT' })).toBe(true)
+    expect(isTreeMutationConflict(new Error('failed'))).toBe(false)
+  })
+
+  it('recognises a code-less stale-tree conflict by its stable marker', () => {
+    expect(
+      isTreeMutationConflict(
+        new Error(`${TREE_PLACEMENT_STALE_MARKER} completely reworded diagnostic`)
+      )
+    ).toBe(true)
+    expect(isTreeMutationConflict(new Error('tree placement is stale: neighbours moved'))).toBe(
+      false
+    )
+  })
+
+  it('recognises a coded committed tree-hook rejection', () => {
+    expect(isCommittedTreeHookFailure({ code: 'ERR_TREE_HOOK_COMMITTED' })).toBe(true)
+    expect(isCommittedTreeHookFailure({ code: 'ERR_CONFLICT' })).toBe(false)
+  })
+
+  it('recognises a code-less committed tree-hook rejection by its stable marker', () => {
+    expect(
+      isCommittedTreeHookFailure(
+        new Error(`${TREE_HOOK_COMMITTED_MARKER} completely reworded diagnostic`)
+      )
+    ).toBe(true)
+    expect(isCommittedTreeHookFailure(new Error('tree mutation committed; hook failed'))).toBe(
+      false
+    )
+  })
+
+  it('refreshes canonical tree data after a rejected mutation', async () => {
+    const mutationError = new Error(`${TREE_PLACEMENT_STALE_MARKER} neighbours moved`)
+    const refresh = vi.fn().mockResolvedValue(undefined)
+
+    await expect(
+      executeAdminTreeMove(vi.fn().mockRejectedValue(mutationError), refresh)
+    ).resolves.toEqual({ status: 'mutation-failed', error: mutationError })
+    expect(refresh).toHaveBeenCalledOnce()
+  })
+
+  it('reports a refresh failure separately after a successful mutation', async () => {
+    const refreshError = new Error('router unavailable')
+
+    await expect(
+      executeAdminTreeMove(
+        vi.fn().mockResolvedValue(undefined),
+        vi.fn().mockRejectedValue(refreshError)
+      )
+    ).resolves.toEqual({ status: 'refresh-failed', error: refreshError })
+  })
+
+  it('keeps a committed hook rejection separate from mutation failure', async () => {
+    const hookError = { code: 'ERR_TREE_HOOK_COMMITTED', message: 'hook failed' }
+    const refresh = vi.fn().mockResolvedValue(undefined)
+
+    const outcome = await executeAdminTreeMove(vi.fn().mockRejectedValue(hookError), refresh)
+
+    expect(outcome).toEqual({ status: 'committed-hook-failed', error: hookError })
+    expect(getAdminTreeMoveUiEffects(outcome)).toEqual({
+      rollback: false,
+      preserveOptimistic: false,
+      structuralFailure: null,
+      committedHookWarning: true,
+      refreshWarning: false,
+    })
+    expect(refresh).toHaveBeenCalledOnce()
+  })
+
+  it('preserves optimistic UI when committed-hook refresh also fails', async () => {
+    const hookError = { code: 'ERR_TREE_HOOK_COMMITTED', message: 'hook failed' }
+    const refreshError = new Error('refresh failed')
+    const outcome = await executeAdminTreeMove(
+      vi.fn().mockRejectedValue(hookError),
+      vi.fn().mockRejectedValue(refreshError)
+    )
+
+    expect(outcome).toEqual({
+      status: 'committed-hook-failed',
+      error: hookError,
+      refreshError,
+    })
+    expect(getAdminTreeMoveUiEffects(outcome)).toEqual({
+      rollback: false,
+      preserveOptimistic: true,
+      structuralFailure: null,
+      committedHookWarning: true,
+      refreshWarning: true,
+    })
+  })
+
+  it('keeps ordinary mutation failure rollback policy', () => {
+    expect(
+      getAdminTreeMoveUiEffects({
+        status: 'mutation-failed',
+        error: { code: 'ERR_CONFLICT' },
+      })
+    ).toEqual({
+      rollback: true,
+      preserveOptimistic: false,
+      structuralFailure: 'conflict',
+      committedHookWarning: false,
+      refreshWarning: false,
+    })
+  })
+
+  it('preserves optimistic rows after refresh failure until canonical rows change', () => {
+    const staleRows = [{ id: 'old' }]
+    expect(shouldSyncAdminTreeRows(staleRows, staleRows, false)).toBe(false)
+    expect(shouldSyncAdminTreeRows([{ id: 'canonical' }], staleRows, false)).toBe(true)
+    expect(shouldSyncAdminTreeRows([{ id: 'canonical' }], null, true)).toBe(false)
+  })
+
+  it('suppresses a second move while the first move is in flight', async () => {
+    const controller = createAdminTreeMoveController()
+    let resolveMutation: (() => void) | undefined
+    const mutate = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveMutation = resolve
+        })
+    )
+    const refresh = vi.fn().mockResolvedValue(undefined)
+
+    const first = controller.execute(mutate, refresh)
+    expect(controller.isMoving()).toBe(true)
+    await expect(controller.execute(mutate, refresh)).resolves.toEqual({ status: 'suppressed' })
+    expect(mutate).toHaveBeenCalledOnce()
+
+    resolveMutation?.()
+    await expect(first).resolves.toEqual({ status: 'ok' })
+    expect(refresh).toHaveBeenCalledOnce()
+    expect(controller.isMoving()).toBe(false)
+  })
+
+  it('refreshes and unlocks after a rejected mutation', async () => {
+    const controller = createAdminTreeMoveController()
+    const mutationError = new Error('rejected')
+    const refresh = vi.fn().mockResolvedValue(undefined)
+
+    await expect(
+      controller.execute(vi.fn().mockRejectedValue(mutationError), refresh)
+    ).resolves.toEqual({ status: 'mutation-failed', error: mutationError })
+    expect(refresh).toHaveBeenCalledOnce()
+    expect(controller.isMoving()).toBe(false)
+  })
+
+  it('unlocks and reports only refresh failure after a successful commit', async () => {
+    const controller = createAdminTreeMoveController()
+    const refreshError = new Error('refresh failed')
+
+    const outcome = await controller.execute(
+      vi.fn().mockResolvedValue(undefined),
+      vi.fn().mockRejectedValue(refreshError)
+    )
+
+    expect(outcome).toEqual({ status: 'refresh-failed', error: refreshError })
+    expect(outcome.status).not.toBe('mutation-failed')
+    expect(controller.isMoving()).toBe(false)
+  })
+
+  it('opts ordinary placement retries into lifecycle reconciliation', async () => {
+    const placeTreeNode = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('post-commit hook failed'))
+      .mockResolvedValue({ orderKey: 'key-1' })
+
+    const retry = () =>
+      placeAdminTreeNode({ placeTreeNode } as any, 'doc-1', {
+        parentDocumentId: 'parent-1',
+        beforeDocumentId: 'left-1',
+      })
+
+    await expect(retry()).rejects.toThrow('post-commit hook failed')
+    await expect(retry()).resolves.toEqual({ orderKey: 'key-1' })
+
+    expect(placeTreeNode).toHaveBeenCalledTimes(2)
+    expect(placeTreeNode).toHaveBeenNthCalledWith(
+      2,
+      'doc-1',
+      expect.objectContaining({ reconcile: true })
+    )
+  })
+
+  it('opts ordinary removal retries into lifecycle reconciliation', async () => {
+    const removeFromTree = vi.fn().mockResolvedValue(undefined)
+
+    await removeAdminTreeNode({ removeFromTree } as any, 'doc-1')
+
+    expect(removeFromTree).toHaveBeenCalledWith('doc-1', { reconcile: true })
+  })
+
+  it('preserves an explicit reconciliation override', async () => {
+    const placeTreeNode = vi.fn().mockResolvedValue({ orderKey: 'key-1' })
+    const removeFromTree = vi.fn().mockResolvedValue(undefined)
+
+    await placeAdminTreeNode({ placeTreeNode } as any, 'doc-1', {
+      parentDocumentId: null,
+      reconcile: false,
+    })
+    await removeAdminTreeNode({ removeFromTree } as any, 'doc-1', { reconcile: false })
+
+    expect(placeTreeNode).toHaveBeenCalledWith('doc-1', {
+      parentDocumentId: null,
+      reconcile: false,
+    })
+    expect(removeFromTree).toHaveBeenCalledWith('doc-1', { reconcile: false })
+  })
+})

package/src/server-fns/collections/tree-mutation.ts

@@ -0,0 +1,165 @@
+import type { CollectionHandle, PlaceTreeNodeOptions, RemoveFromTreeOptions } from '@byline/client'
+import { ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER } from '@byline/core'
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return (
+    typeof error === 'object' &&
+    error != null &&
+    'code' in error &&
+    (error as { code?: unknown }).code === code
+  )
+}
+
+function hasMessageMarker(error: unknown, marker: string): boolean {
+  return error instanceof Error && error.message.startsWith(marker)
+}
+
+/** Prefer the code; the marker survives transports that reconstruct a code-less Error. */
+export function isTreeMutationConflict(error: unknown): boolean {
+  if (hasErrorCode(error, ErrorCodes.CONFLICT)) return true
+  return hasMessageMarker(error, TREE_PLACEMENT_STALE_MARKER)
+}
+
+/** Detect when tree/audit committed even if transport reconstruction dropped the code. */
+export function isCommittedTreeHookFailure(error: unknown): boolean {
+  if (hasErrorCode(error, ErrorCodes.TREE_HOOK_COMMITTED)) return true
+  return hasMessageMarker(error, TREE_HOOK_COMMITTED_MARKER)
+}
+
+export type AdminTreeMoveOutcome =
+  | { status: 'ok' }
+  | { status: 'suppressed' }
+  | { status: 'mutation-failed'; error: unknown; refreshError?: unknown }
+  | { status: 'committed-hook-failed'; error: unknown; refreshError?: unknown }
+  | { status: 'refresh-failed'; error: unknown }
+
+export interface AdminTreeMoveUiEffects {
+  rollback: boolean
+  preserveOptimistic: boolean
+  structuralFailure: 'conflict' | 'generic' | null
+  committedHookWarning: boolean
+  refreshWarning: boolean
+}
+
+/** Pure UI policy for every mutation/refresh outcome. */
+export function getAdminTreeMoveUiEffects(outcome: AdminTreeMoveOutcome): AdminTreeMoveUiEffects {
+  if (outcome.status === 'mutation-failed') {
+    return {
+      rollback: true,
+      preserveOptimistic: false,
+      structuralFailure: isTreeMutationConflict(outcome.error) ? 'conflict' : 'generic',
+      committedHookWarning: false,
+      refreshWarning: outcome.refreshError != null,
+    }
+  }
+  if (outcome.status === 'committed-hook-failed') {
+    return {
+      rollback: false,
+      preserveOptimistic: outcome.refreshError != null,
+      structuralFailure: null,
+      committedHookWarning: true,
+      refreshWarning: outcome.refreshError != null,
+    }
+  }
+  if (outcome.status === 'refresh-failed') {
+    return {
+      rollback: false,
+      preserveOptimistic: true,
+      structuralFailure: null,
+      committedHookWarning: false,
+      refreshWarning: true,
+    }
+  }
+  return {
+    rollback: outcome.status === 'suppressed',
+    preserveOptimistic: false,
+    structuralFailure: null,
+    committedHookWarning: false,
+    refreshWarning: false,
+  }
+}
+
+/** Preserve a committed optimistic move until a later loader returns new row data. */
+export function shouldSyncAdminTreeRows(
+  rows: unknown,
+  preservedRows: unknown,
+  isMoving: boolean
+): boolean {
+  return !isMoving && rows !== preservedRows
+}
+
+/** Keep mutation and canonical-refresh failures distinct for optimistic tree UIs. */
+export async function executeAdminTreeMove(
+  mutate: () => Promise<unknown>,
+  refresh: () => Promise<unknown>
+): Promise<AdminTreeMoveOutcome> {
+  try {
+    await mutate()
+  } catch (error) {
+    const status = isCommittedTreeHookFailure(error)
+      ? ('committed-hook-failed' as const)
+      : ('mutation-failed' as const)
+    try {
+      await refresh()
+      return { status, error }
+    } catch (refreshError) {
+      return { status, error, refreshError }
+    }
+  }
+
+  try {
+    await refresh()
+    return { status: 'ok' }
+  } catch (error) {
+    return { status: 'refresh-failed', error }
+  }
+}
+
+export interface AdminTreeMoveController {
+  isMoving(): boolean
+  execute(
+    mutate: () => Promise<unknown>,
+    refresh: () => Promise<unknown>
+  ): Promise<AdminTreeMoveOutcome>
+}
+
+/** Single-flight controller shared by pointer and keyboard tree moves. */
+export function createAdminTreeMoveController(): AdminTreeMoveController {
+  let moving = false
+  return {
+    isMoving: () => moving,
+    execute: async (mutate, refresh) => {
+      if (moving) return { status: 'suppressed' }
+      moving = true
+      try {
+        return await executeAdminTreeMove(mutate, refresh)
+      } finally {
+        moving = false
+      }
+    },
+  }
+}
+
+/** Admin retries reconcile post-commit tree hooks unless explicitly disabled. */
+export function placeAdminTreeNode(
+  handle: Pick<CollectionHandle, 'placeTreeNode'>,
+  documentId: string,
+  options: PlaceTreeNodeOptions
+): Promise<{ orderKey: string }> {
+  return handle.placeTreeNode(documentId, {
+    ...options,
+    reconcile: options.reconcile ?? true,
+  })
+}
+
+/** Admin retries reconcile post-commit tree hooks unless explicitly disabled. */
+export function removeAdminTreeNode(
+  handle: Pick<CollectionHandle, 'removeFromTree'>,
+  documentId: string,
+  options: RemoveFromTreeOptions = {}
+): Promise<void> {
+  return handle.removeFromTree(documentId, {
+    ...options,
+    reconcile: options.reconcile ?? true,
+  })
+}

package/src/server-fns/collections/tree-read.test.node.ts

@@ -0,0 +1,46 @@
+import { createReadContext } from '@byline/core'
+import { describe, expect, it, vi } from 'vitest'
+
+import { getAdminTreeParent, getAdminUnplacedTreeDocuments } from './tree-read.js'
+
+describe('getAdminTreeParent', () => {
+  it('explicitly selects status:any', async () => {
+    const getTreeParent = vi.fn().mockResolvedValue({
+      placed: false,
+      parentDocumentId: null,
+      parentVisibility: 'none',
+    })
+
+    await getAdminTreeParent({ getTreeParent } as any, 'doc-1')
+
+    expect(getTreeParent).toHaveBeenCalledWith('doc-1', { status: 'any' })
+  })
+})
+
+describe('getAdminUnplacedTreeDocuments', () => {
+  it('uses scoped any-mode reads so hidden unplaced nodes cannot reappear', async () => {
+    const visible = { id: 'visible-unplaced' }
+    const hidden = { id: 'hidden-unplaced' }
+    const readContext = createReadContext()
+    const find = vi.fn(async (options: Record<string, unknown>) => ({
+      docs: options._bypassBeforeRead === true ? [visible, hidden] : [visible],
+      meta: { total: 1, page: 1, pageSize: 1000, totalPages: 1 },
+    }))
+
+    const result = await getAdminUnplacedTreeDocuments(
+      { find } as any,
+      new Set(['visible-placed']),
+      readContext,
+      'en'
+    )
+
+    expect(find).toHaveBeenCalledWith({
+      status: 'any',
+      locale: 'en',
+      pageSize: 1000,
+      _readContext: readContext,
+    })
+    expect(result.map((doc) => doc.id)).toEqual(['visible-unplaced'])
+    expect(result).not.toContain(hidden)
+  })
+})

package/src/server-fns/collections/tree-read.ts

@@ -0,0 +1,26 @@
+import type { ClientDocument, CollectionHandle, TreeParentResult } from '@byline/client'
+import type { ReadContext } from '@byline/core'
+
+/** Admin tree placement reads must include drafts. */
+export function getAdminTreeParent(
+  handle: Pick<CollectionHandle, 'getTreeParent'>,
+  documentId: string
+): Promise<TreeParentResult> {
+  return handle.getTreeParent(documentId, { status: 'any' })
+}
+
+/** Find unplaced nodes through the same row scope as the structural tree read. */
+export async function getAdminUnplacedTreeDocuments(
+  handle: Pick<CollectionHandle, 'find'>,
+  placed: ReadonlySet<string>,
+  readContext: ReadContext,
+  locale?: string
+): Promise<ClientDocument[]> {
+  const all = await handle.find({
+    status: 'any',
+    locale,
+    pageSize: 1000,
+    _readContext: readContext,
+  })
+  return all.docs.filter((doc) => !placed.has(doc.id))
+}