@avelonjs/conformance 0.1.0

package/src/suites/database.ts

@@ -0,0 +1,853 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  Conflict,
+  Invalid,
+  type DatabaseCapabilities,
+  type DatabaseDriver,
+  type TransactionSurface,
+  type Predicate,
+  type QueryIR,
+  type RelationLoad,
+} from '@avelonjs/core'
+import { assertCapabilitySurface, captureFailure, type SuiteContext } from '../harness'
+
+type AssayDriver = DatabaseDriver<DatabaseCapabilities>
+type Row = Record<string, unknown>
+
+function query(overrides: Partial<QueryIR> = {}): QueryIR {
+  return {
+    table: 'assay_users',
+    mode: 'select',
+    select: '*',
+    where: [],
+    relations: [],
+    order: [],
+    ...overrides,
+  }
+}
+
+async function seed(driver: AssayDriver, table: string, values: Row | Row[]): Promise<void> {
+  await driver.execute(query({ table, mode: 'insert', select: [], values, returning: undefined }))
+}
+
+function ids(result: { readonly rows: readonly Row[] }): unknown[] {
+  return result.rows.map((row) => row.id)
+}
+
+async function selectIds(driver: AssayDriver, where: Predicate[]): Promise<unknown[]> {
+  return ids(
+    await driver.execute(
+      query({ select: ['id'], where, order: [{ column: 'id', direction: 'asc' }] }),
+    ),
+  )
+}
+
+async function expectInvalid(operation: () => Promise<unknown>): Promise<Invalid> {
+  const error = await captureFailure(operation)
+  expect(error).toBeInstanceOf(Invalid)
+  if (!(error instanceof Invalid)) throw new Error('Expected Invalid after taxonomy assertion.')
+  expect(error.code).toBe('INVALID')
+  return error
+}
+
+async function expectConflict(operation: () => Promise<unknown>): Promise<Conflict> {
+  const error = await captureFailure(operation)
+  expect(error).toBeInstanceOf(Conflict)
+  if (!(error instanceof Conflict)) throw new Error('Expected Conflict after taxonomy assertion.')
+  expect(error.code).toBe('CONFLICT')
+  return error
+}
+
+function relation(overrides: Partial<RelationLoad> = {}): RelationLoad {
+  return {
+    relation: 'posts',
+    kind: 'hasMany',
+    table: 'assay_posts',
+    localKey: 'id',
+    foreignKey: 'user_id',
+    select: '*',
+    where: null,
+    order: [],
+    relations: [],
+    ...overrides,
+  }
+}
+
+function nestedRelation(depth: number): RelationLoad {
+  const current = relation({
+    relation: `level_${depth}`,
+    kind: 'hasMany',
+    table: 'assay_users',
+    localKey: 'id',
+    foreignKey: 'id',
+  })
+  return depth === 1 ? current : { ...current, relations: [nestedRelation(depth - 1)] }
+}
+
+function hasRoundTripCounter(driver: object): driver is { readonly roundTrips: number } {
+  return 'roundTrips' in driver && typeof driver.roundTrips === 'number'
+}
+
+function hasTransactions(driver: AssayDriver): driver is AssayDriver & TransactionSurface {
+  return (
+    driver.capabilities.transactions && typeof Reflect.get(driver, 'transaction') === 'function'
+  )
+}
+
+function assay<TDriver extends AssayDriver>(
+  context: SuiteContext<TDriver>,
+  name: string,
+  assertion: (driver: TDriver) => Promise<void> | void,
+): void {
+  test(name, async () => {
+    const driver = await context.create()
+    try {
+      await assertion(driver)
+    } finally {
+      await context.cleanup?.(driver)
+    }
+  })
+}
+
+/**
+ * Registers the portable database contract conformance suite.
+ *
+ * The context must provision these empty fixture tables before each test:
+ * `assay_users(id, email, name, age, nickname)`, `assay_profiles(id, user_id, bio)`,
+ * `assay_posts(id, user_id, title, score, published_at)`,
+ * `assay_comments(id, post_id, body, position)`, and
+ * `assay_reactions(id, comment_id, kind)`. User IDs and emails, profile user IDs, and every table's
+ * ID are unique. The `assay_echo` routine returns its argument unchanged. Empty `belongsTo` and
+ * `hasOne` relations are `null`; empty `hasMany` relations are `[]`.
+ *
+ * @param context Fresh driver instances and optional live-service cleanup.
+ */
+export function databaseSuite<TDriver extends AssayDriver>(context: SuiteContext<TDriver>): void {
+  describe(`database conformance: ${context.name}`, () => {
+    assay(context, 'executes select, count, insert, update, and delete modes', async (driver) => {
+      const returningIds: QueryIR['returning'] = driver.capabilities.returning ? ['id'] : undefined
+      const inserted = await driver.execute(
+        query({
+          mode: 'insert',
+          select: [],
+          values: [
+            { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+            { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: 'second' },
+          ],
+          returning: returningIds,
+        }),
+      )
+      expect(inserted).toEqual({
+        rows: driver.capabilities.returning ? [{ id: 'u1' }, { id: 'u2' }] : [],
+        affected: 2,
+      })
+      expect(inserted.count).toBeUndefined()
+
+      const selected = await driver.execute(
+        query({
+          select: ['id', 'name'],
+          where: [{ kind: 'compare', column: 'id', op: '=', value: 'u1' }],
+        }),
+      )
+      expect(selected).toEqual({ rows: [{ id: 'u1', name: 'One' }], affected: 0 })
+
+      const counted = await driver.execute(
+        query({
+          mode: 'count',
+          select: [],
+          where: [{ kind: 'compare', column: 'age', op: '>=', value: 10 }],
+        }),
+      )
+      // Count is scalar metadata: it neither selects rows nor affects rows.
+      expect(counted).toEqual({ rows: [], affected: 0, count: 2 })
+
+      const updated = await driver.execute(
+        query({
+          mode: 'update',
+          select: [],
+          where: [{ kind: 'compare', column: 'id', op: '=', value: 'u1' }],
+          values: { name: 'Updated' },
+          returning: driver.capabilities.returning ? ['id', 'name'] : undefined,
+        }),
+      )
+      expect(updated).toEqual({
+        rows: driver.capabilities.returning ? [{ id: 'u1', name: 'Updated' }] : [],
+        affected: 1,
+      })
+
+      const deleted = await driver.execute(
+        query({
+          mode: 'delete',
+          select: [],
+          where: [{ kind: 'compare', column: 'id', op: '=', value: 'u2' }],
+          returning: returningIds,
+        }),
+      )
+      expect(deleted).toEqual({
+        rows: driver.capabilities.returning ? [{ id: 'u2' }] : [],
+        affected: 1,
+      })
+      expect(await selectIds(driver, [])).toEqual(['u1'])
+    })
+
+    assay(context, 'executes upsert wildcard and explicit update lists', async (driver) => {
+      if (!driver.capabilities.upsert) return
+      await seed(driver, 'assay_users', {
+        id: 'u1',
+        email: 'one@example.test',
+        name: 'Original',
+        age: 10,
+        nickname: null,
+      })
+
+      const wildcard = await driver.execute(
+        query({
+          mode: 'upsert',
+          select: [],
+          values: {
+            id: 'u1',
+            email: 'one@example.test',
+            name: 'Wildcard',
+            age: 20,
+            nickname: 'changed',
+          },
+          conflict: { columns: ['id'], update: '*' },
+          returning: driver.capabilities.returning ? '*' : undefined,
+        }),
+      )
+      expect(wildcard.affected).toBe(1)
+      if (driver.capabilities.returning)
+        expect(wildcard.rows).toEqual([
+          {
+            id: 'u1',
+            email: 'one@example.test',
+            name: 'Wildcard',
+            age: 20,
+            nickname: 'changed',
+          },
+        ])
+      expect(
+        (
+          await driver.execute(
+            query({
+              where: [{ kind: 'compare', column: 'id', op: '=', value: 'u1' }],
+            }),
+          )
+        ).rows,
+      ).toEqual([
+        {
+          id: 'u1',
+          email: 'one@example.test',
+          name: 'Wildcard',
+          age: 20,
+          nickname: 'changed',
+        },
+      ])
+
+      const explicit = await driver.execute(
+        query({
+          mode: 'upsert',
+          select: [],
+          values: {
+            id: 'u1',
+            email: 'replacement@example.test',
+            name: 'Explicit',
+            age: 99,
+            nickname: 'ignored',
+          },
+          conflict: { columns: ['id'], update: ['name'] },
+          returning: driver.capabilities.returning ? '*' : undefined,
+        }),
+      )
+      expect(explicit.affected).toBe(1)
+      if (driver.capabilities.returning)
+        expect(explicit.rows).toEqual([
+          {
+            id: 'u1',
+            email: 'one@example.test',
+            name: 'Explicit',
+            age: 20,
+            nickname: 'changed',
+          },
+        ])
+      expect(
+        (
+          await driver.execute(
+            query({
+              where: [{ kind: 'compare', column: 'id', op: '=', value: 'u1' }],
+            }),
+          )
+        ).rows,
+      ).toEqual([
+        {
+          id: 'u1',
+          email: 'one@example.test',
+          name: 'Explicit',
+          age: 20,
+          nickname: 'changed',
+        },
+      ])
+
+      const created = await driver.execute(
+        query({
+          mode: 'upsert',
+          select: [],
+          values: {
+            id: 'u2',
+            email: 'two@example.test',
+            name: 'Created',
+            age: 30,
+            nickname: null,
+          },
+          conflict: { columns: ['id'], update: '*' },
+          returning: driver.capabilities.returning ? ['id'] : undefined,
+        }),
+      )
+      expect(created).toEqual({
+        rows: driver.capabilities.returning ? [{ id: 'u2' }] : [],
+        affected: 1,
+      })
+    })
+
+    assay(context, 'implements every comparison operator', async (driver) => {
+      await seed(driver, 'assay_users', [
+        { id: 'u1', email: 'one@example.test', name: 'Alpha', age: 10, nickname: null },
+        { id: 'u2', email: 'two@example.test', name: 'alpine', age: 20, nickname: null },
+        { id: 'u3', email: 'three@example.test', name: 'Beta', age: 30, nickname: null },
+      ])
+      const cases: readonly [QueryIRCompareOp, unknown, readonly string[]][] = [
+        ['=', 20, ['u2']],
+        ['!=', 20, ['u1', 'u3']],
+        ['<', 20, ['u1']],
+        ['<=', 20, ['u1', 'u2']],
+        ['>', 20, ['u3']],
+        ['>=', 20, ['u2', 'u3']],
+      ]
+      for (const [op, value, expected] of cases) {
+        expect(await selectIds(driver, [{ kind: 'compare', column: 'age', op, value }])).toEqual([
+          ...expected,
+        ])
+      }
+      expect(
+        await selectIds(driver, [{ kind: 'compare', column: 'name', op: 'like', value: 'Al%' }]),
+      ).toEqual(['u1'])
+      expect(
+        await selectIds(driver, [{ kind: 'compare', column: 'name', op: 'ilike', value: 'AL%' }]),
+      ).toEqual(['u1', 'u2'])
+    })
+
+    assay(context, 'implements null and IN predicates including negation', async (driver) => {
+      await seed(driver, 'assay_users', [
+        { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+        { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: 'x' },
+        { id: 'u3', email: 'three@example.test', name: 'Three', age: 30, nickname: 'y' },
+        { id: 'u4', email: 'four@example.test', name: 'Four', age: 40, nickname: null },
+      ])
+      expect(
+        await selectIds(driver, [{ kind: 'null', column: 'nickname', negated: false }]),
+      ).toEqual(['u1', 'u4'])
+      expect(
+        await selectIds(driver, [{ kind: 'null', column: 'nickname', negated: true }]),
+      ).toEqual(['u2', 'u3'])
+      expect(
+        await selectIds(driver, [{ kind: 'compare', column: 'nickname', op: '!=', value: 'x' }]),
+      ).toEqual(['u3'])
+      expect(
+        await selectIds(driver, [
+          { kind: 'in', column: 'nickname', values: ['x', 'y'], negated: false },
+        ]),
+      ).toEqual(['u2', 'u3'])
+      expect(
+        await selectIds(driver, [{ kind: 'in', column: 'nickname', values: ['x'], negated: true }]),
+      ).toEqual(['u3'])
+      expect(
+        await selectIds(driver, [{ kind: 'in', column: 'id', values: [], negated: false }]),
+      ).toEqual([])
+      expect(
+        await selectIds(driver, [{ kind: 'in', column: 'id', values: [], negated: true }]),
+      ).toEqual(['u1', 'u2', 'u3', 'u4'])
+    })
+
+    assay(context, 'ANDs separate where entries', async (driver) => {
+      await seed(driver, 'assay_users', [
+        { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+        { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: null },
+        { id: 'u3', email: 'three@example.test', name: 'Three', age: 30, nickname: null },
+      ])
+      expect(
+        await selectIds(driver, [
+          { kind: 'compare', column: 'age', op: '>=', value: 20 },
+          { kind: 'compare', column: 'age', op: '<', value: 30 },
+        ]),
+      ).toEqual(['u2'])
+    })
+
+    assay(context, 'ORs branches within an or predicate', async (driver) => {
+      await seed(driver, 'assay_users', [
+        { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+        { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: null },
+        { id: 'u3', email: 'three@example.test', name: 'Three', age: 30, nickname: null },
+      ])
+      expect(
+        await selectIds(driver, [
+          {
+            kind: 'or',
+            predicates: [
+              { kind: 'compare', column: 'id', op: '=', value: 'u1' },
+              { kind: 'compare', column: 'id', op: '=', value: 'u3' },
+            ],
+          },
+        ]),
+      ).toEqual(['u1', 'u3'])
+    })
+
+    assay(context, 'ANDs the ward with query predicates', async (driver) => {
+      await seed(driver, 'assay_users', [
+        { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+        { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: null },
+        { id: 'u3', email: 'three@example.test', name: 'Three', age: 30, nickname: null },
+      ])
+      const result = await driver.execute(
+        query({
+          select: ['id'],
+          where: [{ kind: 'compare', column: 'age', op: '>=', value: 20 }],
+          ward: { kind: 'compare', column: 'age', op: '<', value: 30 },
+        }),
+      )
+      expect(ids(result)).toEqual(['u2'])
+    })
+
+    assay(
+      context,
+      'applies empty boolean identities and folds NOT over constants',
+      async (driver) => {
+        await seed(driver, 'assay_users', {
+          id: 'u1',
+          email: 'one@example.test',
+          name: 'One',
+          age: 10,
+          nickname: null,
+        })
+        expect(await selectIds(driver, [{ kind: 'and', predicates: [] }])).toEqual(['u1'])
+        expect(await selectIds(driver, [{ kind: 'or', predicates: [] }])).toEqual([])
+        expect(
+          await selectIds(driver, [{ kind: 'not', predicate: { kind: 'const', value: false } }]),
+        ).toEqual(['u1'])
+        expect(
+          await selectIds(driver, [{ kind: 'not', predicate: { kind: 'const', value: true } }]),
+        ).toEqual([])
+      },
+    )
+
+    assay(
+      context,
+      'short-circuits constant false without a backing-store round trip',
+      async (driver) => {
+        await seed(driver, 'assay_users', {
+          id: 'u1',
+          email: 'one@example.test',
+          name: 'One',
+          age: 10,
+          nickname: null,
+        })
+        const beforeCount = hasRoundTripCounter(driver) ? driver.roundTrips : undefined
+        const counted = await driver.execute(
+          query({ mode: 'count', select: [], where: [{ kind: 'const', value: false }] }),
+        )
+        expect(counted).toEqual({ rows: [], affected: 0, count: 0 })
+        if (beforeCount !== undefined && hasRoundTripCounter(driver)) {
+          expect(driver.roundTrips).toBe(beforeCount)
+        }
+
+        const beforeSelect = hasRoundTripCounter(driver) ? driver.roundTrips : undefined
+        const selected = await driver.execute(query({ ward: { kind: 'const', value: false } }))
+        expect(selected).toEqual({ rows: [], affected: 0 })
+        if (beforeSelect !== undefined && hasRoundTripCounter(driver)) {
+          expect(driver.roundTrips).toBe(beforeSelect)
+        }
+        // A live driver proves the same property with its transport spy or query log: no statement may
+        // appear between the pre-call and post-call markers.
+      },
+    )
+
+    assay(
+      context,
+      'honors order, null placement, projection, limit, and offset',
+      async (driver) => {
+        await seed(driver, 'assay_users', [
+          { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+          { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: 'alpha' },
+          { id: 'u3', email: 'three@example.test', name: 'Three', age: 30, nickname: 'beta' },
+        ])
+        const page = await driver.execute(
+          query({
+            select: ['id', 'nickname'],
+            order: [{ column: 'nickname', direction: 'asc', nulls: 'last' }],
+            offset: 1,
+            limit: 1,
+          }),
+        )
+        expect(page.rows).toEqual([{ id: 'u3', nickname: 'beta' }])
+        const nullsFirst = await driver.execute(
+          query({
+            select: ['id'],
+            order: [{ column: 'nickname', direction: 'desc', nulls: 'first' }],
+          }),
+        )
+        expect(ids(nullsFirst)).toEqual(['u1', 'u3', 'u2'])
+      },
+    )
+
+    assay(context, 'loads belongsTo, hasOne, and hasMany relations', async (driver) => {
+      if (driver.capabilities.maxRelationDepth < 1) return
+      await seed(driver, 'assay_users', [
+        { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+        { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: null },
+      ])
+      await seed(driver, 'assay_profiles', { id: 'p1', user_id: 'u1', bio: 'Profile one' })
+      await seed(driver, 'assay_posts', [
+        { id: 'post1', user_id: 'u1', title: 'First', score: 1, published_at: null },
+        { id: 'post2', user_id: 'u1', title: 'Second', score: 2, published_at: null },
+      ])
+
+      const post = await driver.execute(
+        query({
+          table: 'assay_posts',
+          select: ['id'],
+          where: [{ kind: 'compare', column: 'id', op: '=', value: 'post1' }],
+          relations: [
+            relation({
+              relation: 'author',
+              kind: 'belongsTo',
+              table: 'assay_users',
+              localKey: 'user_id',
+              foreignKey: 'id',
+              select: ['id', 'name'],
+            }),
+          ],
+        }),
+      )
+      expect(post.rows).toEqual([{ id: 'post1', author: { id: 'u1', name: 'One' } }])
+
+      const user = await driver.execute(
+        query({
+          select: ['id'],
+          where: [{ kind: 'compare', column: 'id', op: '=', value: 'u1' }],
+          relations: [
+            relation({
+              relation: 'profile',
+              kind: 'hasOne',
+              table: 'assay_profiles',
+              foreignKey: 'user_id',
+              select: ['bio'],
+            }),
+            relation({ select: ['id'], order: [{ column: 'id', direction: 'asc' }] }),
+          ],
+        }),
+      )
+      expect(user.rows).toEqual([
+        {
+          id: 'u1',
+          profile: { bio: 'Profile one' },
+          posts: [{ id: 'post1' }, { id: 'post2' }],
+        },
+      ])
+    })
+
+    assay(
+      context,
+      'returns null for empty singular relations and [] for empty hasMany relations',
+      async (driver) => {
+        if (driver.capabilities.maxRelationDepth < 1) return
+        await seed(driver, 'assay_users', [
+          { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+          { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: null },
+        ])
+        await seed(driver, 'assay_posts', {
+          id: 'post1',
+          user_id: 'u2',
+          title: 'Second user post',
+          score: 1,
+          published_at: null,
+        })
+
+        const user = await driver.execute(
+          query({
+            select: ['id'],
+            where: [{ kind: 'compare', column: 'id', op: '=', value: 'u1' }],
+            relations: [
+              relation({
+                relation: 'profile',
+                kind: 'hasOne',
+                table: 'assay_profiles',
+                foreignKey: 'user_id',
+                select: ['bio'],
+              }),
+              relation({ select: ['id'] }),
+            ],
+          }),
+        )
+        const post = await driver.execute(
+          query({
+            table: 'assay_posts',
+            select: ['id'],
+            where: [{ kind: 'compare', column: 'id', op: '=', value: 'post1' }],
+            relations: [
+              relation({
+                relation: 'author',
+                kind: 'belongsTo',
+                table: 'assay_users',
+                localKey: 'user_id',
+                foreignKey: 'id',
+                select: ['id'],
+                where: { kind: 'compare', column: 'id', op: '=', value: 'missing' },
+              }),
+            ],
+          }),
+        )
+
+        expect({ user: user.rows, post: post.rows }).toEqual({
+          user: [{ id: 'u1', profile: null, posts: [] }],
+          post: [{ id: 'post1', author: null }],
+        })
+      },
+    )
+
+    assay(
+      context,
+      'loads nested relations and applies relation limits per parent',
+      async (driver) => {
+        if (driver.capabilities.maxRelationDepth < 2) return
+        await seed(driver, 'assay_users', [
+          { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+          { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: null },
+        ])
+        await seed(driver, 'assay_posts', [
+          { id: 'post1', user_id: 'u1', title: 'First', score: 1, published_at: null },
+          { id: 'post2', user_id: 'u1', title: 'Second', score: 2, published_at: null },
+          { id: 'post3', user_id: 'u2', title: 'Third', score: 3, published_at: null },
+          { id: 'post4', user_id: 'u2', title: 'Fourth', score: 4, published_at: null },
+        ])
+        await seed(driver, 'assay_comments', [
+          { id: 'c1', post_id: 'post2', body: 'Earlier', position: 1 },
+          { id: 'c2', post_id: 'post2', body: 'Later', position: 2 },
+          { id: 'c3', post_id: 'post4', body: 'Other', position: 1 },
+        ])
+        const comments = relation({
+          relation: 'comments',
+          table: 'assay_comments',
+          localKey: 'id',
+          foreignKey: 'post_id',
+          select: ['id'],
+          order: [{ column: 'position', direction: 'desc' }],
+          limit: 1,
+        })
+        const result = await driver.execute(
+          query({
+            select: ['id'],
+            order: [{ column: 'id', direction: 'asc' }],
+            relations: [
+              relation({
+                select: ['id'],
+                order: [{ column: 'score', direction: 'desc' }],
+                limit: 1,
+                relations: [comments],
+              }),
+            ],
+          }),
+        )
+        expect(result.rows).toEqual([
+          { id: 'u1', posts: [{ id: 'post2', comments: [{ id: 'c2' }] }] },
+          { id: 'u2', posts: [{ id: 'post4', comments: [{ id: 'c3' }] }] },
+        ])
+      },
+    )
+
+    assay(context, 'rejects relation loads beyond maxRelationDepth', async (driver) => {
+      const error = await captureFailure(() =>
+        driver.execute(
+          query({ relations: [nestedRelation(driver.capabilities.maxRelationDepth + 1)] }),
+        ),
+      )
+      expect(error).toBeInstanceOf(Invalid)
+    })
+
+    assay(
+      context,
+      'enforces method-gated database capability surfaces in both directions',
+      async (driver) => {
+        assertCapabilitySurface(driver, 'transactions', driver.capabilities.transactions, [
+          'transaction',
+        ])
+        assertCapabilitySurface(driver, 'rowSecurity', driver.capabilities.rowSecurity, [
+          'syncWards',
+        ])
+        assertCapabilitySurface(driver, 'fullTextSearch', driver.capabilities.fullTextSearch, [
+          'search',
+        ])
+        const unavailable = { capabilities: { transactions: false } as const }
+        assertCapabilitySurface(
+          unavailable,
+          'transactions',
+          unavailable.capabilities.transactions,
+          ['transaction'],
+        )
+        expect(() =>
+          assertCapabilitySurface(
+            { ...unavailable, transaction: async () => undefined },
+            'transactions',
+            false,
+            ['transaction'],
+          ),
+        ).toThrow()
+        expect(() =>
+          assertCapabilitySurface(
+            { capabilities: { transactions: true } as const },
+            'transactions',
+            true,
+            ['transaction'],
+          ),
+        ).toThrow()
+      },
+    )
+
+    assay(
+      context,
+      'commits and rolls back transactions and propagates callback results',
+      async (driver) => {
+        if (!hasTransactions(driver)) return
+
+        await expect(
+          driver.transaction(async (transaction) => {
+            await transaction.execute(
+              query({
+                mode: 'insert',
+                select: [],
+                values: {
+                  id: 'rolled-back',
+                  email: 'rollback@example.test',
+                  name: 'Rollback',
+                  age: 10,
+                  nickname: null,
+                },
+              }),
+            )
+            throw new Error('assay rollback')
+          }),
+        ).rejects.toThrow('assay rollback')
+        expect(
+          await selectIds(driver, [
+            { kind: 'compare', column: 'id', op: '=', value: 'rolled-back' },
+          ]),
+        ).toEqual([])
+
+        const callbackResult = { committed: true }
+        const result = await driver.transaction(async (transaction) => {
+          await transaction.execute(
+            query({
+              mode: 'insert',
+              select: [],
+              values: {
+                id: 'committed',
+                email: 'commit@example.test',
+                name: 'Commit',
+                age: 20,
+                nickname: null,
+              },
+            }),
+          )
+          return callbackResult
+        })
+        expect(result).toBe(callbackResult)
+        expect(
+          await selectIds(driver, [{ kind: 'compare', column: 'id', op: '=', value: 'committed' }]),
+        ).toEqual(['committed'])
+      },
+    )
+
+    assay(context, 'normalizes unique insert and upsert violations to Conflict', async (driver) => {
+      await seed(driver, 'assay_users', [
+        { id: 'u1', email: 'one@example.test', name: 'One', age: 10, nickname: null },
+        { id: 'u2', email: 'two@example.test', name: 'Two', age: 20, nickname: null },
+      ])
+      await expectConflict(() =>
+        driver.execute(
+          query({
+            mode: 'insert',
+            select: [],
+            values: { id: 'u3', email: 'one@example.test', name: 'Duplicate', age: 30 },
+          }),
+        ),
+      )
+      if (driver.capabilities.upsert) {
+        await expectConflict(() =>
+          driver.execute(
+            query({
+              mode: 'upsert',
+              select: [],
+              values: { id: 'u1', email: 'two@example.test', name: 'Conflict', age: 10 },
+              conflict: { columns: ['id'], update: '*' },
+            }),
+          ),
+        )
+      }
+    })
+
+    assay(context, 'rejects malformed upsert and count IR as Invalid', async (driver) => {
+      await expectInvalid(() =>
+        driver.execute(
+          query({
+            mode: 'upsert',
+            select: [],
+            values: { id: 'u1', email: 'one@example.test' },
+          }),
+        ),
+      )
+      const malformedCounts: QueryIR[] = [
+        query({ mode: 'count', select: ['id'] }),
+        // Rejecting `*` costs count producers an explicit `[]`, but catches a leaked builder default.
+        query({ mode: 'count', select: '*' }),
+        query({ mode: 'count', select: [], relations: [relation()] }),
+        query({ mode: 'count', select: [], order: [{ column: 'id', direction: 'asc' }] }),
+        query({ mode: 'count', select: [], limit: 1 }),
+        query({ mode: 'count', select: [], offset: 1 }),
+        query({ mode: 'count', select: [], returning: ['id'] }),
+      ]
+      for (const malformed of malformedCounts) {
+        await expectInvalid(() => driver.execute(malformed))
+      }
+    })
+
+    assay(context, 'rejects unknown identifiers as Invalid', async (driver) => {
+      const malformed: QueryIR[] = [
+        query({ table: 'unknown_table' }),
+        query({ select: ['unknown_column'] }),
+        query({ where: [{ kind: 'compare', column: 'unknown_column', op: '=', value: 1 }] }),
+        query({ order: [{ column: 'unknown_column', direction: 'asc' }] }),
+        query({ mode: 'insert', select: [], values: { unknown_column: 1 } }),
+        query({ mode: 'delete', select: [], returning: ['unknown_column'] }),
+        query({ relations: [relation({ table: 'unknown_table' })] }),
+      ]
+      for (const entry of malformed) await expectInvalid(() => driver.execute(entry))
+    })
+
+    assay(context, 'round-trips RPC results from a provisioned routine', async (driver) => {
+      const args = { message: 'hello', nested: { count: 2 }, active: true }
+      expect(await driver.rpc<typeof args>('assay_echo', args)).toEqual(args)
+    })
+
+    assay(
+      context,
+      'maps a missing RPC routine to Invalid with routine metadata',
+      async (driver) => {
+        // NotFound is deliberately absent: DatabaseDriver has no must-exist operation. findOrFail and
+        // route-model binding own NotFound in the model layer. A missing routine is deployment drift,
+        // not a missing page; Invalid avoids a false 404 while preserving the routine name.
+        const error = await expectInvalid(() => driver.rpc('missing_assay_routine', {}))
+        expect(error.metadata.fields?.routine).toContain('missing_assay_routine')
+      },
+    )
+  })
+}
+
+type QueryIRCompareOp = Extract<Predicate, { kind: 'compare' }>['op']