turbine-orm 0.29.0 → 0.31.0

package/dist/cli/mcp.js

@@ -3,8 +3,9 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import pg from 'pg';
 import { findMissingRelationIndexes } from '../index-advisor.js';
+import { addAutoManyToManyRelations, buildRelationsFromForeignKeys, isUnknownTsType, } from '../introspect.js';
 import { QueryInterface, quoteIdent } from '../query/index.js';
-import { isDateType, pgArrayType, pgTypeToTs, singularize, snakeToCamel, } from '../schema.js';
+import { isDateType, pgArrayType, pgTypeToTs, snakeToCamel, } from '../schema.js';
 import { listMigrationFiles } from './migrate.js';
 /**
  * Walk up from the running script to find turbine-orm's own package.json.
@@ -550,7 +551,7 @@ async function loadSchemaMetadata(client, options) {
         labels.push(row.enumlabel);
         enums[row.typname] = labels;
     }
-    const relationsByTable = buildRelations(tableNames, columnsByTable, pkByTable, fkResult.rows);
+    const relationsByTable = buildRelations(tableNames, columnsByTable, pkByTable, fkResult.rows, enums);
     const tables = {};
     for (const tableName of tableNames) {
         const columns = columnsByTable.get(tableName) ?? [];
@@ -589,7 +590,15 @@ async function loadSchemaMetadata(client, options) {
     }
     return { tables, enums };
 }
-function buildRelations(tableNames, columnsByTable, pkByTable, rows) {
+/**
+ * Group raw FK rows into constraint-level entries and delegate relation
+ * naming to the SHARED introspection builder (`buildRelationsFromForeignKeys`
+ * + `addAutoManyToManyRelations` in ../introspect.ts). MCP previously carried
+ * a stale copy of a retired naming scheme, so `turbine mcp` and `turbine
+ * generate` derived DIFFERENT relation names from the same database (N-3).
+ * Exported for the parity unit test.
+ */
+export function buildRelations(tableNames, columnsByTable, pkByTable, rows, enums = {}) {
     const tableSet = new Set(tableNames);
     const groups = new Map();
     for (const row of rows) {
@@ -607,95 +616,18 @@ function buildRelations(tableNames, columnsByTable, pkByTable, rows) {
         groups.set(row.constraint_name, group);
     }
     const foreignKeys = [...groups.values()];
-    const fkCounts = new Map();
-    for (const fk of foreignKeys) {
-        const key = `${fk.sourceTable}→${fk.targetTable}`;
-        fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
-    }
-    const relations = new Map();
-    for (const fk of foreignKeys) {
-        const pairKey = `${fk.sourceTable}→${fk.targetTable}`;
-        const needsDisambiguation = (fkCounts.get(pairKey) ?? 0) > 1;
-        const foreignKey = oneOrMany(fk.sourceColumns);
-        const referenceKey = oneOrMany(fk.targetColumns);
-        const belongsToName = needsDisambiguation
-            ? fk.sourceColumns.length === 1
-                ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
-                : snakeToCamel(fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, ''))
-            : singularize(snakeToCamel(fk.targetTable));
-        const hasManyName = needsDisambiguation
-            ? fk.sourceColumns.length === 1
-                ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-                : snakeToCamel(`${fk.sourceTable}_by_${fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, '')}`)
-            : snakeToCamel(fk.sourceTable);
-        const sourceRels = relations.get(fk.sourceTable) ?? {};
-        sourceRels[belongsToName] = {
-            type: 'belongsTo',
-            name: belongsToName,
-            from: fk.sourceTable,
-            to: fk.targetTable,
-            foreignKey,
-            referenceKey,
-        };
-        relations.set(fk.sourceTable, sourceRels);
-        const targetRels = relations.get(fk.targetTable) ?? {};
-        targetRels[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
-            from: fk.targetTable,
-            to: fk.sourceTable,
-            foreignKey,
-            referenceKey,
-        };
-        relations.set(fk.targetTable, targetRels);
-    }
-    addManyToManyRelations(tableNames, columnsByTable, pkByTable, foreignKeys, relations);
+    const columnFieldsByTable = new Map();
+    const unknownTypedFieldsByTable = new Map();
+    for (const [tbl, cols] of columnsByTable) {
+        columnFieldsByTable.set(tbl, new Set(cols.map((c) => c.field)));
+        // Enum-typed columns also report tsType 'unknown', but the generated type
+        // layer gives them a concrete union — only json/jsonb qualify as shadows.
+        unknownTypedFieldsByTable.set(tbl, new Set(cols.filter((c) => isUnknownTsType(c.tsType) && !Object.hasOwn(enums, c.pgType)).map((c) => c.field)));
+    }
+    const relations = buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, undefined, unknownTypedFieldsByTable);
+    addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, new Map(Array.from(columnsByTable, ([tbl, cols]) => [tbl, cols.map((c) => c.name)])), relations, columnFieldsByTable, unknownTypedFieldsByTable);
     return relations;
 }
