@byline/host-tanstack-start 4.19.0 → 5.0.0

package/src/admin-shell/collections/save-navigation.test.tsx

@@ -9,11 +9,23 @@
 import type React from 'react'
 import { act } from 'react'
 
-import { type MultiCollectionDefinition, SINGLE_STATUS_WORKFLOW } from '@byline/core'
+import {
+  DEFAULT_WORKFLOW,
+  ERR_DOCUMENT_STALE,
+  ERR_LOCK_CONFLICT,
+  type MultiCollectionDefinition,
+  SINGLE_STATUS_WORKFLOW,
+} from '@byline/core'
 import { createRoot, type Root } from 'react-dom/client'
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
 
 const mocks = vi.hoisted(() => ({
+  status: vi.fn(),
+  deletion: vi.fn(),
+  schedule: vi.fn(),
+  confirm: vi.fn(),
+  cancelSchedule: vi.fn(),
+  unpublish: vi.fn(),
   copyToLocale: vi.fn(),
   create: vi.fn(),
   deleteLocale: vi.fn(),
@@ -60,21 +72,21 @@ vi.mock('../../routes/list-return-storage.js', () => ({
 }))
 
 vi.mock('../../server-fns/collections/index.js', () => ({
-  cancelCollectionDocumentScheduledPublish: vi.fn(),
-  confirmCollectionDocumentScheduledPublish: vi.fn(),
+  cancelCollectionDocumentScheduledPublish: mocks.cancelSchedule,
+  confirmCollectionDocumentScheduledPublish: mocks.confirm,
   copyDocumentToLocale: mocks.copyToLocale,
   createCollectionDocument: mocks.create,
-  deleteDocument: vi.fn(),
+  deleteDocument: mocks.deletion,
   deleteDocumentLocale: mocks.deleteLocale,
   duplicateCollectionDocument: mocks.duplicate,
   hasCommittedDocumentHookFailure: (result: { status: string }) =>
     result.status === 'committed-hook-failed',
   hasDeleteSideEffectFailures: () => false,
-  scheduleCollectionDocumentPublish: vi.fn(),
-  unpublishDocument: vi.fn(),
+  scheduleCollectionDocumentPublish: mocks.schedule,
+  unpublishDocument: mocks.unpublish,
   updateCollectionDocumentSystemFields: mocks.updateSystemFields,
   updateCollectionDocumentWithPatches: mocks.update,
-  updateDocumentStatus: vi.fn(),
+  updateDocumentStatus: mocks.status,
 }))
 
 vi.mock('../chrome/loose-router.js', () => ({
@@ -106,6 +118,7 @@ const collection = {
 const initialData = {
   id: 'language-en',
   versionId: 'version-1',
+  revision: 7,
   status: 'published',
   fields: { name: 'English' },
 }
@@ -127,11 +140,12 @@ beforeEach(() => {
     documentId: 'language-th',
     documentVersionId: 'version-created',
   })
-  mocks.update.mockResolvedValue({ status: 'ok' })
+  mocks.update.mockResolvedValue({ status: 'ok', documentId: 'language-en', revision: 8 })
   mocks.updateSystemFields.mockResolvedValue({ status: 'ok' })
   mocks.copyToLocale.mockResolvedValue({
     documentId: 'language-en',
     documentVersionId: 'version-2',
+    revision: 8,
     sourceLocale: 'en',
     targetLocale: 'th',
     fieldsUpdated: 1,
@@ -139,6 +153,7 @@ beforeEach(() => {
   mocks.deleteLocale.mockResolvedValue({
     documentId: 'language-en',
     documentVersionId: 'version-2',
+    revision: 8,
     locale: 'th',
   })
   mocks.duplicate.mockResolvedValue({
@@ -253,6 +268,44 @@ describe('collection post-save navigation', () => {
     })
   })
 
+  it('sends content and metadata in one save using the loaded revision', async () => {
+    act(() => {
+      root.render(
+        <EditView
+          collectionDefinition={collection}
+          initialData={initialData as never}
+          contentLocales={[{ code: 'en', label: 'English' }]}
+          defaultContentLocale="en"
+          locale="en"
+        />
+      )
+    })
+    const patches = [{ kind: 'field.set', path: 'name', value: 'English' }]
+    await act(async () => {
+      await latestSubmit()({
+        data: { name: 'English' },
+        patches,
+        contentDirty: true,
+        pathDirty: true,
+        systemPath: 'renamed',
+        availableLocalesDirty: true,
+        systemAvailableLocales: ['en', 'fr'],
+      })
+    })
+    expect(mocks.update).toHaveBeenCalledExactlyOnceWith({
+      data: {
+        collection: 'languages',
+        id: 'language-en',
+        expectedRevision: 7,
+        patches,
+        locale: 'en',
+        path: 'renamed',
+        availableLocales: ['en', 'fr'],
+      },
+    })
+    expect(mocks.updateSystemFields).not.toHaveBeenCalled()
+  })
+
   it('bypasses the dirty-form blocker during the successful edit refresh', async () => {
     act(() => {
       root.render(
@@ -289,6 +342,7 @@ describe('collection post-save navigation', () => {
       status: 'committed-hook-failed',
       documentId: 'language-en',
       documentVersionId: 'version-2',
+      revision: 8,
       sideEffectFailure: { phase: 'afterUpdate', code: 'ERR_UNHANDLED' },
     })
     act(() => {
@@ -351,6 +405,7 @@ describe('collection post-save navigation', () => {
       status: 'committed-hook-failed',
       documentId: testCase.expectedId,
       documentVersionId: 'version-committed',
+      revision: 8,
       sideEffectFailure: { phase: testCase.phase, code: 'ERR_UNHANDLED' },
     })
     act(() => {
@@ -382,3 +437,96 @@ describe('collection post-save navigation', () => {
     })
   })
 })
+
+describe('collection editor mutation lockout', () => {
+  const stale = ERR_DOCUMENT_STALE({
+    message: 'Test failure',
+    details: {
+      reason: 'revision_mismatch',
+      documentId: 'language-en',
+      expectedRevision: 7,
+      currentRevision: 8,
+    },
+  })
+  const opened = {
+    ...initialData,
+    _publishedVersion: initialData,
+    status: 'draft',
+    _scheduledPublicationEnabled: true,
+    _canSchedulePublication: true,
+    _scheduledPublish: { state: 'needs_reconfirm' },
+  }
+  const renderEditor = () =>
+    act(() =>
+      root.render(
+        <EditView
+          collectionDefinition={{ ...collection, workflow: DEFAULT_WORKFLOW }}
+          initialData={opened as never}
+          contentLocales={[
+            { code: 'en', label: 'English' },
+            { code: 'th', label: 'Thai' },
+          ]}
+          defaultContentLocale="en"
+          locale="en"
+        />
+      )
+    )
+  const operations = [
+    ['onSubmit', mocks.update, { patches: [], contentDirty: true }],
+    ['onStatusChange', mocks.status, 'published'],
+    ['onDelete', mocks.deletion, undefined],
+    ['onDuplicate', mocks.duplicate, undefined],
+    ['onCopyToLocale', mocks.copyToLocale, { targetLocale: 'th', overwrite: true }],
+    ['onDeleteLocale', mocks.deleteLocale, { targetLocale: 'th' }],
+    ['onUnpublish', mocks.unpublish, undefined],
+    ['onSchedulePublication', mocks.schedule, { publishAt: '2030-01-01T00:00:00Z' }],
+    ['onConfirmScheduledPublication', mocks.confirm, undefined],
+    ['onCancelScheduledPublication', mocks.cancelSchedule, undefined],
+  ] as const
+  it.each(operations)(
+    'blocks subsequent writes after %s reports stale',
+    async (name, operation, argument) => {
+      operation.mockRejectedValueOnce(stale)
+      renderEditor()
+      await act(async () => {
+        await expect(latestAction(name)(argument)).rejects.toBe(stale)
+      })
+      expect(mocks.formProps.at(-1)).toMatchObject({
+        mutationIssue: 'stale',
+        mutationsBlocked: true,
+        observedRevision: 7,
+      })
+      for (const [otherName, , otherArgument] of operations) {
+        await act(async () => {
+          await expect(latestAction(otherName)(otherArgument)).rejects.toBe(stale)
+        })
+      }
+      expect(operations.reduce((total, [, mock]) => total + mock.mock.calls.length, 0)).toBe(1)
+      expect(mocks.navigate).not.toHaveBeenCalled()
+      expect(mocks.toastAdd).not.toHaveBeenCalled()
+    }
+  )
+  it.each([
+    ['onSubmit', mocks.update, { patches: [], contentDirty: true }],
+    ['onDelete', mocks.deletion, undefined],
+  ] as const)(
+    'presents confirmed lock rollback safely for %s',
+    async (name, operation, argument) => {
+      const failure = ERR_LOCK_CONFLICT({
+        message: 'raw InnoDB private SQL',
+        details: { reason: 'lock_conflict', rolledBack: true, retryable: true },
+      })
+      operation.mockRejectedValueOnce(failure)
+      renderEditor()
+      await act(async () => {
+        await expect(latestAction(name)(argument)).rejects.toBe(failure)
+      })
+      expect(mocks.formProps.at(-1)).toMatchObject({
+        mutationIssue: 'lock',
+        mutationsBlocked: true,
+        observedRevision: 7,
+      })
+      expect(mocks.toastAdd).not.toHaveBeenCalled()
+    }
+  )
+})

package/src/admin-shell/collections/tree-list.tsx

@@ -1,3 +1,5 @@
+import { DocumentMutationNotice } from '../document-mutation-notice.js'
+import { useDocumentMutationState } from '../document-mutation-state.js'
 /**
  * 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
@@ -144,6 +146,7 @@ export const TreeListView = ({
   /** Header action components (`CollectionAdminConfig.listActions`). */
   listActions?: Array<(props: ListActionComponentProps) => React.ReactNode>
 }) => {
+  const mutation = useDocumentMutationState(undefined)
   const { t } = useTranslation('byline-admin')
   const router = useRouter()
   const toastManager = useToastManager()
@@ -159,10 +162,14 @@ export const TreeListView = ({
   const [moveController] = useState(() => createAdminTreeMoveController())
   const preserveOptimisticForRows = useRef<CollectionTreeRow[] | null>(null)
   useEffect(() => {
-    if (!shouldSyncAdminTreeRows(rows, preserveOptimisticForRows.current, isMoving)) return
+    if (
+      mutation.blocked ||
+      !shouldSyncAdminTreeRows(rows, preserveOptimisticForRows.current, isMoving)
+    )
+      return
     preserveOptimisticForRows.current = null
     setLocalPlaced(rows.filter((r) => !r.unplaced))
-  }, [rows, isMoving])
+  }, [rows, isMoving, mutation.blocked])
 
   const [activeId, setActiveId] = useState<string | null>(null)
   const [overId, setOverId] = useState<string | null>(null)
@@ -186,13 +193,13 @@ export const TreeListView = ({
   }
 
   const handleDragStart = ({ active }: DragStartEvent) => {
-    if (!moveController.isMoving()) setActiveId(String(active.id))
+    if (!mutation.blocked && !moveController.isMoving()) setActiveId(String(active.id))
   }
   const handleDragMove = ({ delta }: DragMoveEvent) => setOffsetLeft(delta.x)
   const handleDragOver = ({ over }: DragOverEvent) => setOverId(over ? String(over.id) : null)
 
   const handleDragEnd = async ({ active, over }: DragEndEvent) => {
-    if (moveController.isMoving()) {
+    if (mutation.blocked || moveController.isMoving()) {
       resetDnd()
       return
     }
@@ -231,10 +238,12 @@ export const TreeListView = ({
       return
     }
 
+    if ('receipt' in outcome) mutation.reportStructure(outcome.receipt)
+    const handled = 'error' in outcome ? mutation.report(outcome.error) : null
     const effects = getAdminTreeMoveUiEffects(outcome)
     if (effects.rollback) setLocalPlaced(current)
 
-    if (effects.structuralFailure != null) {
+    if (!handled && effects.structuralFailure != null) {
       const conflict = effects.structuralFailure === 'conflict'
       toastManager.add({
         title: t(
@@ -318,6 +327,7 @@ export const TreeListView = ({
   return (
     <Section>
       <Container>
+        <DocumentMutationNotice issue={mutation.issue} scheduleNotice={mutation.scheduleNotice} />
         <div className={cx('byline-coll-list-head', styles.head)}>
           <h1 className={cx('byline-coll-list-title', styles.title)}>{collectionLabels.plural}</h1>
           <span className={cx('byline-coll-list-stats', styles.stats)}>
@@ -380,7 +390,7 @@ export const TreeListView = ({
                         key={row.id}
                         id={row.id}
                         dragging={row.id === activeId}
-                        disabled={isMoving}
+                        disabled={mutation.blocked || isMoving}
                         dragHandleLabel={t('collections.list.dragHandleAriaLabel')}
                       >
                         {renderCells(row, depth)}

package/src/admin-shell/collections/version-history.tsx

@@ -1,3 +1,5 @@
+import { DocumentMutationNotice } from '../document-mutation-notice.js'
+import { useDocumentMutationState } from '../document-mutation-state.js'
 /**
  * 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
@@ -55,6 +57,7 @@ interface VersionHistoryRowContext {
   actionLabel: string
   restoreStatusLabel: string
   openCompare: () => void
+  mutationsBlocked: boolean
   openRestore: () => void
 }
 
@@ -126,9 +129,10 @@ export function VersionHistoryCore({
   rowPresentation: VersionHistoryRowPresentation
   loadHistoricalVersion: HistoricalVersionLoader
   onPageSizeChange: (pageSize: number) => void
-  restoreVersion: (versionId: string) => Promise<unknown>
+  restoreVersion: (versionId: string, expectedRevision: number) => Promise<unknown>
   onRestoreComplete: () => void | Promise<void>
 }) {
+  const mutation = useDocumentMutationState(currentDocument)
   const { t } = useTranslation('byline-admin')
   const [selectedVersion, setSelectedVersion] = useState<{
     versionId: string
@@ -150,6 +154,7 @@ export function VersionHistoryCore({
 
   return (
     <>
+      <DocumentMutationNotice issue={mutation.issue} />
       <div className={cx('byline-coll-history-options', styles.options)}>
         <RouterPager
           page={data.meta.page}
@@ -195,7 +200,7 @@ export function VersionHistoryCore({
                 setSelectedVersion({ versionId, label: versionLabel })
               }
               const openRestore = () => {
-                if (versionId == null || versionId === currentVersionId) return
+                if (mutation.blocked || versionId == null || versionId === currentVersionId) return
                 setRestoreTarget({ versionId, label: versionLabel, versionNumber })
               }
 
@@ -228,6 +233,7 @@ export function VersionHistoryCore({
                       actionLabel,
                       restoreStatusLabel,
                       openCompare,
+                      mutationsBlocked: mutation.blocked,
                       openRestore,
                     })}
                   </Table.Row>
@@ -334,11 +340,15 @@ export function VersionHistoryCore({
           </Modal.Header>
           {restoreTarget ? (
             <RestoreVersionModal
+              disabled={mutation.blocked}
+              onMutationError={mutation.report}
               versionLabel={restoreTarget.label}
               versionNumber={restoreTarget.versionNumber}
               restoreStatusLabel={restoreStatusLabel}
               onClose={() => setRestoreTarget(null)}
-              restoreVersion={() => restoreVersion(restoreTarget.versionId)}
+              restoreVersion={() =>
+                restoreVersion(restoreTarget.versionId, mutation.expectedRevision())
+              }
               onRestoreComplete={onRestoreComplete}
             />
           ) : null}

package/src/admin-shell/document-mutation-notice.tsx

@@ -0,0 +1,45 @@
+import { useEffect, useRef } from 'react'
+
+import { useTranslation } from '@byline/i18n/react'
+import { Alert, Button } from '@byline/ui/react'
+
+import { getAdminRoutePath } from '../routes/admin-path.js'
+import type { DocumentMutationIssue } from './document-mutation-state.js'
+
+/** Persistent recovery for list, history and schedule views without local form drafts. */
+export function DocumentMutationNotice({
+  issue,
+  scheduleNotice = false,
+}: {
+  issue: DocumentMutationIssue | null
+  scheduleNotice?: boolean
+}) {
+  const { t } = useTranslation('byline-admin')
+  const warning = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    if (issue) warning.current?.focus()
+  }, [issue])
+  if (!issue && !scheduleNotice) return null
+  return (
+    <div ref={warning} tabIndex={-1} role="alert" aria-live="assertive">
+      {issue && (
+        <Alert close={false} intent="warning" title={t(`documentConcurrency.${issue}Title`)}>
+          <p>{t(`documentConcurrency.${issue}`)}</p>
+          {issue !== 'committed' && (
+            <Button type="button" onClick={() => window.location.reload()}>
+              {t('documentConcurrency.reloadAction')}
+            </Button>
+          )}
+        </Alert>
+      )}
+      {scheduleNotice && (
+        <Alert close={false} intent="warning" title={t('documentConcurrency.schedulesTitle')}>
+          <p>{t('documentConcurrency.schedules')}</p>
+          <a href={getAdminRoutePath('scheduled-publications')}>
+            {t('documentConcurrency.reviewSchedules')}
+          </a>
+        </Alert>
+      )}
+    </div>
+  )
+}

package/src/admin-shell/document-mutation-state.test.tsx

@@ -0,0 +1,146 @@
+import { act } from 'react'
+
+import {
+  ERR_DOCUMENT_HOOK_COMMITTED,
+  ERR_DOCUMENT_STALE,
+  ERR_LOCK_CONFLICT,
+  ERR_VALIDATION,
+} from '@byline/core'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { useDocumentMutationState } from './document-mutation-state.js'
+
+type Observation = { id: string; versionId: string; revision?: number; fields: { title: string } }
+let state: ReturnType<typeof useDocumentMutationState<Observation>>
+let root: Root
+let container: HTMLDivElement
+function Probe({ observation }: { observation: Observation | null }) {
+  state = useDocumentMutationState(observation)
+  return null
+}
+const original: Observation = {
+  id: 'doc',
+  versionId: 'v1',
+  revision: 7,
+  fields: { title: 'Opened' },
+}
+const render = (observation: Observation | null) =>
+  act(() => root.render(<Probe observation={observation} />))
+beforeEach(() => {
+  Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true })
+  container = document.createElement('div')
+  root = createRoot(container)
+  render(original)
+})
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT')
+})
+const stale = ERR_DOCUMENT_STALE({
+  message: 'Test failure',
+  details: {
+    reason: 'revision_mismatch',
+    documentId: 'doc',
+    expectedRevision: 7,
+    currentRevision: 8,
+  },
+})
+
+describe('editor observation ownership', () => {
+  it('does not attach a background metadata revision to the opened fields', () => {
+    render({ ...original, revision: 8 })
+    expect(state.document).toBe(original)
+    expect(state.expectedRevision()).toBe(7)
+  })
+  it('adopts its own structural receipt without discarding fields and surfaces schedule suspension', () => {
+    act(() =>
+      state.adopt({ documentId: 'doc', revision: 8, scheduledPublicationsNeedReconfirmation: true })
+    )
+    expect(state.document).toBe(original)
+    expect(state.expectedRevision()).toBe(8)
+    expect(state.scheduleNotice).toBe(true)
+    const refreshed = { ...original, revision: 8 }
+    render(refreshed)
+    expect(state.document).toBe(refreshed)
+  })
+  it.each([
+    ['stale', stale],
+    [
+      'reload',
+      ERR_VALIDATION({ message: 'Test failure', details: { reason: 'missing_document_revision' } }),
+    ],
+    [
+      'lock',
+      ERR_LOCK_CONFLICT({
+        message: 'Test failure',
+        details: { reason: 'lock_conflict', rolledBack: true, retryable: true },
+      }),
+    ],
+    ['unavailable', { code: 'ERR_NOT_FOUND' }],
+  ])(
+    'blocks every later call after %s without adopting fresh data or a late receipt',
+    (issue, error) => {
+      act(() => {
+        expect(state.report(error)).toBe('blocked')
+      })
+      render({ ...original, revision: 9 })
+      act(() => state.adopt({ documentId: 'doc', revision: 8 }))
+      expect(state.issue).toBe(issue)
+      expect(state.blocked).toBe(true)
+      expect(state.document).toBe(original)
+      expect(state.revision).toBe(7)
+      expect(() => state.assertWritable()).toThrow()
+      expect(() => state.expectedRevision()).toThrow()
+    }
+  )
+  it('keeps a rejected empty singleton empty until a new editor session', () => {
+    act(() => root.unmount())
+    root = createRoot(container)
+    render(null)
+    const error = ERR_DOCUMENT_STALE({
+      message: 'Test failure',
+      details: {
+        reason: 'singleton_slot_changed',
+        singletonPath: 'settings',
+        expectedState: 'empty',
+        currentState: 'document',
+      },
+    })
+    act(() => {
+      state.report(error)
+    })
+    render(original)
+    expect(state.document).toBeNull()
+    expect(state.blocked).toBe(true)
+  })
+  it('keeps committed hook failures distinct and advances only to the committed revision', () => {
+    const error = ERR_DOCUMENT_HOOK_COMMITTED({
+      message: 'Test failure',
+      details: {
+        phase: 'afterUpdate',
+        documentId: 'doc',
+        documentVersionId: 'v2',
+        revision: 8,
+        sideEffectCode: 'ERR_UNHANDLED',
+      },
+    })
+    act(() => {
+      expect(state.report(error)).toBe('committed')
+    })
+    expect(state.issue).toBe('committed')
+    expect(state.blocked).toBe(false)
+    expect(state.expectedRevision()).toBe(8)
+  })
+  it('does not classify arbitrary conflicts or uncertain driver failures as safe rollback', () => {
+    for (const error of [
+      { code: 'ERR_CONFLICT' },
+      new Error('deadlock SQL secret'),
+      { code: 'ECONNRESET' },
+    ]) {
+      expect(state.report(error)).toBeNull()
+    }
+    expect(state.blocked).toBe(false)
+  })
+})

package/src/admin-shell/document-mutation-state.ts

@@ -0,0 +1,95 @@
+import { useRef, useState } from 'react'
+
+import {
+  ErrorCodes,
+  getDocumentRevisionValidationDetails,
+  getDocumentStaleDetails,
+  getLockConflictDetails,
+  parseDocumentRevision,
+} from '@byline/core'
+import { getDocumentHookCommittedDetails } from '@byline/core/services'
+
+import { committedTreeReceipt, structuralReceipt } from '../server-fns/structural-receipt.js'
+
+export type DocumentMutationIssue = 'stale' | 'reload' | 'lock' | 'unavailable' | 'committed'
+
+function documentMutationIssue(error: unknown): DocumentMutationIssue | null {
+  if (getDocumentStaleDetails(error)) return 'stale'
+  if (getDocumentRevisionValidationDetails(error)) return 'reload'
+  if (getLockConflictDetails(error)) return 'lock'
+  if (getDocumentHookCommittedDetails(error) || committedTreeReceipt(error)) return 'committed'
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    Reflect.get(error, 'code') === ErrorCodes.NOT_FOUND
+  )
+    return 'unavailable'
+  return null
+}
+
+/** A rejected observation stays frozen until an explicit editor reload. */
+export function useDocumentMutationState<
+  T extends { id?: unknown; versionId?: unknown; revision?: unknown },
+>(document: T | null | undefined) {
+  const [issue, setIssue] = useState<DocumentMutationIssue | null>(null)
+  const [scheduleNotice, setScheduleNotice] = useState(false)
+  const [, setReceiptRevision] = useState<number | undefined>()
+  const blockedError = useRef<unknown>(undefined)
+  const observation = useRef({ identity: document, revision: document?.revision })
+  if (
+    observation.current.identity !== document &&
+    blockedError.current === undefined &&
+    document?.revision === observation.current.revision
+  ) {
+    observation.current = { identity: document, revision: document?.revision }
+  }
+  const assertWritable = () => {
+    if (blockedError.current !== undefined) throw blockedError.current
+  }
+  const expectedRevision = () => {
+    assertWritable()
+    return parseDocumentRevision(observation.current.revision)
+  }
+  const adopt = (receipt: {
+    documentId: string
+    revision: number
+    scheduledPublicationsNeedReconfirmation?: boolean
+  }) => {
+    if (blockedError.current !== undefined) return
+    if (document?.id != null && receipt.documentId !== document.id) return
+    observation.current.revision = parseDocumentRevision(receipt.revision)
+    setReceiptRevision(receipt.revision)
+    if (receipt.scheduledPublicationsNeedReconfirmation) setScheduleNotice(true)
+  }
+  const reportStructure = (result: unknown) => {
+    const receipt = structuralReceipt(result)
+    if (receipt) adopt(receipt)
+  }
+  const report = (error: unknown): 'blocked' | 'committed' | null => {
+    const kind = documentMutationIssue(error)
+    if (kind === null) return null
+    if (kind === 'committed') {
+      if (blockedError.current !== undefined) return 'blocked'
+      const details = getDocumentHookCommittedDetails(error) ?? committedTreeReceipt(error)
+      if (details) adopt(details)
+      setIssue(kind)
+      return 'committed'
+    }
+    blockedError.current = error
+    setIssue(kind)
+    return 'blocked'
+  }
+  return {
+    issue,
+    blocked: issue !== null && issue !== 'committed',
+    scheduleNotice,
+    document: observation.current.identity,
+    revision:
+      typeof observation.current.revision === 'number' ? observation.current.revision : undefined,
+    expectedRevision,
+    assertWritable,
+    adopt,
+    report,
+    reportStructure,
+  }
+}