@fuzdev/fuz_app 0.64.0 → 0.66.0

package/dist/testing/rpc_round_trip.js

@@ -5,35 +5,39 @@ import './assert_dev_env.js';
  * For every RPC method, generates valid params and fires JSON-RPC requests
  * (POST for all methods, GET for reads), validating that responses are
  * well-formed JSON-RPC. Successful responses are validated against the
- * method's declared output schema. DB-backed via `create_test_app`.
+ * method's declared output schema. DB-backed via the suite's `setup_test`
+ * fixture-producing callback.
+ *
+ * Cadence: per-describe `setup_test()` call (see `round_trip.ts` module
+ * docstring). RPC round-trip tests fire one JSON-RPC envelope per
+ * method-direction and don't mutate state in a way that contaminates the
+ * next case.
  *
  * @module
  */
-import { describe, test, beforeAll, afterAll } from 'vitest';
+import { describe, test, beforeAll } from 'vitest';
 import { ROLE_ADMIN } from '../auth/role_schema.js';
-import { create_test_app, } from './app_server.js';
-import { create_pglite_factory } from './db.js';
 import { generate_valid_body } from './schema_generators.js';
-import { run_migrations } from '../db/migrate.js';
-import { auth_migration_ns } from '../auth/migrations.js';
 import { is_public_auth } from '../http/auth_shape.js';
 import { create_rpc_post_init, create_rpc_get_url, assert_jsonrpc_error_response, assert_jsonrpc_success_response, resolve_rpc_endpoints_for_setup, } from './rpc_helpers.js';
 /**
- * Pick auth headers matching an RPC method's auth requirement.
+ * Pick auth headers matching an RPC method's auth requirement. Accepts
+ * any `KeeperHeaderProvider` — both `TestApp` (in-process) and
+ * `TestFixture` (cross-backend) satisfy the shape structurally.
  */
