feat(followed-countries): watchlist primitive PR A — schema + mutations + queries + service + UI

[koala73]

Summary

PR A of the followed-countries watchlist primitive. Lays the foundation for personalization across the dashboard: per-user country watchlist with a server-authoritative free-tier cap, per-country reverse lookups for future fan-out (digest, breaking-news), and a reusable FollowButton mounted on three panel surfaces.

Plan: docs/plans/2026-05-02-001-feat-followed-countries-watchlist-primitive-plan.md — Codex-approved after 6 deepening rounds.

What ships in PR A

• Convex schema: three new tables — followedCountries rows, followedCountriesCounts aggregate counter, followedCountriesUserMeta per-user serialization doc — with indexes by_user, by_country, by_user_country. Constants in convex/constants.ts: FREE_TIER_FOLLOW_LIMIT=3, MAX_MERGE_INPUT=100, COUNTRY_COUNT_PRIVACY_FLOOR=5.
• Three mutations (server-authoritative cap with OCC-serialized per-user writes, idempotency, atomic counter, ISO-2 registry validation, ConvexError({kind}) typed errors): followCountry, unfollowCountry, mergeAnonymousLocal.
• Three queries: listFollowed (auth'd reactive), countFollowers (public, counter-table-backed O(1) with privacy floor), listFollowersPage (internalQuery, paginated cursor).
• /relay/followed-countries HTTP action — RELAY_SHARED_SECRET-gated; consumed by PR C's brief composer.
• Client service (src/services/followed-countries.ts) — three modes (anonymous / handoffPending / signed-in), auth-state listener with _handoffGeneration race guards, user-scoped subscription snapshot, cross-tab storage event, ConvexError → reason mapping, max-retry + exponential backoff with failed-permanent terminal state.
• FollowButton helper mounted on CountryDeepDivePanel, CountryIntelModal, and CIIPanel rows with proper teardown bookkeeping; exhaustive switch (assertNever) and inFlight busy-state.

Implementation units (8)

• U1 ISO-2 normalizer · U12 schema · U13 mutations · U14 queries+relay · U2 service · U3 sign-in handoff · U4 FollowButton · U5 mount on 3 surfaces

Test plan

• npm run typecheck — clean
• npm run typecheck:api — clean
• npm run test:convex — 292 pass (70 new tests)
• npm run test:data — 7913 pass (98 new tests)
• Unit + integration coverage for: ISO-2 registry parity (set-equality, not just size), free-tier cap, idempotency, counter atomicity, sign-in handoff race guards, user-scoped snapshot leak prevention, anonymous-vs-loading distinction, INPUT_TOO_LARGE permanent-error classification, max-retry exhaustion, cross-tab storage sync, post-await auth re-check, FollowButton rapid double-click suppression, relay endpoint validation, privacy floor edges (4 vs 5), concurrent same-user mutations preserve cap (TOCTOU)

Code review

Full /ce-code-review ran (13 reviewers). 19 of 19 actionable findings resolved across 5 follow-up commits including the P0 TOCTOU. Run artifact: .context/compound-engineering/ce-code-review/20260502-195816-dae403d7/.

TOCTOU resolution (originally P0; fixed in 9b7dd885f)

Convex per-document OCC tracks reads at the document level, not the index-range level. Two parallel followCountry({country: 'US'}) from the same user could both pass the empty-row check and both insert. Fix: a per-user serialization document (followedCountriesUserMeta) that every mutation reads + writes. Concurrent same-user mutations now serialize via Convex's per-document OCC; the loser retries against the winner's commit and either passes correctly (still under cap), fails with FREE_CAP (cap now reached), or returns idempotent (row now exists for same (userId, country)). The denormalized count on the meta row also makes the cap check O(1) for both free and PRO paths.

convex-test does NOT simulate true concurrency (verified: it serializes mutations under a per-function lock). The new tests instead assert the final-state invariant (cap holds, no duplicate (userId, country), count parity) under back-to-back execution, which is the exact behavior production OCC retry produces. Documented inline.

Known issues — deferred to follow-up

P2 — countFollowers unrate-limited. Public unauthenticated query; needs Vercel edge route wrapper for rate limiting. Not pure Convex code; deferred to its own PR.

Next: PR B (consumer wiring)

CII pin-to-top (followed countries first), "Followed only" filter chip on country-scoped panels, deep-dive star sub-action wired to alert-rule create form pre-fill.

Plan + design

• Plan: docs/plans/2026-05-02-001-feat-followed-countries-watchlist-primitive-plan.md (1057 lines, deepened + Codex-approved)
• Codex review: 6 rounds total (1 initial + 4 revise + 1 final approval after architecture deepening from opaque-blob → dedicated table)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
worldmonitor	Ready	Preview, Comment	May 8, 2026 5:50pm

[greptile-apps]

Greptile Summary

This PR lays the foundation for the per-user country watchlist primitive: two new Convex tables (followedCountries + followedCountriesCounts), three server-authoritative mutations with ISO-2 validation and free-tier cap, three queries (including an internal relay helper), a 1 286-line client service managing anonymous/handoff/signed-in modes, and a reusable FollowButton mounted on three panel surfaces.

• Server (Convex): Schema, mutations, queries, and /relay/followed-countries HTTP action all follow existing patterns and are well-guarded; the acknowledged TOCTOU race on the free-tier cap is the only known server-side gap.
• Client service: The handoff state machine is thorough — race guards, exponential backoff, cross-tab storage sync, and cross-user snapshot isolation — but the UNAUTHENTICATED error from mergeAnonymousLocal is classified as permanent (clearing localStorage) while addCountry correctly treats the same error as transient; this inconsistency can silently destroy anonymous follows during a token-delivery race at sign-in.
• FREE_TIER_FOLLOW_LIMIT is hardcoded in both convex/constants.ts and src/services/followed-countries.ts with no compile-time or test-time parity enforcement, creating a drift risk for anonymous-mode cap logic.

Confidence Score: 3/5

The backend mutations, schema, and relay endpoint are safe to merge; the main risk is in the client-side handoff state machine where a transient Convex token-delivery error at sign-in permanently destroys the user's anonymous follow list.

A user who signs in while Convex's token hasn't propagated yet will silently lose all their anonymous follows, with no recovery path short of signing out and back in — even though the next visibilitychange retry would have succeeded. The inconsistency with how addCountry handles the same error confirms this is unintentional.

src/services/followed-countries.ts — specifically the _runHandoff catch block that classifies UNAUTHENTICATED as a permanent error.

Important Files Changed

Filename	Overview
src/services/followed-countries.ts	1 286-line service managing three operating modes (anon/handoff/signed-in); the P1 UNAUTHENTICATED-as-permanent classification incorrectly clears localStorage during transient token races, and _authListenerInstalled is missing from the test reset.
convex/followedCountries.ts	513-line Convex backend: three mutations (followCountry, unfollowCountry, mergeAnonymousLocal), three queries, and two internal queries; TOCTOU on free-tier cap is acknowledged and deferred, counter helpers are transaction-inline as required, ISO-2 validation is correct.
src/utils/follow-button.ts	Reusable FollowButton factory with inFlight latch, assertNever exhaustiveness, proper teardown bookkeeping, and lazy upgrade-modal trigger; no issues found.
convex/schema.ts	Adds followedCountries and followedCountriesCounts tables with correct indexes; schema is clean and well-commented.
convex/http.ts	Adds /relay/followed-countries HTTP action matching the existing relay pattern: timing-safe secret check, JSON body validation with userId length bound, delegates to internalQuery.
convex/lib/iso2.ts	Canonical ISO-2 server-side registry with regex + set-membership validation; correctly exposes _ISO2_REGISTRY_FOR_TESTS for parity tests.
convex/constants.ts	Adds FREE_TIER_FOLLOW_LIMIT (3), MAX_MERGE_INPUT (100), COUNTRY_COUNT_PRIVACY_FLOOR (5) with clear documentation; client-side mirror in the service file creates a drift risk.

Sequence Diagram

sequenceDiagram
    participant Browser as Browser (anon)
    participant Service as FollowedCountriesService
    participant Clerk as Clerk Auth
    participant Convex as Convex (followedCountries)

    Browser->>Service: addCountry("US") [anon]
    Service->>Browser: writes localStorage, dispatches WM_FOLLOWED_COUNTRIES_CHANGED

    Note over Browser,Convex: User signs in
    Clerk-->>Service: onAuthStateChange
    Service->>Service: "_handoffState = pending, increment gen"
    Service->>Convex: mergeAnonymousLocal
    alt Success
        Convex-->>Service: accepted countries
        Service->>Service: "removeLocalStorage, _handoffState = complete"
        Service->>Convex: onUpdate listFollowed
        Convex-->>Service: reactive snapshot
        Service->>Browser: dispatchChanged
    else UNAUTHENTICATED token race current behavior
        Convex-->>Service: ConvexError UNAUTHENTICATED
        Service->>Service: removeLocalStorage loses anonymous follows
        Service->>Service: "_handoffState = failed-permanent"
    else UNAUTHENTICATED token race suggested fix
        Convex-->>Service: ConvexError UNAUTHENTICATED
        Service->>Service: markFailedAndScheduleRetry retry on visibilitychange
    end

Loading

_{Reviews (1): Last reviewed commit: "chore(env): document VITE_FOLLOW_COUNTRI..." | Re-trigger Greptile}

[greptile-apps]

UNAUTHENTICATED treated as permanent clears localStorage during transient token race

UNAUTHENTICATED is classified as a permanent error and triggers removeLocalStorage(), irreversibly destroying the user's anonymous follows. But addCountry (same process, same error) explicitly comments: "Race: Clerk says we're signed in but Convex hasn't seen the identity yet (or the token expired)" and returns HANDOFF_PENDING (transient). During the sign-in handoff, _authStillMatches returning true at this point confirms the user is still signed in per Clerk — so the Convex UNAUTHENTICATED is always a transient JWT-delivery race, not a permanent auth problem. Treating it as permanent loses anonymous follows when a simple retry would have succeeded.

Suggested change

	if (
	kind === 'INPUT_TOO_LARGE' ||
	kind === 'EMPTY_INPUT' ||
	kind === 'UNAUTHENTICATED'
	) {
	// Permanent: the input shape OR the auth identity is the problem.
	// Clear localStorage so the next sign-in starts clean. Install the
	// reactive subscription so signed-in reads still work.
	console.warn(
	`[followed-countries] handoff permanent failure (kind=${kind}); clearing localStorage`,
	);
	removeLocalStorage();
	_handoffState = 'failed-permanent';
	_initialSnapshotReceived = false;
	void _startReactiveSubscription(userIdAtStart, gen);
	return;
	}
	if (kind === 'INPUT_TOO_LARGE' || kind === 'EMPTY_INPUT') {
	// Permanent: the input shape is the problem.
	// Clear localStorage so the next sign-in starts clean. Install the
	// reactive subscription so signed-in reads still work.
	console.warn(
	`[followed-countries] handoff permanent failure (kind=${kind}); clearing localStorage`,
	);
	removeLocalStorage();
	_handoffState = 'failed-permanent';
	_initialSnapshotReceived = false;
	void _startReactiveSubscription(userIdAtStart, gen);
	return;
	}
	if (kind === 'UNAUTHENTICATED') {
	// Transient: Clerk says we're signed in but Convex hasn't received
	// the JWT yet (token delivery race). Same classification as
	// addCountry. _authStillMatches returning true at this point
	// confirms the user is still signed in per Clerk, so this is NOT
	// a permanent auth problem. Retry via visibilitychange.
	_markFailedAndScheduleRetry(userIdAtStart, gen);
	return;
	}

[greptile-apps]

Client-side FREE_TIER_FOLLOW_LIMIT can silently drift from server constant

The constant is hardcoded here as 3 — a copy of convex/constants.ts::FREE_TIER_FOLLOW_LIMIT. If the server value is bumped (e.g. to 5 for a promotion) without updating this file, anonymous users are capped at 3 in the UI while Convex would actually accept 5, and atCap in FollowButton would incorrectly show "Upgrade to follow more" at count 3. There is no test that asserts parity (unlike the ISO-2 registry parity test). Importing directly from the server constant file would enforce parity at compile time; alternatively, adding a parity assertion in the test suite would catch drift.

[greptile-apps]

_resetStateForTests does not reset _authListenerInstalled

If any test invokes installFollowedCountriesAuthListener(), _authListenerInstalled is permanently true for that module instance. After _resetStateForTests(), a subsequent call to installFollowedCountriesAuthListener() silently becomes a no-op — the real auth-state listener is never reinstalled. Current tests use _emitAuthStateForTests directly, so this is not yet exercised, but the gap means the test-reset contract is incomplete and could cause silent failures if test setup is extended.

[greptile-apps]

void _startReactiveSubscription(...) without .catch() swallows unexpected rejections

The three call sites that fire _startReactiveSubscription with void have no error handler. While the function itself is designed not to throw (getters return null on failure and client.onUpdate is synchronous in the Convex SDK), any unexpected rejection propagates as an unhandled promise rejection that is silently discarded. A .catch(err => console.warn('[followed-countries] subscription setup error:', err)) would at minimum surface this in production logs.