Per-user retirement jurisdiction from Stripe billing address (#119)

[brawlaphant]

Closes the autopilot half of #119.

Problem

Subscribers had no way to set their retirement jurisdiction — every scheduled retirement used the hardcoded config.defaultJurisdiction ("US"), making on-chain retirement records inaccurate for non-US subscribers. Marie raised this in the issue.

What this PR does

Wires the resolution chain for the on-chain side without requiring any new UI. Stripe already collects the billing-address country during Checkout — we just plumb it through.

Resolution order (per the issue spec):

1. Explicit jurisdiction param (MCP tool callers) — already worked
2. user.country — new: synced from Stripe billing address at checkout
3. config.defaultJurisdiction — fallback

Changes

• src/server/db.ts
  • ALTER TABLE users ADD COLUMN country migration (ISO 3166-1 alpha-2, nullable)
  • User type gains country: string | null
  • setUserCountry / setUserCountryIfMissing / getUserCountryBySubscriberId helpers
  • normalizeCountryCode validator: accepts \"US\" and sub-national \"US-OR\", rejects invalid input
• src/server/routes.ts
  • checkout.session.completed webhook reads session.customer_details.address.country and calls setUserCountryIfMissing so a Stripe-provided value never overwrites an explicit user setting
• src/services/retire-subscriber.ts
  • Resolves subscriberJurisdiction once at the top of retireForSubscriber (getUserCountryBySubscriberId(...) ?? config.defaultJurisdiction)
  • Replaces the two hardcoded config.defaultJurisdiction sites in the MsgSend and MsgBuyDirect retirement paths
• src/__tests__/user-country.test.ts — 11 new tests

Out of scope (deliberately, flagged in commit)

• Dashboard settings UI for editing country post-signup. The POST /profile/display-name pattern can be mirrored, but the form to call it is design work — better as its own PR.
• customer.updated webhook sync for billing-address edits in the customer portal. Requires enabling that event in the Stripe webhook config.

Test plan

• npm run typecheck — clean
• npm test — 60/60 passing (49 prior + 11 new)
• npm run build — clean
• Reviewer: confirm Stripe Checkout currently collects address for the active price IDs (needed for the webhook sync to populate)
• Reviewer: spot-check the migration on a fresh DB and a populated DB (country column appears, no data loss)

Refs: #119

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces functionality to track and use a user's country for retirement jurisdictions. It includes a database migration to add a country column to the users table, helper functions for normalizing and setting country codes, and logic to sync country data from Stripe billing addresses. The retirement service was updated to prioritize the user's country over the default system jurisdiction. Feedback was provided regarding an inaccurate docstring for the getUserCountryBySubscriberId function, which incorrectly describes its fallback behavior and return type.

[gemini-code-assist]

The docstring for getUserCountryBySubscriberId is inaccurate. It claims to return a resolved code that is "always non-null because fallback is required," but the function signature returns string | null and it does not implement any fallback logic (the fallback is correctly handled by the caller in retire-subscriber.ts). The documentation should be updated to accurately reflect the function's behavior.

/**
 * Get the user's country code for a subscriber.
 * Returns the ISO 3166-1 alpha-2 code (or sub-national code) if set, otherwise null.
 */