tapimo 0.0.2 → 0.1.0

package/src/apps/webhooks.ts

@@ -6,6 +6,7 @@ import type * as App from '../App.js'
 import * as Auth from '../internal/Auth.js'
 import * as Cache from '../internal/Cache.js'
 import * as Cursor from '../internal/Cursor.js'
+import * as Db from '../db/Db.js'
 import * as OpenApi from '../internal/OpenApi.js'
 import * as Response from '../internal/Response.js'
 import * as Schema from '../internal/Schema.js'
@@ -1306,7 +1307,7 @@ export function webhooks(options: webhooks.Options = {}) {
             })
 
           const webhook = c.get('webhook')!
-          const store = webhook.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
@@ -1315,7 +1316,7 @@ export function webhooks(options: webhooks.Options = {}) {
 
           try {
             const subscription = await Webhooks.createSubscription(
-              store,
+              db,
               {
                 chainId,
                 ...(body.context === undefined ? {} : { context: body.context }),
@@ -1365,7 +1366,7 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the query parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
@@ -1375,12 +1376,12 @@ export function webhooks(options: webhooks.Options = {}) {
             // run it concurrently with the page list. Best-effort: a failure
             // omits `meta` rather than failing the page.
             const countPromise = include.includes('totalCount')
-              ? Webhooks.countSubscriptions(store, owner).catch(() => undefined)
+              ? Webhooks.countSubscriptions(db, owner).catch(() => undefined)
               : undefined
 
             // Fetch one extra to detect a further page without a second round-trip.
             // `page` translates to a positional slice of `(page - 1) * limit` rows.
-            const rows = await Webhooks.listSubscriptions(store, owner, {
+            const rows = await Webhooks.listSubscriptions(db, owner, {
               cursor,
               limit: limit + 1,
               offset: page !== undefined && page > 1 ? (page - 1) * limit : undefined,
@@ -1445,13 +1446,13 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the path parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
           const { id } = c.req.valid('param')
           try {
-            const subscription = await Webhooks.getSubscription(store, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id)
             if (!subscription) return notFound(c)
             return c.json(
               Response.validated(schema.getWebhook.Response, toPublic(subscription)),
@@ -1506,7 +1507,7 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the query parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
@@ -1515,19 +1516,19 @@ export function webhooks(options: webhooks.Options = {}) {
           try {
             // Owner-scope first: resolving the subscription under the caller's owner
             // key 404s ids they don't own (indistinguishable from "doesn't exist").
-            const subscription = await Webhooks.getSubscription(store, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id)
             if (!subscription) return notFound(c)
 
             // `totalCount` is opt-in and exact (the delivery log is TTL-bounded);
             // run it concurrently with the page list. Best-effort: a failure
             // omits `meta` rather than failing the page.
             const countPromise = include.includes('totalCount')
-              ? Webhooks.countDeliveries(store, id).catch(() => undefined)
+              ? Webhooks.countDeliveries(db, id).catch(() => undefined)
               : undefined
 
             // Fetch one extra to detect a further page without a second round-trip.
             // `page` translates to a positional slice of `(page - 1) * limit` rows.
-            const rows = await Webhooks.listDeliveries(store, id, {
+            const rows = await Webhooks.listDeliveries(db, id, {
               cursor,
               limit: limit + 1,
               offset: page !== undefined && page > 1 ? (page - 1) * limit : undefined,
@@ -1589,20 +1590,20 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the path parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
           const { id } = c.req.valid('param')
           try {
             // Owner-scope first so unowned/unknown ids are indistinguishable (404).
-            const subscription = await Webhooks.getSubscription(store, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id)
             if (!subscription) return notFound(c)
 
             // Inline delivery (not the queue) so the caller gets an immediate
             // result. `ping` never mutates the subscription's failure/lifecycle
             // state — a test must not disable a healthy endpoint.
-            const { envelope, result } = await Webhooks.ping(store, subscription)
+            const { envelope, result } = await Webhooks.ping(db, subscription)
             return c.json(
               Response.validated(schema.pingWebhook.Response, {
                 delivered: result.ok,
@@ -1653,17 +1654,17 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the path parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
           const { deliveryId, id } = c.req.valid('param')
           try {
             // Owner-scope the subscription first so unowned ids 404 like elsewhere.
-            const subscription = await Webhooks.getSubscription(store, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id)
             if (!subscription) return notFound(c)
 
-            const delivery = await Webhooks.getDelivery(store, id, deliveryId)
+            const delivery = await Webhooks.getDelivery(db, id, deliveryId)
             if (!delivery)
               return Response.error(c, {
                 code: 'delivery_not_found',
@@ -1673,7 +1674,7 @@ export function webhooks(options: webhooks.Options = {}) {
 
             // Replay the exact persisted envelope inline. Unlike `ping`, this is a
             // real event, so the outcome updates the subscription's failure state.
-            const result = await Webhooks.deliverAndRecord(store, subscription, delivery.envelope)
+            const result = await Webhooks.deliverAndRecord(db, subscription, delivery.envelope)
             return c.json(
               Response.validated(schema.retryWebhookDelivery.Response, {
                 delivered: result.ok,
@@ -1733,7 +1734,7 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the request body and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
@@ -1746,11 +1747,11 @@ export function webhooks(options: webhooks.Options = {}) {
             // persisting — otherwise a bad filter would silently widen the match
             // set at scan time.
             if (patch.filters !== undefined) {
-              const existing = await Webhooks.getSubscription(store, owner, id)
+              const existing = await Webhooks.getSubscription(db, owner, id)
               if (!existing) return notFound(c)
               parseFilters(existing.eventType, patch.filters)
             }
-            const subscription = await Webhooks.updateSubscription(store, owner, id, patch)
+            const subscription = await Webhooks.updateSubscription(db, owner, id, patch)
             if (!subscription) return notFound(c)
             return c.json(
               Response.validated(schema.updateWebhook.Response, toPublic(subscription)),
@@ -1796,13 +1797,13 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the path parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
           const { id } = c.req.valid('param')
           try {
-            const deleted = await Webhooks.deleteSubscription(store, owner, id)
+            const deleted = await Webhooks.deleteSubscription(db, owner, id)
             if (!deleted) return notFound(c)
             return c.json(Response.validated(schema.deleteWebhook.Response, { id }), 200)
           } catch (cause) {
@@ -1874,12 +1875,13 @@ type ScanPage = {
 export async function poll(options: poll.Options): Promise<poll.Result> {
   const {
     batchSize = 100,
+    cache: cache_metadata = Store.memory(),
     chainId,
     client,
     confirmations = 2,
+    db,
     eventTypes = ['token:transfer', 'transaction:included', 'log:emitted', 'block:created'],
     maxBlocks = 1_000,
-    store,
     tidx,
   } = options
   const now = options.now ?? (() => new Date())
@@ -1888,7 +1890,7 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
   // Queue producer instead and the consumer runs `deliverAndRecord`.
   const dispatch =
     options.dispatch ??
-    (({ envelope, subscription }) => Webhooks.deliverAndRecord(store, subscription, envelope))
+    (({ envelope, subscription }) => Webhooks.deliverAndRecord(db, subscription, envelope))
 
   // Head resolution is lazy and per-source. RPC types work back from the live
   // RPC head; the legacy TIDX types from the indexed head (never ahead of the
@@ -1901,6 +1903,9 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
     (tidxHead ??= tidx ? await getIndexedHead(tidx, chainId) : await resolveRpcHead())
 
   const rpcSafeBlock = Math.max(0, (await resolveRpcHead()) - confirmations)
+  // Reclaim expired rows (MPP-owned subscriptions, aged delivery logs) once
+  // per tick; reads filter expiry at query time, so this is hygiene only.
+  await Webhooks.pruneExpired(db, { now }).catch(() => {})
   // Per-tick lazy cache so multiple subscriptions of the same/related types
   // share fetched blocks and receipts instead of refetching the same window.
   const cache = createChainCache(client)
@@ -1916,19 +1921,15 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
   for (const eventType of eventTypes) {
     const legacy = eventType === 'token:transfer'
     const safeBlock = legacy ? Math.max(0, (await resolveTidxHead()) - confirmations) : rpcSafeBlock
-    const subscriptions = await Webhooks.listActive(store, chainId, eventType)
+    const subscriptions = await Webhooks.listActive(db, chainId, eventType)
     for (const subscription of subscriptions) {
       result.subscriptions++
-      const cursor = await Webhooks.getCursor(store, subscription.id)
+      const cursor = await Webhooks.getCursor(db, subscription.id)
       if (cursor === null) {
         // First time we've seen this subscription: anchor it at the head of the
         // confirmed window so we never backfill from genesis. Events start
         // flowing from the next tick onward.
-        await Webhooks.setCursor(
-          store,
-          subscription.id,
-          Cursor.encode([safeBlock, endOfBlockIndex]),
-        )
+        await Webhooks.setCursor(db, subscription.id, Cursor.encode([safeBlock, endOfBlockIndex]))
         continue
       }
       const page = await scanSubscription({
@@ -1951,7 +1952,7 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
         // payloads) can render `amount` in token units. Non-fatal on failure.
         const data =
           eventType === 'token:transfer'
-            ? await withTokenMetadata(item.data, { chainId, client, store })
+            ? await withTokenMetadata(item.data, { cache: cache_metadata, chainId, client })
             : item.data
         const envelope = Webhooks.buildEnvelope({
           blockNumber: item.cursor[0],
@@ -1976,21 +1977,16 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
       // matches); keyset scanners advance past the last dispatched row, or — on
       // a complete empty page — to the end of the confirmed window.
       if (failed) {
-        if (accepted) await Webhooks.setCursor(store, subscription.id, Cursor.encode([...accepted]))
+        if (accepted) await Webhooks.setCursor(db, subscription.id, Cursor.encode([...accepted]))
       } else if (page.scannedThrough !== undefined)
         await Webhooks.setCursor(
-          store,
+          db,
           subscription.id,
           Cursor.encode([page.scannedThrough, endOfBlockIndex]),
         )
-      else if (accepted)
-        await Webhooks.setCursor(store, subscription.id, Cursor.encode([...accepted]))
+      else if (accepted) await Webhooks.setCursor(db, subscription.id, Cursor.encode([...accepted]))
       else if (!page.hasMore)
-        await Webhooks.setCursor(
-          store,
-          subscription.id,
-          Cursor.encode([safeBlock, endOfBlockIndex]),
-        )
+        await Webhooks.setCursor(db, subscription.id, Cursor.encode([safeBlock, endOfBlockIndex]))
     }
   }
 
@@ -2009,12 +2005,16 @@ export declare namespace poll {
   type Options = {
     /** Max matching rows scanned per subscription per tick (default 100). */
     batchSize?: number | undefined
+    /** Cache store for the token-metadata memoize (defaults to a fresh in-memory store; pass a persistent one to share lookups across ticks). */
+    cache?: Store.Store | undefined
     /** Chain to poll. Callers loop over chains. */
     chainId: number
     /** viem RPC client for the chain (used by the RPC monitoring scanners). */
     client: Viem.getClient.ReturnType
     /** Reorg-safety window: only emit blocks this far behind head (default 2). */
     confirmations?: number | undefined
+    /** Database holding subscriptions + cursors. */
+    db: Db.Db
     /**
      * Delivery transport. Defaults to inline {@link Webhooks.deliverAndRecord} (self-host);
      * on Cloudflare pass a Queue producer so retry/backoff/DLQ are native.
@@ -2028,8 +2028,6 @@ export declare namespace poll {
     maxBlocks?: number | undefined
     /** Clock for envelope timestamps; injectable for tests. */
     now?: (() => Date) | undefined
-    /** Webhook state store (subscriptions + cursors). */
-    store: Store.State
     /** TIDX query client for the legacy `token:transfer` type. */
     tidx?: Tidx.Client | undefined
   }
@@ -2059,9 +2057,9 @@ export declare namespace poll {
 async function withTokenMetadata(
   data: unknown,
   deps: {
+    cache: Store.Store
     chainId: number
     client: Viem.getClient.ReturnType
-    store: Store.State
   },
 ): Promise<unknown> {
   if (typeof data !== 'object' || data === null) return data
@@ -2079,7 +2077,7 @@ async function withTokenMetadata(
  */
 async function resolveTokenMetadata(
   address: string,
-  deps: { chainId: number; client: Viem.getClient.ReturnType; store: Store.State },
+  deps: { cache: Store.Store; chainId: number; client: Viem.getClient.ReturnType },
 ): Promise<{ decimals: number; symbol: string } | undefined> {
   try {
     return await Store.memoize(
@@ -2089,7 +2087,7 @@ async function resolveTokenMetadata(
       },
       {
         key: `webhook:token-meta:v1:${deps.chainId}:${address}`,
-        store: deps.store,
+        store: deps.cache,
         ttl: Ttl.minutes(5),
       },
     )

package/src/{Cli.test.ts → cli/Cli.test.ts}

@@ -1,6 +1,7 @@
-import { Cli } from 'cadent'
-import * as TestApp from '../test/App.js'
-import * as Runtime from '../test/runtime.js'
+import { Cli } from 'tapimo'
+
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
 
 const apiUrl = 'https://api.tempo-api.test'
 
@@ -12,7 +13,7 @@ describe('from', () => {
       const cli = Cli.from(apiUrl, { version: '1.2.3' })
       await serve(cli, ['--help'])
 
-      expect(cli.name).toMatchInlineSnapshot(`"tempo-api"`)
+      expect(cli.name).toMatchInlineSnapshot(`"tapimo"`)
       expect(cli.description).toMatchInlineSnapshot(`"Tempo API CLI"`)
     } finally {
       fetch.mockRestore()
@@ -20,11 +21,11 @@ describe('from', () => {
   })
 
   test('serves the hosted Tempo API command', async () => {
-    // Verified tokens are KV/store-backed (no bundled fallback), so seed the
-    // store for the default chain to exercise the `--verified` listing.
-    const fetch = mockHostedApi(
-      TestApp.create({ verifiedTokens: { store: TestApp.verifiedStore(Runtime.get().chainId) } }),
-    )
+    // Verified tokens are database-backed (no bundled fallback), so seed the
+    // db for the default chain to exercise the `--verified` listing.
+    const db = TestApp.database()
+    await TestApp.verifiedSeed(db, Runtime.get().chainId)
+    const fetch = mockHostedApi(TestApp.create({ db }))
 
     try {
       const cli = Cli.from(apiUrl)

package/src/{Cli.ts → cli/Cli.ts}

@@ -1,22 +1,29 @@
 import { Cli as incur_Cli, Fetch, type Openapi } from 'incur'
 
-/** Creates an incur CLI backed by a hosted Tempo API. */
+import * as Admin from './commands/admin.js'
+
+/**
+ * Creates an incur CLI backed by a hosted Tempo API, plus the operator
+ * commands (`<cli> admin …`).
+ */
 export function from(url: string | URL, options: from.Options = {}) {
   const {
     description = 'Tempo API CLI',
-    name = 'tempo-api',
+    name = 'tapimo',
     openapi = 'openapi.json',
     request,
     version = '0.0.0',
   } = options
 
-  return incur_Cli.create(name, {
-    description,
-    fetch: Fetch.fromRequest(url, request),
-    openapi,
-    openapiConfig: options.openapiConfig ?? { mode: 'namespace' },
-    version,
-  })
+  return incur_Cli
+    .create(name, {
+      description,
+      fetch: Fetch.fromRequest(url, request),
+      openapi,
+      openapiConfig: options.openapiConfig ?? { mode: 'namespace' },
+      version,
+    })
+    .command(Admin.admin)
 }
 
 export declare namespace from {

package/src/cli/bin.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import * as Cli from './Cli.js'
+
+await Cli.from('https://api.tempo.xyz').serve()

package/src/cli/commands/admin.test.ts

@@ -0,0 +1,71 @@
+import { nanoid } from 'nanoid'
+
+import * as TestCli from '../../../test/cli.js'
+
+describe('admin', () => {
+  describe('migrate', () => {
+    test('behavior: applies migrations', async () => {
+      const { code, envelope } = await TestCli.run([
+        'admin',
+        'migrate',
+        '--db-schema',
+        `t_${nanoid()}`,
+      ])
+      expect(code).toBe(0)
+      expect(envelope).toMatchInlineSnapshot(`
+        {
+          "data": {
+            "migrated": true,
+          },
+          "ok": true,
+        }
+      `)
+    })
+
+    test('behavior: applies migrations from DATABASE_URL without a schema option', async () => {
+      const { code, envelope } = await TestCli.run(['admin', 'migrate'])
+      expect(code).toBe(0)
+      expect(envelope).toEqual({ data: { migrated: true }, ok: true })
+    })
+
+    test('behavior: is idempotent across runs', async () => {
+      const schema = `t_${nanoid()}`
+      expect((await TestCli.run(['admin', 'migrate', '--db-schema', schema])).code).toBe(0)
+      const { code, envelope } = await TestCli.run(['admin', 'migrate', '--db-schema', schema])
+      expect(code).toBe(0)
+      expect(envelope).toEqual({ data: { migrated: true }, ok: true })
+    })
+
+    test('error: a missing connection string exits 1', async () => {
+      const { code, envelope } = await TestCli.run(['admin', 'migrate'], {
+        DATABASE_URL: undefined,
+      })
+      expect(code).toBe(1)
+      expect(envelope).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "missing_database_url",
+            "message": "Set --database-url or DATABASE_URL to the Postgres connection string.",
+          },
+          "ok": false,
+        }
+      `)
+    })
+
+    test('error: a migration failure exits 1', async () => {
+      const { code, envelope } = await TestCli.run(
+        [
+          'admin',
+          'migrate',
+          '--database-url',
+          'postgres://postgres:postgres@127.0.0.1:1/tempo-api',
+          '--db-schema',
+          `t_${nanoid()}`,
+        ],
+        { DATABASE_URL: undefined },
+      )
+      expect(code).toBe(1)
+      expect(envelope.error.code).toBe('migrate_failed')
+    })
+  })
+})

package/src/cli/commands/admin.ts

@@ -0,0 +1,60 @@
+import { Cli as incur_Cli, z } from 'incur'
+
+import * as Db from '../../db/Db.js'
+
+/**
+ * Applies pending Postgres migrations, connecting directly via
+ * `--database-url` or `DATABASE_URL` (never through Hyperdrive — the migrate
+ * advisory lock needs session semantics); `--db-schema` scopes the session.
+ */
+const migrate = incur_Cli.create('migrate', {
+  description: 'Apply pending database migrations.',
+  env: z.object({
+    DATABASE_URL: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Used when --database-url is omitted.'),
+  }),
+  options: z.object({
+    databaseUrl: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Overrides DATABASE_URL.'),
+    dbSchema: z.string().optional().describe('Postgres schema to create and scope the session to.'),
+  }),
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString)
+      return c.error({
+        code: 'missing_database_url',
+        message: 'Set --database-url or DATABASE_URL to the Postgres connection string.',
+      })
+    const db = Db.postgres({
+      connectionString,
+      ...(c.options.dbSchema ? { schema: c.options.dbSchema } : {}),
+    })
+    try {
+      await db.migrate()
+      return { migrated: true }
+    } catch (error) {
+      /* v8 ignore next */
+      const message = error instanceof Error ? error.message : 'Migration failed.'
+      return c.error({
+        code: 'migrate_failed',
+        message,
+      })
+    } finally {
+      await db.close()
+    }
+  },
+})
+
+/**
+ * Operator commands that run against a deployment's infrastructure rather
+ * than the hosted API (database migrations, …).
+ */
+export const admin = incur_Cli
+  .create('admin', {
+    description: 'Operator commands for a Tempo API deployment.',
+  })
+  .command(migrate)

package/src/cloudflare.ts

@@ -52,4 +52,14 @@ export class DurableObject extends CloudflareDurableObject {
   async put(key: string, value: string, options?: Store.Store.PutOptions) {
     await this.#store.put(key, value, options)
   }
+
+  /**
+   * Atomically compares-and-swaps a value.
+   *
+   * The compare and write run on the object's single thread behind its input
+   * gate, so concurrent callers cannot interleave between them.
+   */
+  async swap(key: string, expected: null | string, next: string, options?: Store.Store.PutOptions) {
+    return this.#store.swap!(key, expected, next, options)
+  }
 }

package/src/db/Db.test.ts

@@ -0,0 +1,84 @@
+import { nanoid } from 'nanoid'
+
+import { postgresUrl } from '../../test/containers.js'
+import * as Db from './Db.js'
+import * as Organizations from './tables/organizations.js'
+
+const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+
+describe('postgres', () => {
+  test('behavior: migrate is idempotent', async () => {
+    const db = create()
+    await db.migrate()
+    await db.migrate()
+    expect(await Organizations.get(db, 'missing')).toBeUndefined()
+    await db.close()
+  })
+
+  test('behavior: creates a Postgres db without schema scoping', async () => {
+    const db = Db.postgres({ connectionString: postgresUrl })
+    await db.close()
+  })
+
+  test('behavior: concurrent migrate tolerates the ledger race', async () => {
+    const schema = `t_${nanoid()}`
+    // Pre-create the schema so concurrent migrate races only on the
+    // `migrations` ledger, not `CREATE SCHEMA`.
+    const seed = Db.postgres({ connectionString: postgresUrl, schema })
+    await Organizations.get(seed, 'x').catch(() => {})
+    await seed.close()
+
+    // Several runners migrate the same fresh schema at once (mirrors parallel
+    // deploys). The session advisory lock serializes them; none throw.
+    const dbs = Array.from({ length: 5 }, () =>
+      Db.postgres({ connectionString: postgresUrl, schema }),
+    )
+    await Promise.all(dbs.map((db) => db.migrate()))
+    const created = await Organizations.create(dbs[0]!, { id: 'org_race', name: 'Race' })
+    expect(created.id).toBe('org_race')
+    await Promise.all(dbs.map((db) => db.close()))
+  })
+
+  test('error: rejects a modified applied migration', async () => {
+    const db = create()
+    await db.migrate()
+    await db.kysely
+      .updateTable('migrations')
+      .set({ checksum: '00000000' })
+      .where('name', '=', Db.migrations[0]!.name)
+      .execute()
+    await expect(db.migrate()).rejects.toThrow(/checksum mismatch/)
+    await db.close()
+  })
+
+  test('behavior: transaction rolls back on throw', async () => {
+    const db = create()
+    await db.migrate()
+    await expect(
+      db.transaction(async (tx) => {
+        await Organizations.create(tx, { id: 'org_2', name: 'Roll' })
+        throw new Error('boom')
+      }),
+    ).rejects.toThrow('boom')
+    expect(await Organizations.get(db, 'org_2')).toBeUndefined()
+    await db.close()
+  })
+
+  test('error: transaction rejects nesting', async () => {
+    const db = create()
+    await db.migrate()
+    await expect(db.transaction(() => db.transaction(async () => 1))).rejects.toThrow(/nesting/)
+    await db.close()
+  })
+
+  test('behavior: transaction commits and returns the value', async () => {
+    const db = create()
+    await db.migrate()
+    const id = await db.transaction(
+      async (tx) => (await Organizations.create(tx, { id: 'org_3', name: 'Commit' })).id,
+    )
+    expect(id).toBe('org_3')
+    expect((await Organizations.get(db, 'org_3'))?.name).toBe('Commit')
+    await db.close()
+  })
+})