tapimo 0.15.1 → 0.18.0

package/src/db/tables/routesDeposits.ts

@@ -1,4 +1,4 @@
-import { sql, type JSONColumnType, type Selectable } from 'kysely'
+import { type ExpressionBuilder, type JSONColumnType, type Selectable, sql } from 'kysely'
 
 import * as Fees from '../../internal/Fees.js'
 import type * as Db from '../Db.js'
@@ -810,6 +810,27 @@ export function subsidies(record: Record) {
   ]
 }
 
+function subsidyFinalized(eb: ExpressionBuilder<Db.Database, 'routes_deposits'>) {
+  return eb.or([
+    eb('status', '=', 'completed'),
+    eb.and([
+      eb('status', 'in', ['action-required', 'settling']),
+      eb('tempoGasPaid', 'is not', null),
+    ]),
+    // Fixed-rate shortfalls never create a later Tempo top-up, so provider expense is final.
+    eb.and([
+      eb('status', '=', 'action-required'),
+      eb.exists(
+        eb
+          .selectFrom('routes_deposit_addresses')
+          .select('routes_deposit_addresses.id')
+          .whereRef('routes_deposit_addresses.id', '=', 'routes_deposits.depositAddressId')
+          .where(sql<boolean>`routes_deposit_addresses.provider_state->>'fixedRate' = '1:1'`),
+      ),
+    ]),
+  ])
+}
+
 /** Lists verified production subsidies awaiting a Stripe acknowledgement. */
 export function listUnreportedSubsidies(
   db: Db.Db,
@@ -819,15 +840,7 @@ export function listUnreportedSubsidies(
     .selectFrom('routes_deposits')
     .selectAll()
     .where('environment', '=', 'production')
-    .where((eb) =>
-      eb.or([
-        eb('status', '=', 'completed'),
-        eb.and([
-          eb('status', 'in', ['action-required', 'settling']),
-          eb('tempoGasPaid', 'is not', null),
-        ]),
-      ]),
-    )
+    .where(subsidyFinalized)
     .where((eb) =>
       eb.or([
         sql<boolean>`(provider_subsidy->'amount'->>'baseUnits')::numeric > 0`,
@@ -839,6 +852,17 @@ export function listUnreportedSubsidies(
       ]),
     )
     .where('subsidyMeterReportedAt', 'is', null)
+    .where((eb) =>
+      eb.exists(
+        eb
+          .selectFrom('routes_deposit_addresses')
+          .select('routes_deposit_addresses.id')
+          .whereRef('routes_deposit_addresses.id', '=', 'routes_deposits.depositAddressId')
+          .where(
+            sql<boolean>`coalesce(routes_deposit_addresses.provider_state->'routePolicy'->>'subsidyPayer', 'enterprise') <> 'tempo'`,
+          ),
+      ),
+    )
     .orderBy('statusUpdatedAt', 'asc')
     .orderBy('id', 'asc')
   if (options.limit !== undefined) query = query.limit(options.limit)
@@ -878,17 +902,22 @@ export async function hasUnreportedSubsidies(
       .where('environment', '=', 'production')
       .where('orgId', '=', options.orgId)
       .where('status', 'in', ['action-required', 'settling', 'completed'])
+      .where((eb) =>
+        eb.exists(
+          eb
+            .selectFrom('routes_deposit_addresses')
+            .select('routes_deposit_addresses.id')
+            .whereRef('routes_deposit_addresses.id', '=', 'routes_deposits.depositAddressId')
+            .where(
+              sql<boolean>`coalesce(routes_deposit_addresses.provider_state->'routePolicy'->>'subsidyPayer', 'enterprise') <> 'tempo'`,
+            ),
+        ),
+      )
       .where((eb) =>
         eb.or([
           eb.and([
             sql<boolean>`(provider_subsidy->'amount'->>'baseUnits')::numeric > 0`,
-            eb.or([
-              eb('status', '=', 'completed'),
-              eb.and([
-                eb('status', 'in', ['action-required', 'settling']),
-                eb('tempoGasPaid', 'is not', null),
-              ]),
-            ]),
+            subsidyFinalized(eb),
           ]),
           eb.and([
             eb('settlementTransactionHash', 'is not', null),
@@ -929,15 +958,7 @@ export async function subsidyUsage(
     ])
     .where('orgId', '=', options.orgId)
     .where('environment', '=', options.environment)
-    .where((eb) =>
-      eb.or([
-        eb('status', '=', 'completed'),
-        eb.and([
-          eb('status', 'in', ['action-required', 'settling']),
-          eb('tempoGasPaid', 'is not', null),
-        ]),
-      ]),
-    )
+    .where(subsidyFinalized)
     .where((eb) =>
       eb.or([
         sql<boolean>`(provider_subsidy->'amount'->>'baseUnits')::numeric > 0`,

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

@@ -317,6 +317,86 @@ describe('claim', () => {
     ])
   })
 
+  test('resumes the oldest of several shared provider checkpoints', async () => {
+    const claims: RoutesIdempotency.release.Input[] = []
+    for (const [index, name] of ['older', 'newer'].entries()) {
+      vi.setSystemTime(new Date(now.getTime() + index * 1_000))
+      const request = input({
+        apiKeyId: `key_${name}`,
+        keyHash: `hash_${name}`,
+        operation: RoutesIdempotency.operations.depositAddress,
+      })
+      const claimed = await RoutesIdempotency.claim(db, request)
+      if (claimed.type !== 'claimed') throw new Error('Expected a fresh claim.')
+      claims.push({ ...request, createdAt: claimed.createdAt })
+    }
+    const [older, newer] = claims
+    if (!older || !newer) throw new Error('Expected two claims.')
+    for (const [claimed, response] of [
+      [older, '{"requestId":"relay_older"}'],
+      [newer, '{"requestId":"relay_newer"}'],
+    ] as const)
+      await RoutesIdempotency.checkpoint(db, { ...claimed, replayTtlMs, response })
+
+    await expect(
+      RoutesIdempotency.claim(
+        db,
+        input({
+          apiKeyId: 'key_rotated',
+          keyHash: 'hash_rotated',
+          operation: RoutesIdempotency.operations.depositAddress,
+        }),
+      ),
+    ).resolves.toMatchObject({
+      recoveredClaim: { apiKeyId: older.apiKeyId, createdAt: older.createdAt },
+      response: '{"requestId":"relay_older"}',
+      type: 'resume',
+    })
+  })
+
+  test('resumes the oldest of several provisioned match checkpoints', async () => {
+    const claims: RoutesIdempotency.release.Input[] = []
+    for (const [index, name] of ['older', 'newer', 'retry'].entries()) {
+      vi.setSystemTime(new Date(now.getTime() + index * 1_000))
+      const request = input({
+        apiKeyId: `key_${name}`,
+        keyHash: `hash_${name}`,
+        operation: RoutesIdempotency.operations.depositAddress,
+        requestHash: `req_${name}`,
+      })
+      const claimed = await RoutesIdempotency.claim(db, request)
+      if (claimed.type !== 'claimed') throw new Error('Expected a fresh claim.')
+      claims.push({ ...request, createdAt: claimed.createdAt })
+    }
+    const [older, newer, retry] = claims
+    if (!older || !newer || !retry) throw new Error('Expected three claims.')
+    const reserve = (claimed: RoutesIdempotency.release.Input) =>
+      RoutesIdempotency.reserveDepositAddressMatch(db, {
+        ...claimed,
+        matchHash: 'match_shared',
+        orgId: 'org_test',
+        ttlMs,
+      })
+    await expect(reserve(older)).resolves.toEqual({ type: 'reserved' })
+    await RoutesIdempotency.checkpoint(db, {
+      ...older,
+      replayTtlMs,
+      response: '{"requestId":"relay_older"}',
+    })
+    await expect(reserve(newer)).resolves.toMatchObject({ type: 'resume' })
+    await RoutesIdempotency.checkpoint(db, {
+      ...newer,
+      replayTtlMs,
+      response: '{"requestId":"relay_newer"}',
+    })
+
+    await expect(reserve(retry)).resolves.toMatchObject({
+      claim: { apiKeyId: older.apiKeyId, createdAt: older.createdAt },
+      response: '{"requestId":"relay_older"}',
+      type: 'resume',
+    })
+  })
+
   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)

package/src/db/tables/routesIdempotency.ts

@@ -70,6 +70,7 @@ export async function claim(db: Db.Db, input: claim.Input): Promise<claim.Result
       .where('status', '=', 'provisioned')
       .where((eb) => eb.or([eb('expiresAt', '>', now.toISOString()), eb('irrevocable', '=', true)]))
       .orderBy('createdAt', 'asc')
+      .limit(1)
       .forUpdate()
       .executeTakeFirst()
     if (!recoverable) return { createdAt: inserted.createdAt, type: 'claimed' }
@@ -311,6 +312,7 @@ export async function reserveDepositAddressMatch(
     .where('status', '=', 'provisioned')
     .where((eb) => eb.or([eb('expiresAt', '>', now.toISOString()), eb('irrevocable', '=', true)]))
     .orderBy('createdAt', 'asc')
+    .limit(1)
     .forUpdate()
     .executeTakeFirst()
   if (provisioned && claimed.status === 'pending') {

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

@@ -0,0 +1,143 @@
+import * as TestApp from '../../../test/App.js'
+import * as Organizations from './organizations.js'
+import * as RoutesPolicies from './routesPolicies.js'
+
+describe('save', () => {
+  test('serializes competing version-zero writes as a domain conflict', async () => {
+    const db = TestApp.database()
+    await Organizations.create(db, { id: 'org_policy', name: 'Policy' })
+    const scope = { environment: 'production', orgId: 'org_policy' } as const
+    const results = await Promise.allSettled([
+      RoutesPolicies.save(db, { policy: { maxAmount: '1' }, scope, version: 0 }),
+      RoutesPolicies.save(db, { policy: { maxAmount: '2' }, scope, version: 0 }),
+    ])
+    expect(
+      results
+        .map((result) =>
+          result.status === 'fulfilled' ? result.value.version : result.reason?.name,
+        )
+        .sort((a, b) => String(a).localeCompare(String(b))),
+    ).toMatchInlineSnapshot(`
+      [
+        1,
+        "RoutesPolicies.ConflictError",
+      ]
+    `)
+  })
+})
+
+describe('load', () => {
+  test('preserves missing positional layers', async () => {
+    const db = TestApp.database()
+    await Organizations.create(db, { id: 'org_layers', name: 'Layers' })
+    const loaded = await RoutesPolicies.load(db, {
+      apiKeyId: 'key_1',
+      environment: 'sandbox',
+      orgId: 'org_layers',
+    })
+    expect(loaded.layers).toMatchInlineSnapshot(`
+      [
+        {
+          "policy": {},
+          "scope": {
+            "environment": "sandbox",
+            "orgId": "org_layers",
+          },
+          "version": 0,
+        },
+        {
+          "policy": {},
+          "scope": {
+            "apiKeyId": "key_1",
+            "environment": "sandbox",
+            "orgId": "org_layers",
+          },
+          "version": 0,
+        },
+      ]
+    `)
+  })
+})
+
+describe('clearKey', () => {
+  test('clears every matching scope, increments revisions, and ignores an absent key', async () => {
+    const db = TestApp.database()
+    await Organizations.create(db, { id: 'org_clear', name: 'Clear' })
+    for (const environment of ['production', 'sandbox'] as const)
+      await RoutesPolicies.save(db, {
+        policy: { maxAmount: environment === 'production' ? '1' : '2' },
+        scope: { apiKeyId: 'key_clear', environment, orgId: 'org_clear' },
+        version: 0,
+      })
+
+    const cleared = await RoutesPolicies.clearKey(db, { apiKeyId: 'key_clear' })
+
+    expect(cleared.map(({ policy, version }) => ({ policy, version }))).toEqual([
+      { policy: {}, version: 2 },
+      { policy: {}, version: 2 },
+    ])
+    await expect(
+      RoutesPolicies.save(db, {
+        policy: { maxAmount: '3' },
+        scope: { apiKeyId: 'key_clear', environment: 'production', orgId: 'org_clear' },
+        version: 1,
+      }),
+    ).rejects.toBeInstanceOf(RoutesPolicies.ConflictError)
+    await expect(RoutesPolicies.clearKey(db, { apiKeyId: 'key_missing' })).resolves.toEqual([])
+    for (const environment of ['production', 'sandbox'] as const)
+      expect(
+        await RoutesPolicies.get(db, {
+          apiKeyId: 'key_clear',
+          environment,
+          orgId: 'org_clear',
+        }),
+      ).toMatchObject({ policy: {}, version: 2 })
+  })
+})
+
+describe('copyKey', () => {
+  test('copies independently, no-ops when absent, rejects cross-scope, and rolls back', async () => {
+    const db = TestApp.database()
+    await Organizations.create(db, { id: 'org_copy', name: 'Copy' })
+    const source = { apiKeyId: 'key_source', environment: 'production', orgId: 'org_copy' } as const
+    const destination = { ...source, apiKeyId: 'key_destination' }
+    await RoutesPolicies.save(db, {
+      policy: { maxAmount: '7' },
+      scope: source,
+      version: 0,
+    })
+
+    await RoutesPolicies.copyKey(db, { destination, source })
+    await RoutesPolicies.save(db, {
+      policy: { maxAmount: '9' },
+      scope: source,
+      version: 1,
+    })
+    expect((await RoutesPolicies.get(db, destination))?.policy).toEqual({ maxAmount: '7' })
+    await expect(
+      RoutesPolicies.copyKey(db, {
+        destination: { ...destination, apiKeyId: 'key_absent_destination' },
+        source: { ...source, apiKeyId: 'key_absent' },
+      }),
+    ).resolves.toBeUndefined()
+    await expect(
+      RoutesPolicies.copyKey(db, {
+        destination: { ...destination, environment: 'sandbox' },
+        source,
+      }),
+    ).rejects.toThrow(RoutesPolicies.InvalidScopeError)
+
+    await expect(
+      db.transaction(async (tx) => {
+        await RoutesPolicies.copyKeyIn(tx, {
+          destination: { ...destination, apiKeyId: 'key_rollback' },
+          source,
+        })
+        throw new Error('rollback')
+      }),
+    ).rejects.toThrow('rollback')
+    expect(
+      await RoutesPolicies.get(db, { ...destination, apiKeyId: 'key_rollback' }),
+    ).toBeUndefined()
+  })
+})

package/src/db/tables/routesPolicies.ts

@@ -0,0 +1,251 @@
+import { sql, type Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as Schema from '../Schema.js'
+import type * as Policy from '../../internal/routes/Policy.js'
+import * as RoutesSubsidies from './routesSubsidies.js'
+
+export type Table = Schema.RoutesPolicy
+export type Record = Omit<Selectable<Table>, 'apiKeyId' | 'projectId'> & Policy.Scope
+export type Layer = { scope: Policy.Scope; version: number; policy: Policy.Overrides }
+export class ConflictError extends Error {
+  override name = 'RoutesPolicies.ConflictError'
+}
+export class InvalidScopeError extends Error {
+  override name = 'RoutesPolicies.InvalidScopeError'
+}
+
+export async function get(db: Db.Db, scope: Policy.Scope): Promise<Record | undefined> {
+  const row = await scoped(db, scope).selectAll().executeTakeFirst()
+  return row && domain(row)
+}
+
+export async function load(
+  db: Db.Db,
+  scope: Policy.Scope,
+): Promise<{ layers: Layer[]; legacy: Policy.Legacy }> {
+  const scopes: Policy.Scope[] = [
+    { orgId: scope.orgId, environment: scope.environment },
+    ...(scope.projectId
+      ? [{ orgId: scope.orgId, environment: scope.environment, projectId: scope.projectId }]
+      : []),
+    ...(scope.apiKeyId ? [scope] : []),
+  ]
+  const records = await Promise.all(scopes.map((item) => get(db, item)))
+  const legacy = await RoutesSubsidies.getOrganization(db, scope.orgId)
+  return {
+    layers: records.map((record, index) =>
+      record
+        ? { scope: pickScope(record), version: record.version, policy: record.policy }
+        : { scope: scopes[index]!, version: 0, policy: {} },
+    ),
+    legacy: {
+      subsidyEnabled: legacy?.enabled ?? false,
+      maxAmount: legacy?.maxAmount ?? '0',
+      subsidyPayer: 'enterprise',
+    },
+  }
+}
+
+export function save(
+  db: Db.Db,
+  input: {
+    scope: Policy.Scope
+    version: number
+    policy: Policy.Overrides
+    /** Revalidates external key ownership under the policy lock. */
+    validateScope?: (() => Promise<boolean>) | undefined
+  },
+): Promise<Record> {
+  return db.transaction(async (tx) => {
+    await RoutesSubsidies.lockOrganization(tx, input.scope.orgId)
+    if (input.validateScope && !(await input.validateScope())) throw new InvalidScopeError()
+    return saveIn(tx, input)
+  })
+}
+
+export function clearKey(db: Db.Db, input: clearKey.Input): Promise<readonly Record[]> {
+  return db.transaction((tx) => clearKeyIn(tx, input))
+}
+
+/** Locks current, destination, and historical key policy owners before owner or admission locks. */
+export async function lockKeyOrganizations(
+  db: Db.Db,
+  input: lockKeyOrganizations.Input,
+): Promise<void> {
+  const rows = await db.kysely
+    .selectFrom('routes_policies')
+    .select('orgId')
+    .where('apiKeyId', '=', input.apiKeyId)
+    .distinct()
+    .execute()
+  for (const orgId of [...new Set([...input.orgIds, ...rows.map((row) => row.orgId)])].sort())
+    await RoutesSubsidies.lockOrganization(db, orgId)
+}
+
+export declare namespace lockKeyOrganizations {
+  /** Key being reassigned and its current and destination owners. */
+  type Input = {
+    /** API key identifier. */
+    apiKeyId: string
+    /** Current and destination organization identifiers. */
+    orgIds: readonly string[]
+  }
+}
+
+/** Clears key overrides inside a caller-owned transaction. */
+export async function clearKeyIn(db: Db.Db, input: clearKey.Input): Promise<readonly Record[]> {
+  const rows = await db.kysely
+    .selectFrom('routes_policies')
+    .selectAll()
+    .where('apiKeyId', '=', input.apiKeyId)
+    .orderBy('orgId')
+    .orderBy('environment')
+    .orderBy('projectId')
+    .execute()
+  const records: Record[] = []
+  for (const row of rows) {
+    await RoutesSubsidies.lockOrganization(db, row.orgId)
+    // Former projects may be deleted; retain monotonic revisions without revalidating their existence.
+    const updated = await db.kysely
+      .updateTable('routes_policies')
+      .set({ policy: {}, updatedAt: new Date().toISOString(), version: sql`version + 1` })
+      .where('orgId', '=', row.orgId)
+      .where('environment', '=', row.environment)
+      .where('projectId', '=', row.projectId)
+      .where('apiKeyId', '=', row.apiKeyId)
+      .returningAll()
+      .executeTakeFirst()
+    if (updated) records.push(domain(updated))
+  }
+  return records
+}
+
+export namespace clearKey {
+  export type Input = { apiKeyId: string }
+}
+
+export function copyKey(db: Db.Db, input: copyKey.Input): Promise<Record | undefined> {
+  if (
+    input.source.environment !== input.destination.environment ||
+    input.source.orgId !== input.destination.orgId ||
+    input.source.projectId !== input.destination.projectId
+  )
+    return Promise.reject(new InvalidScopeError())
+  return db.transaction((tx) => copyKeyIn(tx, input))
+}
+
+/** Copies key overrides inside a caller-owned transaction. */
+export async function copyKeyIn(db: Db.Db, input: copyKey.Input): Promise<Record | undefined> {
+  if (
+    input.source.environment !== input.destination.environment ||
+    input.source.orgId !== input.destination.orgId ||
+    input.source.projectId !== input.destination.projectId
+  )
+    throw new InvalidScopeError()
+  await RoutesSubsidies.lockOrganization(db, input.destination.orgId)
+  const source = await get(db, input.source)
+  if (!input.source.apiKeyId || !input.destination.apiKeyId) throw new InvalidScopeError()
+  if (!source) return undefined
+  const destination = await get(db, input.destination)
+  return saveIn(db, {
+    policy: source.policy,
+    scope: input.destination,
+    version: destination?.version ?? 0,
+  })
+}
+
+export namespace copyKey {
+  export type Input = { destination: Policy.Scope; source: Policy.Scope }
+}
+
+async function saveIn(
+  db: Db.Db,
+  input: { scope: Policy.Scope; version: number; policy: Policy.Overrides },
+): Promise<Record> {
+  await validateScope(db, input.scope)
+  if (
+    (input.scope.projectId !== undefined || input.scope.apiKeyId !== undefined) &&
+    input.policy.suspended !== undefined
+  )
+    throw new InvalidScopeError()
+  const before = await get(db, input.scope)
+  if ((before?.version ?? 0) !== input.version) throw new ConflictError()
+  const now = new Date().toISOString()
+  const keys = storage(input.scope)
+  const row =
+    input.version === 0
+      ? await db.kysely
+          .insertInto('routes_policies')
+          .values({ ...keys, version: 1, policy: input.policy, createdAt: now, updatedAt: now })
+          .returningAll()
+          .executeTakeFirstOrThrow()
+      : await db.kysely
+          .updateTable('routes_policies')
+          .set({ version: input.version + 1, policy: input.policy, updatedAt: now })
+          .where('orgId', '=', keys.orgId)
+          .where('environment', '=', keys.environment)
+          .where('projectId', '=', keys.projectId)
+          .where('apiKeyId', '=', keys.apiKeyId)
+          .where('version', '=', input.version)
+          .returningAll()
+          .executeTakeFirst()
+  if (!row) throw new ConflictError()
+  return domain(row)
+}
+
+function scoped(db: Db.Db, scope: Policy.Scope) {
+  const key = storage(scope)
+  return db.kysely
+    .selectFrom('routes_policies')
+    .where('orgId', '=', key.orgId)
+    .where('environment', '=', key.environment)
+    .where('projectId', '=', key.projectId)
+    .where('apiKeyId', '=', key.apiKeyId)
+}
+function storage(scope: Policy.Scope) {
+  return {
+    orgId: scope.orgId,
+    environment: scope.environment,
+    projectId: scope.projectId ?? '',
+    apiKeyId: scope.apiKeyId ?? '',
+  }
+}
+function domain(row: Selectable<Table>): Record {
+  return {
+    orgId: row.orgId,
+    environment: row.environment,
+    ...(row.projectId ? { projectId: row.projectId } : {}),
+    ...(row.apiKeyId ? { apiKeyId: row.apiKeyId } : {}),
+    version: row.version,
+    policy: row.policy,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  }
+}
+function pickScope(value: Policy.Scope): Policy.Scope {
+  return {
+    orgId: value.orgId,
+    environment: value.environment,
+    ...(value.projectId ? { projectId: value.projectId } : {}),
+    ...(value.apiKeyId ? { apiKeyId: value.apiKeyId } : {}),
+  }
+}
+async function validateScope(db: Db.Db, scope: Policy.Scope) {
+  if (scope.projectId) {
+    const project = await db.kysely
+      .selectFrom('projects')
+      .select('id')
+      .where('id', '=', scope.projectId)
+      .where('orgId', '=', scope.orgId)
+      .executeTakeFirst()
+    if (!project) throw new InvalidScopeError()
+  } else {
+    const org = await db.kysely
+      .selectFrom('organizations')
+      .select('id')
+      .where('id', '=', scope.orgId)
+      .executeTakeFirst()
+    if (!org) throw new InvalidScopeError()
+  }
+}

package/src/db/tables/routesTransferSubsidies.ts

@@ -7,6 +7,8 @@ import type * as Schema from '../Schema.js'
 export type Table = Schema.RoutesTransferSubsidy
 /** A shared subsidy transaction and its billing owner. */
 export type Record = Selectable<Table>
+/** Immutable evidence for an expired signed Solana attempt. */
+export type ExpiredAttemptTable = Schema.RoutesTransferSubsidyExpiredAttempt
 
 /** Serializes subsidy preparation for a source payment and returns its persisted settlement. */
 export async function getForUpdateIn(
@@ -36,3 +38,65 @@ export declare namespace getForUpdateIn {
     transactionRef: string
   }
 }
+
+/** Archives an expired Solana signature under the canonical source lock. */
+export async function markExpiredIn(
+  db: Db.Db,
+  options: markExpiredIn.Options,
+): Promise<markExpiredIn.Result> {
+  const settlement = await getForUpdateIn(db, options)
+  if (!settlement) return { type: 'not_found' }
+  if (settlement.transferId !== options.transferId) return { settlement, type: 'shared' }
+  if (
+    settlement.status !== 'active' ||
+    !settlement.destinationChainId.startsWith('solana:') ||
+    settlement.transaction !== options.signedTransaction
+  )
+    return { settlement, type: 'stale' }
+  const signed: unknown = JSON.parse(options.signedTransaction)
+  if (
+    !signed ||
+    typeof signed !== 'object' ||
+    !('hash' in signed) ||
+    signed.hash !== options.signedHash
+  )
+    return { settlement, type: 'stale' }
+
+  // The caller proves final expiry before entering this transaction. Exact transaction
+  // comparison prevents a late recovery worker from replacing a newer signature.
+  const expiredAt = new Date().toISOString()
+  await db.kysely
+    .insertInto('routes_transfer_subsidy_expired_attempts')
+    .values({
+      createdAt: settlement.createdAt,
+      expiredAt,
+      sourceChainId: settlement.sourceChainId,
+      transaction: JSON.stringify(settlement.transaction),
+      transactionHash: options.signedHash,
+      transactionRef: settlement.transactionRef,
+      transferId: settlement.transferId,
+    })
+    .execute()
+  await db.kysely
+    .updateTable('routes_transfer_subsidies')
+    .set({ status: 'expired' })
+    .where('sourceChainId', '=', options.sourceChainId)
+    .where('transactionRef', '=', options.transactionRef)
+    .where('status', '=', 'active')
+    .executeTakeFirstOrThrow()
+  return { settlement: { ...settlement, status: 'expired' }, type: 'expired' }
+}
+
+export declare namespace markExpiredIn {
+  /** Expected canonical signed Solana attempt and its original billing owner. */
+  type Options = getForUpdateIn.Options & {
+    /** Signature of the signed attempt being retired. */
+    signedHash: string
+    /** Exact serialized signed transaction persisted in the settlement row. */
+    signedTransaction: string
+    /** Original subsidy billing owner. */
+    transferId: string
+  }
+  /** Outcome of the source-keyed expiry compare and swap. */
+  type Result = { type: 'not_found' } | { settlement: Record; type: 'expired' | 'shared' | 'stale' }
+}