fix(usage): calibrate active elapsed clock efficiently

frontend/src/api/__tests__/serverTiming.spec.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import {
+  SERVER_NOW_UNIX_MS_HEADER,
+  buildServerTimingMetadata,
+  readServerNowUnixMsFromHeaders,
+  withServerTiming,
+} from '../serverTiming'
+
+describe('serverTiming', () => {
+  it('reads server time from response headers', () => {
+    expect(readServerNowUnixMsFromHeaders({
+      [SERVER_NOW_UNIX_MS_HEADER]: '1779999000123',
+    })).toBe(1_779_999_000_123)
+    expect(readServerNowUnixMsFromHeaders({
+      'X-Aether-Server-Now-Unix-Ms': '1779999000456',
+    })).toBe(1_779_999_000_456)
+  })
+
+  it('does not fall back to body fields', () => {
+    const timing = buildServerTimingMetadata({
+      headers: {},
+      data: {
+        server_now_unix_ms: 1_779_999_000_123,
+      },
+    }, 1_000, 1_100)
+
+    expect(timing).toBeUndefined()
+  })
+
+  it('builds metadata with round trip duration', () => {
+    const timing = buildServerTimingMetadata({
+      headers: {
+        [SERVER_NOW_UNIX_MS_HEADER]: '1050',
+      },
+    }, 1_000, 1_125)
+
+    expect(timing).toEqual({
+      server_now_unix_ms: 1_050,
+      client_send_unix_ms: 1_000,
+      client_receive_unix_ms: 1_125,
+      round_trip_ms: 125,
+    })
+  })
+
+  it('returns the original payload when the header is missing or invalid', () => {
+    const payload = { records: [] }
+
+    expect(withServerTiming({ data: payload, headers: {} }, 1_000)).toBe(payload)
+    expect(withServerTiming({
+      data: payload,
+      headers: { [SERVER_NOW_UNIX_MS_HEADER]: 'not-a-number' },
+    }, 1_000)).toBe(payload)
+    expect(withServerTiming({
+      data: payload,
+      headers: { [SERVER_NOW_UNIX_MS_HEADER]: '0' },
+    }, 1_000)).toBe(payload)
+    expect(withServerTiming({
+      data: payload,
+      headers: { [SERVER_NOW_UNIX_MS_HEADER]: '1050.5' },
+    }, 1_000)).toBe(payload)
+  })
+})

frontend/src/api/__tests__/usage-contract.spec.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 const { getMock, cachedRequestMock, dedupedRequestMock, buildCacheKeyMock } = vi.hoisted(() => ({
   getMock: vi.fn(),
@@ -29,6 +29,10 @@ describe('usageApi contract alignment', () => {
     buildCacheKeyMock.mockClear()
   })
 
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
   it('loads current-user usage records from the Rust usage endpoint and normalizes pagination', async () => {
     getMock.mockResolvedValueOnce({
       data: {
@@ -115,6 +119,56 @@ describe('usageApi contract alignment', () => {
     })
   })
 
+  it('captures admin user usage server timing when the records request resolves', async () => {
+    let now = 1_000
+    vi.spyOn(Date, 'now').mockImplementation(() => now)
+
+    let resolveStats: ((value: unknown) => void) | null = null
+    getMock.mockImplementation((url: string) => {
+      if (url === '/api/admin/usage/stats') {
+        return new Promise(resolve => {
+          resolveStats = resolve
+        })
+      }
+      if (url === '/api/admin/usage/records') {
+        return Promise.resolve({
+          headers: {
+            'x-aether-server-now-unix-ms': '10050',
+          },
+          data: {
+            records: [{ id: 'record-3' }],
+            total: 1,
+            limit: 25,
+            offset: 0,
+          },
+        })
+      }
+      return Promise.reject(new Error(`unexpected url: ${url}`))
+    })
+
+    const resultPromise = usageApi.getUserUsage('user-123', { page: 1, page_size: 25 })
+    now = 1_100
+    await Promise.resolve()
+    now = 20_000
+    resolveStats?.({
+      data: {
+        total_requests: 1,
+        total_tokens: 10,
+        total_cost: 0.1,
+        avg_response_time: 500,
+      },
+    })
+
+    const result = await resultPromise
+
+    expect(result.server_timing).toEqual({
+      server_now_unix_ms: 10_050,
+      client_send_unix_ms: 1_000,
+      client_receive_unix_ms: 1_100,
+      round_trip_ms: 100,
+    })
+  })
+
   it('uses an extended timeout and cache bypass option for admin analytics', async () => {
     getMock
       .mockResolvedValueOnce({