Jurisdiction Matrix

Levy Cover is not available everywhere. The jurisdiction matrix defines which regions are covered, which tiers are available in each, and which carrier underwrites them. The matrix is enforced at unlock - if the rider's location resolves to an unsupported region, the opt-in card never appears.

Where the matrix lives

There are two layers:

1. In-code defaults. src/lib/insurance/jurisdiction-matrix.ts ships with the canonical supported regions for the current release.
2. Runtime overrides. The insurance_offerings table in Supabase can override defaults per subaccount or globally. Super-admin edits flow through /api/admin/insurance/jurisdiction-matrix.

The resolution chain at quote time:

1. Subaccount-specific insurance_offerings row.
2. Global insurance_offerings row (subaccount_id IS NULL).
3. In-code DEFAULT_JURISDICTION_MATRIX.
4. Country wildcard.
5. available: false.

Steps 1-2 are the runtime overrides. Step 3 is the source of truth for adding a new state in a code release.

Phase 1 supported regions

The initial launch matrix is intentionally conservative - friendly DOI states first.

US (Phase 1)

EU (Phase 1)

Phase 2 expansion

Phase 2 adds five US states and unlocks the three-tier menu (Minimal, Standard, Premium) in all live regions. It also introduces Slice as a fallback carrier where Cover Genius is unavailable.

US (Phase 2)

Excluded regions

The following are out of scope for v1 and v2:

If a subaccount operates in an excluded region, the Levy Cover toggle on /dashboard/insurance/settings will be disabled and the opt-in card will never appear at unlock.

How a ride resolves to a jurisdiction

At unlock:

1. The unlock location (lat/lng) is geocoded to an ISO country code + region.
2. The matrix is consulted with the resolution chain above.
3. If the matrix returns available: true, a quote is requested from the matched carrier.
4. The quote response includes the available tiers, prices, and policy wording version.
5. The opt-in card renders with whichever tiers the matrix and the carrier agree on.

Cross-jurisdiction rides bind based on unlock location. If a rider unlocks in a covered jurisdiction and ends the trip in an uncovered one, the policy still applies for the ride - the carrier's policy wording defines the geographic scope.

Adding a new region

To add a new region in a release:

1. Edit src/lib/insurance/jurisdiction-matrix.ts and add the ISO country + region.
2. Confirm the chosen carrier is licensed and willing to underwrite the region (this is a carrier-side decision, not a Levy decision).
3. Insert a global insurance_offerings row for the region so existing subaccounts inherit the default automatically.
4. Run the test suite in src/lib/insurance/__tests__/jurisdiction-matrix.test.ts.
5. Ship.

To enable a region for a single subaccount only - for example a pilot launch in a new state - insert a subaccount-specific insurance_offerings row instead of editing the default matrix.

Disabling a region

If a carrier exits a region mid-quarter, or a DOI raises an objection:

1. Set enabled = false on the matching insurance_offerings row.
2. Existing bound policies stay active until the rides end - the carrier honors them.
3. New unlocks in the region stop offering Levy Cover.
4. Notify affected operators.

The carrier reconciliation cron flags any policies the carrier later voids, and the rides are flagged for premium refund through the ride refund path (see Premium Refunds via the Ride).

Querying the matrix

Operators can inspect the matrix at /dashboard/insurance/settings. The page lists each region the subaccount operates in, the tiers offered, the carrier in use, and any overrides.

Super-admin staff can edit the matrix via /api/admin/insurance/jurisdiction-matrix. Operator-side requests for new regions are routed through support.

---