feat(29.6): route Schedules 2/3/4/5/8 through the shared guarded run()

Story 1.6 (tech hardening), completing the sweep started with Schedule 1.
Every schedule save/delete/check-status now dispatches through
useScheduleBanners.run() (via useScheduleMutations), so a stale in-flight
write can no longer repaint a newly-switched mill/year context, and the
request/error/lock scaffolding lives in one place.

- Schedules 2, 3, 4, 8: adopt useScheduleMutations; drop the hand-rolled
  apiService...put/post/delete().then().catch().finally() chains and (where
  present) the separate `checking` lock (folds into the single `saving`).
- Schedule 5: drop its local runMutation and adopt the shared hook. To keep
  its silent copy-hint resolve, useScheduleBanners.run() now accepts a null
  fallback = "fail silently, no banner" (backward-compatible; every existing
  caller passes a string). All five call sites reproduce their URLs verbatim.
- Delete convergence (AC6): one shared mechanism; each page's post-delete
  empty-state stays at the call site — Schedules 1/3 reset in place (a re-GET
  would 404), list pages 2/4/8 re-seed from a reload, Schedule 5 re-seeds from
  its DELETE response.
- Added a Schedule 1 stale-response regression test (AC1): a mill/year switch
  mid-save no longer applies the late PUT.

Behavior unchanged (AC7): full frontend suite 887 -> 888 green, tsc + eslint clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gpascucci

frontend/src/components/schedule1/__tests__/Schedule1.test.tsx

@@ -16,6 +16,32 @@ vi.mock('@tanstack/react-router', () => ({
 
 import Schedule1 from '@/components/schedule1'
 import MillYearProvider from '@/context/millYear/MillYearProvider'
+import useMillYear from '@/context/millYear/useMillYear'
+
+// Drives a mid-save mill/year change so the shared run() stale-response guard can be exercised
+// (Story 29.6). Module-level so it is not re-created per render (an @eslint-react rule forbids nested
+// component definitions).
+const StaleRaceHarness = () => {
+  const { setContext } = useMillYear()
+  return (
+    <>
+      <button type="button" onClick={() => setContext(999, 2020)}>
+        change
+      </button>
+      <Schedule1 />
+    </>
+  )
+}
+
+// Deterministically drain the event loop so a settled-but-guarded request finishes its whole
+// then/catch/finally chain before a negative assertion runs (turn-based, never wall-clock).
+const flushAsync = async () => {
+  for (let i = 0; i < 4; i += 1) {
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0)
+    })
+  }
+}
 
 const URL = 'http://localhost:3000/api/v1/schedule1'
 
@@ -663,3 +689,56 @@ describe('Schedule1 Other Costs navigation (Story 2.5)', () => {
     expect(mockNavigate).toHaveBeenCalledWith({ to: '/schedule-1/other-costs' })
   })
 })
+
+describe('Schedule1 stale-response guard (Story 29.6)', () => {
+  test('a mill/year change mid-save does not apply the stale response (AC1)', async () => {
+    // The PUT is gated on an explicit release, not a wall-clock delay, so the "stale response settles
+    // after the context change" ordering holds under any CI load. Routing save through the shared
+    // useScheduleMutations run() gives Schedule 1 the isCurrent() guard it previously lacked.
+    let releasePut = () => {}
+    const putGate = new Promise<void>((resolve) => {
+      releasePut = resolve
+    })
+    server.use(
+      http.get(URL, ({ request }) =>
+        request.url.includes('millId=999')
+          ? HttpResponse.json({
+              ...schedule1Doc,
+              millId: 999,
+              year: 2020,
+              editable: false,
+              comments: 'Context 999/2020 loaded',
+            })
+          : HttpResponse.json(schedule1Doc),
+      ),
+      http.put(URL, async () => {
+        await putGate
+        return HttpResponse.json({
+          ...schedule1Doc,
+          message: { key: 'dataSavedSuccesfullyInfoMsg', text: 'Data saved successfully' },
+        })
+      }),
+    )
+
+    render(
+      <MillYearProvider initial={{ millId: 514, year: 2021 }}>
+        <StaleRaceHarness />
+      </MillYearProvider>,
+    )
+    const user = userEvent.setup()
+
+    // Editable 514 loaded → dispatch the save (PUT now in flight) → switch mill/year before it settles.
+    await screen.findByLabelText('Standing Tree to Loaded Truck cost')
+    await user.click(screen.getAllByRole('button', { name: /^save$/i })[0])
+    await user.click(screen.getByRole('button', { name: /change/i }))
+
+    // The new context's document has rendered (read-only 999/2020).
+    expect(await screen.findByText('Context 999/2020 loaded')).toBeInTheDocument()
+
+    // Release the stale PUT, let its chain settle, then confirm nothing from it landed on 999/2020.
+    releasePut()
+    await flushAsync()
+    expect(screen.queryByText('Data saved successfully')).not.toBeInTheDocument()
+    expect(screen.queryByLabelText('Standing Tree to Loaded Truck cost')).not.toBeInTheDocument()
+  })
+})