-const pick_rpc_auth_headers = (method, test_app, authed_account, admin_account) => {
+const pick_rpc_auth_headers = (method, keeper, authed_account, admin_account) => {
     const { auth } = method;
     if (is_public_auth(auth)) {
         return { host: 'localhost', origin: 'http://localhost:5173' };
     }
     if (auth.credential_types?.includes('daemon_token')) {
-        return test_app.create_daemon_token_headers();
+        return keeper.create_daemon_token_headers();
     }
     if (auth.roles?.length) {
         if (auth.roles.includes(ROLE_ADMIN)) {
             return admin_account.create_session_headers();
         }
-        return test_app.create_session_headers();
+        return keeper.create_session_headers();
     }
     return authed_account.create_session_headers();
 };
@@ -54,112 +58,91 @@ const pick_rpc_auth_headers = (method, test_app, authed_account, admin_account)
 export const describe_rpc_round_trip_tests = (options) => {
     const skip_set = new Set(options.skip_methods);
     // Resolve factory-form endpoints once for setup-time iteration (method
-    // enumeration, surface lookup). Real handlers run per-test via the
-    // top-level `rpc_endpoints` slot on `CreateTestAppOptions` —
-    // `action.spec.method` / `.input` / `.output` are ctx-independent, so
-    // the stub-resolved specs match what the live dispatcher serves.
+    // enumeration, surface lookup). The live dispatcher runs against
+    // whatever the backend was started with — `action.spec.method` /
+    // `.input` / `.output` are ctx-independent, so the stub-resolved specs
+    // match what the running backend serves.
     const rpc_endpoints_for_setup = resolve_rpc_endpoints_for_setup(options.rpc_endpoints, options.session_options);
-    const init_schema = async (db) => {
-        await run_migrations(db, [auth_migration_ns]);
-    };
-    const factories = options.db_factories ?? [create_pglite_factory(init_schema)];
-    for (const factory of factories) {
-        const describe_fn = factory.skip ? describe.skip : describe;
-        describe_fn(`RPC round-trip validation (${factory.name})`, () => {
-            let test_app;
-            let authed_account;
-            let admin_account;
-            let db;
-            beforeAll(async () => {
-                db = await factory.create();
-                test_app = await create_test_app({
-                    session_options: options.session_options,
-                    create_route_specs: options.create_route_specs,
-                    db,
-                    rpc_endpoints: options.rpc_endpoints,
-                    app_options: options.app_options,
-                });
-                authed_account = await test_app.create_account({
-                    username: 'rpc_round_trip_authed',
-                    roles: [],
-                });
-                admin_account = await test_app.create_account({
-                    username: 'rpc_round_trip_admin',
-                    roles: [ROLE_ADMIN],
-                });
+    const surface_rpc_endpoints = options.surface_source.surface.rpc_endpoints;
+    void options.capabilities;
+    describe('RPC round-trip validation', () => {
+        let fixture;
+        let authed_account;
+        let admin_account;
+        beforeAll(async () => {
+            fixture = await options.setup_test();
+            authed_account = await fixture.create_account({
+                username: 'rpc_round_trip_authed',
+                roles: [],
             });
-            afterAll(async () => {
-                await test_app.cleanup();
-                await factory.close(db);
+            admin_account = await fixture.create_account({
+                username: 'rpc_round_trip_admin',
+                roles: [ROLE_ADMIN],
             });
-            test('all RPC methods produce valid JSON-RPC responses (POST)', async () => {
-                for (const ep_spec of rpc_endpoints_for_setup) {
-                    const surface_ep = test_app.surface_spec.surface.rpc_endpoints.find((e) => e.path === ep_spec.path);
-                    if (!surface_ep)
+        });
+        test('all RPC methods produce valid JSON-RPC responses (POST)', async () => {
+            for (const ep_spec of rpc_endpoints_for_setup) {
+                const surface_ep = surface_rpc_endpoints.find((e) => e.path === ep_spec.path);
+                if (!surface_ep)
+                    continue;
+                for (const action of ep_spec.actions) {
+                    if (skip_set.has(action.spec.method))
+                        continue;
+                    const surface_method = surface_ep.methods.find((m) => m.name === action.spec.method);
+                    if (!surface_method)
                         continue;
-                    for (const action of ep_spec.actions) {
-                        if (skip_set.has(action.spec.method))
-                            continue;
-                        const surface_method = surface_ep.methods.find((m) => m.name === action.spec.method);
-                        if (!surface_method)
-                            continue;
-                        // generate or override params
-                        const override = options.input_overrides?.get(action.spec.method);
-                        const params = override ?? generate_valid_body(action.spec.input) ?? null;
-                        // pick auth
-                        const headers = pick_rpc_auth_headers(surface_method, test_app, authed_account, admin_account);
-                        const init = create_rpc_post_init(action.spec.method, params);
-                        // merge auth headers into init
-                        Object.assign(init.headers, headers);
-                        const res = await test_app.app.request(ep_spec.path, init);
-                        const body = await res.json();
-                        // validate well-formed JSON-RPC; successful responses also checked against output schema
-                        try {
-                            if (res.ok) {
-                                assert_jsonrpc_success_response(body, action.spec.output);
-                            }
-                            else {
-                                assert_jsonrpc_error_response(body);
-                            }
+                    const override = options.input_overrides?.get(action.spec.method);
+                    const params = override ?? generate_valid_body(action.spec.input) ?? null;
+                    const headers = pick_rpc_auth_headers(surface_method, fixture, authed_account, admin_account);
+                    const init = create_rpc_post_init(action.spec.method, params);
+                    Object.assign(init.headers, headers);
+                    const res = await fixture.transport(ep_spec.path, init);
+                    const body = await res.json();
+                    try {
+                        if (res.ok) {
+                            assert_jsonrpc_success_response(body, action.spec.output);
                         }
-                        catch (e) {
-                            throw new Error(`RPC round-trip POST failed for ${action.spec.method} (status ${res.status}): ${e.message}`);
+                        else {
+                            assert_jsonrpc_error_response(body);
                         }
                     }
+                    catch (e) {
+                        throw new Error(`RPC round-trip POST failed for ${action.spec.method} (status ${res.status}): ${e.message}`);
+                    }
                 }
-            });
-            test('all read RPC methods produce valid JSON-RPC responses (GET)', async () => {
-                for (const ep_spec of rpc_endpoints_for_setup) {
-                    const surface_ep = test_app.surface_spec.surface.rpc_endpoints.find((e) => e.path === ep_spec.path);
-                    if (!surface_ep)
+            }
+        });
+        test('all read RPC methods produce valid JSON-RPC responses (GET)', async () => {
+            for (const ep_spec of rpc_endpoints_for_setup) {
+                const surface_ep = surface_rpc_endpoints.find((e) => e.path === ep_spec.path);
+                if (!surface_ep)
+                    continue;
+                const read_actions = ep_spec.actions.filter((a) => !a.spec.side_effects);
+                for (const action of read_actions) {
+                    if (skip_set.has(action.spec.method))
+                        continue;
+                    const surface_method = surface_ep.methods.find((m) => m.name === action.spec.method);
+                    if (!surface_method)
                         continue;
-                    const read_actions = ep_spec.actions.filter((a) => !a.spec.side_effects);
-                    for (const action of read_actions) {
-                        if (skip_set.has(action.spec.method))
-                            continue;
-                        const surface_method = surface_ep.methods.find((m) => m.name === action.spec.method);
-                        if (!surface_method)
-                            continue;
-                        const override = options.input_overrides?.get(action.spec.method);
-                        const params = override ?? generate_valid_body(action.spec.input) ?? undefined;
-                        const headers = pick_rpc_auth_headers(surface_method, test_app, authed_account, admin_account);
-                        const url = create_rpc_get_url(ep_spec.path, action.spec.method, params);
-                        const res = await test_app.app.request(url, { headers });
-                        const body = await res.json();
-                        try {
-                            if (res.ok) {
-                                assert_jsonrpc_success_response(body, action.spec.output);
-                            }
-                            else {
-                                assert_jsonrpc_error_response(body);
-                            }
+                    const override = options.input_overrides?.get(action.spec.method);
+                    const params = override ?? generate_valid_body(action.spec.input) ?? undefined;
+                    const headers = pick_rpc_auth_headers(surface_method, fixture, authed_account, admin_account);
+                    const url = create_rpc_get_url(ep_spec.path, action.spec.method, params);
+                    const res = await fixture.transport(url, { headers });
+                    const body = await res.json();
+                    try {
+                        if (res.ok) {
+                            assert_jsonrpc_success_response(body, action.spec.output);
                         }
-                        catch (e) {
-                            throw new Error(`RPC round-trip GET failed for ${action.spec.method} (status ${res.status}): ${e.message}`);
+                        else {
+                            assert_jsonrpc_error_response(body);
                         }
                     }
+                    catch (e) {
+                        throw new Error(`RPC round-trip GET failed for ${action.spec.method} (status ${res.status}): ${e.message}`);
+                    }
                 }
-            });
+            }
         });
-    }
+    });
 };

package/dist/testing/schema_introspect.d.ts

@@ -0,0 +1,106 @@
+import './assert_dev_env.js';
+/**
+ * PostgreSQL schema introspection — produces a normalized, JSON-serializable
+ * snapshot of a database's structure for cross-impl parity checks.
+ *
+ * The snapshot covers:
+ *
+ * - `schema_version` rows (`namespace`, `name`, `sequence`) — captures
+ *   migration set state across impls
+ * - Tables with columns (data type, nullability, default, identity)
+ * - Indexes with canonical Postgres-rendered definitions
+ * - Constraints (CHECK, FOREIGN KEY, PRIMARY KEY, UNIQUE, EXCLUSION)
+ * - Sequences with data type — distinguishes `int4` (SERIAL) from `int8`
+ *   (BIGSERIAL)
+ *
+ * Designed for `pg_catalog` introspection — works against both PostgreSQL
+ * and PGlite. The snapshot is fully deterministic: every collection sorts by
+ * a stable key and excludes time-varying fields like `applied_at`.
+ *
+ * Paired with `schema_parity.ts` for comparison + assertion helpers.
+ *
+ * @module
+ */
+import type { Db } from '../db/db.js';
+/** Per-column structural metadata. */
+export interface ColumnSnapshot {
+    /** SQL standard type name from `information_schema.columns.data_type`. */
+    readonly data_type: string;
+    /** Postgres-native type name from `information_schema.columns.udt_name`. */
+    readonly udt_name: string;
+    /** `true` when the column accepts NULL. */
+    readonly is_nullable: boolean;
+    /** Default-value expression as Postgres reports it, or `null` if none. */
+    readonly column_default: string | null;
+    /** `true` when the column was declared GENERATED ... AS IDENTITY. */
+    readonly is_identity: boolean;
+}
+/** Per-table structural metadata. */
+export interface TableSnapshot {
+    /** Column metadata keyed by column name (sorted on serialization). */
+    readonly columns: Record<string, ColumnSnapshot>;
+    /** Index definitions as Postgres renders them via `pg_indexes.indexdef`. */
+    readonly indexes: ReadonlyArray<{
+        readonly name: string;
+        readonly definition: string;
+    }>;
+    /** Constraint definitions as Postgres renders them via `pg_get_constraintdef`. */
+    readonly constraints: ReadonlyArray<{
+        readonly name: string;
+        readonly type: string;
+        readonly definition: string;
+    }>;
+}
+/** Sequence metadata — `data_type` is `bigint` (BIGSERIAL) or `integer` (SERIAL). */
+export interface SequenceSnapshot {
+    readonly data_type: string;
+}
+/** One row in the `schema_version` migration tracker. */
+export interface SchemaVersionRow {
+    readonly namespace: string;
+    readonly name: string;
+    readonly sequence: number;
+}
+/**
+ * Normalized database schema snapshot for parity comparison.
+ *
+ * All fields are deterministically ordered on capture so structural equality
+ * via `JSON.stringify` or per-key comparison yields stable results.
+ */
+export interface SchemaSnapshot {
+    /** Migration tracker rows, sorted by `(namespace, sequence)`. */
+    readonly schema_version: ReadonlyArray<SchemaVersionRow>;
+    /** Tables keyed by name. */
+    readonly tables: Record<string, TableSnapshot>;
+    /** Sequences keyed by name. */
+    readonly sequences: Record<string, SequenceSnapshot>;
+}
+/** Filter options for `query_schema_snapshot`. */
+export interface QuerySchemaSnapshotOptions {
+    /**
+     * Schema name to introspect — defaults to `'public'`. Single-schema only;
+     * cross-schema introspection isn't a current need.
+     */
+    readonly schema?: string;
+    /**
+     * Tables to exclude from the snapshot. The `schema_version` table itself
+     * is always excluded (its content is captured separately).
+     */
+    readonly exclude_tables?: ReadonlyArray<string>;
+}
+/**
+ * Introspect a live database into a deterministic `SchemaSnapshot`.
+ *
+ * Reads `information_schema` and `pg_catalog` to capture tables, columns,
+ * indexes, constraints, sequences, and `schema_version` migration tracker
+ * rows. The `applied_at` timestamp is deliberately excluded — only the set
+ * of applied migrations matters for parity.
+ *
+ * The `schema_version` table itself never appears in the `tables` field;
+ * its structure is identical across consumers and would only add noise.
+ *
+ * @throws Error when the `schema_version` table is missing — callers must
+ *   ensure migrations have run before introspecting.
+ */
+export declare const query_schema_snapshot: (db: Db, options?: QuerySchemaSnapshotOptions) => Promise<SchemaSnapshot>;
+//# sourceMappingURL=schema_introspect.d.ts.map

package/dist/testing/schema_introspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_introspect.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/schema_introspect.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACjD,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACtF,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;QACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC5B,CAAC,CAAC;CACH;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACzD,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC/C,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACrD;AAED,kDAAkD;AAClD,MAAM,WAAW,0BAA0B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChD;AAyDD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GACjC,IAAI,EAAE,EACN,UAAS,0BAA+B,KACtC,OAAO,CAAC,cAAc,CA+GxB,CAAC"}

package/dist/testing/schema_introspect.js

@@ -0,0 +1,123 @@
+import './assert_dev_env.js';
+const sort_keys = (record) => {
+    const sorted = {};
+    for (const key of Object.keys(record).sort()) {
+        sorted[key] = record[key];
+    }
+    return sorted;
+};
+const contype_to_kind = (contype) => {
+    switch (contype) {
+        case 'p':
+            return 'PRIMARY KEY';
+        case 'f':
+            return 'FOREIGN KEY';
+        case 'u':
+            return 'UNIQUE';
+        case 'c':
+            return 'CHECK';
+        case 'x':
+            return 'EXCLUSION';
+        case 't':
+            return 'TRIGGER';
+        default:
+            return contype;
+    }
+};
+/**
+ * Introspect a live database into a deterministic `SchemaSnapshot`.
+ *
+ * Reads `information_schema` and `pg_catalog` to capture tables, columns,
+ * indexes, constraints, sequences, and `schema_version` migration tracker
+ * rows. The `applied_at` timestamp is deliberately excluded — only the set
+ * of applied migrations matters for parity.
+ *
+ * The `schema_version` table itself never appears in the `tables` field;
+ * its structure is identical across consumers and would only add noise.
+ *
+ * @throws Error when the `schema_version` table is missing — callers must
+ *   ensure migrations have run before introspecting.
+ */
+export const query_schema_snapshot = async (db, options = {}) => {
+    const schema = options.schema ?? 'public';
+    const exclude_tables = new Set(options.exclude_tables ?? []);
+    exclude_tables.add('schema_version');
+    // schema_version rows — the migration tracker. Exclude `applied_at`
+    // because timestamps differ across bootstraps even when the migration
+    // set is identical.
+    const schema_version_rows = await db.query(`SELECT namespace, name, sequence
+		 FROM schema_version
+		 ORDER BY namespace ASC, sequence ASC`);
+    // All tables in the target schema, minus the excludes.
+    const table_rows = await db.query(`SELECT table_name
+		 FROM information_schema.tables
+		 WHERE table_schema = $1 AND table_type = 'BASE TABLE'
+		 ORDER BY table_name ASC`, [schema]);
+    const table_names = table_rows.map((r) => r.table_name).filter((n) => !exclude_tables.has(n));
+    // Columns — batched in one query, grouped client-side. udt_name
+    // distinguishes int4 from int8 (SERIAL vs BIGSERIAL).
+    const column_rows = await db.query(`SELECT table_name, column_name, data_type, udt_name, is_nullable,
+		        column_default, is_identity
+		 FROM information_schema.columns
+		 WHERE table_schema = $1
+		 ORDER BY table_name ASC, ordinal_position ASC`, [schema]);
+    // Indexes — pg_indexes.indexdef gives the canonical CREATE INDEX statement
+    // as Postgres would re-emit it, which normalizes whitespace and case.
+    const index_rows = await db.query(`SELECT tablename, indexname, indexdef
+		 FROM pg_indexes
+		 WHERE schemaname = $1
+		 ORDER BY tablename ASC, indexname ASC`, [schema]);
+    // Constraints — pg_get_constraintdef produces a canonical text rendering.
+    const constraint_rows = await db.query(`SELECT c.conrelid::regclass::text AS table_name,
+		        c.conname,
+		        c.contype::text,
+		        pg_get_constraintdef(c.oid) AS definition
+		 FROM pg_constraint c
+		 JOIN pg_namespace n ON n.oid = c.connamespace
+		 WHERE n.nspname = $1
+		   AND c.conrelid != 0
+		 ORDER BY table_name ASC, conname ASC`, [schema]);
+    // Sequences — data_type distinguishes bigint (BIGSERIAL) from integer (SERIAL).
+    const sequence_rows = await db.query(`SELECT sequence_name, data_type
+		 FROM information_schema.sequences
+		 WHERE sequence_schema = $1
+		 ORDER BY sequence_name ASC`, [schema]);
+    const tables = {};
+    for (const name of table_names) {
+        const columns = {};
+        for (const row of column_rows) {
+            if (row.table_name !== name)
+                continue;
+            columns[row.column_name] = {
+                data_type: row.data_type,
+                udt_name: row.udt_name,
+                is_nullable: row.is_nullable === 'YES',
+                column_default: row.column_default,
+                is_identity: row.is_identity === 'YES',
+            };
+        }
+        const indexes = index_rows
+            .filter((r) => r.tablename === name)
+            .map((r) => ({ name: r.indexname, definition: r.indexdef }));
+        const constraints = constraint_rows
+            // `conrelid::regclass::text` returns either bare (`foo`) or schema-
+            // qualified (`public.foo`) depending on the connection's search_path,
+            // so accept both forms here.
+            .filter((r) => r.table_name === name || r.table_name === `${schema}.${name}`)
+            .map((r) => ({
+            name: r.conname,
+            type: contype_to_kind(r.contype),
+            definition: r.definition,
+        }));
+        tables[name] = { columns: sort_keys(columns), indexes, constraints };
+    }
+    const sequences = {};
+    for (const row of sequence_rows) {
+        sequences[row.sequence_name] = { data_type: row.data_type };
+    }
+    return {
+        schema_version: schema_version_rows,
+        tables: sort_keys(tables),
+        sequences: sort_keys(sequences),
+    };
+};

package/dist/testing/schema_parity.d.ts

@@ -0,0 +1,144 @@
+import './assert_dev_env.js';
+/**
+ * Cross-impl schema parity — structural diff + assertion over two
+ * `SchemaSnapshot`s captured via `query_schema_snapshot`.
+ *
+ * Two live impls (TS fuz_app vs Rust spine) are each other's parity
+ * reference. After both bootstrap, snapshot each, diff, fail loudly on
+ * drift. The diff entries name the specific divergence (column type,
+ * missing index, schema_version row absent on one side) so the error
+ * message points at the source.
+ *
+ * Consumer pattern (in zzz's integration runner or fuz_app's own
+ * cross-backend tests):
+ *
+ * ```ts
+ * const snapshot_a = await query_schema_snapshot(db_after_deno_bootstrap);
+ * const snapshot_b = await query_schema_snapshot(db_after_rust_bootstrap);
+ * assert_schema_snapshots_equal(snapshot_a, snapshot_b, {a: 'deno', b: 'rust'});
+ * ```
+ *
+ * Non-coverage — drift the gate does **not** detect:
+ *
+ * - enum types (`CREATE TYPE ... AS ENUM`)
+ * - regular triggers (`pg_trigger`); `CONSTRAINT TRIGGER` is captured via
+ *   pg_constraint, but standalone `CREATE TRIGGER` is not
+ * - views, materialized views, functions, procedures
+ * - table storage parameters (fillfactor, tablespace, autovacuum settings)
+ * - column physical order — the snapshot keys columns by name, so two
+ *   impls with the same columns in different declaration order compare
+ *   equal (functional parity is preserved; `SELECT *` ordering is not)
+ * - `COMMENT ON ...`
+ * - the `schema_version` table's own structure (only its rows are
+ *   captured)
+ * - permissions / `GRANT`s
+ *
+ * None of these are used by the current fuz_app auth schema. Extend
+ * `query_schema_snapshot` + `SchemaDiff` if a consumer's schema reaches
+ * for them; omitting them today keeps the diff surface focused on what
+ * fuz_app actually emits.
+ *
+ * @module
+ */
+import type { ColumnSnapshot, SchemaSnapshot, SchemaVersionRow } from './schema_introspect.js';
+/** Structured drift entry. `where` is the named source impl ('a' or 'b'). */
+export type SchemaDiff = {
+    readonly kind: 'schema_version_only_in';
+    readonly where: 'a' | 'b';
+    readonly row: SchemaVersionRow;
+} | {
+    readonly kind: 'schema_version_sequence_differs';
+    readonly namespace: string;
+    readonly name: string;
+    readonly a: number;
+    readonly b: number;
+} | {
+    readonly kind: 'table_only_in';
+    readonly where: 'a' | 'b';
+    readonly table: string;
+} | {
+    readonly kind: 'column_only_in';
+    readonly where: 'a' | 'b';
+    readonly table: string;
+    readonly column: string;
+} | {
+    readonly kind: 'column_field_differs';
+    readonly table: string;
+    readonly column: string;
+    readonly field: keyof ColumnSnapshot;
+    readonly a: unknown;
+    readonly b: unknown;
+} | {
+    readonly kind: 'index_only_in';
+    readonly where: 'a' | 'b';
+    readonly table: string;
+    readonly index: string;
+} | {
+    readonly kind: 'index_definition_differs';
+    readonly table: string;
+    readonly index: string;
+    readonly a: string;
+    readonly b: string;
+} | {
+    readonly kind: 'constraint_only_in';
+    readonly where: 'a' | 'b';
+    readonly table: string;
+    readonly constraint: string;
+} | {
+    readonly kind: 'constraint_differs';
+    readonly table: string;
+    readonly constraint: string;
+    readonly a: {
+        type: string;
+        definition: string;
+    };
+    readonly b: {
+        type: string;
+        definition: string;
+    };
+} | {
+    readonly kind: 'sequence_only_in';
+    readonly where: 'a' | 'b';
+    readonly sequence: string;
+} | {
+    readonly kind: 'sequence_data_type_differs';
+    readonly sequence: string;
+    readonly a: string;
+    readonly b: string;
+};
+/**
+ * Structural diff between two snapshots — empty array means parity holds.
+ *
+ * Order of diffs is deterministic: schema_version first, then tables in
+ * sorted order (with column/index/constraint sub-diffs grouped per table),
+ * then sequences. Consumers can rely on this for stable diff output.
+ */
+export declare const diff_schema_snapshots: (a: SchemaSnapshot, b: SchemaSnapshot) => Array<SchemaDiff>;
+/** Labels used in formatted output — defaults to `'a'` and `'b'`. */
+export interface SchemaDiffLabels {
+    readonly a?: string;
+    readonly b?: string;
+}
+/**
+ * Render a diff list as a human-readable multi-line string. Empty diffs
+ * produce an empty string.
+ */
+export declare const format_schema_diffs: (diffs: ReadonlyArray<SchemaDiff>, labels?: SchemaDiffLabels) => string;
+/**
+ * Throw if the two snapshots disagree. The error message names the impls
+ * (via `labels`) and lists every diff, so the failure is self-diagnosing.
+ *
+ * Consumers wire this after bootstrapping each impl against an isolated DB:
+ *
+ * ```ts
+ * await drop_recreate_db('zzz_test');
+ * await spawn_backend(deno_config);
+ * const snapshot_deno = await query_schema_snapshot(db, {});
+ * await drop_recreate_db('zzz_test');
+ * await spawn_backend(rust_config);
+ * const snapshot_rust = await query_schema_snapshot(db, {});
+ * assert_schema_snapshots_equal(snapshot_deno, snapshot_rust, {a: 'deno', b: 'rust'});
+ * ```
+ */
+export declare const assert_schema_snapshots_equal: (a: SchemaSnapshot, b: SchemaSnapshot, labels?: SchemaDiffLabels) => void;
+//# sourceMappingURL=schema_parity.d.ts.map

package/dist/testing/schema_parity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_parity.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/schema_parity.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EACX,cAAc,EACd,cAAc,EACd,gBAAgB,EAGhB,MAAM,wBAAwB,CAAC;AAEhC,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GACnB;IACA,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;CAC9B,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAC,GACnF;IACA,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACvB,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,cAAc,CAAC;IACrC,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;CACnB,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACtB,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC3B,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC;IAC/C,QAAQ,CAAC,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC;CAC9C,GACD;IAAC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,GACzF;IACA,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAAI,GAAG,cAAc,EAAE,GAAG,cAAc,KAAG,KAAK,CAAC,UAAU,CAoC5F,CAAC;AAuIF,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAC/B,OAAO,aAAa,CAAC,UAAU,CAAC,EAChC,SAAQ,gBAAqB,KAC3B,MA8DF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,6BAA6B,GACzC,GAAG,cAAc,EACjB,GAAG,cAAc,EACjB,SAAQ,gBAAqB,KAC3B,IAQF,CAAC"}