toga-ai 1.0.924 → 1.0.925

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -13,7 +13,7 @@
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Per-tenant/language/role JSON config that drives almost all commerce UI text, fields, and login fetches (Layer A global + Layer B FIELDS registry); open before |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | Expedited shipping options are config-gated to show only when the cart holds a computer kit; open when touching cart shipping-method options or the gate config. |
 | [Filter / Search-Results Page & the Two Search Entry Points](features/filter-search-results-page.md) | Two search entry points (Home in-place vs Header→/filter) render the same card via different code paths and FIELDS files; open for any search-results or kit-car |
-| [Force Logout on Deployment (DeploymentGuard) — commerce](features/force-logout-on-deployment.md) | Signs every user out when a deploy bumps a Core parameter, after showing a notice; open for surprise logouts, a repeating "new version" toaster, or `useDeployme |
+| [Force Logout on Deployment (DeploymentGuard) — commerce](features/force-logout-on-deployment.md) | Signs every user out when a deploy bumps a Core parameter, after showing a notice; open for surprise logouts, "why wasn't I logged out?", a repeating "new versi |
 | ["Order For" — header pill, delegated token switch, and the cart hand-off](features/header-order-for-dropdown.md) | Header pill that switches the session to a delegated token so a buyer orders **as** someone else; open before touching the pill, `useOrderForZu`, the delegation |
 | [Inactive-item purchase gating (standalone lines only — kits are exempt by design)](features/inactive-item-purchase-gating.md) | `Items.isActive = 0` blocks standalone purchase but means something different on kit components, so the gate keys on purchase CONTEXT not the flag; open when to |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | How the hostname resolves the tenant and fans out to API base URL, theme (CSS variables), and fields; open when adding a tenant or debugging wrong-theme/wrong-A |

package/knowledge/2.0/apps/toga2-commerce/features/force-logout-on-deployment.md

@@ -6,13 +6,13 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-09-25
+updated: 2026-10-01
 owners: [apeterson]
 files:
   - toga2-commerce/src/hooks/useDeploymentGuard.tsx
   - toga2-commerce/src/lib/deploymentVersion.ts
+  - toga2-commerce/src/lib/queryClient.ts
   - toga2-commerce/src/components/AuthLayout/AuthLayout.tsx
-  - toga2-commerce/src/contexts/AuthContext.tsx
   - toga2-commerce/src/lib/authStorage.ts
 related:
   - ./sso-redirect-and-session-gating.md
@@ -20,7 +20,7 @@ related:
   - ../../toga25-supply/features/force-logout-on-deployment.md
 ---
 
-Signs every user out when a deploy bumps a Core parameter, after showing a notice; open for surprise logouts, a repeating "new version" toaster, or `useDeploymentGuard`.
+Signs every user out when a deploy bumps a Core parameter, after showing a notice; open for surprise logouts, "why wasn't I logged out?", a repeating "new version" toaster, or `useDeploymentGuard`.
 
 ## Summary
 
@@ -30,17 +30,50 @@ Ported from toga25-supply (`force-logout-on-deployment`). Two commerce-only diff
 - **Mounted as `<DeploymentGuard />` inside `AuthLayout`**, not in `AuthContext`. `ToasterProvider` sits **below** `AuthProvider` in `App.tsx`, so the context that owns sign-out cannot raise a toaster; the guard component is inside both providers.
 - **Baseline lives only in `localStorage["deployment-version"]`**, listed in `AUTH_STORAGE_KEYS` so logout clears it. No baseline → the check is skipped, which is what stops a sign-out loop.
 
+Reached commerce `_production` only in merge `26e2fae7` (2026-09-30, TRUE-81991); supply had it earlier. That gap is why one parameter bump logged supply users out and commerce users not at all.
+
 ## How it works
 
-1. Query `META_LAST_REFRESH_DATETIME`, `enabled` only while authenticated, `staleTime: 0`, `refetchOnWindowFocus: true`, `refetchInterval` **5 minutes**. The old version refetched only on navigation, so an idle tab never noticed a deploy.
-2. First observation writes the baseline and never signs out.
+1. One query on `META_LAST_REFRESH_DATETIME`, `enabled` only while authenticated, `staleTime: 0`, `refetchOnWindowFocus: true`, `refetchInterval` **5 minutes**.
+2. First observation writes the baseline (`action: "establish-baseline"`) and never signs out.
 3. A later differing value → toaster → 2.5s timer → `logout()` + reload.
 4. `logout()` clears `AUTH_STORAGE_KEYS`, including the baseline, so the next login just re-baselines.
 
+### What actually triggers a refetch (and what does not)
+
+Exactly three things, verified 2026-10-01:
+
+1. query mount — a full page load or browser refresh;
+2. `refetchOnWindowFocus` — see the gotcha below for what "focus" really means;
+3. the 5-minute `refetchInterval`.
+
+**An in-app route change does not refetch.** Neither app invalidates `["deploymentVersion"]` on `location.pathname`, and supply has no broad `invalidateQueries()` anywhere. "It logged me out when I changed pages" is always (2) or (3) landing at that moment.
+
+`refetchIntervalInBackground` is unset (default `false`), so the 5-minute poll **pauses while the tab is hidden** and resumes on return. Nobody is signed out in a background tab.
+
+**User-visible guarantee:** a signed-in user is signed out within 5 minutes of the bump while their tab is open and on screen; if the tab was hidden, at the moment they come back.
+
+### Query config vs supply (does not change sign-out timing)
+
+| | app-wide `refetchOnWindowFocus` | guard query |
+|---|---|---|
+| toga25-supply (`App.tsx`) | default `true` — every on-screen query refetches on focus | inherits |
+| toga2-commerce (`lib/queryClient.ts`) | `false` | opts back in individually |
+
+Because the guard opts in, sign-out timing is **identical** in both apps. Deleting commerce's `refetchOnWindowFocus: false` buys no change in logout behavior and costs a burst of requests on every tab switch. Commerce `origin/_production` and `origin/_sandbox-client` are byte-identical for `useDeploymentGuard.tsx`, `App.tsx`, and `queryClient.ts` — sandbox-vs-prod differences were timing, not build.
+
 ## Gotchas
 
+- **⚠ "Window focus" means tab visibility, not app focus.** React Query v5 (`query-core` 5.101.4) registers **only** `visibilitychange`; the v4 focus/blur listeners are gone. Alt-tabbing to Teams/Outlook and back does **not** refetch — the tab was never hidden. Switching browser tabs, minimize/restore, and lock/wake do. Applies to every `refetchOnWindowFocus` query in every 2.0 React app. See [frontend standard §4](../../../standards/frontend.md).
+- **⚠ The first bump after the guard ships is always a no-op.** `localStorage["deployment-version"]` is written in one place only — the guard's own first observation — and nothing seeds it at login. A browser that has never run the guard has nothing to compare against, so the first fetch just stores the value. By design (it is the no-logout-loop guard), but it means "we bumped the parameter and nobody was logged out" is expected right after a deploy that introduces the guard.
+- **⚠ `key=` on `GET /core-parameters` is silently ignored.** Both apps send `?fields=value&key=META_LAST_REFRESH_DATETIME`. api2 parses only `fields, where, join, ojoin, sort, recordsPerPage, page, distinct, group, client, seekValues, seekUuid, surface`, and `/core-parameters` is plain CRUD (no scripted method on `Model/Core/Parameter.php`). The response is page 1 of **all** Core Parameters and the code reads `coreParameters[0].value`. It works today only because row 0 happens to be the right one — adding or reordering Core Parameters would silently point the guard at another row. Correct form: `where: { and: [{ key: { "=": "META_LAST_REFRESH_DATETIME" } }] }`. Never rely on `key=` as a filter anywhere in 2.0.
 - **⚠ Do not depend an effect on `addToaster`.** It is rebuilt on every `ToasterProvider` render, and raising the toaster re-renders that provider — the effect re-ran and its cleanup cleared the `setTimeout` it had just set, so the notice showed and the sign-out never fired. Keep unstable callbacks in refs and depend only on the stable value.
 - **⚠ The "already fired" flag must be module scope, not `useRef`.** The guard is mounted inside `AuthLayout`; a route change remounts it and a per-mount ref resets to `false`, so the notice reappeared on every navigation. Also do not clear the timer on unmount.
 
+## Deferred — sign out on route change
+
+To also fire on an in-app navigation: a `useLocation()` effect calling `refetch()` on `pathname` change, with `refetch` held in a **ref** (its identity changes every render; depending on it directly loops). Commerce can do this as-is — `<DeploymentGuard />` is inside `AuthLayout`, inside the router. **Supply cannot**: its guard sits in `App.tsx` **above** `<AppRouter />`, so `useLocation()` would throw; the guard must move inside the router first. Not implemented — deferred 2026-10-01.
+
 ## Change history
+- 2026-10-01 — Documented the exact refetch triggers (mount / tab-visibility / 5-min poll; **not** route change), the background-pause behavior, the first-bump no-op, the ignored `key=` param, and the commerce-vs-supply query config difference. Route-change refetch deferred. (apeterson)
 - 2026-09-25 — Built for commerce: moved out of `AuthContext` into `<DeploymentGuard />` so a toaster can be shown; added 5-min poll + focus refetch; baseline key added to `AUTH_STORAGE_KEYS`. TRUE-81991. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/force-logout-on-deployment.md

@@ -6,28 +6,31 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-10-01
 owners: [apeterson]
 files:
   - toga25-supply/src/hooks/useDeploymentGuard.tsx
   - toga25-supply/src/App.tsx
-related: []
+related:
+  - ../../toga2-commerce/features/force-logout-on-deployment.md
 ---
 
 Force-signs-out every user when a deploy bumps a Core parameter, so session + caches reset to the new build; open when debugging surprise logouts or `useDeploymentGuard`.
 
 ## Summary
 
-On large deploys the backend bumps Core parameter `META_LAST_REFRESH_DATETIME`. The FE watches it and, when it changes mid-session, force-signs-out every logged-in user so session, `localStorage`, and React Query cache (including the persisted `supply-chain-query-cache`) reset cleanly and they pick up the new build + data. Implemented as a headless `<DeploymentGuard />` driven by the `useDeploymentGuard` hook, mounted inside the `AuthProvider` / `ToasterProvider` tree in `App.tsx`.
+On large deploys the backend bumps Core parameter `META_LAST_REFRESH_DATETIME`. The FE watches it and, when it changes mid-session, force-signs-out every logged-in user so session, `localStorage`, and React Query cache (including the persisted `supply-chain-query-cache`) reset cleanly. Implemented as a headless `<DeploymentGuard />` driven by `useDeploymentGuard`, mounted inside the `AuthProvider` / `ToasterProvider` tree in `App.tsx` — **above** `<AppRouter />`, so the hook cannot use `useLocation()`.
 
 ## How it works
 
-1. **Poll the Core parameter.** TanStack `useQuery` reads `META_LAST_REFRESH_DATETIME` via `apiGet("/core-parameters", { fields: ["value"], key: "META_LAST_REFRESH_DATETIME" })`, reading `response.data.coreParameters` (tolerant of the value arriving as an array or a single object). Query: `enabled` only while authenticated, `staleTime: 0`, `refetchOnWindowFocus: true`, `refetchInterval` 5 minutes.
-2. **Establish a baseline.** The value observed right after login is stored in `localStorage` key `deployment-version`. The **first** observation only sets the baseline — never logs out. The mismatch check is skipped when no baseline exists.
-3. **Detect a change.** A later fetch whose value differs from the stored baseline triggers the reset.
-4. **Reset UX.** On mismatch: a **non-dismissing info toast** ("A new version is available — signing you out briefly…"), wait **2.5s** for readability, then call `AuthContext` `logout()`.
-5. **Centralized logout does the wipe.** `logout()` runs `performLogout()` + `clearUser()` + `localStorage.clear()` (wipes **all** `localStorage` — tokens, `zu-user`, `zu-hostname`, the persisted query cache, and the `deployment-version` baseline) + `queryClient.clear()`, then `performLogout()` hard-redirects to `/`.
+1. **Poll the Core parameter.** TanStack `useQuery` reads `META_LAST_REFRESH_DATETIME` via `apiGet("/core-parameters", { fields: ["value"], key: "META_LAST_REFRESH_DATETIME" })`, reading `response.data.coreParameters` (tolerant of an array or a single object). Query: `enabled` only while authenticated, `staleTime: 0`, `refetchOnWindowFocus: true`, `refetchInterval` 5 minutes.
+2. **Establish a baseline.** The first observed value is stored in `localStorage["deployment-version"]`; the first observation only sets the baseline and never logs out.
+3. **Detect a change.** A later fetch whose value differs triggers the reset.
+4. **Reset UX.** Non-dismissing info toast ("A new version is available — signing you out briefly…"), wait **2.5s**, then `AuthContext` `logout()`.
+5. **Centralized logout does the wipe.** `logout()` runs `performLogout()` + `clearUser()` + `localStorage.clear()` (tokens, `zu-user`, `zu-hostname`, the persisted query cache, and the `deployment-version` baseline) + `queryClient.clear()`, then hard-redirects to `/`. Clearing the baseline is what prevents a logout loop.
 
-### Why there is no logout loop
+**When it actually fires, the first-bump no-op, and the ignored `key=` param are identical here** — documented once in [commerce's force-logout doc](../../toga2-commerce/features/force-logout-on-deployment.md) (sections *What actually triggers a refetch* and *Gotchas*). Supply-only difference: `App.tsx` leaves `refetchOnWindowFocus` at React Query's default `true` app-wide, so every on-screen query refetches on tab visibility — not just this one. Sign-out timing is the same in both apps.
 
-`logout()` clears the baseline and reloads, so the next login's first fetch just re-establishes the baseline (the mismatch check is skipped when no baseline exists). Simpler than the sibling `toga2-commerce` implementation (`src/contexts/AuthContext.tsx`), which polls the same Core parameter but had to preserve the value across logout. toga25-supply's centralized `logout()` (`localStorage.clear` + `queryClient.clear` + `performLogout` redirect) made the port cleaner.
+## Change history
+- 2026-10-01 — Recorded that the guard sits above the router (blocks `useLocation()`); moved the shared trigger/gotcha detail to the commerce doc rather than duplicating it. (apeterson)
+- 2026-09-16 — Initial implementation. (apeterson)

package/knowledge/2.0/standards/frontend.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-09-16
+updated: 2026-10-01
 owners: [jcardinal, apeterson]
 files: []
 related:
@@ -191,6 +191,15 @@ const queryClient = new QueryClient({
 });
 ```
 
+**MUST: read `refetchOnWindowFocus` as "tab became visible", not "app regained focus".**
+React Query v5 (`query-core` 5.101.4) registers **only** `visibilitychange`; v4's focus/blur
+listeners are gone. So alt-tabbing to another **application** (Teams, Outlook) and back does
+**not** refetch — the browser tab was never hidden. Switching browser **tabs**,
+minimize/restore, and lock/wake do. Likewise `refetchInterval` **pauses while the tab is
+hidden** unless `refetchIntervalInBackground: true` is set. Do not design a freshness or
+session guarantee on the assumption that alt-tab refetches.
+(Case: [commerce force-logout-on-deployment](../apps/toga2-commerce/features/force-logout-on-deployment.md).)
+
 **SHOULD: fetch with React Query, not react-router data APIs.** Both apps **deliberately avoid**
 router `loader`/`action`/`useLoaderData`; data flows through React Query so caching, invalidation,
 and optimistic updates live in one system. Do not mix the two paradigms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.924",
+  "version": "1.0.925",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",