fix(premium): fan out ALL PRO-gated loaders on Free→Pro + close supply-chain race (koala73#3828)

* fix(premium): fan out ALL PRO-gated loaders on Free→Pro + close supply-chain race

Two empty-on-mobile bug reports, one root cause: PRO-gated loaders silently
strand when hasPremiumAccess() returns false at the boot tick.

## Symptom 1 — PREMIUM STOCK ANALYSIS empty body

data-loader.ts:456 gates loadStockAnalysis on `hasPremiumAccess() && shouldLoad(...)`.
If Clerk/Convex haven't hydrated by the loadAllData(true) boot call, the task
is skipped. App.ts:1017-1031 firePremiumLoaders only re-fired loadTradePolicy
on Free→Pro — every other PRO-gated loader was on its own. The scheduled
refresh that WOULD have caught up is gated to SITE_VARIANT === 'finance'
(App.ts:1495), so on the full variant the panel sits empty for the entire
session. Secondary contributor: Panel.ts:954 showRetrying and Panel.ts:1045
setContent both `if (this._locked) return;` silently, so even if loadStockAnalysis
DID run while the panel was rendering its locked CTA, the data render was
swallowed; unlockPanel then restored the pre-lock _savedContent (an empty body).

Fix: expand firePremiumLoaders to fan out stock-analysis, stock-backtest,
daily-market-brief, market-implications, wsb-tickers, and resilience-ranking.
Each loader is idempotent and self-checks hasPremiumAccess() internally, so
the calls are safe to fire even if they were already covered by a scheduler.

## Symptom 2 — Route Explorer "No modeled lane" for HK→DE (Pro user)

src/services/supply-chain/index.ts had 8 fetchers gated by the BARE
`hasPremiumAccess()` (no auth state) which reads only the cached isProUser()
Convex tier signal. RouteExplorer.fetchLane uses `hasPremiumAccess(getAuthState())`
which ALSO accepts Clerk's user.role === 'pro'. The two diverge during the
Clerk-resolved-but-Convex-stale window: RouteExplorer's outer gate passes, then
fetchRouteExplorerLane's inner gate fails and returns `{ ...emptyRouteExplorerLane,
...args }` — which has noModeledLane: true. The UI then renders "No modeled
lane for this pair", the SAME message shown when the dataset genuinely lacks
the lane. The user can't tell the two cases apart.

Fix: introduce a `gatedPremium()` helper that always calls
`hasPremiumAccess(getAuthState())`, and route all 8 supply-chain fetcher
gates through it. Eliminates the divergence window for every supply-chain
consumer in one shot.

## Audit-locking regression test

tests/premium-loaders-fan-out-coverage.test.mts statically extracts every
`this.loadX()` call sitting inside an `if (hasPremiumAccess(...))` block in
data-loader.ts and asserts each appears in App.ts:firePremiumLoaders (with
a documented ALLOWLIST escape hatch). The next contributor who adds a
PRO-gated loader without wiring fan-out gets a CI failure with a clear
"add `void this.dataLoader.loadX();` to firePremiumLoaders" message.

* fix(premium): address PR koala73#3828 review — revert no-op, fix real HK→DE cause, fix test regex

Three follow-ups to PR koala73#3828 review findings:

## P1: Reverted supply-chain auth-aware change — it was a no-op

Reviewer is correct: bare `hasPremiumAccess()` already includes the Clerk
signal because `panel-gating.ts:31` calls `isProUser()`, and
`widget-store.ts:175` `isProUser()` already does
`getAuthState().user?.role === 'pro'`. So `hasPremiumAccess()` and
`hasPremiumAccess(getAuthState())` return identically — passing auth state
only saves a redundant inner check. My `gatedPremium()` helper closed no
race window. Reverted the 8 supply-chain call sites + helper + comment.

## P1 followup: actual HK→DE root cause — port-cluster data is wrong

Hong Kong's port cluster in `scripts/shared/country-port-clusters.json`
only lists `["china-us-west", "intra-asia-container"]`. Germany lists the
Asia-Europe routes (`china-europe-suez`, `asia-europe-cape`,
`transatlantic`). Zero overlap → `sharedRoutes.length === 0` →
`noModeledLane = true`. The Route Explorer message is technically
correct: the lane wasn't modeled. The DATA was wrong — HK is one of the
world's busiest container ports and ships to Europe via Suez routinely.

Added `china-europe-suez` and `asia-europe-cape` to HK's cluster. HK→DE
now has 2 shared routes (was 0). Verified other Asian ports (TW, KR, JP,
VN, TH, PH) have the same gap — left for a follow-up PR since each needs
review against actual shipping data.

## P2: Fan-out coverage test was extracting the wrong loaders

Reviewer caught that the regex missed shape (c) single-line gates like
`if (hasPremiumAccess() && shouldLoad('wsb-ticker-scanner')) tasks.push(...)`.
On investigation it was worse: the broadened regex ONLY matched shape (b)
`if (hasPremiumAccess()) { ... }`. The other loaders happened to appear
inside an init() handler that ALSO matches shape (b), giving false
confidence that the production gates at lines 456/459/462 were covered.

Replaced the regex-only approach with a line-walking extractor:
1. Find every line containing `hasPremiumAccess(`
2. Filter to `if`/`else if` gates
3. Collect calls from the line itself (covers shape c)
4. If the line ends with `{`, walk forward with brace-depth tracking
   until the matching close (covers shapes a and b)

Now extracts all 6 PRO-gated loaders (was 4, with 2 of those caught
coincidentally via init()). Added a fixture test that proves all 3 shapes
extract correctly — a future "regex simplification" that drops a shape
fails immediately with a clear message.

Author: koala73

scripts/shared/country-port-clusters.json

@@ -90,7 +90,7 @@
   "LA": { "nearestRouteIds": ["intra-asia-container"], "coastSide": "landlocked" },
   "MN": { "nearestRouteIds": ["china-us-west"], "coastSide": "landlocked" },
   "NP": { "nearestRouteIds": ["india-se-asia"], "coastSide": "landlocked" },
-  "HK": { "nearestRouteIds": ["china-us-west", "intra-asia-container"], "coastSide": "pacific" },
+  "HK": { "nearestRouteIds": ["china-europe-suez", "asia-europe-cape", "china-us-west", "intra-asia-container"], "coastSide": "pacific" },
   "MO": { "nearestRouteIds": ["china-us-west"], "coastSide": "pacific" },
   "ZW": { "nearestRouteIds": ["brazil-china-bulk", "asia-europe-cape"], "coastSide": "landlocked" },
   "ZM": { "nearestRouteIds": ["brazil-china-bulk"], "coastSide": "landlocked" },

src/App.ts

@@ -1022,10 +1022,21 @@ export class App {
         // Entitlement just resolved → fire PRO-gated initial loads that were
         // skipped at boot. Each loader early-returns if the panel isn't
         // mounted and re-checks hasPremiumAccess() internally, so these
-        // calls are safe and idempotent. Without this, trade-policy would
-        // sit empty for up to REFRESH_INTERVALS.tradePolicy (~10 min) after
-        // sign-in because the scheduler's viewport gate is the only retry.
+        // calls are safe and idempotent. Without this, panels would sit empty
+        // until the next scheduled refresh (10+ min for trade-policy; FOREVER
+        // on the full variant for stock-analysis / stock-backtest / daily-
+        // market-brief / market-implications because their schedulers are
+        // gated to SITE_VARIANT === 'finance'). The audit-locking regression
+        // test in tests/premium-loaders-fan-out-coverage.test.mts asserts
+        // every `hasPremiumAccess() && shouldLoad('X')` gate in data-loader.ts
+        // has a matching call here.
         void this.dataLoader.loadTradePolicy();
+        void this.dataLoader.loadStockAnalysis();
+        void this.dataLoader.loadStockBacktest();
+        void this.dataLoader.loadDailyMarketBrief();
+        void this.dataLoader.loadMarketImplications();
+        void this.dataLoader.loadWsbTickers();
+        void this.dataLoader.loadResilienceRanking();
       }
       _prevHadPremium = nowPremium;
     };

tests/premium-loaders-fan-out-coverage.test.mts

@@ -0,0 +1,154 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// REGRESSION GUARD for PR #3828 (Free→Pro hydration race).
+//
+// `App.ts:firePremiumLoaders` fans out PRO-gated loaders on the Free→Pro
+// entitlement transition. If a NEW loader is gated behind
+// `hasPremiumAccess() && shouldLoad('X')` in `data-loader.ts` but a
+// corresponding `this.dataLoader.loadX()` line is missing from
+// `firePremiumLoaders`, the panel sits empty for the WHOLE SESSION on any
+// variant where the scheduled refresh isn't registered (the stock-analysis /
+// stock-backtest / daily-market-brief / market-implications schedulers are
+// gated to SITE_VARIANT === 'finance').
+//
+// This test extracts the gated loader names from data-loader.ts and asserts
+// each appears in firePremiumLoaders. It's deliberately static-grep based so
+// it catches the omission at the moment of commit, without needing to wire
+// up the full App.ts runtime.
+
+const REPO_ROOT = resolve(import.meta.dirname, '..');
+const APP_TS = readFileSync(resolve(REPO_ROOT, 'src/App.ts'), 'utf8');
+const DATA_LOADER_TS = readFileSync(resolve(REPO_ROOT, 'src/app/data-loader.ts'), 'utf8');
+
+// Loaders we deliberately do NOT include in the fan-out, with rationale.
+// Add an entry here (not silently in source) if you skip a loader.
+const ALLOWLIST: Record<string, string> = {
+  // None today. Format: `loaderName: 'why this is intentionally excluded'`.
+};
+
+/** Pull every `this.loadX()` call that sits inside an `if (hasPremiumAccess(...))` gate. */
+function extractGatedLoaders(src: string): Set<string> {
+  const loaders = new Set<string>();
+  const callRe = /this\.load([A-Z][A-Za-z0-9]+)\(\)/g;
+  const addCallsFromBlock = (block: string): void => {
+    for (const c of block.matchAll(callRe)) loaders.add(`load${c[1]}`);
+  };
+
+  // Three gate shapes appear in data-loader.ts and all three strand the
+  // loader on boot if Pro hasn't hydrated yet:
+  //   (a) `if (hasPremiumAccess() && shouldLoad('X')) { tasks.push(...load...()) }`
+  //   (b) `if (hasPremiumAccess()) { await Promise.allSettled([this.load...()]) }`
+  //   (c) `if (hasPremiumAccess() && shouldLoad('X')) tasks.push(...);`  ← single-line, no braces
+  //
+  // Regex with nested parens (a/c) and balanced braces (a/b) is fragile —
+  // PR #3828 review caught the original regex only matching shape (b)
+  // (the other loaders happened to appear via an init()-handler block that
+  // ALSO matches shape (b), giving false confidence). Walk line-by-line
+  // instead: find every line containing `hasPremiumAccess(`, then collect
+  // calls from that line PLUS the subsequent block (braced or single-line).
+  const lines = src.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (!/\bhasPremiumAccess\(/.test(line)) continue;
+    if (!/^\s*(?:if|else if)\s*\(/.test(line)) continue;   // only `if` gates, not call sites in other contexts
+
+    addCallsFromBlock(line);   // single-line gates (shape c)
+
+    // If the gate ends with `{`, collect from following lines until matching `}`.
+    if (/\{\s*$/.test(line)) {
+      let depth = 1;
+      for (let j = i + 1; j < lines.length && depth > 0; j++) {
+        const inner = lines[j]!;
+        addCallsFromBlock(inner);
+        for (const ch of inner) {
+          if (ch === '{') depth++;
+          else if (ch === '}') depth--;
+          if (depth === 0) break;
+        }
+      }
+    }
+  }
+  return loaders;
+}
+
+/** Pull every `void this.dataLoader.loadX()` call from inside the firePremiumLoaders block. */
+function extractFanOutLoaders(src: string): Set<string> {
+  const start = src.indexOf('const firePremiumLoaders');
+  assert.ok(start >= 0, 'could not locate firePremiumLoaders in App.ts — refactor would silently bypass this guard');
+  // Match until the closing `};` of the function body. The function ends with `_prevHadPremium = nowPremium;\n    };`.
+  const end = src.indexOf('\n    };', start);
+  assert.ok(end > start, 'could not locate end of firePremiumLoaders block');
+  const block = src.slice(start, end);
+
+  const loaders = new Set<string>();
+  const re = /void\s+this\.dataLoader\.load([A-Z][A-Za-z0-9]+)\(\)/g;
+  for (const match of block.matchAll(re)) {
+    loaders.add(`load${match[1]}`);
+  }
+  return loaders;
+}
+
+describe('firePremiumLoaders fan-out coverage', () => {
+  const gatedLoaders = extractGatedLoaders(DATA_LOADER_TS);
+  const fanOutLoaders = extractFanOutLoaders(APP_TS);
+
+  it('PR #3828 review fix: extracts loaders from single-line gates (no braces)', () => {
+    // Synthetic fixture covering all three shapes the production regex must
+    // handle. If a future "simplification" of the regex drops shape (c) again,
+    // this test fails immediately with a clear message instead of giving a
+    // false-positive pass on the production source.
+    const fixture = `
+    // (a) braced + viewport gate
+    if (hasPremiumAccess() && shouldLoad('a-panel')) {
+      tasks.push({ name: 'a', task: runGuarded('a', () => this.loadAaa()) });
+    }
+    // (b) braced + premium-only
+    if (hasPremiumAccess()) {
+      await Promise.allSettled([
+        this.loadBbb(),
+        this.loadCcc(),
+      ]);
+    }
+    // (c) single-line, NO braces — the shape #3828 review caught me missing
+    if (hasPremiumAccess() && shouldLoad('d-panel')) tasks.push({ name: 'd', task: runGuarded('d', () => this.loadDdd()) });
+    `;
+    const extracted = extractGatedLoaders(fixture);
+    assert.ok(extracted.has('loadAaa'), 'missed shape (a) braced + viewport gate');
+    assert.ok(extracted.has('loadBbb'), 'missed shape (b) braced + premium-only [first call]');
+    assert.ok(extracted.has('loadCcc'), 'missed shape (b) braced + premium-only [second call]');
+    assert.ok(extracted.has('loadDdd'), 'missed shape (c) single-line gate — fan-out coverage would have a blind spot');
+  });
+
+  it('extracts at least one PRO-gated loader from data-loader.ts (sanity)', () => {
+    // If this fails, the regex stopped matching — likely because data-loader.ts
+    // changed the gate shape (e.g. `hasPremiumAccess()` got replaced or moved).
+    // Update extractGatedLoaders before bumping this test or you risk silently
+    // turning off the coverage check.
+    assert.ok(gatedLoaders.size > 0, `no PRO-gated loaders found via regex — gate-shape changed?`);
+  });
+
+  it('extracts at least one fan-out loader from App.ts (sanity)', () => {
+    assert.ok(fanOutLoaders.size > 0, 'firePremiumLoaders has no `void this.dataLoader.loadX()` calls — has the function been renamed?');
+  });
+
+  it('every PRO-gated loader is fanned out on Free→Pro transition', () => {
+    const missing: string[] = [];
+    for (const loader of gatedLoaders) {
+      if (fanOutLoaders.has(loader)) continue;
+      if (loader in ALLOWLIST) continue;
+      missing.push(loader);
+    }
+    assert.deepEqual(
+      missing,
+      [],
+      `${missing.length} PRO-gated loader(s) in data-loader.ts are NOT re-fired by App.ts firePremiumLoaders on Free→Pro transition:\n` +
+      missing.map((l) => `  - ${l}`).join('\n') +
+      `\n\nFix: add \`void this.dataLoader.${missing[0] ?? 'loadX'}();\` to the firePremiumLoaders block in App.ts.\n` +
+      `If you intentionally do NOT want this loader re-fired (e.g. it has its own entitlement subscription),\n` +
+      `add it to the ALLOWLIST in this test with a one-line rationale.`,
+    );
+  });
+});