tapimo 0.15.0 → 0.18.0

package/src/db/Db.test.ts

@@ -4,16 +4,26 @@ import * as pg from 'pg'
 
 import * as Runtime from '../../test/runtime.js'
 import * as TestRoutes from '../../test/Routes.js'
+import * as ManagementWebhooks from '../apps/management/routes/webhooks.js'
+import type * as Campaigns from '../internal/rewards/Campaigns.js'
+import * as DepositAddress from '../internal/routes/DepositAddress.js'
 import * as Transfer from '../internal/routes/Transfer.js'
+import * as EarnVaults from './tables/earnVaults.js'
+import * as RewardAccounts from './tables/rewardAccounts.js'
+import * as RewardCampaigns from './tables/rewardCampaigns.js'
+import * as RewardRuns from './tables/rewardRuns.js'
+import * as RoutesDepositAddresses from './tables/routesDepositAddresses.js'
 import * as RoutesTransferTransactions from './tables/routesTransferTransactions.js'
 import * as RoutesTransfers from './tables/routesTransfers.js'
 import * as RoutesTransferSubsidies from './tables/routesTransferSubsidies.js'
 import * as Db from './Db.js'
+import * as VerifiedTokens from './tables/verifiedTokens.js'
 import * as Webhooks from '../internal/Webhooks.js'
 import * as Invitations from './tables/invitations.js'
 import * as ApiKeyOwnerTombstones from './tables/apiKeyOwnerTombstones.js'
 import * as Organizations from './tables/organizations.js'
 import * as Projects from './tables/projects.js'
+import * as RoutesPolicies from './tables/routesPolicies.js'
 import * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
 
 const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
@@ -27,6 +37,599 @@ describe('postgres', () => {
     await db.close()
   })
 