frontend/src/components/schedule2/index.tsx

@@ -2,7 +2,7 @@ import type { FC } from 'react'
 import type Schedule2Response from '@/interfaces/Schedule2Response'
 import type { CostBlock, CheckStatusResponse } from '@/interfaces/Schedule2Response'
 import type Schedule2Request from '@/interfaces/Schedule2Request'
-import { useCallback, useState } from 'react'
+import { useState } from 'react'
 import {
   Button,
   Column,
@@ -18,9 +18,9 @@ import {
   TextArea,
 } from '@carbon/react'
 import apiService from '@/service/api-service'
-import useMillYear from '@/context/millYear/useMillYear'
+import { useScheduleContextGuard } from '@/hooks/useScheduleContextGuard'
 import { useScheduleDocument } from '@/hooks/useScheduleDocument'
-import { extractDetail } from '@/utils/error'
+import { useScheduleMutations } from '@/hooks/useScheduleMutations'
 import { fmtCurrency, fmtNumber, numStr, toNum } from '@/utils/number'
 import CommaNumberInput from '@/components/core/CommaNumberInput'
 import LoadingScreen from '@/components/core/LoadingScreen'
@@ -79,22 +79,28 @@ function buildRequest(doc: Schedule2Response, form: FieldValues): Schedule2Reque
 }
 
 const Schedule2: FC = () => {
-  const { millId, year } = useMillYear()
-  const contextMissing = millId === null || year === null
+  const { millId, year, contextMissing, isCurrent } = useScheduleContextGuard()
+
+  // Save/delete/check-status all run through the shared hook's guarded run() (Story 29.6): a stale
+  // in-flight write can no longer repaint a newly-switched mill/year. `saving` is the single in-flight
+  // lock for every write (it also gates Check Status). `checkResult` holds the Check Status response.
+  const {
+    saving,
+    message: saveMessage,
+    actionError: saveError,
+    checkResult: statusMessages,
+    setMessage: setSaveMessage,
+    setActionError: setSaveError,
+    setCheckResult: setStatusMessages,
+    clearBanners,
+    resetBanners,
+    save,
+    remove,
+    checkStatus,
+  } = useScheduleMutations<CheckStatusResponse>({ path: '/v1/schedule2', millId, year, isCurrent })
 
-  const [saving, setSaving] = useState(false)
-  const [saveMessage, setSaveMessage] = useState<string | null>(null)
-  const [saveError, setSaveError] = useState<string | null>(null)
-  const [statusMessages, setStatusMessages] = useState<CheckStatusResponse | null>(null)
   const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false)
 
