tapimo 0.15.0 → 0.18.0

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

@@ -9,6 +9,7 @@ import * as Deposit from '../../internal/routes/Deposit.js'
 import * as DepositAddress from '../../internal/routes/DepositAddress.js'
 import * as Transfer from '../../internal/routes/Transfer.js'
 import * as Db from '../Db.js'
+import * as ApiKeyOwnerTombstones from './apiKeyOwnerTombstones.js'
 import * as EnabledBillingSources from './enabledBillingSources.js'
 import * as Memberships from './memberships.js'
 import * as Organizations from './organizations.js'
@@ -665,48 +666,52 @@ describe('deleteOrganization', () => {
     await db.close()
   })
 
-  test('behavior: preserves an org with unreported billable sponsorships', async () => {
-    const db = create()
-    await db.migrate()
-    await Organizations.create(db, { id: 'org_1', name: 'One' })
-    await StripeCustomers.create(db, {
-      orgId: 'org_1',
-      stripeCustomerId: 'cus_org_1',
-    })
-    await EnabledBillingSources.add(db, {
-      createdBy: 'admin@tempo.xyz',
-      orgId: 'org_1',
-      source: 'stripe',
-    })
-    await SponsoredTransactions.upsert(db, {
-      apiKeyId: 'key_1',
-      billable: true,
-      chainId: 4217,
-      environment: 'production',
-      orgId: 'org_1',
-      projectId: 'prj_1',
-      signPayload: `0x${'bb'.repeat(32)}`,
-      transaction: `0x76${'cc'.repeat(16)}`,
-      transactionHash: `0x${'aa'.repeat(32)}`,
-    })
+  test.each([Viem.chainId.mainnet, 421700001])(
+    'behavior: preserves billable sponsorships on chain %s',
+    async (chainId) => {
+      const db = create()
+      await db.migrate()
+      await Organizations.create(db, { id: 'org_1', name: 'One' })
+      await StripeCustomers.create(db, {
+        orgId: 'org_1',
+        stripeCustomerId: 'cus_org_1',
+      })
+      await EnabledBillingSources.add(db, {
+        createdBy: 'admin@tempo.xyz',
+        orgId: 'org_1',
+        source: 'stripe',
+      })
+      await SponsoredTransactions.upsert(db, {
+        apiKeyId: 'key_1',
+        billable: true,
+        chainId,
+        environment: 'production',
+        orgId: 'org_1',
+        projectId: 'prj_1',
+        signPayload: `0x${'bb'.repeat(32)}`,
+        transaction: `0x76${'cc'.repeat(16)}`,
+        transactionHash: `0x${'aa'.repeat(32)}`,
+      })
 
-    expect(await Organizations.hasUnreportedMeteredUsage(db, 'org_1')).toBe(true)
-    await expect(Organizations.deleteOrganization(db, 'org_1')).rejects.toThrow(
-      Organizations.UnreportedMeteredUsageError,
-    )
-    expect(await Organizations.get(db, 'org_1')).toBeDefined()
-    expect(await EnabledBillingSources.isEnabled(db, { orgId: 'org_1', source: 'stripe' })).toBe(
-      true,
-    )
-    expect(await StripeCustomers.get(db, 'org_1')).toBeDefined()
-    await db.close()
-  })
+      expect(await Organizations.hasUnreportedMeteredUsage(db, 'org_1')).toBe(true)
+      await expect(Organizations.deleteOrganization(db, 'org_1')).rejects.toThrow(
+        Organizations.UnreportedMeteredUsageError,
+      )
+      expect(await Organizations.get(db, 'org_1')).toBeDefined()
+      expect(await EnabledBillingSources.isEnabled(db, { orgId: 'org_1', source: 'stripe' })).toBe(
+        true,
+      )
+      expect(await StripeCustomers.get(db, 'org_1')).toBeDefined()
+      expect(await ApiKeyOwnerTombstones.isDeleted(db, { orgId: 'org_1' })).toBe(false)
+      await db.close()
+    },
+  )
 
