From 7dacf5916ecfef4953fd08b4159ad5f2203681f1 Mon Sep 17 00:00:00 2001
From: Eric Bailey <git@esb.lol>
Date: Thu, 8 Jan 2026 09:59:09 -0600
Subject: [PATCH] Clarify some comments

---
 src/ageAssurance/data.tsx | 4 ++++
 src/ageAssurance/state.ts | 8 +++++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/src/ageAssurance/data.tsx b/src/ageAssurance/data.tsx
index e06e291052..4bbafa8214 100644
--- a/src/ageAssurance/data.tsx
+++ b/src/ageAssurance/data.tsx
@@ -146,6 +146,10 @@ export function useConfigQuery() {
        * @see https://tanstack.com/query/latest/docs/framework/react/guides/initial-query-data#initial-data-from-the-cache-with-initialdataupdatedat
        */
       staleTime: IS_DEV ? 5e3 : 1000 * 60 * 60,
+      /**
+       * N.B. if prefetch failed above, we'll have no `initialData`, and this
+       * query will run on startup.
+       */
       initialData: getConfigFromCache(),
       initialDataUpdatedAt: () =>
         qc.getQueryState(configQueryKey)?.dataUpdatedAt,
diff --git a/src/ageAssurance/state.ts b/src/ageAssurance/state.ts
index cc8b60ac52..7ba86fe695 100644
--- a/src/ageAssurance/state.ts
+++ b/src/ageAssurance/state.ts
@@ -30,7 +30,13 @@ export function useAgeAssuranceState(): AgeAssuranceState {
         access: AgeAssuranceAccess.Safe,
       }
 
-    // should never happen, but need to guard
+    /**
+     * This can happen if the prefetch fails (such as due to network issues).
+     * The query handler will try it again, but if it continues to fail, of
+     * course we won't have config.
+     *
+     * In this case, fail open (unknown status/access) to avoid blocking users.
+     */
     if (!config) {
       logger.warn('useAgeAssuranceState: missing config')
       return {