-  // Clear the mutation notifications whenever a fresh document loads (mill/year change).
-  const resetMessages = useCallback(() => {
-    setSaveMessage(null)
-    setSaveError(null)
-    setStatusMessages(null)
-  }, [])
-
   const { data, setData, form, setForm, setField, errorDetail, isLoading } =
     useScheduleDocument<Schedule2Response>({
       path: '/v1/schedule2',
@@ -103,7 +109,7 @@ const Schedule2: FC = () => {
       contextMissing,
       seedForm,
       mapLoadError,
-      onReset: resetMessages,
+      onReset: resetBanners,
     })
 
   const handleSave = () => {
@@ -119,58 +125,43 @@ const Schedule2: FC = () => {
       setSaveError('Please correct the highlighted fields before saving.')
       return
     }
-    setSaving(true)
-    setSaveMessage(null)
-    setSaveError(null)
-    setStatusMessages(null)
-    apiService
-      .getAxiosInstance()
-      .put<Schedule2Response>(
-        `/v1/schedule2?millId=${millId}&year=${year}`,
-        buildRequest(data, form),
-      )
-      .then((response) => {
-        setData(response.data)
-        setForm(seedForm(response.data))
+    clearBanners() // drop any prior banners incl. a now-stale Check Status result
+    save<Schedule2Response>(buildRequest(data, form), {
+      fallback: 'Schedule could not be saved.',
+      onSuccess: (doc) => {
+        setData(doc)
+        setForm(seedForm(doc))
         // Success text verbatim from the API message field (AD-8), never hardcoded.
-        setSaveMessage(response.data.message?.text ?? null)
-      })
-      .catch((error: unknown) => {
-        // Keep the entered values; surface the API's verbatim ProblemDetail.detail.
-        setSaveError(extractDetail(error) || 'Schedule could not be saved.')
-      })
-      .finally(() => setSaving(false))
+        setSaveMessage(doc.message?.text ?? null)
+      },
+    })
   }
 
   const handleDelete = () => {
     if (saving) {
       return
     }
     setConfirmDeleteOpen(false)
-    setSaving(true)
-    setSaveMessage(null)
-    setSaveError(null)
-    setStatusMessages(null)
-    const api = apiService.getAxiosInstance()
-    api
-      .delete<{ message?: { text?: string } }>(`/v1/schedule2?millId=${millId}&year=${year}`)
-      .then((response) => {
-        const deleteMessage = response.data?.message?.text ?? null
-        // Schedule 2 never 404s: with the summary gone, a re-GET returns the 200 empty EDITABLE
-        // document (revisionCount null). Reload it so the meta row / form reflect reality and the
-        // Licensee can immediately re-enter data (legacy AF1), while keeping the API delete message.
-        return api
+    clearBanners() // the deleted schedule's check result / save banner are stale
+    remove<{ message?: { text?: string } }>({
+      fallback: 'Unable to delete Schedule 2.',
+      // Schedule 2 never 404s: with the summary gone, a re-GET returns the 200 empty EDITABLE
+      // document (revisionCount null). Reload it so the meta row / form reflect reality and the
+      // Licensee can immediately re-enter data (legacy AF1), while keeping the API delete message.
+      // This per-page empty-state lives at the call site (Story 29.6): list/re-GET pages re-seed
+      // from the reload, single-doc reset-in-place pages (Schedules 1/3) reset in place instead.
+      onSuccess: (delResp) => {
+        const deleteMessage = delResp?.message?.text ?? null
+        apiService
+          .getAxiosInstance()
           .get<Schedule2Response>(`/v1/schedule2?millId=${millId}&year=${year}`)
           .then((reload) => {
             setData(reload.data)
             setForm(seedForm(reload.data))
             setSaveMessage(deleteMessage)
           })
-      })
-      .catch((error: unknown) => {
-        setSaveError(extractDetail(error) || 'Unable to delete Schedule 2.')
-      })
-      .finally(() => setSaving(false))
+      },
+    })
   }
 
   const handleCheckStatus = () => {
@@ -187,20 +178,11 @@ const Schedule2: FC = () => {
       setSaveError('Please correct the highlighted fields before checking status.')
       return
     }
-    setSaving(true)
-    setSaveMessage(null)
-    setSaveError(null)
-    setStatusMessages(null)
-    apiService
-      .getAxiosInstance()
-      .post<CheckStatusResponse>(`/v1/schedule2/check-status?millId=${millId}&year=${year}`)
-      .then((response) => {
-        setStatusMessages(response.data)
-      })
-      .catch((error: unknown) => {
-        setSaveError(extractDetail(error) || 'Unable to check status.')
-      })
-      .finally(() => setSaving(false))
+    clearBanners() // don't leave a stale Save success banner beside a new check result
+    checkStatus<CheckStatusResponse>({
+      fallback: 'Unable to check status.',
+      onSuccess: setStatusMessages,
+    })
   }
 
   if (contextMissing) {