+  test.each(['targetYield', 'boostRewards', 'both'] as const)(
+    'behavior: extends d730 %s rewards without resetting accounting',
+    async (capability) => {
+      const db = create()
+      try {
+        await db.migrate()
+        const config = rewardExtensionConfig()
+        if (capability === 'targetYield') delete config.boostRewards
+        if (capability === 'boostRewards') delete config.targetYield
+        const campaign = await seedRewardExtension(db, { config })
+        const controls = [
+          await seedRewardExtension(db, { chainId: 42431, config }),
+          await seedRewardExtension(db, { config, vaultAddress: `0x${'ab'.repeat(20)}` }),
+        ]
+        const schedule = config.targetYield ?? config.boostRewards!
+        const run = await RewardRuns.ensure(db, {
+          ...campaign,
+          endsAt: schedule.endTimestamp,
+          startsAfter: schedule.startTimestamp,
+        })
+        await RewardRuns.transition(db, {
+          fence: run.fence,
+          id: run.id,
+          patch: {},
+          phase: 'delivered',
+        })
+        await RewardCampaigns.advance(db, {
+          ...campaign,
+          deliveredThrough: schedule.endTimestamp,
+          eventCursor: { blockNumber: 1234, logIndex: 7, transactionIndex: 2 },
+          expectedDeliveredThrough: schedule.startTimestamp,
+        })
+        await RewardAccounts.replace(db, {
+          ...campaign,
+          accounts: [
+            {
+              accrualRemainder: '17',
+              allocatedPrincipalAssets: '25000000',
+              cumulativeEntitlement: '900',
+              cumulativePaid: '700',
+              deferral: 'below minimum',
+              eligibilityRegisteredAt: '2026-09-01T00:00:00.000Z',
+              lots: [],
+              pendingRewardAssets: '23',
+              publicEarnShares: '30000000000000000000',
+              qualifiedEarnShares: '25000000000000000000',
+              recipient: `0x${'cd'.repeat(20)}`,
+              registrationOrder: '3',
+              updatedAt: '2026-09-30T12:00:00.000Z',
+            },
+          ],
+        })
+        const before = await RewardCampaigns.get(db, campaign)
+        const accounts = await RewardAccounts.list(db, campaign)
+        const runs = await db.kysely.selectFrom('reward_runs').selectAll().execute()
+        const through = Date.parse('2026-10-01T17:00:00Z') / 1_000
+        expect(
+          (await RewardCampaigns.listDue(db, { limit: 10, through })).some(
+            (entry) =>
+              entry.chainId === campaign.chainId && entry.vaultAddress === campaign.vaultAddress,
+          ),
+        ).toBe(false)
+
+        await replayRewardExtension(db)
+        const updated = await RewardCampaigns.get(db, campaign)
+        const endTimestamp = Date.parse('2026-12-17T12:00:00-05:00') / 1_000
+        expect(updated).toEqual({
+          ...before,
+          config: {
+            ...(config.boostRewards
+              ? { boostRewards: { ...config.boostRewards, endTimestamp } }
+              : {}),
+            ...(config.targetYield ? { targetYield: { ...config.targetYield, endTimestamp } } : {}),
+          },
+          updatedAt: expect.any(String),
+        })
+        expect(await RewardAccounts.list(db, campaign)).toEqual(accounts)
+        expect(await db.kysely.selectFrom('reward_runs').selectAll().execute()).toEqual(runs)
+        for (const control of controls)
+          expect(await RewardCampaigns.get(db, control)).toEqual(control)
+        expect(await RewardCampaigns.listDue(db, { limit: 10, through })).toContainEqual(updated)
+
+        await replayRewardExtension(db)
+        await db.migrate()
+        expect(await RewardCampaigns.get(db, campaign)).toEqual(updated)
+      } finally {
+        await db.close()
+      }
+    },
+  )
+
+  test.each(['pending', 'indexing', 'paying', 'failed', 'delivered'] as const)(
+    'behavior: refuses d730 extension with unresolved %s work',
+    async (state) => {
+      const db = create()
+      try {
+        await db.migrate()
+        const campaign = await seedRewardExtension(db, { config: rewardExtensionConfig() })
+        const schedule = campaign.config.boostRewards!
+        if (state === 'pending')
+          await RewardCampaigns.upsert(db, {
+            ...campaign,
+            config: { boostRewards: { ...schedule, targetAnnualRateBps: 800 } },
+            now: schedule.startTimestamp + 1,
+          })
+        else {
+          const run = await RewardRuns.ensure(db, {
+            ...campaign,
+            endsAt: schedule.endTimestamp,
+            startsAfter: schedule.startTimestamp,
+          })
+          await RewardRuns.transition(db, { fence: run.fence, id: run.id, patch: {}, phase: state })
+        }
+        const before = await RewardCampaigns.get(db, campaign)
+        await expect(replayRewardExtension(db)).rejects.toThrow(
+          state === 'pending'
+            ? 'resolve the pending configuration'
+            : 'finish outstanding reward runs',
+        )
+        expect(await RewardCampaigns.get(db, campaign)).toEqual(before)
+        expect(
+          await db.kysely
+            .selectFrom('migrations')
+            .select('name')
+            .where('name', '=', '0302_extend_d730_reward_campaign')
+            .execute(),
+        ).toEqual([])
+      } finally {
+        await db.close()
+      }
+    },
+  )
+
+  test('behavior: d730 extension preserves later end dates and operational pause', async () => {
+    const db = create()
+    try {
+      await db.migrate()
+      const config = rewardExtensionConfig()
+      config.targetYield!.endTimestamp = Date.parse('2027-01-01T00:00:00Z') / 1_000
+      const campaign = await seedRewardExtension(db, { config })
+      await RewardCampaigns.setPaused(db, { ...campaign, paused: true })
+      await replayRewardExtension(db)
+      expect(await RewardCampaigns.get(db, campaign)).toEqual({
+        ...campaign,
+        config: {
+          ...config,
+          boostRewards: {
+            ...config.boostRewards,
+            endTimestamp: Date.parse('2026-12-17T17:00:00Z') / 1_000,
+          },
+        },
+        paused: true,
+        updatedAt: expect.any(String),
+      })
+      expect(await RewardCampaigns.listDue(db, { limit: 10, through: 1_800_000_000 })).toEqual([])
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('behavior: each preview schema receives the subsidy status constraint', async () => {
+    const schemas = [`t_${nanoid()}`, `t_${nanoid()}`]
+    const dbs = schemas.map((schema) =>
+      Db.postgres({ connectionString: Runtime.postgresUrl, schema }),
+    )
+    try {
+      for (const db of dbs) await db.migrate()
+      for (const schema of schemas) {
+        const result = await sql<{ exists: boolean }>`
+          SELECT EXISTS (
+            SELECT 1 FROM pg_constraint AS c
+            JOIN pg_class AS t ON t.oid = c.conrelid
+            JOIN pg_namespace AS n ON n.oid = t.relnamespace
+            WHERE c.conname = 'routes_transfer_subsidies_status_check'
+              AND t.relname = 'routes_transfer_subsidies'
+              AND n.nspname = ${schema}
+          ) AS exists
+        `.execute(dbs[0]!.kysely)
+        expect(result.rows[0]?.exists).toBe(true)
+      }
+    } finally {
+      for (const db of dbs) await db.close()
+    }
+  })
+
+  test.each([
+    { chainId: 4217, migration: '0299_verified_tokens_ousd', version: 'existing_0299_ousd' },
+    {
+      chainId: 42431,
+      migration: '0301_verified_tokens_ousd_testnet',
+      version: 'existing_0301_ousd',
+    },
+  ])('behavior: publishes OUSD into an existing $chainId verified-token list', async (options) => {
+    const db = create()
+    try {
+      await db.migrate()
+      await db.kysely
+        .insertInto('verified_token_lists')
+        .values({
+          chainId: options.chainId,
+          updatedAt: '2026-09-22T00:00:00.000Z',
+          version: 'existing',
+        })
+        .execute()
+      await db.kysely
+        .insertInto('verified_tokens')
+        .values({
+          address: '0x20c0000000000000000000000000000000000000',
+          chainId: options.chainId,
+          currency: 'USD',
+          decimals: 6,
+          logoUri: null,
+          name: 'PathUSD',
+          position: 0,
+          symbol: 'pathUSD',
+        })
+        .execute()
+
+      const migration = Db.migrations.find((candidate) => candidate.name === options.migration)!
+      const startedAt = await sql<{ value: Date }>`SELECT clock_timestamp() AS value`.execute(
+        db.kysely,
+      )
+      await migration.up(db.kysely).execute()
+      const list = await db.kysely
+        .selectFrom('verified_token_lists')
+        .selectAll()
+        .where('chainId', '=', String(options.chainId))
+        .executeTakeFirstOrThrow()
+      await migration.up(db.kysely).execute()
+
+      expect(
+        await db.kysely
+          .selectFrom('verified_tokens')
+          .selectAll()
+          .where('chainId', '=', String(options.chainId))
+          .orderBy('position')
+          .execute(),
+      ).toMatchObject([
+        { address: '0x20c0000000000000000000000000000000000000', position: 0 },
+        {
+          address: '0x20c0000000000000000000006a37da5c996874be',
+          currency: 'USD',
+          decimals: 6,
+          name: 'OpenUSD',
+          position: 1,
+          symbol: 'OUSD',
+        },
+      ])
+      const replayed = await db.kysely
+        .selectFrom('verified_token_lists')
+        .selectAll()
+        .where('chainId', '=', String(options.chainId))
+        .executeTakeFirstOrThrow()
+      const finishedAt = await sql<{ value: Date }>`SELECT clock_timestamp() AS value`.execute(
+        db.kysely,
+      )
+      expect(replayed).toEqual(list)
+      expect(new Date(list.updatedAt).getTime()).toBeGreaterThanOrEqual(
+        startedAt.rows[0]!.value.getTime(),
+      )
+      expect(new Date(list.updatedAt).getTime()).toBeLessThanOrEqual(
+        finishedAt.rows[0]!.value.getTime(),
+      )
+      await expect(
+        db.kysely
+          .selectFrom('verified_token_lists')
+          .select('version')
+          .where('chainId', '=', String(options.chainId))
+          .executeTakeFirstOrThrow(),
+      ).resolves.toEqual({ version: options.version })
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('behavior: serializes the OUSD migration with verified-token publishers', async () => {
+    const schema = `t_${nanoid()}`
+    const database = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema })
+    const db = database()
+    const migrationDb = database()
+    const observerDb = database()
+    try {
+      await db.migrate()
+      const locked = Promise.withResolvers<void>()
+      const release = Promise.withResolvers<void>()
+      const publication = db.transaction(async (tx) => {
+        await sql`SELECT pg_advisory_xact_lock(1987342187, 4217)`.execute(tx.kysely)
+        locked.resolve()
+        await release.promise
+        await VerifiedTokens.publish(tx, 4217, {
+          tokens: [
+            {
+              address: '0x20c0000000000000000000000000000000000001',
+              currency: 'USD',
+              decimals: 6,
+              name: 'Published USD',
+              symbol: 'pUSD',
+            },
+          ],
+          updatedAt: '2026-09-27T00:00:00.000Z',
+          version: 'published',
+        })
+      })
+      await locked.promise
+
+      const migration = Db.migrations.find(
+        (candidate) => candidate.name === '0299_verified_tokens_ousd',
+      )!
+      const migrated = migrationDb.transaction(async (tx) => {
+        await sql`SELECT set_config('search_path', quote_ident(${schema}), true)`.execute(tx.kysely)
+        await migration.up(tx.kysely).execute()
+      })
+      try {
+        await expect
+          .poll(async () => {
+            const { rows } = await sql<{ waiting: boolean }>`SELECT EXISTS (
+              SELECT 1 FROM pg_locks
+              WHERE locktype = 'advisory'
+                AND classid = 1987342187
+                AND objid = 4217
+                AND NOT granted
+            ) AS waiting`.execute(observerDb.kysely)
+            return rows[0]!.waiting
+          })
+          .toBe(true)
+      } finally {
+        release.resolve()
+      }
+      await publication
+      await migrated
+
+      await expect(VerifiedTokens.list(db, 4217)).resolves.toMatchObject([
+        { symbol: 'pUSD' },
+        { address: '0x20c0000000000000000000006a37da5c996874be', symbol: 'OUSD' },
+      ])
+    } finally {
+      await db.close()
+      await migrationDb.close()
+      await observerDb.close()
+    }
+  })
+
+  test('behavior: migrates legacy funding webhook event types without changing subscription state', async () => {
+    const db = create()
+    try {
+      await db.migrate()
+      const owner = { orgId: 'org_legacy_webhooks', type: 'api_key' } as const
+      for (const eventType of ['routes:deposit.updated', 'routes:transfer.updated'] as const) {
+        for (const status of ['active', 'paused', 'disabled'] as const) {
+          const subscription = await Webhooks.createSubscription(
+            db,
+            {
+              chainId: 4217,
+              context: { title: 'Legacy subscription' },
+              destination: { type: 'url', url: 'https://hooks.example.com/endpoint' },
+              environment: 'production',
+              eventType,
+              filters: { status: ['completed'] },
+              owner,
+              projectId: 'prj_legacy',
+            },
+            { now: () => new Date('2026-08-24T17:30:13.847Z'), startBlockNumber: 123 },
+          )
+          // Seed the persisted pre-rename value without widening the current event type contract.
+          await sql`
+            UPDATE webhook_subscriptions
+            SET event_type = ${eventType.replace('routes:', 'funding:')},
+                status = ${status}, failure_count = 10,
+                last_delivery_at = '2026-08-24T19:21:13.478Z'
+            WHERE id = ${subscription.id}
+          `.execute(db.kysely)
+        }
+      }
+      for (const eventType of ['routes:deposit.updated', 'token:transfer'] as const)
+        await Webhooks.createSubscription(db, {
+          chainId: 4217,
+          destination: { type: 'url', url: 'https://hooks.example.com/current' },
+          eventType,
+          owner,
+        })
+
+      const records = () =>
+        db.kysely.selectFrom('webhook_subscriptions').selectAll().orderBy('id').execute()
+      const before = await records()
+      const list = () => Webhooks.listSubscriptions(db, owner)
+      expect(ManagementWebhooks.schema.ListResponse.safeParse({ data: await list() }).success).toBe(
+        false,
+      )
+      const name = '0282_webhook_subscription_routes_event_types'
+      await db.kysely.deleteFrom('migrations').where('name', '=', name).execute()
+      await db.migrate()
+
+      const expected = before.map((record) => ({
+        ...record,
+        eventType: record.eventType.replace('funding:', 'routes:'),
+      }))
+      expect(await records()).toEqual(expected)
+      expect(ManagementWebhooks.schema.ListResponse.safeParse({ data: await list() }).success).toBe(
+        true,
+      )
+      expect(await list()).toHaveLength(8)
+
+      // Exercise statement replay as well as the migration ledger's normal no-op path.
+      const migration = Db.migrations.find((migration) => migration.name === name)!
+      await migration.up(db.kysely).execute()
+      await db.migrate()
+      expect(await records()).toEqual(expected)
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('behavior: combined policy migration preserves previously migrated data', async () => {
+    const db = create()
+    try {
+      await db.migrate()
+      const org = await Organizations.create(db, { name: 'Existing policy owner' })
+      const scope = { orgId: org.id, environment: 'production' } as const
+      const policy = await RoutesPolicies.save(db, { scope, version: 0, policy: { access: [] } })
+      await db.kysely
+        .insertInto('api_key_admissions')
+        .values({
+          id: 'key_existing',
+          orgId: org.id,
+          projectId: null,
+          expiresAt: null,
+          pendingScopes: JSON.stringify(['routes:read']),
+        })
+        .execute()
+      // Existing previews have the DDL but only the former migration names in their ledger.
+      const combined = await db.kysely
+        .deleteFrom('migrations')
+        .where('name', '=', '0280_routes_policies')
+        .returningAll()
+        .executeTakeFirstOrThrow()
+      const historical = [
+        { ...combined, name: '0267_routes_policies' },
+        { ...combined, name: '0270_api_key_pending_scopes' },
+        { ...combined, name: '0270_routes_policies' },
+      ]
+      await db.kysely.insertInto('migrations').values(historical).execute()
+
+      await db.migrate()
+      await db.migrate()
+      expect(await RoutesPolicies.get(db, scope)).toEqual(policy)
+      expect(
+        await db.kysely
+          .selectFrom('api_key_admissions')
+          .select('pendingScopes')
+          .where('id', '=', 'key_existing')
+          .executeTakeFirst(),
+      ).toEqual({ pendingScopes: ['routes:read'] })
+      expect(
+        await db.kysely
+          .selectFrom('migrations')
+          .selectAll()
+          .where(
+            'name',
+            'in',
+            historical.map(({ name }) => name),
+          )
+          .orderBy('name')
+          .execute(),
+      ).toEqual(historical)
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('behavior: staged policy upgrades preserve legacy rows and allow distinct commitments only after compatible workers', async () => {
+    const schema = `t_${nanoid()}`
+    const db = Db.postgres({ connectionString: Runtime.postgresUrl })
+    try {
+      await db.kysely.executeQuery(
+        CompiledQuery.raw(`CREATE SCHEMA ${pg.escapeIdentifier(schema)}`),
+      )
+      await db.transaction(async (tx) => {
+        await sql`SELECT set_config('search_path', quote_ident(${schema}), true)`.execute(tx.kysely)
+        const boundary = Db.migrations.findIndex(({ name }) => name === '0280_routes_policies')
+        expect(boundary).toBeGreaterThan(0)
+        for (const migration of Db.migrations.slice(0, boundary))
+          await migration.up(tx.kysely).execute()
+        const org = await Organizations.create(tx, { name: 'Legacy route customer' })
+        const first = await DepositAddress.create(tx, {
+          environment: 'production',
+          orgId: org.id,
+          deliveryStrategy: 'provider',
+          providerOutputToken: TestRoutes.providerOutputToken(),
+          snapshot: TestRoutes.depositAddressSnapshot({ subsidize: true }),
+        })
+        const before = await RoutesDepositAddresses.get(tx, first.id)
+        const replacement = Db.migrations.findIndex(
+          ({ name }) => name === '0281_routes_deposit_address_policy_identity',
+        )
+        expect(replacement).toBeGreaterThan(boundary)
+        for (const migration of Db.migrations.slice(boundary, replacement))
+          await migration.up(tx.kysely).execute()
+        expect(await RoutesDepositAddresses.get(tx, first.id)).toEqual(before)
+        // Exact pre-policy worker ON CONFLICT target, executed against the upgraded schema.
+        const oldInsert = (record: RoutesDepositAddresses.Record) =>
+          tx.kysely
+            .insertInto('routes_deposit_addresses')
+            .values({ ...record, providerRequestIds: JSON.stringify(record.providerRequestIds) })
+            .onConflict((oc) =>
+              oc
+                .columns([
+                  'orgId',
+                  'environment',
+                  'projectId',
+                  'sourceChainId',
+                  'sourceTokenKey',
+                  'destinationTokenKey',
+                  'recipient',
+                  'refundAddress',
+                  'subsidize',
+                ])
+                .doNothing(),
+            )
+            .returningAll()
+            .executeTakeFirst()
+        const record = {
+          ...first,
+          id: DepositAddress.generateId(),
+          address: `0x${'83'.repeat(20)}`,
+          recipient: `0x${'84'.repeat(20)}`,
+        }
+        expect(await oldInsert(record)).toMatchObject({ id: record.id })
+        expect(await oldInsert({ ...record, id: DepositAddress.generateId() })).toBeUndefined()
+        const match = {
+          destinationTokenKey: record.destinationTokenKey,
+          environment: record.environment,
+          orgId: record.orgId,
+          recipient: record.recipient,
+          refundAddress: record.refundAddress,
+          sourceChainId: record.sourceChainId,
+          sourceTokenKey: record.sourceTokenKey,
+          subsidize: record.subsidize,
+        }
+        expect(
+          await RoutesDepositAddresses.insertOrGet(tx, {
+            match,
+            record: { ...record, id: DepositAddress.generateId() },
+          }),
+        ).toMatchObject({ id: record.id })
+        await expect(
+          RoutesDepositAddresses.insertOrGet(tx, {
+            match: { ...match, policyKey: '["tempo","0.050000"]', providerId: record.providerId },
+            record: {
+              ...record,
+              id: DepositAddress.generateId(),
+              address: `0x${'85'.repeat(20)}`,
+              providerState: { routePolicyKey: '["tempo","0.050000"]' },
+            },
+          }),
+        ).rejects.toThrow(RoutesDepositAddresses.IdentityConflictError)
+        // Targetless DO NOTHING keeps the transaction usable after a uniqueness conflict.
+        expect(await RoutesDepositAddresses.countByOrganization(tx, org.id)).toBe(2)
+
+        // Only policy-aware workers can run after the financial identity upgrade; their inserts are targetless.
+        for (let attempt = 0; attempt < 2; attempt++)
+          await Db.migrations[replacement]!.up(tx.kysely).execute()
+        const commitment = {
+          ...record,
+          address: `0x${'85'.repeat(20)}`,
+          id: DepositAddress.generateId(),
+          providerState: { routePolicyKey: '["tempo","0.050000"]' },
+        }
+        const policyMatch = {
+          ...match,
+          policyKey: '["tempo","0.050000"]',
+          providerId: record.providerId,
+        }
+        expect(
+          await RoutesDepositAddresses.insertOrGet(tx, { match: policyMatch, record: commitment }),
+        ).toEqual(commitment)
+        expect(
+          await RoutesDepositAddresses.insertOrGet(tx, {
+            match: policyMatch,
+            record: { ...commitment, id: DepositAddress.generateId() },
+          }),
+        ).toEqual(commitment)
+        expect(await RoutesDepositAddresses.getMatching(tx, match)).toEqual(record)
+        expect(await RoutesDepositAddresses.get(tx, first.id)).toEqual(before)
+        expect(await RoutesDepositAddresses.countByOrganization(tx, org.id)).toBe(3)
+      })
+    } finally {
+      await db.kysely.executeQuery(
+        CompiledQuery.raw(`DROP SCHEMA IF EXISTS ${pg.escapeIdentifier(schema)} CASCADE`),
+      )
+      await db.close()
+    }
+  })
+
   test('behavior: raw owner deletes fence API keys for older application code', async () => {
     const db = create()
     await db.migrate()
@@ -262,6 +865,154 @@ describe('postgres', () => {
     }
   })
 
+  test('behavior: archives an expired Solana settlement and preserves its billing owner', async () => {
+    const db = create()
+    await db.migrate()
+    try {
+      const chainId = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'
+      const token = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+      const recipient = '82RrXaHHzCuSYG7oiQgHyEDRiYHKmrNTTka3D2QtUnTL'
+      const snapshot = TestRoutes.transferSnapshot({
+        destinationChain: { addressFormat: 'base58', id: chainId, kind: 'solana', name: 'Solana' },
+        destinationToken: {
+          address: token,
+          currency: 'USD',
+          decimals: 6,
+          name: 'USD Coin',
+          standard: 'SPL',
+          symbol: 'USDC',
+          tokenKey: `${chainId}/spl:${token}`,
+          verified: true,
+        },
+        recipient,
+        sourceTransactionHashes: [`0x${'ab'.repeat(32)}`],
+      })
+      const amount = { baseUnits: '1', currency: 'USD', decimals: 6, formatted: '0.000001' }
+      const account = 'EhsfgAGLqLuBysRpXFNHmgDQc81zzPvypY4eNjgZV97X'
+      const signed = {
+        account,
+        amount: '1',
+        chainId,
+        hash: '3UBy3CJGU8pWLWpuXaa9dtNjdSJdvrng8gyKSyUGifxEqBDzjmJukP7Fg5GdtsJjYKMXMv14SszGUrEyNgKoQaMB',
+        transaction:
+          'AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAA==',
+      }
+      const replacement = {
+        ...signed,
+        hash: '2ApX6qqMYmcC2k1PVnZ7zKjx1ewGTvds9urXMcSP3owqvrUBjXpVrnxSqmsG6J4xv29VCNMBVurBepLhu2PTEyNx',
+      }
+      const owner = await Transfer.create(db, {
+        apiKeyId: 'key_owner',
+        environment: 'production',
+        orgId: 'org_owner',
+        snapshot,
+      })
+      const initial = await Transfer.transition(db, {
+        expectedVersion: owner.version,
+        id: owner.id,
+        providerState: { transferSubsidy: JSON.stringify(signed) },
+        status: 'processing',
+        subsidyAccount: account,
+        subsidyAmount: amount,
+        subsidyChainId: chainId,
+        subsidyTokenAddress: token,
+        subsidyTransactionHash: signed.hash,
+      })
+      expect(initial.type).toBe('applied')
+      const key = {
+        sourceChainId: snapshot.sourceChain.id,
+        transactionRef: snapshot.sourceTransactionHashes![0]!,
+      }
+      const marked = await db.transaction((tx) =>
+        RoutesTransferSubsidies.markExpiredIn(tx, {
+          ...key,
+          signedHash: signed.hash,
+          signedTransaction: JSON.stringify(signed),
+          transferId: owner.id,
+        }),
+      )
+      expect(marked).toMatchObject({ type: 'expired', settlement: { transferId: owner.id } })
+      expect(
+        await db.transaction((tx) =>
+          RoutesTransferSubsidies.markExpiredIn(tx, {
+            ...key,
+            signedHash: signed.hash,
+            signedTransaction: JSON.stringify(signed),
+            transferId: owner.id,
+          }),
+        ),
+      ).toMatchObject({ type: 'stale' })
+      const archived = await db.kysely
+        .selectFrom('routes_transfer_subsidy_expired_attempts')
+        .selectAll()
+        .execute()
+      expect(archived).toMatchObject([
+        { transaction: JSON.stringify(signed), transactionHash: signed.hash, transferId: owner.id },
+      ])
+      const foreign = await Transfer.create(db, {
+        apiKeyId: 'key_foreign',
+        environment: 'production',
+        orgId: 'org_foreign',
+        snapshot,
+      })
+      await expect(
+        Transfer.transition(db, {
+          expectedVersion: foreign.version,
+          id: foreign.id,
+          providerState: { transferSubsidy: JSON.stringify(replacement) },
+          status: 'processing',
+          subsidyAccount: account,
+          subsidyAmount: amount,
+          subsidyChainId: chainId,
+          subsidyTokenAddress: token,
+          subsidyTransactionHash: replacement.hash,
+        }),
+      ).rejects.toThrow('Only the subsidy owner may replace an expired settlement')
+      const staleShared = await Transfer.transition(db, {
+        expectedVersion: foreign.version,
+        id: foreign.id,
+        providerState: { transferSubsidy: JSON.stringify(signed) },
+        status: 'processing',
+        subsidyAccount: account,
+        subsidyAmount: amount,
+        subsidyChainId: chainId,
+        subsidyTokenAddress: token,
+        subsidyTransactionHash: signed.hash,
+      })
+      expect(staleShared.type).toBe('applied')
+      expect(staleShared.type === 'applied' && staleShared.record.subsidyAmount).toBeNull()
+      expect(
+        await db.transaction((tx) => RoutesTransferSubsidies.getForUpdateIn(tx, key)),
+      ).toMatchObject({ status: 'expired', transaction: JSON.stringify(signed) })
+      await expect(
+        Transfer.transition(db, {
+          expectedVersion: initial.type === 'applied' ? initial.record.version : 2,
+          id: owner.id,
+          providerState: {
+            transferSubsidy: JSON.stringify({ ...replacement, amount: '2' }),
+          },
+          subsidyTransactionHash: replacement.hash,
+        }),
+      ).rejects.toThrow('Expired subsidy replacement changed settlement terms')
+      const next = await Transfer.transition(db, {
+        expectedVersion: initial.type === 'applied' ? initial.record.version : 2,
+        id: owner.id,
+        providerState: { transferSubsidy: JSON.stringify(replacement) },
+        subsidyTransactionHash: replacement.hash,
+      })
+      expect(next.type).toBe('applied')
+      expect(
+        await db.transaction((tx) => RoutesTransferSubsidies.getForUpdateIn(tx, key)),
+      ).toMatchObject({
+        status: 'active',
+        transaction: JSON.stringify(replacement),
+        transferId: owner.id,
+      })
+    } finally {
+      await db.close()
+    }
+  })
+
   test('behavior: legacy invitation inserts do not grant early access', async () => {
     const db = create()
     await db.migrate()
@@ -415,3 +1166,129 @@ describe('postgres', () => {
     await db.close()
   })
 })
+
+describe('observe', () => {
+  test('separates connection waits from query execution', async () => {
+    const db = create()
+    await db.migrate()
+    try {
+      const durations: number[] = []
+      const timings: Db.observe.Timing[] = []
+      const observed = Db.observe(db, {
+        onQuery: (duration, timing) => {
+          durations.push(duration)
+          timings.push(timing)
+        },
+      })
+      await Promise.all([
+        sql`SELECT pg_sleep(0.04)`.execute(observed.kysely),
+        sql`SELECT 1`.execute(observed.kysely),
+      ])
+
+      expect(timings).toHaveLength(2)
+      expect(timings.some((timing) => timing.acquire >= 30)).toBe(true)
+      expect(timings.some((timing) => timing.query >= 30)).toBe(true)
+      expect(durations).toEqual(timings.map((timing) => timing.acquire + timing.query))
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('reports one duration per query and leaves results intact', async () => {
+    const db = create()
+    await db.migrate()
+    try {
+      const durations: number[] = []
+      const observed = Db.observe(db, { onQuery: (ms) => durations.push(ms) })
+      expect(await Organizations.get(observed, 'missing')).toBeUndefined()
+      expect(await Organizations.get(observed, 'missing')).toBeUndefined()
+
+      expect(durations).toHaveLength(2)
+      expect(durations.every((ms) => ms > 0)).toBe(true)
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('reports rejected queries and leaves unobserved handles silent', async () => {
+    const db = create()
+    await db.migrate()
+    try {
+      const durations: number[] = []
+      const observed = Db.observe(db, { onQuery: (ms) => durations.push(ms) })
+      await expect(
+        sql`SELECT * FROM missing_table_for_observe`.execute(observed.kysely),
+      ).rejects.toThrow()
+      expect(await Organizations.get(db, 'missing')).toBeUndefined()
+
+      expect(durations).toHaveLength(1)
+      expect(durations[0]).toBeGreaterThan(0)
+    } finally {
+      await db.close()
+    }
+  })
+})
+
+function rewardExtensionConfig(): Campaigns.Config {
+  const schedule = {
+    endTimestamp: Date.parse('2026-09-30T12:00:00Z') / 1_000,
+    intervalSeconds: 300,
+    startTimestamp: Date.parse('2026-09-01T00:00:00Z') / 1_000,
+  }
+  return {
+    boostRewards: {
+      ...schedule,
+      excludedAddresses: [],
+      funding: { wallet: `0x${'12'.repeat(20)}` },
+      perUserPrincipalCapAssets: '25000000000',
+      targetAnnualRateBps: 700,
+      totalPrincipalCapAssets: '10000000000000',
+      treasury: `0x${'34'.repeat(20)}`,
+    },
+    targetYield: {
+      ...schedule,
+      annualRate: { bps: 500 },
+      funding: [{ remainder: true, wallet: `0x${'56'.repeat(20)}` }],
+    },
+  }
+}
+
+async function seedRewardExtension(db: Db.Db, options: seedRewardExtension.Options) {
+  const chainId = options.chainId ?? 4217
+  const vaultAddress = options.vaultAddress ?? '0xd730394f3bb85a4828e35fc5e361dcc9f894fa4f'
+  await EarnVaults.upsert(db, {
+    chainId,
+    description: null,
+    label: 'Reward extension fixture',
+    privateInputTokens: [],
+    privateOutputTokens: [],
+    vaultAddress,
+    zones: [],
+  })
+  return RewardCampaigns.upsert(db, {
+    assetAddress: `0x${'78'.repeat(20)}`,
+    assetDecimals: 6,
+    chainId,
+    config: options.config,
+    earnShareAddress: `0x${'90'.repeat(20)}`,
+    earnShareDecimals: 18,
+    now: Date.parse('2026-08-31T00:00:00Z') / 1_000,
+    vaultAddress,
+  })
+}
+
+declare namespace seedRewardExtension {
+  type Options = {
+    chainId?: number
+    config: Campaigns.Config
+    vaultAddress?: `0x${string}`
+  }
+}
+
+async function replayRewardExtension(db: Db.Db) {
+  await db.kysely
+    .deleteFrom('migrations')
+    .where('name', '=', '0302_extend_d730_reward_campaign')
+    .execute()
+  await db.migrate()
+}