feat(focus): restaurant picker + server-side 90-day background backfill - #564

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/plans/2026-07-02-focus-picker-and-background-sync-plan.md`:
- Around line 7-8: The live verification step currently hard-codes a
machine-specific absolute path, which leaks a private filesystem layout and
breaks portability. Update the verification note in this plan to use the same
repo-relative or env-var-based form used elsewhere in the document, and keep the
`FOCUS_API_KEY`/`FOCUS_API_SECRET`/`FOCUS_RESTAURANT_GUID` guidance intact
without exposing any values.

In
`@docs/superpowers/specs/2026-07-02-focus-picker-and-background-sync-design.md`:
- Around line 191-194: The cron backfill cap is inconsistent between this
section and the later binding resolution, so align the `processBackfillBatch`
limit with the final `maxDays` choice. Update the spec text near
`processBackfillBatch` to use the same cron value as §8.3, and make sure any
related references to `BUDGET_MS`, per-restaurant budget, and the cron batch
behavior in the surrounding design stay consistent.
- Around line 212-214: Update the Connection query in the relevant React Query
hook so polling stops as soon as a connection enters error, even if it is still
is_active and initial_sync_done is false. Adjust the conditional refetchInterval
logic to also check the connection status before returning 8000, and otherwise
return false; keep staleTime unchanged. Use the existing query setup and data
fields in the Connection query function/hook to locate the change.
- Around line 169-178: The custom-range flow still uses the obsolete
backgrounding path, which conflicts with the updated design and makes the
behavior ambiguous. Remove the scheduleBackground/waitUntil wording from the
custom range section and update the flow to be synchronous instead. Keep the
range-processing logic centered on processDateRangeTransactions and the
custom-range handling in focusTransactionSyncHandler or focusBackfillBatch, but
describe it as executing inline and returning the normal response path rather
than backgrounded:true.

In `@package.json`:
- Line 98: Upgrade the fast-xml-parser dependency in package.json from 4.5.6 to
a fixed 5.5.6+ release, since it parses untrusted Focus XML and the current
version is in the affected CVE range. Then verify
supabase/functions/_shared/focusDatafeedParser.ts still keeps DTD/entity
handling disabled when constructing or using the parser, and adjust the parser
configuration there if needed.

In `@supabase/functions/_shared/focusBackfillSyncHandler.ts`:
- Around line 356-376: The best-effort write to focus_connections currently
handles only the resolved error case in the `.then()` callback and can still
produce an unhandled rejection if the promise rejects before resolving. Update
the fire-and-forget update in `focusBackfillSyncHandler` to fail safely by
adding a `.catch()` on the Supabase chain (or wrapping the async write in a
try/catch helper) so network/runtime failures are swallowed and only logged,
preserving the intended never-throw behavior for this error-state write.

In `@supabase/functions/_shared/focusDatafeedParser.ts`:
- Around line 112-116: The XMLParser configuration in focusDatafeedParser should
disable entity processing for this external feed. Update the XMLParser options
in the parser setup to set processEntities to false unless entity/DOCTYPE
support is explicitly required, keeping the existing ignoreAttributes,
parseTagValue, and trimValues behavior unchanged.

In `@supabase/functions/_shared/focusTransactionSyncHandler.ts`:
- Around line 302-319: `processDayTransactions` and
`processDateRangeTransactions` are swallowing
`sync_focus_transactions_to_unified_sales` RPC failures by only calling
`console.warn`, so callers still see success even when `unified_sales` is out of
sync. Update the return shape in these functions to surface the RPC outcome (for
example a warning/failure flag or message) and propagate it from the shared sync
block that calls `deps.supabase.rpc('sync_focus_transactions_to_unified_sales',
...)`. Add tests for both the single-day and range paths to assert the
RPC-failure case is reported to the caller instead of being silently ignored.

In `@supabase/functions/focus-backfill-sync/index.ts`:
- Around line 35-48: The auth check in focus-backfill-sync is fail-open when
SUPABASE_SERVICE_ROLE_KEY is missing because serviceRoleKey becomes an empty
string and handleBackfillSync can accept an empty Bearer token. Change the flow
in the main try block and/or handleBackfillSync so missing
SUPABASE_SERVICE_ROLE_KEY is treated as a misconfiguration and immediately
rejected with a non-2xx response, before createClient or timingSafeEqual is
used. Keep the fix centered around handleBackfillSync, serviceRoleKey, and the
Authorization Bearer parsing so only a real configured secret can pass.

In `@supabase/migrations/20260701130000_focus_transactions_unified_sales.sql`:
- Around line 92-263: The sync logic in the per-check loop fixes item-level
orphans, but it still leaves whole-check rows behind when a `focus_orders` check
is voided or deleted, and the later aggregation still relies on `synced_at >=
v_sync_start`, which misses those removed checks. Add a check-level cleanup in
the same migration before the aggregation step to delete `unified_sales` rows
for `pos_system = 'focus'` whose `external_order_id` no longer matches any
`focus_orders` record in the processed date range, while preserving
`parent_sale_id IS NULL` so split rows stay intact. Then restore the aggregation
behavior to the `focus_daily_reports` approach from
`20260627150000_focus_sync_hardening.sql`, or otherwise ensure deleted dates are
explicitly re-aggregated.

In `@supabase/migrations/20260701140000_focus_transactions_cron.sql`:
- Line 13: The schedule comment is misleading because the cron expression
described by the text does not match the actual interval used by the focus
transactions job. Update the comment near the cron setup in the migration so it
accurately reflects the intended schedule for the focus transactions cron,
keeping it consistent with the cron expression used by the scheduling logic and
avoiding any mention of the wrong frequency.

In `@supabase/migrations/20260701150000_focus_transactions_integrity.sql`:
- Around line 12-24: In the previous migration file
(20260701130000_focus_transactions_unified_sales.sql), the cleanup logic for
unified_sales table (around lines 92-261) only handles pruning rows for checks
that exist in focus_orders. Add an explicit DELETE statement that removes
orphaned unified_sales rows where the corresponding focus_orders record no
longer exists, using the natural key columns (restaurant_id, business_date,
focus_check_id) in a NOT IN or LEFT JOIN condition to identify and delete rows
whose referenced focus_orders have been deleted.

In `@supabase/tests/46_focus_transactions_schema.sql`:
- Around line 124-188: The current checks in the focus transaction schema test
only confirm that SELECT and ALL policies exist on the transaction tables, but
they do not verify the actual policy predicates. Update the assertions around
pg_policies for focus_orders, focus_order_items, and focus_payments to inspect
the policy condition fields (such as qual and with_check) and confirm they match
the migration contract, specifically the user_restaurants membership and role IN
('owner', 'manager') logic.
- Around line 289-297: The card_last4 test only covers an overlong value, so the
PCI boundary in the focus_payments checks may still miss short or non-numeric
fragments. Update the SQL in the focus_transactions_schema test around the
throws_ok cases for focus_payments.card_last4 to add assertions for a too-short
value and a non-digit value, alongside the existing 5-digit case, so the
constraint is validated against all non-4-digit inputs.

In `@tests/unit/focusSyncB6.test.tsx`:
- Around line 203-222: The test name in FocusSync B6 is misleading because it
claims the destructive toast path is covered, but the body only checks the
disabled Sync button and that triggerManualSync is not called. Either rename the
test around renderFocusSync to reflect the disabled-button guard, or adjust the
test to exercise handleSync’s missing-date branch and assert mockToast is called
so the toast behavior is actually covered.

---

Outside diff comments:
In `@docs/superpowers/plans/2026-07-02-focus-picker-and-background-sync-plan.md`:
- Around line 165-178: The custom-range guidance is inconsistent with the
binding resolution because it still tells implementers to use
scheduleBackground/waitUntil even though custom range handling is meant to be
synchronous. Update the plan section that describes the custom-range flow so it
no longer references backgrounding for custom ranges and instead aligns with the
synchronous behavior already defined in the custom-range rules, keeping the
instructions consistent with the surrounding focus-picker and background-sync
plan.
- Around line 191-194: Make the backfill batch cap consistent across the plan
and its tests: the current maxDays value conflicts with the cron backfill limit
described in the plan’s backfill section. Update the backfill configuration in
the plan so the same maxDays limit is used everywhere, and align any test
expectations or references that mention the alternate value. Use the backfill
cron section and related test descriptions as the source of truth when updating
the maxDays setting.

In `@supabase/functions/_shared/focusSyncDataHandler.ts`:
- Around line 102-138: The CAS helper types in focusSyncDataHandler are missing
one step in the update chain, so the declared surface does not match the actual
.update(...).eq(...).eq(...).eq('sync_cursor', ...) usage. Update the chain
types around CasUpdateResult, CasEq1, CasEq2, and CasEq3 so the helper supports
the 4-step CAS flow used by the sync logic, matching the shape already used in
focusBackfillSyncHandler and allowing select() only after the extra eq() level.

---

Nitpick comments:
In `@src/hooks/useFocusConnection.tsx`:
- Around line 111-117: Update useFocusConnection’s useQuery options so the query
stays fresh for 30 seconds instead of forcing immediate staleness; in
useFocusConnection.tsx, change the staleTime setting in the hook’s query config
to 30_000 while keeping refetchInterval unchanged. This reduces extra
focus/remount refetches without affecting the backfill polling behavior.

In `@supabase/functions/_shared/focusBulkSyncHandler.ts`:
- Around line 386-393: The error path in focusBulkSyncHandler’s
processConnection catch block is not advancing last_sync_time, so failing
connections keep getting picked first by the ORDER BY last_sync_time ASC NULLS
FIRST query. Update the catch block in focusBulkSyncHandler to perform the same
best-effort fire-and-forget last_sync_time bump used by focusBackfillSyncHandler
after logging/pushing the error, while keeping the existing error handling and
result.errors behavior intact.
- Around line 196-231: The Lynk incremental sync path in processConnection
currently throws on missing credentials or when processDayTransactions fails,
but it never updates the focus_connections row to an error state. Update this
branch to persist connection_status: 'error' and a meaningful last_error before
returning/throwing, mirroring the legacy FocusAuthError handling and the
focusBackfillSyncHandler failure path. Use the existing symbols
processConnection, processDayTransactions, and the focus_connections update
logic so UI polling on connection_status reflects incremental-sync failures.

In `@supabase/functions/_shared/focusLynkClient.ts`:
- Around line 229-254: The fetchDatafeed path in focusLynkClient should not use
a fixed per-request timeout that can exceed the caller’s remaining backfill
budget. Update the POST /api/lynk/sync flow and the related blob GET path it
feeds (the same network pattern referenced by fetchDatafeed) to use a shared
deadline-based AbortController or otherwise derive timeouts from the remaining
budget passed through processBackfillBatch, so each day’s work stays within the
caller’s slice. Keep the existing fetch/deps.fetch structure and syncUrl
handling, but make TIMEOUT_MS or request cancellation budget-aware rather than
independently allowing ~30s per request.

In `@supabase/functions/_shared/focusSyncDataHandler.ts`:
- Around line 438-485: The incremental path in focusSyncDataHandler should
persist failures the same way the backfill branch does: after
processDayTransactions returns r1/r2, if status is error, update
focus_connections via deps.serviceClient to set connection_status to error and
last_error from the failure result before returning. Keep the existing timestamp
refresh for success/empty cases, and preserve the current CAS behavior around
the sync_cursor/readCursor update.
- Around line 297-316: The Lynk-path secret decryption in focusSyncDataHandler’s
handleSyncData flow is not protected, so a decrypt failure can escape instead of
returning a consistent Edge Function JSON error. Wrap the
getEncryptionService()/encSvc.decrypt(connRow.api_secret_encrypted) block in
try/catch, handle the failure the same way the legacy path handles
FocusAuthError, and return a jsonError response with an appropriate
status/message so the Lynk path matches the existing error-response convention.

In `@tests/unit/focusSyncDataHandler.test.ts`:
- Line 631: The repeated `as any` casts on `serviceClientOpts.connection`
indicate the shared mock type is missing the Lynk-specific fields. Update the
`MockConnection` type used by `makeServiceClientMock` to include the `api_key`,
`api_secret_encrypted`, and `environment` properties so
`MOCK_CONNECTION_LYNK_BACKFILL` and `MOCK_CONNECTION_LYNK_INCREMENTAL` can be
passed without casts. Then remove all the `as any` call sites in
`focusSyncDataHandler.test.ts` and keep the fixtures strongly typed.

In `@tests/unit/focusTransactionSyncHandler.test.ts`:
- Around line 166-535: Prefix the critical-path test cases in
processDayTransactions with CRITICAL: in their description strings, especially
the ones covering focus_orders upsert failure, items/payments batch upserts,
unified_sales RPC params, and voided-check deletes. Update the relevant it(...)
titles in focusTransactionSyncHandler.test.ts so they clearly identify
financial/business-critical behavior while leaving the test logic and assertions
unchanged.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@supabase/functions/_shared/focusBulkSyncHandler.ts`:
- Around line 400-411: The update in focusBulkSyncHandler should not blindly
write sync_cursor and initial_sync_done for Lynk backfill rows, since that can
overwrite a newer cursor from focus-backfill-sync. In the bulk sync persistence
path, use the existing identifiers row.sync_cursor and newSyncCursor to either
omit sync_cursor/initial_sync_done from this update when the Lynk backfill
branch is returning the cursor unchanged, or add a compare-and-swap guard on
sync_cursor before calling .update(...).eq('id', row.id).eq('restaurant_id',
row.restaurant_id).