Repair Tenant Routing Drift

I have analyzed the reported intermittent 404s during your regional migration. The evidence suggests a cache-invalidation lag where the API Gateway's local route cache is not synchronized with the authoritative Shard Mapping Service during the migration state transition.

Tenant Routing Drift Diagnosis

Invariant

A tenant route resolution must query the authoritative Shard Mapping Service or a strictly versioned cache entry that matches the current migration epoch.

Recommended Repair Pattern

Implement a "Soft Fallback" during the migration window. If a request hits a shard and returns a 404, the gateway must force a cache refresh against the authoritative store before returning a failure to the client.

// Proposed Guard Logic for Route Resolver
async function resolveTenantRoute(tenantId: string): Promise<Route> {
  let route = await cache.get(`route:${tenantId}`);
  
  if (!route || route.status === 'MIGRATING') {
    // Force authoritative fetch if cache is stale or in transition
    route = await shardService.fetchAuthoritative(tenantId);
    await cache.set(`route:${tenantId}`, route, { ttl: 60 });
  }
  
  return route;
}

Next steps

1. Reduce the TTL for the route:{tenantId} cache key to 30 seconds during the migration window.
2. Add a Migration-Epoch header to internal requests to detect mismatched snapshots in background workers.
3. Verify the fix by simulating a shard failover in the staging environment using the provided resolver logic.