fix(SDK-1291): poll payroll processing without depending on re-renders

[mariechatfield]

Summary

• PayrollConfiguration, PayrollOverview, and PrintChecksForm each drove a poll off a query's refetchInterval and decided completion in a useEffect reading rendered query data. That makes "is this done?" a function of whether the query observer notifies the component of new data. When it doesn't, the operation finishes correctly server-side and the screen never advances.
• PayrollOverview is the worse case: its main query is non-suspense and gates the whole screen on !payrollData, so a dropped notification freezes the very first read, not just a later one.
• PrintChecksForm had no deadline/failsafe at all, so a stuck poll would spin indefinitely with no way out.
• Adds usePollingTask: a hook whose loop owns its own timer, reads the server directly each tick, and evaluates the terminal state inside its own closure — independent of whether the component ever re-renders. Converts all three surfaces to it, adding a 3-minute deadline (verified against the server before reporting failure) to PrintChecksForm for parity with the other two.
• Extracts each surface's completion logic into a per-domain hook (useCalculationPoll, useSubmissionPoll, useGenerationPoll) that wraps usePollingTask with the domain's own evaluate/onDeadline rules, keeping the three components thin. The interval (5s) and deadline (3min) were identical across all three call sites with no reason to vary, so they're now defaults on usePollingTask itself (DEFAULT_POLL_INTERVAL_MS / DEFAULT_POLL_DEADLINE_MS) rather than a constant redeclared three times.
• useCalculationPoll/useSubmissionPoll poll through the render query's own refetch instead of building a second query. Live-repro on sdk-app surfaced a real hang under this exact fix: each hook built an independent query (via queryClient.fetchQuery + buildPayrollsGetQuery) for the same queryKey the component's own usePayrollsGet(Suspense) call already observes. The submit mutation's global invalidateQueries (see createSdkQueryClient) triggers a background refetch on that same key at nearly the same instant the poll's first tick starts, and TanStack can silently orphan one of the two promises rather than settling it — the poll's await read(...) then hangs forever, no error, well before its own 3-minute deadline. Routing both hooks through the already-mounted query's refetch removes the second fetch path entirely, so there's nothing left to race. This also drops payrollRequest/useGustoEmbeddedContext/useQueryClient/buildPayrollsGetQuery from both hooks. useGenerationPoll is intentionally left on fetchQuery — nothing renders generatedDocumentsGet data (it's only ever downloaded), so there's no sibling observer for it to race against and no refetch to reuse.

Test plan

• usePollingTask unit suite (10/10): start/stop, retry-on-rejection, deadline-vs-terminal-result precedence, double-start/unmount guarantees
• PayrollConfiguration.test.tsx (29/29, incl. 6 new regression tests for the SDK-1291 shape)
• PayrollOverview.test.tsx (9/9, incl. two tests exercising a real multi-tick pending→processed transition via fake timers)
• PrintChecksForm.test.tsx (11/11, incl. new coverage for the added deadline path)
• tsc --noEmit and eslint clean across all touched files
• Live-verified on sdk-app: reproduced the pre-fix hang on a real submit (payroll reached submit_success server-side while the poll sat silent past its deadline); re-ran the identical flow post-fix and it resolved to "Payroll submitted" within ~2s

[mariechatfield]

On 0.54.1 (or any other version off current main) and when installed in a top-level startTransition island so that no parent or sibling can force a re-render, and when there is something preventing render-time updates from react-query to the component... this is what gets stuck polling forever.

Using the hook (which queries the query client directly, instead of waiting for a render-time observer to notify react that some state has changed and a useEffect needs re-computing), it loads as expected:

[mariechatfield]

Before: we were relying on polling every 5_000 ms to get a new value for payrollData, then waiting for that new value to be "changed" such that a useEffect would re-run

[mariechatfield]

This is all just moved from below to here, no actual logic change

[mariechatfield]

This is probably the best encapsulation of the change. Instead of setting isPolling to be true (which will then cause the options sent to the suspense query, which will keep loading until something changes, which will then cause a different useEffect to re-fire and set isPolling to false...eventually)...

we actually call a function whose entire job is to manage polling

[mariechatfield]

Extract logic from the middle of the useEffect into functions for emitProcessed and emitProcessingFailed so we can consistently set the right alerts / event bodies

[mariechatfield]

This is the main polling logic. All the actual business logic for "is this payroll still being calculated?" along with how long we should keep polling is in the useCalculationPoll hook -- the component is in charge of

• when to call startCalculationPoll
• what to do while isPolling is active
• what to do when the payroll is either calculated, or fails to calculate in time

[mariechatfield]

All the business logic remains, but now it's in a plain old javascript functions. This is now the source of truth for "given the latest data from the server and our current knowledge about what we've seen so far, can we tell if this payroll is done calculating?"

[mariechatfield]

Domain-agnostic logic for how to poll on a regular basis, with support for translating any value into "is this a done state" and handlers for running up against a deadline. The three usages so far each call a react-query API for their fetch tasks, but this is purely generic