Skip to content

Whole-company replacement: one suspended-replacement function - #2091

Merged
Kevinjohn merged 116 commits into
issue/2018-planning-cache-splitfrom
issue/2020-suspended-replacement
Nov 16, 2026
Merged

Kevinjohn merged 116 commits into
issue/2018-planning-cache-splitfrom
issue/2020-suspended-replacement

Conversation

@Kevinjohn

@Kevinjohn Kevinjohn commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

What and why

The whole-company replacement protocol (check readiness, suspend planning writes, send, then refresh or require a reload) was written five times, mostly inside view code, with small differences.

  • apps/frontend/src/data/planning/suspendedReplacement.ts runSuspendedReplacement runs it once and returns a typed outcome: blocked, departed, refused, committed or uncertain. Committed and uncertain carry reloadRequired; while it is true, writes stay suspended until a reload.
  • apps/frontend/src/data/companyDataRequests.ts holds the transfer preview and apply and both anonymise requests; URLs, methods, headers and bodies are unchanged.
  • ImportExport.tsx, useServerImport.ts, CompanyAnonymiseSection.tsx, SettingsDataSection.tsx and useLifecycleActions.ts call it and render the outcome. No file under components/ or hooks/ calls apiFetch, suspendPlanningCommands or planningReadyForReplacement.
  • A refused request resumes writes, so its message stays visible and the action can be retried.
  • New suspendedReplacement.test.ts; it goes red when a 502 is treated as a refusal and when writes are never released.

Decisions made without the owner

  • Two recovery modes: company-wide anonymisation reloads and never refreshes or reports "departed", as before (suspendedReplacement.ts:65, :84, :103); the other callers refresh.
  • A rejected refresh is treated as a failed refresh (suspendedReplacement.ts:75). refreshPlanning resolves false rather than throwing, so the old appended error text could practically not appear.
  • Example data shows its busy state before the readiness check, not only after it (SettingsDataSection.tsx:78).
  • The two hard-coded "Finish loading…" notices are now catalogue messages with the same text, and settings_archived_committed_refresh_skipped, whose code path could not run, is removed.

Closes #2020

Gate evidence

  • pnpm run check:changed <predecessor branch>: the frontend suite step hit its 1200-second cap under heavy machine load; a rerun of the suite passed, as did every other step.
  • Pre-push check:push (format, type-check, lint): passed.
  • Validation workflow on this head: run 43910919613
  • Stack tip gate on issue/2027-single-job-files, which contains this branch: gate:all passed (backend 572 tests; frontend 3823 tests) and e2e passed (309 tests). The later scripts-move tip 59ee4999b, which also contains the follow-up merges, passed gate:all and e2e (309).

Merge order

#2063 → #2064 → #2065 → #2066 → #2067 → #2068 → #2069 → #2070 → #2071 → #2072 → #2073 → #2074 → #2075 → #2076 → #2077 → #2078 → #2079 → #2080 → #2081 → #2082 → #2083 → #2084 → #2085 → #2086 → #2087 → #2088 → #2089 → #2090 → #2091

Merge predecessor for this PR: #2090.

One linear stack; each PR targets the previous PR's branch, so no pair of open PRs conflicts.

Closes #1973.

The docs build, navigation check, lightbox runtime and screenshot
publication check now live together in scripts/docs/. Repository-root
lookups gain one level, and the docs workflow path filters, pnpm
commands, ESLint ignores, VitePress config and lightbox test point at
the new paths. Command names and the generated site are unchanged.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #2025.

The sidebar, the command palette and the document title each kept their
own list of routes and repeated the disciplines, capacity overview and
diagnostics visibility decisions. navLinks.ts now holds APP_ROUTES, one
table in sidebar and palette order where each route carries its sidebar
placement and visibility rule. useVisibleRoutes builds the visibility
context from the member's role, permission status and company settings
and lists the visible routes; AppShell and the palette read from it and
the document title looks labels up in the same table.

Which routes each role sees is unchanged, and a new test pins the visible
routes per role, capacity overview setting and disciplines flag. Route
guards and server authorization in route_access.ts are untouched and stay
independent of what the client shows.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…tion

Closes #2020.

Import, company-wide anonymisation, resource anonymisation and example data
each repeated the replacement protocol: check readiness, suspend planning
writes, send, then refresh or require a reload. The copies differed in small
ways and lived mostly in view code.

runSuspendedReplacement in data/planning/suspendedReplacement.ts now owns that
protocol and returns a typed outcome: blocked, departed, refused, committed or
uncertain, with reloadRequired when writes stay suspended. Refused requests
resume writes so the message stays visible and the action can be retried; an
uncertain result reconciles with a fresh read, or keeps writes suspended for a
page reload when that read fails or the caller recovers by reloading.

