@byline/host-tanstack-start 3.21.0 → 4.0.0

package/src/routes/create-collection-edit-route.tsx

@@ -19,6 +19,7 @@ import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs
 import { useNavigate } from '../admin-shell/chrome/loose-router.js'
 import { EditView } from '../admin-shell/collections/edit.js'
 import { getCollectionDocument } from '../server-fns/collections/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 import { getContentLocaleRouteConfig } from './get-content-locale-route-config.js'
 
 const searchSchema = z.object({
@@ -116,11 +117,14 @@ export function createCollectionEditRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: `/admin` },
-              { label: collectionDef.labels.plural, href: `/admin/collections/${collection}` },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              {
+                label: collectionDef.labels.plural,
+                href: getAdminRoutePath('collections', collection),
+              },
               {
                 label: t('common.actions.edit'),
-                href: `/admin/collections/${collection}/${id}`,
+                href: getAdminRoutePath('collections', collection, id),
               },
             ]}
           />

package/src/routes/create-collection-history-route.tsx

@@ -24,6 +24,7 @@ import {
   getCollectionDocumentAuditLog,
   getCollectionDocumentHistory,
 } from '../server-fns/collections/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 import { getContentLocaleRouteConfig } from './get-content-locale-route-config.js'
 
 const searchSchema = z.object({
@@ -119,15 +120,18 @@ export function createCollectionHistoryRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: `/admin` },
-              { label: collectionDef.labels.plural, href: `/admin/collections/${collection}` },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              {
+                label: collectionDef.labels.plural,
+                href: getAdminRoutePath('collections', collection),
+              },
               {
                 label: t('common.actions.edit'),
-                href: `/admin/collections/${collection}/${Route.useParams().id}`,
+                href: getAdminRoutePath('collections', collection, Route.useParams().id),
               },
               {
                 label: t('collections.breadcrumbs.history'),
-                href: `/admin/collections/${collection}/${Route.useParams().id}/history`,
+                href: getAdminRoutePath('collections', collection, Route.useParams().id, 'history'),
               },
             ]}
           />

package/src/routes/create-collection-list-route.tsx

@@ -30,6 +30,7 @@ import {
   placeTreeNode,
   reorderCollectionDocument,
 } from '../server-fns/collections/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 import type { CollectionTreeRow } from '../server-fns/collections/tree.js'
 
 const searchSchema = z.object({
@@ -167,10 +168,10 @@ export function createCollectionListRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: `/admin` },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
               {
                 label: data.included.collection.labels.plural,
-                href: `/admin/collections/${collection}`,
+                href: getAdminRoutePath('collections', collection),
               },
             ]}
           />

package/src/routes/create-sign-in-route.tsx

