tapimo 0.14.0 → 0.15.0

package/src/db/tables/routesIdempotency.test.ts

@@ -0,0 +1,796 @@
+import * as pg from 'pg'
+
+import * as TestApp from '../../../test/App.js'
+import * as RoutesIdempotency from './routesIdempotency.js'
+
+const db = TestApp.database()
+
+const now = new Date('2026-01-01T00:00:00.000Z')
+const replayTtlMs = 86_400_000
+const ttlMs = 60_000
+
+beforeEach(() => vi.useFakeTimers({ now, toFake: ['Date'] }))
+afterEach(async () => {
+  try {
+    await db.kysely.deleteFrom('routes_idempotency_requests').execute()
+  } finally {
+    vi.useRealTimers()
+  }
+})
+
+function input(overrides: Partial<RoutesIdempotency.claim.Input> = {}) {
+  return {
+    apiKeyId: 'key_test',
+    irrevocable: false,
+    keyHash: `hash_${Math.random().toString(36).slice(2)}`,
+    operation: RoutesIdempotency.operations.transfer,
+    orgId: 'org_test',
+    requestHash: 'req_aaaa',
+    ttlMs,
+    ...overrides,
+  }
+}
+
+function databaseError(message: string, code = '23503') {
+  const error = new pg.DatabaseError(message, message.length, 'error')
+  error.code = code
+  return error
+}
+
+describe('claim', () => {
+  test('allows a rolling old worker to retain its provider result', async () => {
+    const claimed = input()
+    await db.kysely
+      .insertInto('routes_idempotency_requests')
+      .values({
+        apiKeyId: claimed.apiKeyId,
+        createdAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+        irrevocable: false,
+        keyHash: claimed.keyHash,
+        matchHash: null,
+        operation: null,
+        orgId: null,
+        requestHash: claimed.requestHash,
+        response: null,
+        status: 'pending',
+        transferId: null,
+      })
+      .execute()
+
+    await expect(
+      db.kysely
+        .updateTable('routes_idempotency_requests')
+        .set({ response: '{"requestId":"legacy"}', status: 'provisioned' })
+        .where('apiKeyId', '=', claimed.apiKeyId)
+        .where('keyHash', '=', claimed.keyHash)
+        .returning(['response', 'status'])
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({ response: '{"requestId":"legacy"}', status: 'provisioned' })
+  })
+
+  test('claims, blocks equivalent concurrent requests, and flags mismatches', async () => {
+    const first = input()
+    expect(await RoutesIdempotency.claim(db, first)).toEqual({
+      createdAt: now.toISOString(),
+      type: 'claimed',
+    })
+    expect(await RoutesIdempotency.claim(db, first)).toEqual({ type: 'pending' })
+    expect(await RoutesIdempotency.claim(db, { ...first, requestHash: 'req_bbbb' })).toEqual({
+      type: 'mismatch',
+    })
+  })
+
+  test('reserves a reusable match across different request fingerprints', async () => {
+    const first = input({ operation: RoutesIdempotency.operations.depositAddress })
+    const second = {
+      ...first,
+      apiKeyId: 'key_second',
+      keyHash: 'hash_second',
+      requestHash: 'req_bbbb',
+    }
+
+    const firstClaim = await RoutesIdempotency.claim(db, first)
+    const secondClaim = await RoutesIdempotency.claim(db, second)
+    if (firstClaim.type !== 'claimed' || secondClaim.type !== 'claimed')
+      throw new Error('Expected fresh claims.')
+    await expect(
+      RoutesIdempotency.reserveDepositAddressMatch(db, {
+        apiKeyId: first.apiKeyId,
+        createdAt: firstClaim.createdAt,
+        keyHash: first.keyHash,
+        matchHash: 'match_same',
+        orgId: first.orgId,
+        ttlMs,
+      }),
+    ).resolves.toEqual({ type: 'reserved' })
+    await expect(
+      RoutesIdempotency.reserveDepositAddressMatch(db, {
+        apiKeyId: second.apiKeyId,
+        createdAt: secondClaim.createdAt,
+        keyHash: second.keyHash,
+        matchHash: 'match_same',
+        orgId: second.orgId,
+        ttlMs,
+      }),
+    ).resolves.toEqual({ type: 'pending' })
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['apiKeyId', 'keyHash'])
+        .where('matchHash', '=', 'match_same')
+        .execute(),
+    ).resolves.toEqual([{ apiKeyId: first.apiKeyId, keyHash: first.keyHash }])
+  })
+
+  test('rejects a stale reservation owner after lease reclamation', async () => {
+    const request = input({ operation: RoutesIdempotency.operations.depositAddress })
+    const original = await RoutesIdempotency.claim(db, request)
+    if (original.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    vi.setSystemTime(new Date(now.getTime() + ttlMs + 1))
+    const replacement = await RoutesIdempotency.claim(db, request)
+    if (replacement.type !== 'claimed') throw new Error('Expected a replacement claim.')
+
+    await expect(
+      RoutesIdempotency.reserveDepositAddressMatch(db, {
+        apiKeyId: request.apiKeyId,
+        createdAt: original.createdAt,
+        keyHash: request.keyHash,
+        matchHash: 'match_reclaimed',
+        orgId: request.orgId,
+        ttlMs,
+      }),
+    ).resolves.toEqual({ type: 'lost' })
+    await expect(
+      RoutesIdempotency.reserveDepositAddressMatch(db, {
+        apiKeyId: request.apiKeyId,
+        createdAt: replacement.createdAt,
+        keyHash: request.keyHash,
+        matchHash: 'match_reclaimed',
+        orgId: request.orgId,
+        ttlMs,
+      }),
+    ).resolves.toEqual({ type: 'reserved' })
+  })
+
+  test('keeps the source checkpoint resumable during canonical recovery', async () => {
+    const source = input({ operation: RoutesIdempotency.operations.depositAddress })
+    const sourceClaim = await RoutesIdempotency.claim(db, source)
+    if (sourceClaim.type !== 'claimed') throw new Error('Expected a fresh source claim.')
+    await RoutesIdempotency.reserveDepositAddressMatch(db, {
+      apiKeyId: source.apiKeyId,
+      createdAt: sourceClaim.createdAt,
+      keyHash: source.keyHash,
+      matchHash: 'match_checkpoint',
+      orgId: source.orgId,
+      ttlMs,
+    })
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: source.apiKeyId,
+      createdAt: sourceClaim.createdAt,
+      keyHash: source.keyHash,
+      replayTtlMs,
+      response: '{"amount":"100000000"}',
+    })
+    const retry = { ...source, apiKeyId: 'key_retry', keyHash: 'hash_retry' }
+    const retryClaim = await RoutesIdempotency.claim(db, {
+      ...retry,
+      requestHash: 'request_different_amount',
+    })
+    if (retryClaim.type !== 'claimed') throw new Error('Expected a fresh retry claim.')
+
+    await expect(
+      RoutesIdempotency.reserveDepositAddressMatch(db, {
+        apiKeyId: retry.apiKeyId,
+        createdAt: retryClaim.createdAt,
+        keyHash: retry.keyHash,
+        matchHash: 'match_checkpoint',
+        orgId: retry.orgId,
+        ttlMs,
+      }),
+    ).resolves.toMatchObject({
+      checkpointFresh: true,
+      claim: {
+        apiKeyId: source.apiKeyId,
+        createdAt: sourceClaim.createdAt,
+        keyHash: source.keyHash,
+      },
+      type: 'resume',
+    })
+    await expect(
+      RoutesIdempotency.reserveDepositAddressMatch(db, {
+        apiKeyId: source.apiKeyId,
+        createdAt: sourceClaim.createdAt,
+        keyHash: source.keyHash,
+        matchHash: 'match_checkpoint',
+        orgId: source.orgId,
+        ttlMs,
+      }),
+    ).resolves.toEqual({ type: 'provisioned' })
+  })
+
+  test('marks an expired cross-key match checkpoint quote as stale', async () => {
+    const source = input({
+      irrevocable: true,
+      operation: RoutesIdempotency.operations.depositAddress,
+    })
+    const sourceClaim = await RoutesIdempotency.claim(db, source)
+    if (sourceClaim.type !== 'claimed') throw new Error('Expected a fresh source claim.')
+    await RoutesIdempotency.reserveDepositAddressMatch(db, {
+      apiKeyId: source.apiKeyId,
+      createdAt: sourceClaim.createdAt,
+      keyHash: source.keyHash,
+      matchHash: 'match_expired_checkpoint',
+      orgId: source.orgId,
+      ttlMs,
+    })
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: source.apiKeyId,
+      createdAt: sourceClaim.createdAt,
+      keyHash: source.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"relay_expired_checkpoint"}',
+    })
+    vi.setSystemTime(new Date(now.getTime() + replayTtlMs + 1))
+    const retry = { ...source, apiKeyId: 'key_expired_retry', keyHash: 'hash_expired_retry' }
+    const retryClaim = await RoutesIdempotency.claim(db, {
+      ...retry,
+      requestHash: 'request_expired_different_amount',
+    })
+    if (retryClaim.type !== 'claimed') throw new Error('Expected a fresh retry claim.')
+
+    await expect(
+      RoutesIdempotency.reserveDepositAddressMatch(db, {
+        apiKeyId: retry.apiKeyId,
+        createdAt: retryClaim.createdAt,
+        keyHash: retry.keyHash,
+        matchHash: 'match_expired_checkpoint',
+        orgId: retry.orgId,
+        ttlMs,
+      }),
+    ).resolves.toMatchObject({
+      checkpointFresh: false,
+      response: '{"requestId":"relay_expired_checkpoint"}',
+      type: 'resume',
+    })
+  })
+
+  test('accepts a pre-deploy request fingerprint for an existing claim', async () => {
+    const legacy = input({ requestHash: 'req_legacy' })
+    const claimed = await RoutesIdempotency.claim(db, legacy)
+    if (claimed.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    await RoutesIdempotency.complete(db, {
+      apiKeyId: legacy.apiKeyId,
+      createdAt: claimed.createdAt,
+      keyHash: legacy.keyHash,
+      replayTtlMs,
+      response: '{"id":"rda_legacy"}',
+    })
+
+    await expect(
+      RoutesIdempotency.claim(db, {
+        ...legacy,
+        compatibleRequestHashes: [legacy.requestHash],
+        requestHash: 'req_owner_scoped',
+      }),
+    ).resolves.toEqual({ response: '{"id":"rda_legacy"}', type: 'replay' })
+  })
+
+  test('shares a live provider checkpoint with a rotated organization key', async () => {
+    const original = input({ operation: RoutesIdempotency.operations.depositAddress })
+    const claimed = await RoutesIdempotency.claim(db, original)
+    if (claimed.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: original.apiKeyId,
+      createdAt: claimed.createdAt,
+      keyHash: original.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"relay_request_1"}',
+    })
+    const rotated = {
+      ...original,
+      apiKeyId: 'key_rotated',
+      keyHash: 'hash_rotated',
+    }
+
+    expect(await RoutesIdempotency.claim(db, rotated)).toEqual({
+      checkpointFresh: true,
+      createdAt: now.toISOString(),
+      recoveredClaim: {
+        apiKeyId: original.apiKeyId,
+        createdAt: now.toISOString(),
+        keyHash: original.keyHash,
+      },
+      response: '{"requestId":"relay_request_1"}',
+      type: 'resume',
+    })
+    expect(
+      await db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['apiKeyId', 'keyHash', 'status'])
+        .where('requestHash', '=', original.requestHash)
+        .orderBy('status')
+        .execute(),
+    ).toEqual([
+      { apiKeyId: rotated.apiKeyId, keyHash: rotated.keyHash, status: 'pending' },
+      { apiKeyId: original.apiKeyId, keyHash: original.keyHash, status: 'provisioned' },
+    ])
+  })
+
+  test('attributes an equivalent rolling-worker checkpoint for the same API key', async () => {
+    const original = input({ operation: RoutesIdempotency.operations.depositAddress })
+    const claimed = await RoutesIdempotency.claim(db, original)
+    if (claimed.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: original.apiKeyId,
+      createdAt: claimed.createdAt,
+      keyHash: original.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"relay_legacy"}',
+    })
+    await db.kysely
+      .updateTable('routes_idempotency_requests')
+      .set({ matchHash: null, operation: null, orgId: null })
+      .where('apiKeyId', '=', original.apiKeyId)
+      .where('keyHash', '=', original.keyHash)
+      .execute()
+    const retry = { ...original, keyHash: 'hash_retry' }
+
+    expect(await RoutesIdempotency.claim(db, retry)).toMatchObject({
+      recoveredClaim: { apiKeyId: original.apiKeyId, keyHash: original.keyHash },
+      response: '{"requestId":"relay_legacy"}',
+      type: 'resume',
+    })
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['operation', 'orgId', 'requestHash'])
+        .where('apiKeyId', '=', original.apiKeyId)
+        .where('keyHash', '=', original.keyHash)
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({
+      operation: RoutesIdempotency.operations.depositAddress,
+      orgId: original.orgId,
+      requestHash: original.requestHash,
+    })
+  })
+
+  test('canonicalizes and fences an adopted subsidized legacy checkpoint', async () => {
+    const legacy = input({
+      operation: RoutesIdempotency.operations.depositAddress,
+      requestHash: 'req_legacy',
+    })
+    const result = await RoutesIdempotency.claim(db, legacy)
+    if (result.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: legacy.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: legacy.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"legacy"}',
+    })
+    await db.kysely
+      .updateTable('routes_idempotency_requests')
+      .set({ irrevocable: false, operation: null, orgId: null })
+      .where('apiKeyId', '=', legacy.apiKeyId)
+      .where('keyHash', '=', legacy.keyHash)
+      .execute()
+
+    const canonical = {
+      ...legacy,
+      compatibleRequestHashes: [legacy.requestHash],
+      recoveredIrrevocable: true,
+      requestHash: 'req_canonical',
+    }
+    await expect(RoutesIdempotency.claim(db, canonical)).resolves.toMatchObject({
+      type: 'resume',
+    })
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['irrevocable', 'requestHash'])
+        .where('apiKeyId', '=', legacy.apiKeyId)
+        .where('keyHash', '=', legacy.keyHash)
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({ irrevocable: true, requestHash: canonical.requestHash })
+    await expect(
+      RoutesIdempotency.claim(db, {
+        ...canonical,
+        apiKeyId: 'key_other_scope',
+        keyHash: 'hash_other_scope',
+        requestHash: 'req_other_scope',
+      }),
+    ).resolves.toMatchObject({ type: 'claimed' })
+  })
+
+  test('does not restore liability when adopting a completed legacy claim', async () => {
+    const claimed = input({
+      irrevocable: true,
+      operation: RoutesIdempotency.operations.depositAddress,
+    })
+    const result = await RoutesIdempotency.claim(db, claimed)
+    if (result.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"legacy"}',
+    })
+    await RoutesIdempotency.complete(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"id":"rda_legacy"}',
+    })
+    await db.kysely
+      .updateTable('routes_idempotency_requests')
+      .set({ irrevocable: false, operation: null, orgId: null })
+      .where('apiKeyId', '=', claimed.apiKeyId)
+      .where('keyHash', '=', claimed.keyHash)
+      .execute()
+    expect(
+      await RoutesIdempotency.claim(db, {
+        ...claimed,
+        orgId: 'org_one',
+        recoveredIrrevocable: true,
+      }),
+    ).toMatchObject({ type: 'replay' })
+    expect(await RoutesIdempotency.claim(db, { ...claimed, orgId: 'org_two' })).toEqual({
+      type: 'mismatch',
+    })
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['irrevocable', 'operation', 'orgId'])
+        .where('apiKeyId', '=', claimed.apiKeyId)
+        .where('keyHash', '=', claimed.keyHash)
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({
+      irrevocable: false,
+      operation: RoutesIdempotency.operations.depositAddress,
+      orgId: 'org_one',
+    })
+  })
+
+  test('does not restore liability when adopting a pending legacy claim', async () => {
+    const claimed = input({
+      operation: RoutesIdempotency.operations.depositAddress,
+    })
+    await expect(RoutesIdempotency.claim(db, claimed)).resolves.toMatchObject({ type: 'claimed' })
+    await db.kysely
+      .updateTable('routes_idempotency_requests')
+      .set({ operation: null, orgId: null })
+      .where('apiKeyId', '=', claimed.apiKeyId)
+      .where('keyHash', '=', claimed.keyHash)
+      .execute()
+
+    await expect(
+      RoutesIdempotency.claim(db, { ...claimed, recoveredIrrevocable: true }),
+    ).resolves.toEqual({ type: 'pending' })
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['irrevocable', 'operation', 'orgId'])
+        .where('apiKeyId', '=', claimed.apiKeyId)
+        .where('keyHash', '=', claimed.keyHash)
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({
+      irrevocable: false,
+      operation: RoutesIdempotency.operations.depositAddress,
+      orgId: claimed.orgId,
+    })
+  })
+
+  test('replays the stored response after completion', async () => {
+    const claimed = input()
+    const result = await RoutesIdempotency.claim(db, claimed)
+    expect(result.type).toBe('claimed')
+    if (result.type !== 'claimed') return
+    const completedAt = new Date('2026-01-01T00:00:30.000Z')
+    vi.setSystemTime(completedAt)
+    await RoutesIdempotency.complete(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"id":"rtr_test"}',
+      transferId: 'rtr_test',
+    })
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select('expiresAt')
+        .where('apiKeyId', '=', claimed.apiKeyId)
+        .where('keyHash', '=', claimed.keyHash)
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({ expiresAt: '2026-01-02T00:00:30.000Z' })
+    expect(await RoutesIdempotency.claim(db, claimed)).toEqual({
+      response: '{"id":"rtr_test"}',
+      type: 'replay',
+    })
+    // A different request against the completed key still conflicts.
+    expect(await RoutesIdempotency.claim(db, { ...claimed, requestHash: 'req_bbbb' })).toEqual({
+      type: 'mismatch',
+    })
+  })
+
+  test('completes non-transfer resources without a transfer id', async () => {
+    const claimed = input({ irrevocable: true })
+    const result = await RoutesIdempotency.claim(db, claimed)
+    expect(result.type).toBe('claimed')
+    if (result.type !== 'claimed') return
+    await RoutesIdempotency.complete(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"id":"rda_test"}',
+    })
+
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['irrevocable', 'transferId'])
+        .where('apiKeyId', '=', claimed.apiKeyId)
+        .where('keyHash', '=', claimed.keyHash)
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({ irrevocable: false, transferId: null })
+  })
+
+  test('reclaims an expired row in place', async () => {
+    const claimed = input()
+    await RoutesIdempotency.claim(db, claimed)
+    const afterExpiry = new Date('2026-01-01T00:01:00.001Z')
+    vi.setSystemTime(afterExpiry)
+    expect(await RoutesIdempotency.claim(db, claimed)).toEqual({
+      createdAt: afterExpiry.toISOString(),
+      type: 'claimed',
+    })
+  })
+
+  test('expires abandoned pending deposit-address reservations', async () => {
+    const claimed = input({
+      operation: RoutesIdempotency.operations.depositAddress,
+      orgId: 'org_address',
+    })
+    await RoutesIdempotency.claim(db, claimed)
+    expect(
+      await RoutesIdempotency.countInFlightDepositAddresses(db, {
+        orgId: claimed.orgId,
+        userId: null,
+      }),
+    ).toBe(1)
+    expect(await RoutesIdempotency.hasInFlightDepositAddress(db, claimed.orgId)).toBe(true)
+
+    vi.setSystemTime(new Date(now.getTime() + ttlMs + 1))
+    expect(
+      await RoutesIdempotency.countInFlightDepositAddresses(db, {
+        orgId: claimed.orgId,
+        userId: null,
+      }),
+    ).toBe(0)
+    await expect(
+      RoutesIdempotency.claim(db, {
+        ...claimed,
+        apiKeyId: 'key_rotated_after_expiry',
+        keyHash: 'hash_rotated_after_expiry',
+      }),
+    ).resolves.toMatchObject({ type: 'claimed' })
+    expect(await RoutesIdempotency.hasInFlightDepositAddress(db, claimed.orgId)).toBe(true)
+  })
+
+  test('keeps provider-attempted subsidy reservations after expiry', async () => {
+    const claimed = input({
+      operation: RoutesIdempotency.operations.depositAddress,
+      orgId: 'org_subsidized_pending',
+    })
+    const result = await RoutesIdempotency.claim(db, claimed)
+    if (result.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    await expect(
+      RoutesIdempotency.markProviderAttempt(db, {
+        apiKeyId: claimed.apiKeyId,
+        createdAt: result.createdAt,
+        keyHash: claimed.keyHash,
+        ttlMs,
+      }),
+    ).resolves.toBe(true)
+    vi.setSystemTime(new Date(now.getTime() + ttlMs + 1))
+
+    expect(await RoutesIdempotency.hasInFlightDepositAddress(db, claimed.orgId)).toBe(true)
+    await expect(RoutesIdempotency.claim(db, claimed)).resolves.toEqual({ type: 'pending' })
+  })
+
+  test('bounds unattributed provider checkpoints by their replay expiry', async () => {
+    const legacy = input({ operation: RoutesIdempotency.operations.depositAddress })
+    const claimed = await RoutesIdempotency.claim(db, legacy)
+    if (claimed.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: legacy.apiKeyId,
+      createdAt: claimed.createdAt,
+      keyHash: legacy.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"legacy"}',
+    })
+    await db.kysely
+      .updateTable('routes_idempotency_requests')
+      .set({ operation: null, orgId: null })
+      .where('apiKeyId', '=', legacy.apiKeyId)
+      .where('keyHash', '=', legacy.keyHash)
+      .execute()
+
+    expect(await RoutesIdempotency.hasUnattributedInFlightClaim(db)).toBe(true)
+    vi.setSystemTime(new Date(now.getTime() + replayTtlMs + 1))
+    expect(await RoutesIdempotency.hasUnattributedInFlightClaim(db)).toBe(false)
+  })
+
+  test('release frees a pending claim for retry', async () => {
+    const claimed = input()
+    const result = await RoutesIdempotency.claim(db, claimed)
+    expect(result.type).toBe('claimed')
+    if (result.type !== 'claimed') return
+    await RoutesIdempotency.release(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+    })
+    expect(await RoutesIdempotency.claim(db, claimed)).toEqual({
+      createdAt: now.toISOString(),
+      type: 'claimed',
+    })
+  })
+
+  test('stale completion and release cannot mutate a replacement claim', async () => {
+    const claimed = input()
+    const original = await RoutesIdempotency.claim(db, claimed)
+    expect(original.type).toBe('claimed')
+    if (original.type !== 'claimed') return
+
+    const afterExpiry = new Date('2026-01-01T00:01:00.001Z')
+    vi.setSystemTime(afterExpiry)
+    const replacement = await RoutesIdempotency.claim(db, claimed)
+    expect(replacement.type).toBe('claimed')
+    if (replacement.type !== 'claimed') return
+
+    const identity = {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: original.createdAt,
+      keyHash: claimed.keyHash,
+    }
+    expect(
+      await RoutesIdempotency.complete(db, {
+        ...identity,
+        replayTtlMs,
+        response: '{"id":"rtr_stale"}',
+        transferId: 'rtr_stale',
+      }),
+    ).toBeUndefined()
+    await RoutesIdempotency.release(db, identity)
+    expect(await RoutesIdempotency.claim(db, claimed)).toEqual({
+      type: 'pending',
+    })
+  })
+})
+
+describe('isOwnerFenceError', () => {
+  test('accepts only the route owner trigger violations', () => {
+    expect(
+      RoutesIdempotency.isOwnerFenceError(
+        databaseError('ownerless route idempotency creation is disabled'),
+      ),
+    ).toBe(true)
+    expect(
+      RoutesIdempotency.isOwnerFenceError(databaseError('route idempotency owner was deleted')),
+    ).toBe(true)
+    expect(
+      RoutesIdempotency.isOwnerFenceError(
+        databaseError('insert or update violates an unrelated foreign key constraint'),
+      ),
+    ).toBe(false)
+    expect(
+      RoutesIdempotency.isOwnerFenceError(
+        databaseError('route idempotency owner was deleted', '23505'),
+      ),
+    ).toBe(false)
+  })
+})
+
+describe('checkpoint', () => {
+  test('resumes a provider result and completes it', async () => {
+    const claimed = input()
+    const result = await RoutesIdempotency.claim(db, claimed)
+    expect(result.type).toBe('claimed')
+    if (result.type !== 'claimed') return
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"relay_request_1"}',
+    })
+
+    expect(await RoutesIdempotency.claim(db, claimed)).toEqual({
+      checkpointFresh: true,
+      createdAt: now.toISOString(),
+      response: '{"requestId":"relay_request_1"}',
+      type: 'resume',
+    })
+    await RoutesIdempotency.complete(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"id":"rda_test"}',
+    })
+    expect(await RoutesIdempotency.claim(db, claimed)).toEqual({
+      response: '{"id":"rda_test"}',
+      type: 'replay',
+    })
+  })
+
+  test('expires unsubsidized checkpoints from capacity while keeping them resumable', async () => {
+    const claimed = input({
+      operation: RoutesIdempotency.operations.depositAddress,
+      orgId: 'org_provisioned',
+    })
+    const result = await RoutesIdempotency.claim(db, claimed)
+    if (result.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"relay_request_1"}',
+    })
+    vi.setSystemTime(new Date(now.getTime() + replayTtlMs + 1))
+
+    expect(await RoutesIdempotency.claim(db, claimed)).toMatchObject({
+      checkpointFresh: false,
+      response: '{"requestId":"relay_request_1"}',
+      type: 'resume',
+    })
+    expect(
+      await RoutesIdempotency.countInFlightDepositAddresses(db, {
+        orgId: claimed.orgId,
+        userId: null,
+      }),
+    ).toBe(0)
+  })
+
+  test('keeps subsidized checkpoints reserved after replay expiry', async () => {
+    const claimed = input({
+      irrevocable: true,
+      operation: RoutesIdempotency.operations.depositAddress,
+      orgId: 'org_subsidized_provisioned',
+    })
+    const result = await RoutesIdempotency.claim(db, claimed)
+    if (result.type !== 'claimed') throw new Error('Expected a fresh claim.')
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"relay_request_2"}',
+    })
+    vi.setSystemTime(new Date(now.getTime() + replayTtlMs + 1))
+
+    expect(
+      await RoutesIdempotency.countInFlightDepositAddresses(db, {
+        orgId: claimed.orgId,
+        userId: null,
+      }),
+    ).toBe(1)
+    await expect(
+      RoutesIdempotency.claim(db, {
+        ...claimed,
+        apiKeyId: 'key_subsidized_rotated',
+        keyHash: 'hash_subsidized_rotated',
+      }),
+    ).resolves.toMatchObject({
+      checkpointFresh: false,
+      response: '{"requestId":"relay_request_2"}',
+      type: 'resume',
+    })
+  })
+})