The transfer preview, transfer apply and both anonymise requests moved to
data/companyDataRequests.ts with unchanged URLs, methods and bodies, so no
component calls apiFetch, suspendPlanningCommands or
planningReadyForReplacement. The two hard-coded "finish loading" notices are
now catalogue messages with the same text, and the never-produced "refresh
skipped" lifecycle message is removed.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #2023.

The schedule, the capacity overview and the Resources list each carried
their own copy of the Studio/Supplementary fallback bands and the
placeholder-last resource order, and seven open-coded checks decided
whether a resource kind was switched on for the company.

apps/frontend/src/lib/resourceGrouping.ts now owns:
- isResourceKindEnabled, the one answer to whether a kind is enabled;
  the palette, allocation and time-off resource pickers, the schedule
  filter, the person schedule, the time-off list and the capacity
  overview use it;
- buildResourceBand and buildEngagementGroups, with every band title
  (Resources, Overall, Unassigned, Unassigned demand, External / 3rd
  party, Studio, Supplementary) read from the message layer;
- createResourceComparator, the one resource order, which the schedule,
  the capacity overview and the Resources list all sort with.

Owner decisions: both placeholder avatar colours stay as they are. The
schedule gives a placeholder its discipline colour (its own colour when
it has none), while the capacity overview gathers placeholders into the
uncoloured Unassigned demand band so they show their own colour; comments
in SchedulerGridRow and CapacityOverviewTableGrid state this as
intended. The Resources list uses the shared order; placeholders and
externals are always Studio, so its order is unchanged.

English is the only locale, so the new titles are added to en.json only.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #2022.

The in-flight guard, the stale-edit check and the handling of a cancelled
save were copied into each entity form, and the forms disagreed on where the
current rows came from: seven read the store singleton at submit time while
the resource form took them as a parameter.

useEditSubmit now owns that protocol. It takes the current rows as an input
(each form subscribes to its slice), refuses a stale edit, saves, closes on
success, keeps the draft open on a blocked create, and shows any other failure
on the form. The activity, client, discipline, external, project, closure,
time-off and resource forms all prepare a validated save and hand it to the
hook; the time-off and resource forms keep their own accepted-submission and
company-switch guards around it.

A save the user cancels in the Restore cleanup dialog now leaves every form
open without an error. The activity, client and project forms already did
this; the discipline, external, closure, time-off and resource forms showed
"The planning save was cancelled." as a form error.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #2035.

The allocation and time-off forms each kept a copy of the repeat and
repeat-until state, and they disagreed about a repeat switched on before
the start date was valid: time off marked the end date as suggested and
filled it once a valid start date arrived, while allocations left it empty.

Owner decision: both forms follow the time-off behaviour. Switching repeat on
always marks the end date as suggested, and it is filled from the form's
default once a valid start date exists.

useRepeatUntil now holds the repeat choice, the repeat-until date and the
suggestion flag, and takes the default-date function as a parameter. The
allocation form passes defaultRepeatUntilDate and the time-off form passes
defaultTimeOffRepeatUntilDate. A new allocation modal test covers repeat
switched on before a valid start; the existing time-off form test covers the
same case for time off.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Refs #2022.

The shared edit-submit hook made every form stay silent when the user
cancels the Restore cleanup dialog. Before it, the discipline, external,
closure, time-off and resource forms showed "The planning save was
cancelled." as the form error, while the activity, client and project
forms stayed open with no error.

useEditSubmit now takes an optional cancelledMessage. The five forms that
showed the message pass resolveErrorMessage, which produced it before, and
the other three omit it, so every form behaves as it did before the hook.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…-until-hook

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #1974.

The port registry, lane claims, launcher, demo and full-stack runners and
the port guard now live together in scripts/dev/. Imports from Vite,
VitePress, Playwright, the backend test runner, end-to-end support and
the remaining scripts follow the new paths, as do the port guard's file
list and messages, the docs workflow path filter, package scripts and
the user story source links. Repository-root lookups gain one level.
Command names and behaviour are unchanged.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #2024.

Gesture helpers now take their inputs instead of reading the store:
gestureWorkingWeeks takes a GestureCalendar (resources and the company
working week), and gestureAnnouncements splits the visible-window
over-capacity count (buildVisibleOverCapacity) from its message
(formatCapacityAnnouncement). useAllocationGestureController is the one
place that reads the live store, at the moment of each call, so commits
and keyboard actions still see the current calendar and a preview frame
for a known lane still reads nothing.