@@ -9,7 +9,7 @@
 /**
  * Sign-in page route factory.
  *
- * Lives outside the `/admin` subtree so the authenticated-admin layout
+ * Lives outside the configured admin subtree so the authenticated-admin layout
  * (and its `beforeLoad` guard) does not apply. Preserves a `callbackUrl`
  * query param so sign-ins triggered by the admin guard redirect back to
  * the originally-requested path.
@@ -21,6 +21,7 @@ import type { LocaleCode } from '@byline/i18n'
 
 import { SignInPage } from '../admin-shell/chrome/sign-in-page.js'
 import { getActiveLocaleFn } from '../server-fns/i18n/index.js'
+import { resolveAdminCallbackPath, resolveAdminSignInRedirect } from './admin-path.js'
 
 interface SignInSearch {
   callbackUrl?: string
@@ -30,7 +31,7 @@ export function createSignInRoute(path: string) {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
   const Route: any = createFileRoute(path as never)({
     validateSearch: (search: Record<string, unknown>): SignInSearch => {
-      const callbackUrl = typeof search.callbackUrl === 'string' ? search.callbackUrl : undefined
+      const callbackUrl = resolveAdminCallbackPath(search.callbackUrl)
       return { callbackUrl }
     },
     beforeLoad: async () => {
@@ -45,7 +46,12 @@ export function createSignInRoute(path: string) {
     component: function SignInRouteComponent() {
       const { callbackUrl } = Route.useSearch() as SignInSearch
       const { activeLocale } = Route.useRouteContext() as { activeLocale: LocaleCode }
-      return <SignInPage callbackUrl={callbackUrl} activeLocale={activeLocale} />
+      return (
+        <SignInPage
+          redirectTo={resolveAdminSignInRedirect(callbackUrl)}
+          activeLocale={activeLocale}
+        />
+      )
     },
   })
   return Route

package/src/routes/index.ts

@@ -6,6 +6,16 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+export {
+  getAdminRouteId,
+  getAdminRoutePath,
+  isAdminRoutePathActive,
+  isRoutePathWithin,
+  resolveAdminCallbackPath,
+  resolveAdminSignInRedirect,
+} from './admin-path.js'
+export { configureSignInRoutePath, getSignInRoutePath } from './sign-in-path.js'
+
 /**
  * Route factories for the Byline admin UI on TanStack Start.
  *
@@ -14,6 +24,7 @@
  * `createFileRoute(path)({...})`. The host's route file collapses to:
  *
  *   import { createCollectionListRoute } from '@byline/host-tanstack-start/routes'
+ *   // Default admin mount example:
  *   export const Route = createCollectionListRoute('/_byline/admin/collections/$collection/')
  *
  * Routes that need host-specific data (i18n bridge component, content

package/src/routes/sign-in-path.test.node.ts

@@ -0,0 +1,79 @@
+import { defineClientConfig } from '@byline/core'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  configureSignInRoutePath,
+  createSignInRoutePathResolver,
+  getSignInRoutePath,
+} from './sign-in-path.js'
+
+describe('sign-in route configuration', () => {
+  beforeEach(() => {
+    defineClientConfig({
+      serverURL: 'http://localhost:3000',
+      routes: { signIn: '/staff/login/' },
+      collections: [],
+      admin: [],
+      i18n: {
+        interface: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+  })
+
+  it('reads and normalizes routes.signIn', () => {
+    expect(getSignInRoutePath()).toBe('/staff/login')
+  })
+
+  it('allows a deprecated signInPath override when it matches canonical config', () => {
+    expect(configureSignInRoutePath('staff/login/')).toBe('/staff/login')
+  })
+
+  it('rejects an invalid or divergent deprecated override when resolved', () => {
+    expect(() => configureSignInRoutePath('/auth/login/')).toThrow(/must match routes\.signIn/)
+    expect(() => configureSignInRoutePath('/auth/../login')).toThrow(/routes\.signIn/)
+  })
+
+  it('validates an override against configured rather than default route trees', () => {
+    defineClientConfig({
+      serverURL: 'http://localhost:3000',
+      routes: { admin: '/cms', api: '/rpc', signIn: '/admin/login' },
+      collections: [],
+      admin: [],
+      i18n: {
+        interface: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+
+    expect(configureSignInRoutePath('/admin/login/')).toBe('/admin/login')
+    expect(() => configureSignInRoutePath('/cms/login')).toThrow(/routes\.signIn/)
+  })
+
+  it('defers a deprecated override until parent beforeLoad config registration', () => {
+    defineClientConfig({
+      serverURL: 'http://localhost:3000',
+      routes: { signIn: '/old/login' },
+      collections: [],
+      admin: [],
+      i18n: {
+        interface: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+    const resolveSignInPath = createSignInRoutePathResolver('/staff/login/')
+
+    defineClientConfig({
+      serverURL: 'http://localhost:3000',
+      routes: { signIn: '/staff/login' },
+      collections: [],
+      admin: [],
+      i18n: {
+        interface: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+
+    expect(resolveSignInPath()).toBe('/staff/login')
+  })
+})

package/src/routes/sign-in-path.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { getClientConfig, resolveRoutes } from '@byline/core'
+
+/** Read the canonical client-safe sign-in destination. */
+export function getSignInRoutePath(): string {
+  return getClientConfig().routes.signIn
+}
+
+/** @deprecated Configure `routes.signIn`; retained for route-factory input validation. */
+export function configureSignInRoutePath(legacyOverride?: string): string {
+  const routes = getClientConfig().routes
+  const configured = routes.signIn
+  if (legacyOverride === undefined) return configured
+
+  const normalizedOverride = resolveRoutes({ ...routes, signIn: legacyOverride }).signIn
+  if (normalizedOverride !== configured) {
+    throw new Error(
+      `createAdminLayoutRoute signInPath (${normalizedOverride}) must match routes.signIn (${configured})`
+    )
+  }
+  return configured
+}
+
+/** Defer deprecated override validation until the admin route's beforeLoad boundary. */
+export function createSignInRoutePathResolver(legacyOverride?: string): () => string {
+  return legacyOverride === undefined
+    ? getSignInRoutePath
+    : () => configureSignInRoutePath(legacyOverride)
+}

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 })
+  })
+})