-  test('behavior: deletes an org with only failed or non-mainnet sponsorships', async () => {
+  test('behavior: deletes an org with only reported or non-billable sponsorships', async () => {
     const db = create()
     await db.migrate()
     await Organizations.create(db, { id: 'org_1', name: 'One' })
-    const failed = await SponsoredTransactions.upsert(db, {
+    const reported = await SponsoredTransactions.upsert(db, {
       apiKeyId: 'key_1',
       billable: true,
       chainId: Viem.chainId.mainnet,
@@ -717,10 +722,14 @@ describe('deleteOrganization', () => {
       transaction: `0x76${'cc'.repeat(16)}`,
       transactionHash: `0x${'aa'.repeat(32)}`,
     })
-    await SponsoredTransactions.fail(db, failed.id, '2026-01-01T00:00:00.000Z')
+    await SponsoredTransactions.finalize(db, reported.id, {
+      feeAmount: '100',
+      finalizedAt: '2026-01-01T00:00:00.000Z',
+    })
+    await SponsoredTransactions.markReported(db, reported.id, '2026-01-01T00:00:01.000Z')
     const testnet = await SponsoredTransactions.upsert(db, {
       apiKeyId: 'key_1',
-      billable: true,
+      billable: false,
       chainId: Viem.chainId.testnet,
       environment: 'production',
       orgId: 'org_1',
@@ -878,6 +887,51 @@ describe('deleteOrganization', () => {
     await db.close()
   })
 
+  test('behavior: deletion waits for an in-flight sponsorship and preserves its billing identity', async () => {
+    const schema = `t_${nanoid()}`
+    const db = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
+    const concurrent = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
+    await db.migrate()
+    await settleRouteRollout(db)
+    await Organizations.create(db, { id: 'org_1', name: 'One' })
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_org_1' })
+    const recorded = Promise.withResolvers<void>()
+    const release = Promise.withResolvers<void>()
+    const sponsorship = db.transaction(async (tx) => {
+      await SponsoredTransactions.upsert(tx, {
+        apiKeyId: 'key_1',
+        billable: true,
+        chainId: 421700001,
+        environment: 'production',
+        orgId: 'org_1',
+        signPayload: `0x${'bb'.repeat(32)}`,
+        transaction: `0x76${'cc'.repeat(16)}`,
+      })
+      recorded.resolve()
+      await release.promise
+    })
+    await recorded.promise
+    const deletion = Organizations.deleteOrganization(concurrent, 'org_1')
+    try {
+      expect(
+        await Promise.race([
+          deletion.then(
+            () => 'deleted',
+            () => 'rejected',
+          ),
+          new Promise((resolve) => setTimeout(() => resolve('waiting'), 100)),
+        ]),
+      ).toBe('waiting')
+    } finally {
+      release.resolve()
+    }
+    await sponsorship
+    await expect(deletion).rejects.toThrow(Organizations.UnreportedMeteredUsageError)
+    expect(await StripeCustomers.get(db, 'org_1')).toBeDefined()
+    expect(await ApiKeyOwnerTombstones.isDeleted(db, { orgId: 'org_1' })).toBe(false)
+    await Promise.all([db.close(), concurrent.close()])
+  })
+
   test('behavior: serializes deletion with subsidy liability persistence', async () => {
     const schema = `t_${nanoid()}`
     const db = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
@@ -984,54 +1038,64 @@ describe('deleteOrganization', () => {
     await db.close()
   })
 
-  test('behavior: preserves an org with a recoverable failed fill intent', async () => {
-    const db = create()
-    await db.migrate()
-    await Organizations.create(db, { id: 'org_1', name: 'One' })
-    const failed = await SponsoredTransactions.upsert(db, {
-      apiKeyId: 'key_1',
-      billable: true,
-      chainId: Viem.chainId.mainnet,
-      environment: 'production',
-      orgId: 'org_1',
-      projectId: 'prj_1',
-      signPayload: `0x${'bb'.repeat(32)}`,
-      transaction: `0x76${'cc'.repeat(16)}`,
-    })
-    await SponsoredTransactions.fail(db, failed.id, new Date().toISOString())
+  test.each([undefined, `0x${'aa'.repeat(32)}`])(
+    'behavior: preserves a failed sponsorship with hash %s',
+    async (transactionHash) => {
+      const db = create()
+      await db.migrate()
+      await Organizations.create(db, { id: 'org_1', name: 'One' })
+      const failed = await SponsoredTransactions.upsert(db, {
+        apiKeyId: 'key_1',
+        billable: true,
+        chainId: Viem.chainId.mainnet,
+        environment: 'production',
+        orgId: 'org_1',
+        projectId: 'prj_1',
+        signPayload: `0x${'bb'.repeat(32)}`,
+        transaction: `0x76${'cc'.repeat(16)}`,
+        transactionHash,
+      })
+      await SponsoredTransactions.fail(db, failed.id, new Date().toISOString())
 
-    expect(await Organizations.hasUnreportedMeteredUsage(db, 'org_1')).toBe(true)
-    await expect(Organizations.deleteOrganization(db, 'org_1')).rejects.toThrow(
-      Organizations.UnreportedMeteredUsageError,
-    )
-    expect(await Organizations.get(db, 'org_1')).toBeDefined()
-    await db.close()
-  })
+      expect(await Organizations.hasUnreportedMeteredUsage(db, 'org_1')).toBe(true)
+      await expect(Organizations.deleteOrganization(db, 'org_1')).rejects.toThrow(
+        Organizations.UnreportedMeteredUsageError,
+      )
+      expect(await Organizations.get(db, 'org_1')).toBeDefined()
+      await db.close()
+    },
+  )
 
-  test('behavior: deletes an org with only expired failed fill intents', async () => {
-    const db = create()
-    await db.migrate()
-    await Organizations.create(db, { id: 'org_1', name: 'One' })
-    const failed = await SponsoredTransactions.upsert(db, {
-      apiKeyId: 'key_1',
-      billable: true,
-      chainId: Viem.chainId.mainnet,
-      environment: 'production',
-      orgId: 'org_1',
-      projectId: 'prj_1',
-      signPayload: `0x${'bb'.repeat(32)}`,
-      transaction: `0x76${'cc'.repeat(16)}`,
-    })
-    await SponsoredTransactions.fail(
-      db,
-      failed.id,
-      new Date(Date.now() - SponsoredTransactions.failedIntentRecoveryTtlMs - 1).toISOString(),
-    )
+  test.each([undefined, `0x${'aa'.repeat(32)}`])(
+    'behavior: recovery expiry cannot clear a signed liability with hash %s',
+    async (transactionHash) => {
+      const db = create()
+      await db.migrate()
+      await Organizations.create(db, { id: 'org_1', name: 'One' })
+      const failed = await SponsoredTransactions.upsert(db, {
+        apiKeyId: 'key_1',
+        billable: true,
+        chainId: Viem.chainId.mainnet,
+        environment: 'production',
+        orgId: 'org_1',
+        projectId: 'prj_1',
+        signPayload: `0x${'bb'.repeat(32)}`,
+        transaction: `0x76${'cc'.repeat(16)}`,
+        transactionHash,
+      })
+      await SponsoredTransactions.fail(
+        db,
+        failed.id,
+        new Date(Date.now() - SponsoredTransactions.failedIntentRecoveryTtlMs - 1).toISOString(),
+      )
 
-    expect(await Organizations.hasUnreportedMeteredUsage(db, 'org_1')).toBe(false)
-    expect(await Organizations.deleteOrganization(db, 'org_1')).toBe(true)
-    await db.close()
-  })
+      expect(await Organizations.hasUnreportedMeteredUsage(db, 'org_1')).toBe(true)
+      await expect(Organizations.deleteOrganization(db, 'org_1')).rejects.toThrow(
+        Organizations.UnreportedMeteredUsageError,
+      )
+      await db.close()
+    },
+  )
 
   test('behavior: deletes enabled billing sources', async () => {
     const db = create()

package/src/db/tables/organizations.ts

@@ -1,7 +1,6 @@
-import { sql, type ExpressionBuilder, type Selectable } from 'kysely'
+import { sql, type Selectable } from 'kysely'
 
 import * as Id from '../../internal/Id.js'
-import * as Viem from '../../internal/Viem.js'
 import * as ApiKeyAdmissions from './apiKeyAdmissions.js'
 import * as ApiKeyOwnerTombstones from './apiKeyOwnerTombstones.js'
 import * as AuthAccounts from './authAccounts.js'
@@ -9,7 +8,6 @@ import * as RoutesDepositAddresses from './routesDepositAddresses.js'
 import * as RoutesDeposits from './routesDeposits.js'
 import * as RoutesIdempotency from './routesIdempotency.js'
 import * as RoutesTransfers from './routesTransfers.js'
-import * as SponsoredTransactions from './sponsoredTransactions.js'
 import * as Users from './users.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
@@ -139,7 +137,7 @@ export declare namespace createOwned {
  *
  * @param db - The database.
  * @param id - The organization id (`org_…`).
- * @param options - Post-commit lifecycle hooks.
+ * @param options - Deletion lifecycle hooks.
  * @returns Whether the organization existed and was deleted.
  */
 export async function deleteOrganization(
@@ -149,25 +147,9 @@ export async function deleteOrganization(
 ): Promise<boolean> {
   const result = await RoutesDeposits.withSubsidySettlement(db, {
     fn: async (tx) => {
-      const failedSince = new Date(
-        Date.now() - SponsoredTransactions.failedIntentRecoveryTtlMs,
-      ).toISOString()
-      const unreportedSponsorship = await tx.kysely
-        .selectFrom('sponsored_transactions')
-        .select('id')
-        .where('orgId', '=', id)
-        .where('billable', '=', true)
-        .where('chainId', '=', Viem.chainId.mainnet)
-        .where('meterReportedAt', 'is', null)
-        .where(unreportedSponsorshipStatus(failedSince))
-        .limit(1)
-        .executeTakeFirst()
-      const [unreportedDepositSubsidy, unreportedTransferSubsidy] = await Promise.all([
-        RoutesDeposits.hasUnreportedSubsidies(tx, { orgId: id }),
-        RoutesTransfers.hasUnreportedSubsidies(tx, id),
-      ])
-      if (unreportedSponsorship || unreportedDepositSubsidy || unreportedTransferSubsidy)
-        throw new UnreportedMeteredUsageError()
+      // Fence new commitments before checking liabilities; a rejected deletion rolls back the fence.
+      await ApiKeyOwnerTombstones.markDeleted(tx, { orgId: id })
+      if (await hasUnreportedMeteredUsage(tx, id)) throw new UnreportedMeteredUsageError()
       if (await RoutesIdempotency.hasUnattributedInFlightClaim(tx))
         throw new IrrevocableDepositAddressError()
       if (await RoutesIdempotency.hasInFlightDepositAddress(tx, id))
@@ -180,7 +162,6 @@ export async function deleteOrganization(
         now: new Date().toISOString(),
         orgId: id,
       })
-      await ApiKeyOwnerTombstones.markDeleted(tx, { orgId: id })
       await ApiKeyAdmissions.releaseOwner(tx, { orgId: id })
       await tx.kysely
         .deleteFrom('webhook_subscriptions')
@@ -201,6 +182,8 @@ export async function deleteOrganization(
         .deleteFrom('organizations')
         .where('id', '=', id)
         .executeTakeFirst()
+      // Publish external deletion fences before committing the irreversible owner removal.
+      if (result.numDeletedRows > 0n) await options.beforeCommit?.()
       const deactivatedById = new Map(deactivated.map((record) => [record.id, record]))
       return {
         deactivated: previous.flatMap((previous) => {
@@ -218,8 +201,10 @@ export async function deleteOrganization(
 }
 
 export declare namespace deleteOrganization {
-  /** Post-commit organization deletion hooks. */
+  /** Organization deletion hooks. */
   type Options = {
+    /** Publishes the KV owner fence before commit; failure rolls back deletion. */
+    beforeCommit?: (() => Promise<void>) | undefined
     /** Receives committed deposit-address deactivation transitions. */
     onDepositAddressesDeactivated?:
       | ((transitions: readonly DepositAddressDeactivation[]) => Promise<void> | void)
@@ -237,17 +222,13 @@ export declare namespace deleteOrganization {
 
 /** Whether an organization has metered usage awaiting Stripe settlement. */
 export async function hasUnreportedMeteredUsage(db: Db.Db, id: string): Promise<boolean> {
-  const failedSince = new Date(
-    Date.now() - SponsoredTransactions.failedIntentRecoveryTtlMs,
-  ).toISOString()
+  // Timeouts and recovery cutoffs do not revoke signatures. Only acknowledged billing clears a billable commitment, on any chain.
   const sponsorship = await db.kysely
     .selectFrom('sponsored_transactions')
     .select('id')
     .where('orgId', '=', id)
     .where('billable', '=', true)
-    .where('chainId', '=', Viem.chainId.mainnet)
     .where('meterReportedAt', 'is', null)
-    .where(unreportedSponsorshipStatus(failedSince))
     .limit(1)
     .executeTakeFirst()
   if (sponsorship) return true
@@ -585,19 +566,6 @@ export declare namespace upsert {
   }
 }
 
-/** Blocks rows that can still settle or recover into billable mainnet spend. */
-function unreportedSponsorshipStatus(failedSince: string) {
-  return (eb: ExpressionBuilder<Db.Database, 'sponsored_transactions'>) =>
-    eb.or([
-      eb('status', '!=', 'failed'),
-      eb.and([
-        eb('status', '=', 'failed'),
-        eb('transactionHash', 'is', null),
-        eb('finalizedAt', '>=', failedSince),
-      ]),
-    ])
-}
-
 /** Organization deletion is blocked by a provider subsidy that cannot be revoked. */
 export class IrrevocableDepositAddressError extends Error {
   override name = 'Organizations.IrrevocableDepositAddressError'

package/src/db/tables/requestUsage.ts

@@ -27,6 +27,7 @@ export type MeterEventTable = {
   deltaCount: Count
   environment: Environment
   error: string | null
+  eventTimestamp: string | null
   firstAttemptedAt: string
   identifier: string
   orgId: string
@@ -135,6 +136,7 @@ export async function insertPending(db: Db.Db, input: insertPending.Input): Prom
       deltaCount: input.deltaCount,
       environment: input.environment,
       error: null,
+      eventTimestamp: input.eventTimestamp,
       firstAttemptedAt: now,
       identifier: input.identifier,
       orgId: input.orgId,
@@ -159,6 +161,8 @@ export declare namespace insertPending {
     deltaCount: number
     /** Environment the requests were served under. */
     environment: Environment
+    /** Timestamp sent with this frozen Stripe meter event (ISO 8601). */
+    eventTimestamp: string
     /** Deterministic id; also the Stripe identifier and idempotency key. */
     identifier: string
     /** Organization id (`org_…`). */
@@ -211,7 +215,8 @@ export function settle(db: Db.Db, identifier: string, at: string): Promise<boole
 }
 
 /**
- * Records a transient failure on a pending event; it stays pending for retry.
+ * Records failure detail on a pending event; it stays visible for retry or
+ * manual reconciliation.
  *
  * @param db - The database.
  * @param identifier - The event identifier.
@@ -233,5 +238,11 @@ function toBucket(row: Selectable<BucketTable>): Bucket {
 
 /** Maps a meter-event row to its domain record. */
 function toMeterEvent(row: Selectable<MeterEventTable>): MeterEvent {
-  return { ...row, deltaCount: Number(row.deltaCount), sequence: Number(row.sequence) }
+  const { eventTimestamp, ...record } = row
+  return {
+    ...record,
+    deltaCount: Number(row.deltaCount),
+    ...(eventTimestamp === null ? {} : { eventTimestamp }),
+    sequence: Number(row.sequence),
+  }
 }

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

@@ -1360,6 +1360,140 @@ describe('reward execution fencing and transaction journal', () => {
   })
 })
 
+describe('latestDelivered', () => {
+  test('returns the newest delivered run among several', async () => {
+    const db = TestApp.database()
+    const runs = await seedRunSequence(db)
+    await deliver(db, runs[0])
+    await deliver(db, runs[1])
+
+    const latest = await RewardRuns.latestDelivered(db, { chainId: 4217, vaultAddress })
+
+    expect(latest?.endsAt).toBe('2000000400')
+  })
+})
+
+describe('latestSummary', () => {
+  test('returns the run with the newest start whatever its phase', async () => {
+    const db = TestApp.database()
+    const runs = await seedRunSequence(db)
+    await deliver(db, runs[0])
+
+    const latest = await RewardRuns.latestSummary(db, { chainId: 4217, vaultAddress })
+
+    expect([latest?.id, latest?.phase]).toEqual([runs[2].id, 'indexing'])
+  })
+})
+
+describe('latestForIntent', () => {
+  test('returns the newest attempt among equally ranked states', async () => {
+    const db = TestApp.database()
+    await seedCampaign(db)
+    const run = await RewardRuns.ensure(db, {
+      chainId: 4217,
+      config,
+      endsAt: 2_000_000_300,
+      startsAfter: 2_000_000_000,
+      vaultAddress,
+    })
+    const signerIntent = targetYieldIntent()
+    const intentId = Signer.id(signerIntent)
+    const expireAttempt = async (options: { nonce: string; replacementOf?: string }) => {
+      const attempt = await RewardTransactionAttempts.create(db, {
+        chainId: 4217,
+        intent: { id: intentId, operation: 'targetYield', payload: signerIntent },
+        replacementOf: options.replacementOf,
+        runId: run.id,
+        signer,
+        vaultAddress,
+      })
+      await RewardTransactionAttempts.recordSignature(db, {
+        expiresAt: '2026-01-01T00:00:00.000Z',
+        id: attempt.id,
+        nonce: options.nonce,
+        signedBytes: '0x01',
+        transactionHash: `0x${options.nonce.repeat(64)}`,
+      })
+      await RewardTransactionAttempts.expire(db, attempt.id)
+      return attempt
+    }
+    const older = await expireAttempt({ nonce: '1' })
+    const newer = await expireAttempt({ nonce: '2', replacementOf: older.id })
+    await setCreatedAt(db, {
+      [older.id]: '2026-01-01T00:00:00.000Z',
+      [newer.id]: '2026-01-02T00:00:00.000Z',
+    })
+
+    await expect(
+      RewardTransactionAttempts.latestForIntent(db, { intentId, runId: run.id }),
+    ).resolves.toMatchObject({ id: newer.id, state: 'expired' })
+  })
+})
+
+describe('latestRecoverable', () => {
+  test('returns the newest recoverable attempt for a run operation', async () => {
+    const db = TestApp.database()
+    await seedCampaign(db)
+    const run = await RewardRuns.ensure(db, {
+      chainId: 4217,
+      config,
+      endsAt: 2_000_000_300,
+      startsAfter: 2_000_000_000,
+      vaultAddress,
+    })
+    const signerIntent = targetYieldIntent()
+    const [older, newer] = await Promise.all(
+      [`0x${'11'.repeat(32)}` as const, `0x${'22'.repeat(32)}` as const].map((id) =>
+        RewardTransactionAttempts.create(db, {
+          chainId: 4217,
+          intent: { id, operation: 'targetYield', payload: signerIntent },
+          runId: run.id,
+          signer,
+          vaultAddress,
+        }),
+      ),
+    )
+    if (!older || !newer) throw new Error('Expected two attempts.')
+    await setCreatedAt(db, {
+      [older.id]: '2026-01-01T00:00:00.000Z',
+      [newer.id]: '2026-01-02T00:00:00.000Z',
+    })
+
+    await expect(
+      RewardTransactionAttempts.latestRecoverable(db, { operation: 'targetYield', runId: run.id }),
+    ).resolves.toMatchObject({ id: newer.id, state: 'created' })
+  })
+})
+
+function targetYieldIntent() {
+  return {
+    controller: '0x7000000000000000000000000000000000000007',
+    domain: {
+      chainId: 4217,
+      earnShare: shareAddress,
+      earnVault: vaultAddress,
+      factory: '0x8000000000000000000000000000000000000008',
+      treasury: '0x0000000000000000000000000000000000000000',
+    },
+    funders: [funder],
+    maxEarnShareSupply: '100',
+    operation: 'targetYield' as const,
+    requestedAssets: ['5'],
+  } satisfies Signer.Request['intent']
+}
+
+async function setCreatedAt(
+  db: ReturnType<typeof TestApp.database>,
+  createdAt: { [id: string]: string },
+) {
+  for (const [id, value] of Object.entries(createdAt))
+    await db.kysely
+      .updateTable('reward_transaction_attempts')
+      .set({ createdAt: value })
+      .where('id', '=', id)
+      .execute()
+}
+
 async function seedCampaign(db: ReturnType<typeof TestApp.database>) {
   await seedVault(db)
   return RewardCampaigns.upsert(db, {
@@ -1386,3 +1520,32 @@ async function seedVault(db: ReturnType<typeof TestApp.database>) {
     zones: [],
   })
 }
+
+/** Seeds three consecutive runs, advancing the campaign boundary between them. */
+async function seedRunSequence(db: ReturnType<typeof TestApp.database>) {
+  await seedCampaign(db)
+  const runs = []
+  for (const startsAfter of [2_000_000_000, 2_000_000_200, 2_000_000_400]) {
+    runs.push(
+      await RewardRuns.ensure(db, {
+        chainId: 4217,
+        config,
+        endsAt: startsAfter + 200,
+        startsAfter,
+        vaultAddress,
+      }),
+    )
+    if (startsAfter === 2_000_000_400) break
+    await RewardCampaigns.advance(db, {
+      chainId: 4217,
+      deliveredThrough: startsAfter + 200,
+      expectedDeliveredThrough: startsAfter,
+      vaultAddress,
+    })
+  }
+  return runs as [RewardRuns.Record, RewardRuns.Record, RewardRuns.Record]
+}
+
+async function deliver(db: ReturnType<typeof TestApp.database>, run: RewardRuns.Record) {
+  await RewardRuns.transition(db, { fence: run.fence, id: run.id, patch: {}, phase: 'delivered' })
+}

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

@@ -14,6 +14,20 @@ const input = {
   walletAddress: Schema.Address.parse(`0x${'Bb'.repeat(20)}`),
 } as const satisfies RewardEligibilityAssociations.upsert.Options
 
+describe('get', () => {
+  test('normalizes addresses and scopes registration by chain, vault, and wallet', async () => {
+    const db = TestApp.database()
+    const { record } = await RewardEligibilityAssociations.upsert(db, input)
+    await expect(RewardEligibilityAssociations.get(db, input)).resolves.toEqual(record)
+    for (const selector of [
+      { ...input, chainId: 42431 },
+      { ...input, vaultAddress: input.walletAddress },
+      { ...input, walletAddress: input.vaultAddress },
+    ])
+      await expect(RewardEligibilityAssociations.get(db, selector)).resolves.toBeUndefined()
+  })
+})
+
 describe('upsert', () => {
   test('creates a normalized association and refreshes its latest registration', async () => {
     vi.useFakeTimers()

package/src/db/tables/rewardEligibilityAssociations.ts

@@ -22,6 +22,30 @@ export type Table = Omit<
 /** A stored reward eligibility association. */
 export type Record = db_Schema.RewardEligibilityAssociation
 
+/** Reads one wallet's eligibility registration for a vault. */
+export async function get(db: Db.Db, options: get.Options): Promise<Record | undefined> {
+  const row = await db.kysely
+    .selectFrom('reward_eligibility_associations')
+    .selectAll()
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .where('walletAddress', '=', normalize(options.walletAddress))
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+export declare namespace get {
+  /** One vault and wallet registration selector. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Earn vault address. */
+    vaultAddress: Address
+    /** Wallet whose eligibility is read. */
+    walletAddress: Address
+  }
+}
+
 /** Inserts or refreshes one eligibility association. */
 export async function upsert(db: Db.Db, options: upsert.Options): Promise<upsert.Result> {
   const now = new Date().toISOString()