feat(stack): verify declared v3 schemas against introspected domains

Author: tobyhede

packages/stack/__tests__/supabase-verify.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import { encryptedTable, types } from '@/eql/v3'
+import type { IntrospectionResult } from '@/supabase/introspect'
+import { verifyDeclaredSchemas } from '@/supabase/verify'
+
+const introspection: IntrospectionResult = [
+  {
+    tableName: 'users',
+    columns: [
+      { columnName: 'id', domainName: null },
+      { columnName: 'email', domainName: 'text_search' },
+      { columnName: 'amount', domainName: 'integer_ord' },
+    ],
+  },
+]
+
+describe('verifyDeclaredSchemas', () => {
+  it('passes when every declared column matches its introspected domain', () => {
+    const users = encryptedTable('users', {
+      email: types.TextSearch('email'),
+      amount: types.IntegerOrd('amount'),
+    })
+    expect(() => verifyDeclaredSchemas({ users }, introspection)).not.toThrow()
+  })
+
+  it('passes when only a subset of encrypted columns is declared', () => {
+    const users = encryptedTable('users', { email: types.TextSearch('email') })
+    expect(() => verifyDeclaredSchemas({ users }, introspection)).not.toThrow()
+  })
+
+  it('throws naming the table when a declared table is absent', () => {
+    const orders = encryptedTable('orders', {
+      total: types.IntegerOrd('total'),
+    })
+    expect(() => verifyDeclaredSchemas({ orders }, introspection)).toThrow(
+      /table "orders"/,
+    )
+  })
+
+  it('throws naming the column when a declared column is absent', () => {
+    const users = encryptedTable('users', { missing: types.TextEq('missing') })
+    expect(() => verifyDeclaredSchemas({ users }, introspection)).toThrow(
+      /users\.missing/,
+    )
+  })
+
+  it('throws naming both domains when the domain differs', () => {
+    // email is actually text_search; declaring text_eq must fail at startup.
+    const users = encryptedTable('users', { email: types.TextEq('email') })
+    expect(() => verifyDeclaredSchemas({ users }, introspection)).toThrow(
+      /text_eq.*text_search|text_search.*text_eq/,
+    )
+  })
+})

packages/stack/src/supabase/verify.ts

@@ -0,0 +1,48 @@
+import { stripDomainSchema } from '@/eql/v3/domain-registry'
+import type { IntrospectionResult } from './introspect'
+import type { V3Schemas } from './schema-builder'
+
+/**
+ * Verify declared v3 tables against the introspected database. For every
+ * declared column, assert the column exists and its introspected `domain_name`
+ * matches the declared (unqualified) `eqlType`. Any mismatch throws at
+ * construction — a wrong domain is caught here instead of as a 23514 CHECK
+ * violation on the first query. Declaring a subset of a table's encrypted
+ * columns is allowed; undeclared columns are synthesized from their domains.
+ */
+export function verifyDeclaredSchemas(
+  schemas: V3Schemas,
+  introspection: IntrospectionResult,
+): void {
+  const index = new Map<string, Map<string, string | null>>()
+  for (const table of introspection) {
+    const cols = new Map<string, string | null>()
+    for (const col of table.columns) cols.set(col.columnName, col.domainName)
+    index.set(table.tableName, cols)
+  }
+
+  for (const declared of Object.values(schemas)) {
+    const tableName = declared.tableName
+    const cols = index.get(tableName)
+    if (!cols) {
+      throw new Error(
+        `[supabase v3]: declared table "${tableName}" was not found in the database`,
+      )
+    }
+    for (const builder of Object.values(declared.columnBuilders)) {
+      const dbName = builder.getName()
+      if (!cols.has(dbName)) {
+        throw new Error(
+          `[supabase v3]: declared column "${tableName}.${dbName}" was not found in the database`,
+        )
+      }
+      const expected = stripDomainSchema(builder.getEqlType())
+      const actual = cols.get(dbName)
+      if (actual !== expected) {
+        throw new Error(
+          `[supabase v3]: column "${tableName}.${dbName}" has domain "${actual ?? '(none)'}" but the schema declares "${expected}"`,
+        )
+      }
+    }
+  }
+}