The inline Add activity path in useAllocationModalState no longer
serialises the whole data slice to decide whether its draft may follow
the new revision. isSoleAcknowledgedAdvance in planningCacheController
answers it from planning metadata: same context, revision exactly one
past the draft's, and that revision acknowledged. Each committed change
advances the company revision by one, so this admits the same cases as
the old row comparison.

Shared pieces leave the scheduler folder so person-schedule, time off and
the capacity overview no longer import scheduler internals:
useCalendarToday moves to hooks/, buildAllocationAttribution to lib/, and
the renderable date-range checks to lib/renderableDateRanges.ts. The
Draft and Patch types move from store/entityDrafts.ts to
lib/entityDrafts.ts, so lib/ no longer imports from store/. No behaviour
changes.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #2021.

The single accountClient object covered sessions, companies, diagnostics,
example data, members, avatars, invitations, masquerade, admission and
invitation sign-up, and handed raw responses to screens that then read status
codes and decoded bodies themselves.

The raw requests now live in one module per concern: sessionRequests,
memberRequests, invitationRequests, admissionRequests, masqueradeRequests and
invitationSignupRequests, plus companyDataRequests for example data. Every
URL, method, header and body is unchanged, and createInvitation keeps its
masquerade-context race check. Each module is read only by its typed client:
teamAccessClient, ownershipTransferAccess, masqueradeApi, fetchAuthStatus and
the company directory reader.

Screens that read responses themselves now call typed readers instead:
invitationSignupClient returns preview and sign-up results, the getting-started
client returns the dismissed flag, readServerDiagnostics returns one
observation, readSoleCompanyOwnership answers the setup-conflict check, and
readImportSummary decodes a committed import. No component inspects a
response status or parses a body.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #2026.

Backend:
- executePlanningIntent takes one ExecutePlanningIntentOptions object
  instead of six positional parameters. Its body is unchanged, so the
  write-access refusal, the company check, the writes and the caller's
  revision and audit steps in mutatePlanning keep their order.
- PlanningCapabilities drops canAnonymise, which was computed for every
  operation and never read, and takes its role type from the shared Role
  instead of re-listing the four roles. PlanningAuthority extends it, so
  authority.ts no longer repeats the capability fields.

Frontend:
- sendPlanningCommand no longer accepts an `original` argument; the
  planning session never read it, and typedPlanningActions stops
  passing it.
- createTypedPlanningActions takes a getter typed to the two store
  fields it reads (data and sendPlanningCommand) rather than the whole
  StoreState.
- SchedulerGrid calls useSchedulerGridVirtualization with the four
  values it needs instead of a wrapper that took three whole hook
  results, and its modal boundary and footer take the modal state and
  the visible closures instead of the whole interactions and
  virtualization results.

useMembersOrchestration's return stays as it is: its one consumer,
MembersSection, uses nearly every key and already hands each child a
Pick of it. SchedulerGridRow's props are all read by the row or the
header and lane it renders.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #1975.

The bundle budget, SPA route checks, Paraglide parity check, static route
list and the Adonis public sync now live together in scripts/build/.
The sync script and parity check resolve the repository root one level
higher; the budget and route checks keep reading dist/ from the working
directory. Package scripts, workflow build steps, frontend imports,
ESLint allowances and the tests that read or copy these files follow
the new paths. Command names and behaviour are unchanged.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Refs #2021.

The documentation policy check found user-story links to the deleted
accountClient.ts. Each story now names the request module or typed client that
replaced the method it describes.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #1976.

The Playwright run mode, worker runtime and guardian, preset and browser
runners, the production rehearsal server and their tests now live
together in scripts/e2e/; browser scenarios stay in e2e/. Playwright
config, the end-to-end type-check project, frontend and backend tests,
ESLint allowances, the port guard's file list and package scripts follow
the new paths. The changed-file selector's end-to-end input pattern now
matches scripts/e2e/playwright*, and the preset path test copies its
files into the same folder layout. Command names and behaviour are
unchanged.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #2027.

Each move keeps behaviour; only where code lives changes.

- packages/shared dateMath: the time-zone resolver moves to
  lib/calendarToday.ts and the working-week policy to lib/workingWeek.ts.
  resolveCalendarToday returns a typed result and reports an invalid zone to
  its caller with the local-date fallback instead of calling console.warn.
  The frontend's readCalendarToday keeps the same fallback and the bounded
  console breadcrumb; the backend example-data service logs the zone instead.
- useLifecycleActions: resource anonymisation and its reload gate move to
  data/resourceAnonymisation.ts; the hook keeps archive and restore and the
  shared queue.
- useAppShellController: account entry, page effects, notices and global
  shortcuts move to components/app-shell/; the controller composes them in
  the same order.