-function addManyToManyRelations(tableNames, columnsByTable, pkByTable, foreignKeys, relations) {
-    for (const tableName of tableNames) {
-        const pk = pkByTable.get(tableName) ?? [];
-        if (pk.length !== 2)
-            continue;
-        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-        if (tableFks.length !== 2 || tableFks.some((fk) => fk.sourceColumns.length !== 1))
-            continue;
-        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-        const pkSet = new Set(pk);
-        if (!fkCols.every((column) => pkSet.has(column)) || new Set(fkCols).size !== 2)
-            continue;
-        const [fkA, fkB] = tableFks;
-        if (fkA.targetTable === fkB.targetTable)
-            continue;
-        const junctionColumns = (columnsByTable.get(tableName) ?? []).map((column) => column.name);
-        if (junctionColumns.length !== 2)
-            continue;
-        addManyToManyDirection(relations, tableName, fkA, fkB);
-        addManyToManyDirection(relations, tableName, fkB, fkA);
-    }
-}
-function addManyToManyDirection(relations, junctionTable, self, other) {
-    const sourceTable = self.targetTable;
-    const targetTable = other.targetTable;
-    const relName = snakeToCamel(targetTable);
-    const tableRelations = relations.get(sourceTable) ?? {};
-    if (tableRelations[relName])
-        return;
-    tableRelations[relName] = {
-        type: 'manyToMany',
-        name: relName,
-        from: sourceTable,
-        to: targetTable,
-        referenceKey: oneOrMany(self.targetColumns),
-        foreignKey: oneOrMany(self.targetColumns),
-        through: {
-            table: junctionTable,
-            sourceKey: self.sourceColumns[0],
-            targetKey: other.sourceColumns[0],
-        },
-    };
-    relations.set(sourceTable, tableRelations);
-}
 async function estimateRows(client, schema) {
     const result = await client.query(`SELECT c.relname, c.reltuples::bigint::text AS reltuples
      FROM pg_class c
@@ -723,9 +655,6 @@ function extractIndexColumns(indexdef) {
         .replace(/ (ASC|DESC)$/i, '')
         .replace(/^"|"$/g, ''));
 }
-function oneOrMany(columns) {
-    return columns.length === 1 ? columns[0] : columns;
-}
 function optionalLimit(value) {
     if (value === undefined)
         return 50;

package/dist/client.d.ts

@@ -68,6 +68,19 @@ export interface PgCompatPoolClient {
      * sequential.
      */
     readonly supportsPipelining?: boolean;
+    /**
+     * Optional engine seam: scope a transaction's user callback to its own
+     * async subtree. When present, `TurbineClient.transaction` / `$transaction`
+     * invoke the callback as `wrapTransactionCallback(() => fn(tx))` instead of
+     * `fn(tx)` directly. Single-writer engines (PowDB) implement it with
+     * `AsyncLocalStorage.run()` to plant their re-entrancy marker so that it
+     * exists ONLY inside the callback's async subtree: a transaction opened
+     * from inside the callback is detected as re-entrant (typed E017), while
+     * the CALLER's context stays unmarked, so same-tick sibling transactions
+     * queue FIFO instead of being falsely flagged. Absent on pg and every other
+     * engine, in which case the callback runs unwrapped (zero behavior change).
+     */
+    wrapTransactionCallback?<R>(fn: () => Promise<R>): Promise<R>;
 }
 /**
  * Minimal pg-compatible pool. Pass any driver that satisfies this interface
@@ -149,8 +162,12 @@ export interface TurbineConfig {
     logging?: boolean;
     /** Default LIMIT applied to findMany() when no limit is specified (opt-in, default: undefined) */
     defaultLimit?: number;
-    /** Log a warning when findMany() is called without a limit (default: false) */
-    warnOnUnlimited?: boolean;
+    /**
+     * Log a warning when findMany() is called without a limit (default: false).
+     * Pass a per-table map (`{ users: false }`) to override the default for
+     * specific tables; per-call `warnOnUnlimited` on findMany args wins over both.
+     */
+    warnOnUnlimited?: boolean | Record<string, boolean>;
     /**
      * Interpret Postgres `timestamp` (without time zone) values as UTC — both
      * at the driver level (OID 1114 type parser, registered only when Turbine

package/dist/client.js

@@ -763,14 +763,36 @@ export class TurbineClient {
      */
     async transaction(fn) {
         const client = await this.pool.connect();
+        /**
+         * Only true once BEGIN has actually succeeded. If BEGIN itself throws
+         * (e.g. a single-writer engine's transaction gate times out or rejects a
+         * re-entrant begin), issuing a "best-effort" ROLLBACK would be a stray
+         * statement from a context that never opened a transaction — on a driver
+         * with one shared engine handle (PowDB embedded) it would roll back a
+         * DIFFERENT caller's open transaction.
+         */
+        let began = false;
         try {
             await client.query(this.dialect.beginStatement());
-            const result = await fn(client);
+            began = true;
+            // Engine seam: single-writer engines scope their transaction re-entrancy
+            // marker to the callback's async subtree (see
+            // PgCompatPoolClient.wrapTransactionCallback). Absent everywhere else.
+            const wrap = client.wrapTransactionCallback;
+            // `.call` erases the generic, so the callback's Promise<T> is re-asserted.
+            const result = wrap ? (await wrap.call(client, () => fn(client))) : await fn(client);
             await client.query(this.dialect.commitStatement());
             return result;
         }
         catch (err) {
-            await client.query(this.dialect.rollbackStatement());
+            if (began) {
+                try {
+                    await client.query(this.dialect.rollbackStatement());
+                }
+                catch {
+                    // Best-effort rollback — the connection may have died mid-query.
+                }
+            }
             throw err;
         }
         finally {
@@ -804,11 +826,21 @@ export class TurbineClient {
             }
         };
         let timedOut = false;
+        /**
+         * Only true once BEGIN has actually succeeded. If BEGIN itself throws —
+         * e.g. a single-writer engine's transaction gate times out in its FIFO
+         * queue or rejects a re-entrant begin (PowDB, E002/E017) — this context
+         * never opened a transaction, so the catch below must NOT issue its
+         * best-effort ROLLBACK: on a driver with one shared engine handle that
+         * stray ROLLBACK would tear down a DIFFERENT caller's open transaction.
+         */
+        let began = false;
         try {
             // BEGIN with optional isolation level — the dialect owns the keyword and
             // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
             const isolationSql = options?.isolationLevel ? ISOLATION_LEVELS[options.isolationLevel] : undefined;
             await client.query(this.dialect.beginStatement(isolationSql));
+            began = true;
             // Apply transaction-local session context (RLS / multi-tenant GUCs).
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
             // user fn. Any error here propagates to the catch below and rolls back
@@ -841,6 +873,12 @@ export class TurbineClient {
                 }
             }
             let result;
+            // Engine seam: when the checked-out connection exposes
+            // wrapTransactionCallback (single-writer engines such as PowDB), run the user
+            // callback through it so the engine can scope its re-entrancy marker to
+            // the callback's async subtree. All other drivers: plain fn(tx).
+            const wrap = client.wrapTransactionCallback;
+            const runCallback = () => (wrap ? wrap.call(client, () => fn(tx)) : fn(tx));
             if (timeout) {
                 // Race between the function and a timeout. If the timeout fires we
                 // need to actually abort the in-flight query — otherwise the backend
@@ -862,14 +900,14 @@ export class TurbineClient {
                     }, timeout);
                 });
                 try {
-                    result = await Promise.race([fn(tx), timeoutPromise]);
+                    result = await Promise.race([runCallback(), timeoutPromise]);
                 }
                 finally {
                     clearTimeout(timer);
                 }
             }
             else {
-                result = await fn(tx);
+                result = await runCallback();
             }
             await client.query(this.dialect.commitStatement());
             if (this.logging) {
@@ -881,8 +919,11 @@ export class TurbineClient {
             // If the timeout fired we already destroyed the connection — issuing a
             // ROLLBACK on a released client would throw "Client has already been
             // released". Skip the rollback in that case (the backend rolled back
-            // when its socket was closed).
-            if (!timedOut && !released) {
+            // when its socket was closed). Likewise skip it when BEGIN never
+            // succeeded (`began` false) — there is no transaction to roll back and
+            // the stray statement could hit another caller's transaction on a
+            // shared-handle engine.
+            if (began && !timedOut && !released) {
                 try {
                     await client.query(this.dialect.rollbackStatement());
                 }

package/dist/generate.d.ts

@@ -23,6 +23,18 @@ export interface GenerateOptions {
      * library's dependency graph. Default: `false`.
      */
     zod?: boolean;
+    /**
+     * Omit the `Generated at: <ISO timestamp>` line from every generated file
+     * header (T-8b — reproducible codegen). With this set, byte-identical
+     * schemas regenerate to byte-identical output, so regens produce empty
+     * diffs. Default: `false` (timestamp included, unchanged behavior).
+     */
+    noTimestamp?: boolean;
+}
+/** Per-file generator options (subset of {@link GenerateOptions} the emitters need). */
+export interface GenerateFileOptions {
+    /** Omit the `Generated at:` header line for reproducible output. */
+    noTimestamp?: boolean;
 }
 export declare function generate(options: GenerateOptions): {
     outDir: string;
@@ -33,7 +45,7 @@ export declare function generate(options: GenerateOptions): {
  * and *Relations brand-field interfaces). Exported so tests can pin the
  * generator output without writing files to disk.
  */
-export declare function generateTypes(schema: SchemaMetadata): string;
+export declare function generateTypes(schema: SchemaMetadata, options?: GenerateFileOptions): string;
 /**
  * Generate the contents of `zod.ts`. Emits, per table, `XSchema` (the full
  * row), `XCreateSchema` (PK/defaulted/nullable columns optional, STORED
@@ -41,6 +53,6 @@ export declare function generateTypes(schema: SchemaMetadata): string;
  * columns omitted, every remaining column optional). Exported so tests can pin
  * the output without writing files.
  */
-export declare function generateZod(schema: SchemaMetadata): string;
-export declare function generateMetadata(schema: SchemaMetadata): string;
-export declare function generateIndex(schema: SchemaMetadata): string;
+export declare function generateZod(schema: SchemaMetadata, options?: GenerateFileOptions): string;
+export declare function generateMetadata(schema: SchemaMetadata, options?: GenerateFileOptions): string;
+export declare function generateIndex(schema: SchemaMetadata, options?: GenerateFileOptions): string;

package/dist/generate.js

@@ -50,21 +50,22 @@ export function generate(options) {
     }
     mkdirSync(outDir, { recursive: true });
     const files = [];
+    const fileOptions = { noTimestamp: options.noTimestamp };
     // Generate types.ts
-    const typesContent = generateTypes(options.schema);
+    const typesContent = generateTypes(options.schema, fileOptions);
     writeFileSync(join(outDir, 'types.ts'), typesContent, 'utf-8');
     files.push('types.ts');
     // Generate metadata.ts
-    const metadataContent = generateMetadata(options.schema);
+    const metadataContent = generateMetadata(options.schema, fileOptions);
     writeFileSync(join(outDir, 'metadata.ts'), metadataContent, 'utf-8');
     files.push('metadata.ts');
     // Generate index.ts (configured client)
-    const indexContent = generateIndex(options.schema);
+    const indexContent = generateIndex(options.schema, fileOptions);
     writeFileSync(join(outDir, 'index.ts'), indexContent, 'utf-8');
     files.push('index.ts');
     // Generate zod.ts (optional — --zod flag)
     if (options.zod) {
-        const zodContent = generateZod(options.schema);
+        const zodContent = generateZod(options.schema, fileOptions);
         writeFileSync(join(outDir, 'zod.ts'), zodContent, 'utf-8');
         files.push('zod.ts');
     }
@@ -73,24 +74,51 @@ export function generate(options) {
 // ---------------------------------------------------------------------------
 // types.ts generator
 // ---------------------------------------------------------------------------
-function generatedFileHeader() {
+function generatedFileHeader(options) {
+    // `noTimestamp` omits the volatile line entirely (T-8b) so regenerating an
+    // unchanged schema produces byte-identical files.
     return [
         '/**',
         ' * Auto-generated by turbine-orm — DO NOT EDIT',
         ' *',
-        ` * Generated at: ${new Date().toISOString()}`,
+        ...(options?.noTimestamp ? [] : [` * Generated at: ${new Date().toISOString()}`]),
         ' * @see https://turbineorm.dev',
         ' */',
         '',
     ];
 }
+/**
+ * The relations of a table that are safe to surface in the generated TYPE
+ * layer. A relation whose name equals a scalar column field would shadow the
+ * column: `interface XWithY extends X` becomes TS2430, the `XCreate & { y?: … }`
+ * intersection collapses (TS2322), and neither the column nor the relation is
+ * targetable. Introspection no longer produces such names (they are
+ * disambiguated at the source), but hand-written or legacy metadata may —
+ * skip those relations here with a warning instead of emitting broken types.
+ * The runtime metadata (metadata.ts) still carries every relation.
+ */
+function typeSafeRelations(table, warn = true) {
+    const columnFields = new Set(table.columns.map((c) => c.field));
+    const usable = [];
+    for (const [relName, rel] of Object.entries(table.relations)) {
+        if (columnFields.has(relName)) {
+            if (warn) {
+                console.warn(`[turbine] Relation "${relName}" on table "${table.name}" shadows a column field of the same name — ` +
+                    `omitting it from the generated types. Rename the relation (or the column) to expose it.`);
+            }
+            continue;
+        }
+        usable.push([relName, rel]);
+    }
+    return usable;
+}
 /**
  * Generate the contents of `types.ts` (entity interfaces, *Create / *Update,
  * and *Relations brand-field interfaces). Exported so tests can pin the
  * generator output without writing files to disk.
  */
-export function generateTypes(schema) {
-    const lines = [...generatedFileHeader()];
+export function generateTypes(schema, options) {
+    const lines = [...generatedFileHeader(options)];
     // We import UpdateOperatorInput so generated *Update types can express
     // atomic increment / decrement / multiply / divide / set operators on
     // numeric columns (TASK-3.4).
@@ -106,9 +134,15 @@ export function generateTypes(schema) {
     // `${TargetType}Relations` (for deep inference) or `{}` (the no-relations
     // default) into each `RelationDescriptor`. Built once up-front because
     // relations can point at tables we haven't iterated to yet.
+    // Relations that can be surfaced in the type layer, computed once per table
+    // (relations that would shadow a scalar column field are excluded + warned).
+    const safeRelationsByTable = new Map();
+    for (const t of Object.values(schema.tables)) {
+        safeRelationsByTable.set(t.name, typeSafeRelations(t));
+    }
     const tablesWithRelations = new Set();
     for (const t of Object.values(schema.tables)) {
-        if (Object.keys(t.relations).length > 0)
+        if ((safeRelationsByTable.get(t.name) ?? []).length > 0)
             tablesWithRelations.add(t.name);
     }
     // Generate enum types
@@ -173,11 +207,12 @@ export function generateTypes(schema) {
         // any depth — `RelationRelations<R[K]>` reads the third type parameter
         // and threads it into the next recursion step. If the target table has
         // no relations of its own, the descriptor uses `{}` (the default).
-        const hasRelations = Object.keys(table.relations).length > 0;
+        const safeRelations = safeRelationsByTable.get(table.name) ?? [];
+        const hasRelations = safeRelations.length > 0;
         if (hasRelations) {
             lines.push(`/** Available relations for the \`${table.name}\` table */`);
             lines.push(`export interface ${typeName}Relations {`);
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 // manyToMany is a collection too → 'many' cardinality (same as hasMany).
                 const cardinality = rel.type === 'hasMany' || rel.type === 'manyToMany' ? "'many'" : "'one'";
@@ -187,7 +222,7 @@ export function generateTypes(schema) {
             lines.push('}');
             lines.push('');
             // --- Legacy per-relation interfaces (kept for backward compatibility) ---
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 if (rel.type === 'hasMany' || rel.type === 'manyToMany') {
                     lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
@@ -211,7 +246,8 @@ export function generateTypes(schema) {
     // ---------------------------------------------------------------------------
     for (const table of Object.values(schema.tables)) {
         const typeName = entityName(table.name);
-        const hasRels = Object.keys(table.relations).length > 0;
+        const safeRelations = safeRelationsByTable.get(table.name) ?? [];
+        const hasRels = safeRelations.length > 0;
         // WhereUnique — union of unique constraint shapes, deduplicating PK
         const seen = new Set();
         const uniqueSets = [];
@@ -243,14 +279,14 @@ export function generateTypes(schema) {
         // CreateInput / UpdateInput — extends base type with optional relation fields
         if (hasRels) {
             lines.push(`export type ${typeName}CreateInput = ${typeName}Create & {`);
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 lines.push(`  ${relName}?: ${targetType}NestedCreateInput;`);
             }
             lines.push('};');
             lines.push('');
             lines.push(`export type ${typeName}UpdateInput = ${typeName}Update & {`);
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 if (rel.type === 'hasMany') {
                     lines.push(`  ${relName}?: ${targetType}NestedUpdateInput;`);
@@ -266,7 +302,7 @@ export function generateTypes(schema) {
     // Emit NestedCreateInput, NestedUpdateInput, ConnectOrCreate for every table
     for (const table of Object.values(schema.tables)) {
         const typeName = entityName(table.name);
-        const hasRels = Object.keys(table.relations).length > 0;
+        const hasRels = (safeRelationsByTable.get(table.name) ?? []).length > 0;
         // NestedCreateInput uses *CreateInput (which includes relation fields) when
         // the table has relations, otherwise falls back to the plain *Create type.
         const createRefType = hasRels ? `${typeName}CreateInput` : `${typeName}Create`;
@@ -351,8 +387,8 @@ function zodBaseType(col, enums) {
  * columns omitted, every remaining column optional). Exported so tests can pin
  * the output without writing files.
  */
-export function generateZod(schema) {
-    const lines = [...generatedFileHeader()];
+export function generateZod(schema, options) {
+    const lines = [...generatedFileHeader(options)];
     // `zod` is a USER dependency — this generated file imports it, but the Turbine
     // library runtime never does, so Zod stays out of the package's dep graph.
     lines.push("import { z } from 'zod';");
@@ -409,9 +445,9 @@ export function generateZod(schema) {
 // ---------------------------------------------------------------------------
 // metadata.ts generator
 // ---------------------------------------------------------------------------
-export function generateMetadata(schema) {
+export function generateMetadata(schema, options) {
     const lines = [
-        ...generatedFileHeader(),
+        ...generatedFileHeader(options),
         "import type { SchemaMetadata } from 'turbine-orm';",
         '',
         'export const SCHEMA: SchemaMetadata = {',
@@ -511,10 +547,15 @@ export function generateMetadata(schema) {
 // ---------------------------------------------------------------------------
 // index.ts generator (configured client with typed table accessors)
 // ---------------------------------------------------------------------------
-export function generateIndex(schema) {
+export function generateIndex(schema, options) {
     const tableEntries = Object.values(schema.tables);
+    // Must mirror generateTypes: `XRelations` only exists in types.ts when the
+    // table has at least one type-safe (non-column-shadowing) relation.
+    const hasSafeRelations = new Map();
+    for (const t of tableEntries)
+        hasSafeRelations.set(t.name, typeSafeRelations(t, false).length > 0);
     const lines = [
-        ...generatedFileHeader(),
+        ...generatedFileHeader(options),
         "import { TurbineClient as BaseTurbineClient, TransactionClient as BaseTransactionClient, QueryInterface } from 'turbine-orm';",
         "import type { TurbineConfig, TransactionOptions, DeferredQuery, PipelineResults } from 'turbine-orm';",
         "import { SCHEMA } from './metadata.js';",
@@ -523,7 +564,7 @@ export function generateIndex(schema) {
     const typeImports = [];
     for (const t of tableEntries) {
         typeImports.push(entityName(t.name));
-        if (Object.keys(t.relations).length > 0) {
+        if (hasSafeRelations.get(t.name)) {
             typeImports.push(`${entityName(t.name)}Relations`);
         }
     }
@@ -545,7 +586,7 @@ export function generateIndex(schema) {
     for (const table of tableEntries) {
         const typeName = entityName(table.name);
         const accessor = snakeToCamelStr(table.name);
-        const hasRelations = Object.keys(table.relations).length > 0;
+        const hasRelations = hasSafeRelations.get(table.name) === true;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
         lines.push(`  /** Query interface for the \`${table.name}\` table (transaction-scoped) */`);
         lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
@@ -587,7 +628,7 @@ export function generateIndex(schema) {
     for (const table of tableEntries) {
         const typeName = entityName(table.name);
         const accessor = snakeToCamelStr(table.name);
-        const hasRelations = Object.keys(table.relations).length > 0;
+        const hasRelations = hasSafeRelations.get(table.name) === true;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
         lines.push(`  /** Query interface for the \`${table.name}\` table */`);
         lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
@@ -670,6 +711,11 @@ function serializeColumn(col) {
         `arrayType: '${escSQ(col.arrayType ?? col.pgArrayType)}'`,
         `pgArrayType: '${escSQ(col.pgArrayType)}'`,
     ];
+    // Cross-schema type marker — introspection records it only for types living
+    // outside the introspected schema; it must survive codegen or the runtime
+    // enum-cast guard in query/builder.ts loses the signal (N-5).
+    if (col.pgTypeSchema !== undefined)
+        parts.push(`pgTypeSchema: '${escSQ(col.pgTypeSchema)}'`);
     // Emit isGenerated only when set (server-generated serial/identity), so the
     // output stays byte-identical for the common client-default columns.
     if (col.isGenerated)

package/dist/index.d.ts

@@ -43,11 +43,12 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByArgs, type HavingClause, type JsonFilter, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, defineSchema, type ManyToManyDef, type ReferenceDef, type SchemaDef, type TableDef, table, } from './schema-builder.js';
+export { schemaDefToMetadata } from './schema-metadata.js';
 export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type DefinedSeed, defineSeed, type SeedFunction } from './seed.js';
 export { type TurbineHttpOptions, turbineHttp } from './serverless.js';

package/dist/index.js

@@ -56,6 +56,8 @@ export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs,
 export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, 
 // Legacy compat (deprecated — use object format with defineSchema)
 table, } from './schema-builder.js';
+// Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB
+export { schemaDefToMetadata } from './schema-metadata.js';
 // Schema SQL — generate DDL, diff, and push
 export { schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 // Seed helper