@opensaas/stack-cli 0.20.1 → 0.22.0

package/dist/generator/prisma.js

@@ -1,16 +1,45 @@
 import * as fs from 'fs';
 import * as path from 'path';
 /**
- * Map OpenSaas field types to Prisma field types
+ * Decide which auto-timestamp columns the generator should inject into a list's model.
+ *
+ * Auto-timestamps are OFF by default (matching Keystone 6, which never adds them
+ * automatically — see ADR-0004). They are enabled globally via `db: { timestamps: true }`
+ * and can be overridden per-list via the list's `db.timestamps` option (which takes
+ * precedence over the global setting).
+ *
+ * When timestamps resolve to enabled, the auto column is skipped for any timestamp field
+ * the list already declares itself (`createdAt`/`updatedAt`), so Prisma never sees a
+ * duplicate field (`P1012`).
+ *
+ * @returns flags indicating whether to emit each auto column.
  */
-function mapFieldTypeToPrisma(fieldName, field, provider, listName) {
-    // Relationships are handled separately
-    if (field.type === 'relationship') {
-        return null;
+export function resolveListTimestamps(
+// ListConfig is generic over per-list TypeInfo; the generator only reads `db`/`fields`,
+// which are invariant across that generic, so the default `TypeInfo` is sufficient.
+listConfig, dbConfig) {
+    // Per-list override wins over the global setting; otherwise fall back to the global
+    // default (off when unset).
+    const enabled = listConfig.db?.timestamps ?? dbConfig.timestamps ?? false;
+    if (!enabled) {
+        return { createdAt: false, updatedAt: false };
     }
+    // Skip the auto column for any timestamp the list already declares to avoid a
+    // duplicate-field error (Prisma P1012).
+    const declaresCreatedAt = Object.prototype.hasOwnProperty.call(listConfig.fields, 'createdAt');
+    const declaresUpdatedAt = Object.prototype.hasOwnProperty.call(listConfig.fields, 'updatedAt');
+    return {
+        createdAt: !declaresCreatedAt,
+        updatedAt: !declaresUpdatedAt,
+    };
+}
+/**
+ * Map OpenSaas field types to Prisma field types
+ */
+function mapFieldTypeToPrisma(fieldName, field, provider, listName, keystoneCompat) {
     // Use field's own Prisma type generator if available
     if (field.getPrismaType) {
-        const result = field.getPrismaType(fieldName, provider, listName);
+        const result = field.getPrismaType(fieldName, provider, listName, keystoneCompat);
         return result.type;
     }
     // Fallback for fields without generator methods
@@ -19,311 +48,112 @@ function mapFieldTypeToPrisma(fieldName, field, provider, listName) {
 /**
  * Get field modifiers (?, @default, @unique, etc.)
  */
-function getFieldModifiers(fieldName, field, provider, listName) {
-    // Handle relationships separately
-    if (field.type === 'relationship') {
-        const relField = field;
-        if (relField.many) {
-            return '[]';
-        }
-        else {
-            return '?';
-        }
-    }
+function getFieldModifiers(fieldName, field, provider, listName, keystoneCompat) {
     // Use field's own Prisma type generator if available
     if (field.getPrismaType) {
-        const result = field.getPrismaType(fieldName, provider, listName);
+        const result = field.getPrismaType(fieldName, provider, listName, keystoneCompat);
         return result.modifiers || '';
     }
     // Fallback for fields without generator methods
     return '';
 }
-/**
- * Parse relationship ref to get target list and optional field
- * Supports both 'ListName.fieldName' and 'ListName' formats
- */
-function parseRelationshipRef(ref) {
-    const parts = ref.split('.');
-    if (parts.length === 1) {
-        // List-only ref (e.g., 'Term')
-        const list = parts[0];
-        if (!list) {
-            throw new Error(`Invalid relationship ref: ${ref}`);
-        }
-        return { list };
-    }
-    else if (parts.length === 2) {
-        // List and field ref (e.g., 'User.posts')
-        const [list, field] = parts;
-        if (!list || !field) {
-            throw new Error(`Invalid relationship ref: ${ref}`);
-        }
-        return { list, field };
-    }
-    else {
-        throw new Error(`Invalid relationship ref: ${ref}`);
-    }
-}
-/**
- * Check if a relationship is one-to-one (bidirectional with both sides having many: false)
- */
-function isOneToOneRelationship(listName, fieldName, field, config) {
-    // Must be bidirectional (has target field)
-    const { list: targetList, field: targetField } = parseRelationshipRef(field.ref);
-    if (!targetField) {
-        return false;
-    }
-    // This side must be single (many: false or undefined)
-    if (field.many) {
-        return false;
-    }
-    // Check if target list exists
-    const targetListConfig = config.lists[targetList];
-    if (!targetListConfig) {
-        throw new Error(`Referenced list "${targetList}" not found in config`);
-    }
-    // Check if target field exists and is a relationship
-    const targetFieldConfig = targetListConfig.fields[targetField];
-    if (!targetFieldConfig) {
-        throw new Error(`Referenced field "${targetList}.${targetField}" not found. If you want a one-sided relationship, use ref: "${targetList}" instead of ref: "${targetList}.${targetField}"`);
-    }
-    if (targetFieldConfig.type !== 'relationship') {
-        throw new Error(`Referenced field "${targetList}.${targetField}" is not a relationship field`);
-    }
-    const targetRelField = targetFieldConfig;
-    return !targetRelField.many;
-}
-/**
- * Determine if this side of a relationship should have the foreign key
- * For one-to-one relationships, only one side should have the foreign key
- */
-function shouldHaveForeignKey(listName, fieldName, field, config) {
-    // List-only refs always create foreign keys
-    const { list: targetList, field: targetField } = parseRelationshipRef(field.ref);
-    if (!targetField) {
-        return true;
-    }
-    // Many-side never has foreign key (it's on the one-side)
-    if (field.many) {
-        return false;
-    }
-    // Check if this is a one-to-one relationship
-    const isOneToOne = isOneToOneRelationship(listName, fieldName, field, config);
-    if (!isOneToOne) {
-        // One-to-many or many-to-one: the single side has the foreign key
-        return true;
-    }
-    // One-to-one relationship: check db.foreignKey configuration
-    const targetListConfig = config.lists[targetList];
-    const targetFieldConfig = targetListConfig.fields[targetField];
-    const thisSideExplicit = field.db?.foreignKey;
-    const otherSideExplicit = targetFieldConfig.db?.foreignKey;
-    // Validate: both sides cannot be true
-    if (thisSideExplicit === true && otherSideExplicit === true) {
-        throw new Error(`Invalid one-to-one relationship: both "${listName}.${fieldName}" and "${targetList}.${targetField}" have db.foreignKey set to true. Only one side can store the foreign key.`);
-    }
-    // If this side explicitly wants the foreign key, use it
-    if (thisSideExplicit === true) {
-        return true;
-    }
-    // If other side explicitly wants it, don't use it on this side
-    if (otherSideExplicit === true) {
-        return false;
-    }
-    // Default: use alphabetical ordering to ensure consistency
-    // The "smaller" list name (alphabetically) gets the foreign key
-    const comparison = listName.localeCompare(targetList);
-    if (comparison !== 0) {
-        return comparison < 0;
-    }
-    // Same list (self-referential): use field name ordering
-    return fieldName.localeCompare(targetField) < 0;
-}
-/**
- * Check if a relationship field is many-to-many
- */
-function isManyToManyRelationship(listName, fieldName, field, config) {
-    // Must be a many relationship
-    if (!field.many) {
-        return { isManyToMany: false, targetList: '', targetField: undefined };
-    }
-    const { list: targetList, field: targetField } = parseRelationshipRef(field.ref);
-    // List-only refs with many: true are many-to-many (implicit single on other side)
-    if (!targetField) {
-        return { isManyToMany: true, targetList, targetField: undefined };
-    }
-    // Check if target field exists and is also many
-    const targetListConfig = config.lists[targetList];
-    if (!targetListConfig) {
-        // Target list doesn't exist - not a valid many-to-many
-        // (error will be thrown by existing validation code)
-        return { isManyToMany: false, targetList, targetField };
-    }
-    const targetFieldConfig = targetListConfig.fields[targetField];
-    if (!targetFieldConfig) {
-        // Target field doesn't exist - not a valid many-to-many
-        // (error will be thrown by existing validation code if needed)
-        return { isManyToMany: false, targetList, targetField };
-    }
-    if (targetFieldConfig.type !== 'relationship') {
-        // Target field is not a relationship - not a valid many-to-many
-        return { isManyToMany: false, targetList, targetField };
-    }
-    const targetRelField = targetFieldConfig;
-    // Both sides must have many: true for many-to-many
-    return { isManyToMany: !!targetRelField.many, targetList, targetField };
-}
 /**
  * Generate Prisma schema from OpenSaas config
+ *
+ * @param prismaClientOutput - Module specifier for the patched Prisma client's
+ *   `generator { output }`, relative to the schema file's directory. Defaults to
+ *   the legacy `../<opensaasPath>/prisma-client` so existing projects are
+ *   unaffected; the output-path resolver supplies a recomputed value when the
+ *   schema or `.opensaas` dir is relocated via the `output` config block.
  */
-export function generatePrismaSchema(config) {
+export function generatePrismaSchema(config, prismaClientOutput) {
     const lines = [];
     const opensaasPath = config.opensaasPath || '.opensaas';
-    const joinTableNaming = config.db.joinTableNaming || 'prisma';
+    const clientOutput = prismaClientOutput ?? `../${opensaasPath}/prisma-client`;
+    // Keystone-compat mode: when on, non-null text without an explicit default
+    // gets Keystone's implicit empty-string default. Threaded to fields via
+    // getPrismaType, the same way provider/listName already reach them.
+    const keystoneCompat = config.db.keystoneCompat ?? false;
+    // Postgres multi-schema: when the datasource declares more than one schema,
+    // Prisma requires the `multiSchema` preview feature and a `schemas = [...]`
+    // array on the datasource. Each model then carries a `@@schema(...)`.
+    const schemas = config.db.schemas;
+    const multiSchema = Array.isArray(schemas) && schemas.length > 0;
     // Generator and datasource
     lines.push('generator client {');
     lines.push('  provider = "prisma-client"');
-    lines.push(`  output   = "../${opensaasPath}/prisma-client"`);
+    lines.push(`  output   = "${clientOutput}"`);
+    if (multiSchema) {
+        lines.push('  previewFeatures = ["multiSchema"]');
+    }
     lines.push('}');
     lines.push('');
     lines.push('datasource db {');
     lines.push(`  provider = "${config.db.provider}"`);
+    if (multiSchema) {
+        lines.push(`  schemas  = [${schemas.map((s) => `"${s}"`).join(', ')}]`);
+    }
     lines.push('}');
     lines.push('');
-    // Collect enum definitions from all fields (first pass)
     const enumDefinitions = new Map();
     for (const [listName, listConfig] of Object.entries(config.lists)) {
         for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
             if (fieldConfig.type === 'relationship' || fieldConfig.virtual)
                 continue;
             if (fieldConfig.getPrismaType) {
-                const result = fieldConfig.getPrismaType(fieldName, config.db.provider, listName);
+                const result = fieldConfig.getPrismaType(fieldName, config.db.provider, listName, keystoneCompat);
                 if (result.enumValues && result.enumValues.length > 0) {
-                    enumDefinitions.set(result.type, result.enumValues);
+                    // The enum lives in the owning model's schema (so an enum used by an
+                    // `auth`-schema model lands in `auth`, not `public`). Default to
+                    // `public` when the list declares no schema.
+                    enumDefinitions.set(result.type, {
+                        values: result.enumValues,
+                        schema: listConfig.db?.schema ?? 'public',
+                    });
                 }
             }
         }
     }
     // Generate enum blocks
-    for (const [enumName, values] of enumDefinitions) {
+    for (const [enumName, { values, schema: enumSchema }] of enumDefinitions) {
         lines.push(`enum ${enumName} {`);
         for (const value of values) {
             lines.push(`  ${value}`);
         }
+        // In multi-schema mode every enum must declare an `@@schema(...)` or Prisma
+        // rejects the schema (P1012). Greenfield (single schema) output is unchanged.
+        if (multiSchema) {
+            lines.push(`  @@schema("${enumSchema}")`);
+        }
         lines.push('}');
         lines.push('');
     }
-    // Track many-to-many relationships (for Keystone naming)
-    const manyToManyRelationships = [];
-    // Track synthetic relation fields that need to be added to target lists
-    // Map of listName -> array of synthetic fields
-    const syntheticFields = new Map();
-    // First pass: collect all relationship info and identify synthetic fields and many-to-many relationships
-    const processedManyToMany = new Set(); // Track processed many-to-many to avoid duplicates
+    // Compute every relationship field's Prisma contribution by delegating to the
+    // relationship field builder. The generator stays a neutral coordinator: it
+    // never inspects relationship topology itself, it only places the lines the
+    // field returns into the right model.
+    const relationResults = new Map();
+    // Synthetic back-relation lines keyed by the target model they belong to.
+    const backRelationsByTarget = new Map();
     for (const [listName, listConfig] of Object.entries(config.lists)) {
         for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
-            if (fieldConfig.type === 'relationship') {
-                const relField = fieldConfig;
-                const { list: targetList, field: targetField } = parseRelationshipRef(relField.ref);
-                // Check if this is a many-to-many relationship (only if it's a many relationship)
-                const m2mCheck = relField.many
-                    ? isManyToManyRelationship(listName, fieldName, relField, config)
-                    : { isManyToMany: false, targetList: '', targetField: undefined };
-                if (m2mCheck.isManyToMany) {
-                    // Create a unique key to avoid processing the same relationship twice
-                    const relationshipKey = targetField
-                        ? // Bidirectional: use sorted list names to ensure uniqueness
-                            [listName, fieldName, targetList, targetField].sort().join('.')
-                        : // List-only: just use source side
-                            `${listName}.${fieldName}`;
-                    if (!processedManyToMany.has(relationshipKey)) {
-                        processedManyToMany.add(relationshipKey);
-                        // Check for per-field relationName (takes precedence)
-                        const sourceRelationName = relField.db?.relationName;
-                        let targetRelationName;
-                        if (targetField) {
-                            const targetListConfig = config.lists[targetList];
-                            const targetFieldConfig = targetListConfig?.fields[targetField];
-                            if (targetFieldConfig?.type === 'relationship') {
-                                targetRelationName = targetFieldConfig.db?.relationName;
-                            }
-                        }
-                        // Validate both sides match if both specify relationName
-                        if (sourceRelationName &&
-                            targetRelationName &&
-                            sourceRelationName !== targetRelationName) {
-                            throw new Error(`Relation name mismatch: ${listName}.${fieldName} has relationName "${sourceRelationName}" but ${targetList}.${targetField} has "${targetRelationName}". Both sides must use the same relationName.`);
-                        }
-                        // Use per-field relationName if set (either side), otherwise fall back to global naming
-                        const explicitRelationName = sourceRelationName || targetRelationName;
-                        let relationName;
-                        let joinTableName;
-                        let ownerSide = 'source';
-                        if (explicitRelationName) {
-                            // Per-field relationName takes precedence
-                            relationName = explicitRelationName;
-                            joinTableName = `_${explicitRelationName}`;
-                        }
-                        else if (joinTableNaming === 'keystone') {
-                            // For Keystone naming, we need to determine which side owns the join table name
-                            // Keystone uses the side where the relationship is defined
-                            // For bidirectional many-to-many, we need to pick one side deterministically
-                            joinTableName = `_${listName}_${fieldName}`;
-                            relationName = `${listName}_${fieldName}`;
-                            if (targetField) {
-                                // Bidirectional many-to-many
-                                // Use alphabetical ordering to determine owner (ensures both sides agree)
-                                const sourceKey = `${listName}.${fieldName}`;
-                                const targetKey = `${targetList}.${targetField}`;
-                                if (sourceKey.localeCompare(targetKey) < 0) {
-                                    ownerSide = 'source';
-                                    joinTableName = `_${listName}_${fieldName}`;
-                                    relationName = `${listName}_${fieldName}`;
-                                }
-                                else {
-                                    ownerSide = 'target';
-                                    joinTableName = `_${targetList}_${targetField}`;
-                                    relationName = `${targetList}_${targetField}`;
-                                }
-                            }
-                        }
-                        else {
-                            // Default Prisma naming - no explicit relation name needed
-                            // Prisma will auto-generate join table name
-                            relationName = '';
-                            joinTableName = '';
-                        }
-                        // Only track M2M relationships that need explicit relation names
-                        if (relationName) {
-                            manyToManyRelationships.push({
-                                sourceList: listName,
-                                sourceField: fieldName,
-                                targetList,
-                                targetField,
-                                ownerSide,
-                                joinTableName,
-                                relationName,
-                            });
-                        }
-                    }
+            // Skip non-relationship fields and virtual relationships (which contribute
+            // no database columns and therefore no Prisma schema lines).
+            if (fieldConfig.type !== 'relationship' || fieldConfig.virtual)
+                continue;
+            const relField = fieldConfig;
+            if (!relField.getPrismaRelation) {
+                throw new Error(`Relationship field "${listName}.${fieldName}" does not implement getPrismaRelation method`);
+            }
+            const result = relField.getPrismaRelation(fieldName, listConfig.fields, listName, config);
+            relationResults.set(`${listName}.${fieldName}`, result);
+            if (result.backRelation) {
+                const existing = backRelationsByTarget.get(result.backRelation.targetList);
+                if (existing) {
+                    existing.push(result.backRelation.line);
                 }
-                // If no target field specified, we need to add a synthetic back-reference field
-                // on the target model. Prisma requires both sides of any relationship to be
-                // defined, including implicit many-to-many relationships.
-                // This applies to all list-only refs (both many-to-many and many-to-one).
-                if (!targetField) {
-                    const syntheticFieldName = `from_${listName}_${fieldName}`;
-                    // Use explicit relation name if set, otherwise auto-generate
-                    const relationName = relField.db?.relationName ?? `${listName}_${fieldName}`;
-                    if (!syntheticFields.has(targetList)) {
-                        syntheticFields.set(targetList, []);
-                    }
-                    syntheticFields.get(targetList).push({
-                        fieldName: syntheticFieldName,
-                        sourceList: listName,
-                        sourceField: fieldName,
-                        relationName,
-                    });
+                else {
+                    backRelationsByTarget.set(result.backRelation.targetList, [result.backRelation.line]);
                 }
             }
         }
@@ -331,17 +161,17 @@ export function generatePrismaSchema(config) {
     // Generate models for each list
     for (const [listName, listConfig] of Object.entries(config.lists)) {
         lines.push(`model ${listName} {`);
-        // Add id field - singleton lists use Int @id (always 1) to match Keystone 6 behaviour
+        // Add id field - singleton lists emit a bare `id Int @id` (no `@default(1)`) to
+        // match Keystone 6, which emits no column default for singleton ids (see ADR-0004).
+        // Non-singleton lists are unchanged: `id String @id @default(cuid())`.
         if (listConfig.isSingleton) {
-            lines.push('  id        Int      @id @default(1)');
+            lines.push('  id        Int      @id');
         }
         else {
             lines.push('  id        String   @id @default(cuid())');
         }
-        // Track relationship fields for later processing
-        const relationshipFields = [];
-        // Track foreign key fields that need indexes
-        const foreignKeyIndexes = [];
+        // Track relationship field names (in declaration order) for later processing
+        const relationshipFieldNames = [];
         // Add regular fields
         for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
             // Skip virtual fields - they don't create database columns
@@ -349,16 +179,36 @@ export function generatePrismaSchema(config) {
                 continue;
             }
             if (fieldConfig.type === 'relationship') {
-                relationshipFields.push({
-                    name: fieldName,
-                    field: fieldConfig,
-                });
+                relationshipFieldNames.push(fieldName);
                 continue;
             }
-            const prismaType = mapFieldTypeToPrisma(fieldName, fieldConfig, config.db.provider, listName);
+            // Multi-column fields (e.g. storage image()/file() in Keystone-parity
+            // mode) emit several physical columns instead of one. The generator stays
+            // neutral: it places whatever lines the field returns, the same way it
+            // delegates to relationship fields via getPrismaRelation. See ADR-0006.
+            if (fieldConfig.getPrismaColumns) {
+                const columns = fieldConfig.getPrismaColumns(fieldName);
+                if (columns && columns.length > 0) {
+                    for (const column of columns) {
+                        const colMods = (column.modifiers ?? '').trimStart();
+                        const colNull = colMods.startsWith('?') ? '?' : '';
+                        let colAttrs = colMods.startsWith('?') ? colMods.slice(1).trimStart() : colMods;
+                        // Append @map to bind the column to its physical name (the live
+                        // Keystone column). Emitted whenever a `map` is supplied so the
+                        // mapping is explicit and configurable.
+                        if (column.map) {
+                            colAttrs = `${colAttrs ? colAttrs + ' ' : ''}@map("${column.map}")`;
+                        }
+                        const paddedColName = column.name.padEnd(12);
+                        lines.push(`  ${paddedColName} ${column.type}${colNull}${colAttrs ? ' ' + colAttrs : ''}`);
+                    }
+                    continue;
+                }
+            }
+            const prismaType = mapFieldTypeToPrisma(fieldName, fieldConfig, config.db.provider, listName, keystoneCompat);
             if (!prismaType)
                 continue; // Skip if no type returned
-            const modifiers = getFieldModifiers(fieldName, fieldConfig, config.db.provider, listName);
+            const modifiers = getFieldModifiers(fieldName, fieldConfig, config.db.provider, listName, keystoneCompat);
             // Format with proper spacing: '?' attaches to type directly, other modifiers get a space
             const paddedName = fieldName.padEnd(12);
             const modStr = modifiers.trimStart();
@@ -366,120 +216,54 @@ export function generatePrismaSchema(config) {
             const attrPart = modStr.startsWith('?') ? modStr.slice(1).trimStart() : modStr;
             lines.push(`  ${paddedName} ${prismaType}${nullPart}${attrPart ? ' ' + attrPart : ''}`);
         }
-        // Add relationship fields
-        for (const { name: fieldName, field: relField } of relationshipFields) {
-            const { list: targetList, field: targetField } = parseRelationshipRef(relField.ref);
-            const paddedName = fieldName.padEnd(12);
-            if (relField.many) {
-                // Check if this is a many-to-many relationship
-                const m2mCheck = isManyToManyRelationship(listName, fieldName, relField, config);
-                let relationLine;
-                // Check if this M2M relationship has an explicit relation name (per-field or global Keystone naming)
-                const m2mRel = manyToManyRelationships.find((rel) => (rel.sourceList === listName && rel.sourceField === fieldName) ||
-                    (rel.targetList === listName && rel.targetField === fieldName));
-                if (m2mCheck.isManyToMany && m2mRel) {
-                    // Many-to-many with explicit relation name (per-field or Keystone naming)
-                    relationLine = `  ${paddedName} ${targetList}[]  @relation("${m2mRel.relationName}")`;
-                }
-                else if (targetField) {
-                    // Standard bidirectional one-to-many or many-to-many with Prisma naming
-                    relationLine = `  ${paddedName} ${targetList}[]`;
-                }
-                else {
-                    // List-only ref: use named relation
-                    const relationName = `${listName}_${fieldName}`;
-                    relationLine = `  ${paddedName} ${targetList}[]  @relation("${relationName}")`;
-                }
-                // Apply extendPrismaSchema if defined (many side has no FK line)
-                if (relField.db?.extendPrismaSchema) {
-                    const extended = relField.db.extendPrismaSchema({ relationLine });
-                    relationLine = extended.relationLine;
-                }
-                lines.push(relationLine);
-            }
-            else {
-                // Single relationship - check if this side should have the foreign key
-                const hasForeignKey = shouldHaveForeignKey(listName, fieldName, relField, config);
-                if (hasForeignKey) {
-                    // This side has the foreign key
-                    const foreignKeyField = `${fieldName}Id`;
-                    const fkPaddedName = foreignKeyField.padEnd(12);
-                    // Check if this is a one-to-one relationship
-                    const isOneToOne = isOneToOneRelationship(listName, fieldName, relField, config);
-                    const uniqueModifier = isOneToOne ? ' @unique' : '';
-                    // Get the map attribute
-                    // If foreignKey is an object with map property, use it
-                    // Otherwise, default to fieldName (not fieldNameId)
-                    let mapModifier = '';
-                    if (typeof relField.db?.foreignKey === 'object' && relField.db.foreignKey.map) {
-                        mapModifier = ` @map("${relField.db.foreignKey.map}")`;
-                    }
-                    else {
-                        // Default to field name (not fieldNameId)
-                        mapModifier = ` @map("${fieldName}")`;
-                    }
-                    let fkLine = `  ${fkPaddedName} String?${uniqueModifier}${mapModifier}`;
-                    let relationLine;
-                    if (targetField) {
-                        // Standard bidirectional relationship
-                        relationLine = `  ${paddedName} ${targetList}?  @relation(fields: [${foreignKeyField}], references: [id])`;
-                    }
-                    else {
-                        // List-only ref: use named relation
-                        const relationName = `${listName}_${fieldName}`;
-                        relationLine = `  ${paddedName} ${targetList}?  @relation("${relationName}", fields: [${foreignKeyField}], references: [id])`;
-                    }
-                    // Apply extendPrismaSchema if defined
-                    if (relField.db?.extendPrismaSchema) {
-                        const extended = relField.db.extendPrismaSchema({ fkLine, relationLine });
-                        fkLine = extended.fkLine ?? fkLine;
-                        relationLine = extended.relationLine;
-                    }
-                    lines.push(fkLine);
-                    lines.push(relationLine);
-                    // Track foreign key for index generation
-                    // Default to true (matching Keystone behavior) unless explicitly set to false
-                    const indexType = relField.isIndexed ?? true;
-                    if (indexType !== false) {
-                        foreignKeyIndexes.push({
-                            foreignKeyField,
-                            indexType,
-                        });
-                    }
-                }
-                else {
-                    // This side does NOT have the foreign key (other side of one-to-one)
-                    // Just add the relation field without foreign key
-                    let relationLine = `  ${paddedName} ${targetList}?`;
-                    // Apply extendPrismaSchema if defined (no FK line on this side)
-                    if (relField.db?.extendPrismaSchema) {
-                        const extended = relField.db.extendPrismaSchema({ relationLine });
-                        relationLine = extended.relationLine;
-                    }
-                    lines.push(relationLine);
-                }
+        // Add relationship fields (lines + foreign key indexes) from the precomputed results
+        const foreignKeyIndexes = [];
+        for (const fieldName of relationshipFieldNames) {
+            const result = relationResults.get(`${listName}.${fieldName}`);
+            lines.push(...result.modelLines);
+            if (result.foreignKeyIndex) {
+                foreignKeyIndexes.push(result.foreignKeyIndex);
             }
         }
         // Add synthetic relation fields for list-only refs pointing to this list
-        const syntheticFieldsForList = syntheticFields.get(listName);
-        if (syntheticFieldsForList) {
-            for (const { fieldName: syntheticFieldName, sourceList, relationName, } of syntheticFieldsForList) {
-                const paddedName = syntheticFieldName.padEnd(12);
-                lines.push(`  ${paddedName} ${sourceList}[]  @relation("${relationName}")`);
+        const backRelations = backRelationsByTarget.get(listName);
+        if (backRelations) {
+            for (const line of backRelations) {
+                lines.push(line);
             }
         }
-        // Always add timestamps
-        lines.push('  createdAt DateTime @default(now())');
-        lines.push('  updatedAt DateTime @default(now()) @updatedAt');
+        // Add auto-timestamps when enabled (off by default — see ADR-0004). The auto
+        // column is skipped for any timestamp the list declares itself (handled inside
+        // resolveListTimestamps) so Prisma never sees a duplicate field (P1012).
+        const timestamps = resolveListTimestamps(listConfig, config.db);
+        if (timestamps.createdAt) {
+            lines.push('  createdAt DateTime @default(now())');
+        }
+        if (timestamps.updatedAt) {
+            lines.push('  updatedAt DateTime @default(now()) @updatedAt');
+        }
         // Add indexes for foreign key fields
-        for (const { foreignKeyField, indexType } of foreignKeyIndexes) {
-            if (indexType === 'unique') {
-                lines.push(`  @@unique([${foreignKeyField}])`);
+        for (const index of foreignKeyIndexes) {
+            if (index.indexType === 'unique') {
+                lines.push(`  @@unique([${index.foreignKeyField}])`);
             }
-            else if (indexType === true) {
-                lines.push(`  @@index([${foreignKeyField}])`);
+            else if (index.indexType === true) {
+                lines.push(`  @@index([${index.foreignKeyField}])`);
             }
         }
+        // Map the model to a custom table name when configured (e.g. adopting
+        // existing tables whose physical name differs from the list key).
+        if (listConfig.db?.map) {
+            lines.push(`  @@map("${listConfig.db.map}")`);
+        }
+        // Place the model in a specific database schema (Postgres multi-schema).
+        // In multi-schema mode every model must declare an `@@schema(...)` or Prisma
+        // rejects the schema (P1012). A list inherits its own `db.schema` when set,
+        // otherwise it defaults to `public` (mirroring the enum default added in
+        // #504). Greenfield (single schema) output is unchanged — no `@@schema`.
+        if (multiSchema) {
+            lines.push(`  @@schema("${listConfig.db?.schema ?? 'public'}")`);
+        }
         lines.push('}');
         lines.push('');
     }
@@ -495,9 +279,12 @@ export function generatePrismaSchema(config) {
 }
 /**
  * Write Prisma schema to file
+ *
+ * @param prismaClientOutput - Optional override for the patched Prisma client
+ *   output path, forwarded to {@link generatePrismaSchema}.
  */
-export function writePrismaSchema(config, outputPath) {
-    const schema = generatePrismaSchema(config);
+export function writePrismaSchema(config, outputPath, prismaClientOutput) {
+    const schema = generatePrismaSchema(config, prismaClientOutput);
     // Ensure directory exists
     const dir = path.dirname(outputPath);
     if (!fs.existsSync(dir)) {