- useTeamDirectory: the member action lock moves to useTeamActionLock.
- e2e_reset_control: the HTTP listener retirement and its timeout helper move
  to start/e2e_retirable_listener.ts.

lib/dateDisplay.ts stays combined: its formatters and the date-style mirror
are one job, date presentation, and passing the style through every caller
would change the API of about fifteen call sites rather than split the file.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…ded-replacement

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…nt-client-results

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…-submit-protocol

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…ce-grouping

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…-boundaries

Resolves the split of planningCacheController.ts from #2018:
isSoleAcknowledgedAdvance joins the other readiness predicates in
planningReadiness.ts, its test moves beside that module, and imports of
PlanningControllerError and the metadata type use the modules that now
declare them.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Part of #2022. After merging #2018's split of planningCacheController.ts,
the External form test imports the error class from planningErrors.ts.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…ce-grouping

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…-boundaries

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…-route-table

Resolves the import conflicts: AppShell reads readPlanningProblem from
planningNotices.ts after #2018's split and no longer needs the capacity
overview route anchor, and buildPaletteItems keeps the route table type
from #2025 together with the shared resource-kind predicate from #2023.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…ntil-hook

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…ntracts

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…-files

Resolves the conflicts with #2027's splits: the document title in
app-shell/pageEffects.ts reads the #2025 route table, globalShortcuts.ts
imports isShownByPlanningState from planningNotices.ts after #2018, and
ClosureForm keeps #2027's calendar reader without the ref #2022 removed.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Closes #1977.

The changed-file selector, gate runner and command list, pre-push hook,
Node 26 check and workflow outcome report now live together in
scripts/ci/, and the gate command fixture moves to scripts/ci/fixtures/.
The Git hook, package scripts, workflow run steps (including the
tooling and static scope selection in gate.yml and static-analysis.yml)
and CONTRIBUTING.md follow the new paths, and repository-root lookups
gain one level.

The selector now matches script files in any scripts/ subfolder and
finds the test files that import a script by their relative path, so a
change to a moved script still selects its tests. Its fixtures name the
moved paths. Command names are unchanged.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Part of #2031.

Step 3.1. The 33 AuthProvider tests move unchanged into six files beside
AuthProvider.tsx, each keeping its describe title:
- AuthProvider.test.tsx: when tenant data opens, closes and refreshes,
  and the limited screens that hold it back;
- AuthProvider.bootCheck.test.tsx: the /api/auth/me request and the
  fail-closed error boundary;
- AuthProvider.signInWall.test.tsx: 401 outcomes, invite routes and the
  setup notice;
- AuthProvider.masqueradeBootstrap.test.tsx: booting into an active
  member view;
- AuthProvider.sessionRecheck.test.tsx: refreshAuth and the planning 401
  re-check;
- AuthProvider.companySetup.test.tsx: first company setup.
me, freshProvider and deferred move to AuthProvider.testSupport.ts and
SessionProbe to src/test/SessionProbe.tsx, since lint allows a .tsx
module to export components only. Each file keeps its own masqueradeApi
mock and afterEach, because vi.mock is hoisted per file. The ordered
tests and hooks of the old file, with describe path and whitespace-free
body, match the new files with no differences.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Part of #1975. The .dockerignore rule **/build also matched the new
scripts/build/ folder, so the image's pnpm run build would not find
the build tooling it runs. Re-include that folder; other build output
stays excluded.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…ntenance

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…-shared

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…ing-docs

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Stop committing the generated documentation site
Move the shared pnpm process helper into scripts/shared/
Move repository maintenance checks into scripts/maintenance/
Move release packaging and smoke tests into scripts/release/
Move CI selection, gates and reporting into scripts/ci/
Move browser-test infrastructure into scripts/e2e/
Move application build tooling into scripts/build/
Move local development and port management into scripts/dev/
Move documentation tooling into scripts/docs/
…unt-request-tests

Tests: split the account request tests by module
…uerade-controller-tests

Tests: split the masquerade controller tests by concern
…ning-cache-tests

Tests: split the planning cache controller tests by concern
…-provider-tests

Tests: split the AuthProvider tests by concern
Split smaller files that hold a second unrelated job
Narrow contracts that are wider than their consumers
Repeat end date: one hook for the allocation and time-off forms
Scheduler: pure gesture helpers, planning-owned revision checks, no feature cycle
Resource grouping and kind rules: one module for schedule and capacity overview
…ults

Account client: typed results and a split by concern
@Kevinjohn
Kevinjohn merged commit 51380f1 into issue/2018-planning-cache-split Nov 16, 2026
2 checks passed
@Kevinjohn
Kevinjohn deleted the issue/2020-suspended-replacement branch November 16, 2026 23:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

polish-done Polish review complete

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant