@prisma-next/family-sql 0.4.2 → 0.4.3

package/dist/control.mjs

@@ -1,6 +1,6 @@
 import { n as sqlFamilyAuthoringFieldPresets, t as sqlFamilyAuthoringTypes } from "./authoring-type-constructors-BAR65pSK.mjs";
 import { c as extractCodecControlHooks, o as collectInitDependencies, s as isDatabaseDependencyProvider, t as verifySqlSchema } from "./verify-sql-schema-Ovz7RXR5.mjs";
-import { r as readMarker, t as collectSupportedCodecTypeIds } from "./verify-4GshvY4p.mjs";
+import { t as collectSupportedCodecTypeIds } from "./verify-BdES8wgQ.mjs";
 import { sqlEmission } from "@prisma-next/sql-contract-emitter";
 import { emptyCodecLookup } from "@prisma-next/framework-components/codec";
 import { SchemaTreeNode, VERIFY_CODE_HASH_MISMATCH, VERIFY_CODE_MARKER_MISSING, VERIFY_CODE_TARGET_MISMATCH, assembleAuthoringContributions } from "@prisma-next/framework-components/control";
@@ -10,6 +10,1012 @@ import { defaultIndexName } from "@prisma-next/sql-schema-ir/naming";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { notOk, ok } from "@prisma-next/utils/result";
 
+//#region src/core/operation-preview.ts
+function isDdlStatement(sqlStatement) {
+	const trimmed = sqlStatement.trim().toLowerCase();
+	return trimmed.startsWith("create ") || trimmed.startsWith("alter ") || trimmed.startsWith("drop ");
+}
+function hasExecuteSteps(operation) {
+	const candidate = operation;
+	if (!("execute" in candidate) || !Array.isArray(candidate["execute"])) return false;
+	return candidate["execute"].every((step) => typeof step === "object" && step !== null && "sql" in step);
+}
+/**
+* Extracts a best-effort SQL DDL preview for CLI plan output.
+* Presentation-only: never used to decide migration correctness.
+*/
+function extractSqlDdl(operations) {
+	const statements = [];
+	for (const operation of operations) {
+		if (!hasExecuteSteps(operation)) continue;
+		for (const step of operation.execute) if (typeof step.sql === "string" && isDdlStatement(step.sql)) statements.push(step.sql.trim());
+	}
+	return statements;
+}
+/**
+* Wraps `extractSqlDdl` into the family-agnostic `OperationPreview` shape.
+* Each statement carries `language: 'sql'`.
+*/
+function sqlOperationsToPreview(operations) {
+	return { statements: extractSqlDdl(operations).map((text) => ({
+		text,
+		language: "sql"
+	})) };
+}
+
+//#endregion
+//#region src/core/psl-contract-infer/default-mapping.ts
+const DEFAULT_FUNCTION_ATTRIBUTES = {
+	"autoincrement()": "@default(autoincrement())",
+	"now()": "@default(now())"
+};
+function mapDefault(columnDefault, options) {
+	switch (columnDefault.kind) {
+		case "literal": return { attribute: `@default(${formatLiteralValue(columnDefault.value)})` };
+		case "function": {
+			const attribute = options?.functionAttributes?.[columnDefault.expression] ?? DEFAULT_FUNCTION_ATTRIBUTES[columnDefault.expression] ?? options?.fallbackFunctionAttribute?.(columnDefault.expression);
+			return attribute ? { attribute } : { comment: `// Raw default: ${columnDefault.expression.replace(/[\r\n]+/g, " ")}` };
+		}
+	}
+}
+function formatLiteralValue(value) {
+	if (value === null) return "null";
+	switch (typeof value) {
+		case "boolean":
+		case "number": return String(value);
+		case "string": return quoteString(value);
+		default: return quoteString(JSON.stringify(value));
+	}
+}
+function quoteString(str) {
+	return `"${escapeString(str)}"`;
+}
+function escapeString(str) {
+	return JSON.stringify(str).slice(1, -1);
+}
+
+//#endregion
+//#region src/core/psl-contract-infer/name-transforms.ts
+const PSL_RESERVED_WORDS = new Set([
+	"model",
+	"enum",
+	"types",
+	"type",
+	"generator",
+	"datasource"
+]);
+const IDENTIFIER_PART_PATTERN = /[A-Za-z0-9]+/g;
+function hasSeparators(input) {
+	return /[^A-Za-z0-9]/.test(input);
+}
+function extractIdentifierParts(input) {
+	return input.match(IDENTIFIER_PART_PATTERN) ?? [];
+}
+function createSyntheticIdentifier(input) {
+	let hash = 2166136261;
+	for (const char of input) {
+		hash ^= char.codePointAt(0) ?? 0;
+		hash = Math.imul(hash, 16777619);
+	}
+	return `x${(hash >>> 0).toString(16)}`;
+}
+function sanitizeIdentifierCharacters(input) {
+	const sanitized = input.replace(/[^\w]/g, "");
+	return sanitized.length > 0 ? sanitized : createSyntheticIdentifier(input);
+}
+function capitalize(word) {
+	return word.charAt(0).toUpperCase() + word.slice(1);
+}
+function snakeToPascalCase(input) {
+	const parts = extractIdentifierParts(input);
+	if (parts.length === 0) return capitalize(sanitizeIdentifierCharacters(input));
+	return parts.map(capitalize).join("");
+}
+function snakeToCamelCase(input) {
+	const parts = extractIdentifierParts(input);
+	if (parts.length === 0) return sanitizeIdentifierCharacters(input);
+	const [firstPart = input, ...rest] = parts;
+	return firstPart.charAt(0).toLowerCase() + firstPart.slice(1) + rest.map(capitalize).join("");
+}
+function needsEscaping(name) {
+	return PSL_RESERVED_WORDS.has(name.toLowerCase()) || /^\d/.test(name);
+}
+function escapeName(name) {
+	return `_${name}`;
+}
+function escapeIfNeeded(name) {
+	return needsEscaping(name) ? escapeName(name) : name;
+}
+function toModelName(tableName) {
+	let name;
+	if (hasSeparators(tableName)) name = snakeToPascalCase(tableName);
+	else name = tableName.charAt(0).toUpperCase() + tableName.slice(1);
+	if (needsEscaping(name)) return {
+		name: escapeName(name),
+		map: tableName
+	};
+	if (name !== tableName) return {
+		name,
+		map: tableName
+	};
+	return { name };
+}
+function toFieldName(columnName) {
+	let name;
+	if (hasSeparators(columnName)) name = snakeToCamelCase(columnName);
+	else name = columnName.charAt(0).toLowerCase() + columnName.slice(1);
+	if (needsEscaping(name)) return {
+		name: escapeName(name),
+		map: columnName
+	};
+	if (name !== columnName) return {
+		name,
+		map: columnName
+	};
+	return { name };
+}
+function toEnumName(pgTypeName) {
+	let name;
+	if (hasSeparators(pgTypeName)) name = snakeToPascalCase(pgTypeName);
+	else name = pgTypeName.charAt(0).toUpperCase() + pgTypeName.slice(1);
+	if (needsEscaping(name)) return {
+		name: escapeName(name),
+		map: pgTypeName
+	};
+	if (name !== pgTypeName) return {
+		name,
+		map: pgTypeName
+	};
+	return { name };
+}
+function pluralize(word) {
+	if (word.endsWith("s") || word.endsWith("x") || word.endsWith("z") || word.endsWith("ch") || word.endsWith("sh")) return `${word}es`;
+	if (word.endsWith("y") && !/[aeiou]y$/i.test(word)) return `${word.slice(0, -1)}ies`;
+	return `${word}s`;
+}
+function deriveRelationFieldName(fkColumns, referencedTableName) {
+	if (fkColumns.length === 1) {
+		const [col = referencedTableName] = fkColumns;
+		const stripped = col.replace(/_id$/i, "").replace(/Id$/, "");
+		if (stripped.length > 0 && stripped !== col) return escapeIfNeeded(snakeToCamelCase(stripped));
+		return escapeIfNeeded(snakeToCamelCase(referencedTableName));
+	}
+	return escapeIfNeeded(snakeToCamelCase(referencedTableName));
+}
+function deriveBackRelationFieldName(childModelName, isOneToOne) {
+	const base = childModelName.charAt(0).toLowerCase() + childModelName.slice(1);
+	return isOneToOne ? base : pluralize(base);
+}
+function toNamedTypeName(columnName) {
+	let name;
+	if (hasSeparators(columnName)) name = snakeToPascalCase(columnName);
+	else name = columnName.charAt(0).toUpperCase() + columnName.slice(1);
+	return escapeIfNeeded(name);
+}
+
+//#endregion
+//#region src/core/psl-contract-infer/postgres-default-mapping.ts
+const POSTGRES_FUNCTION_ATTRIBUTES = { "gen_random_uuid()": "@default(dbgenerated(\"gen_random_uuid()\"))" };
+function formatDbGeneratedAttribute(expression) {
+	return `@default(dbgenerated(${JSON.stringify(expression)}))`;
+}
+function createPostgresDefaultMapping() {
+	return {
+		functionAttributes: POSTGRES_FUNCTION_ATTRIBUTES,
+		fallbackFunctionAttribute: formatDbGeneratedAttribute
+	};
+}
+
+//#endregion
+//#region src/core/psl-contract-infer/postgres-type-map.ts
+const POSTGRES_TO_PSL = {
+	text: "String",
+	bool: "Boolean",
+	boolean: "Boolean",
+	int4: "Int",
+	integer: "Int",
+	int8: "BigInt",
+	bigint: "BigInt",
+	float8: "Float",
+	"double precision": "Float",
+	numeric: "Decimal",
+	decimal: "Decimal",
+	timestamptz: "DateTime",
+	"timestamp with time zone": "DateTime",
+	jsonb: "Json",
+	bytea: "Bytes"
+};
+const PRESERVED_NATIVE_TYPES = {
+	"character varying": {
+		pslType: "String",
+		attributeName: "db.VarChar"
+	},
+	character: {
+		pslType: "String",
+		attributeName: "db.Char"
+	},
+	char: {
+		pslType: "String",
+		attributeName: "db.Char"
+	},
+	varchar: {
+		pslType: "String",
+		attributeName: "db.VarChar"
+	},
+	uuid: {
+		pslType: "String",
+		attributeName: "db.Uuid"
+	},
+	int2: {
+		pslType: "Int",
+		attributeName: "db.SmallInt"
+	},
+	smallint: {
+		pslType: "Int",
+		attributeName: "db.SmallInt"
+	},
+	float4: {
+		pslType: "Float",
+		attributeName: "db.Real"
+	},
+	real: {
+		pslType: "Float",
+		attributeName: "db.Real"
+	},
+	timestamp: {
+		pslType: "DateTime",
+		attributeName: "db.Timestamp"
+	},
+	"timestamp without time zone": {
+		pslType: "DateTime",
+		attributeName: "db.Timestamp"
+	},
+	date: {
+		pslType: "DateTime",
+		attributeName: "db.Date"
+	},
+	time: {
+		pslType: "DateTime",
+		attributeName: "db.Time"
+	},
+	"time without time zone": {
+		pslType: "DateTime",
+		attributeName: "db.Time"
+	},
+	timetz: {
+		pslType: "DateTime",
+		attributeName: "db.Timetz"
+	},
+	"time with time zone": {
+		pslType: "DateTime",
+		attributeName: "db.Timetz"
+	},
+	json: {
+		pslType: "Json",
+		attributeName: "db.Json"
+	}
+};
+const PARAMETERIZED_NATIVE_TYPES = {
+	"character varying": {
+		pslType: "String",
+		attributeName: "db.VarChar"
+	},
+	character: {
+		pslType: "String",
+		attributeName: "db.Char"
+	},
+	char: {
+		pslType: "String",
+		attributeName: "db.Char"
+	},
+	varchar: {
+		pslType: "String",
+		attributeName: "db.VarChar"
+	},
+	numeric: {
+		pslType: "Decimal",
+		attributeName: "db.Numeric"
+	},
+	timestamp: {
+		pslType: "DateTime",
+		attributeName: "db.Timestamp"
+	},
+	timestamptz: {
+		pslType: "DateTime",
+		attributeName: "db.Timestamptz"
+	},
+	time: {
+		pslType: "DateTime",
+		attributeName: "db.Time"
+	},
+	timetz: {
+		pslType: "DateTime",
+		attributeName: "db.Timetz"
+	}
+};
+const PARAMETERIZED_TYPE_PATTERN = /^(.+?)\((.+)\)$/;
+const ENUM_CODEC_ID = "pg/enum@1";
+function getOwnMappingValue(map, key) {
+	return Object.hasOwn(map, key) ? map[key] : void 0;
+}
+function getOwnRecordValue(map, key) {
+	return Object.hasOwn(map, key) ? map[key] : void 0;
+}
+function createNativeTypeAttribute(name, args) {
+	return args && args.length > 0 ? {
+		name,
+		args
+	} : { name };
+}
+function splitTypeParameterList(params) {
+	return params.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+}
+function createPostgresTypeMap(enumTypeNames) {
+	return { resolve(nativeType) {
+		if (enumTypeNames?.has(nativeType)) return {
+			pslType: nativeType,
+			nativeType
+		};
+		const paramMatch = nativeType.match(PARAMETERIZED_TYPE_PATTERN);
+		if (paramMatch) {
+			const [, baseType = nativeType, params = ""] = paramMatch;
+			const template = getOwnRecordValue(PARAMETERIZED_NATIVE_TYPES, baseType);
+			if (template) return {
+				pslType: template.pslType,
+				nativeType,
+				typeParams: {
+					baseType,
+					params
+				},
+				nativeTypeAttribute: createNativeTypeAttribute(template.attributeName, splitTypeParameterList(params))
+			};
+		}
+		const preservedType = getOwnRecordValue(PRESERVED_NATIVE_TYPES, nativeType);
+		if (preservedType) return {
+			pslType: preservedType.pslType,
+			nativeType,
+			nativeTypeAttribute: createNativeTypeAttribute(preservedType.attributeName)
+		};
+		const pslType = getOwnMappingValue(POSTGRES_TO_PSL, nativeType);
+		if (pslType) return {
+			pslType,
+			nativeType
+		};
+		return {
+			unsupported: true,
+			nativeType
+		};
+	} };
+}
+function extractEnumInfo(annotations) {
+	const storageTypes = (annotations?.["pg"])?.["storageTypes"];
+	const typeNames = /* @__PURE__ */ new Set();
+	const definitions = /* @__PURE__ */ new Map();
+	if (storageTypes) {
+		for (const [key, typeInstance] of Object.entries(storageTypes)) if (typeInstance.codecId === ENUM_CODEC_ID) {
+			typeNames.add(key);
+			const values = typeInstance.typeParams?.["values"];
+			if (Array.isArray(values)) definitions.set(key, values);
+		}
+	}
+	return {
+		typeNames,
+		definitions
+	};
+}
+
+//#endregion
+//#region src/core/psl-contract-infer/raw-default-parser.ts
+const NEXTVAL_PATTERN = /^nextval\s*\(/i;
+const NOW_FUNCTION_PATTERN = /^(now\s*\(\s*\)|CURRENT_TIMESTAMP)$/i;
+const CLOCK_TIMESTAMP_PATTERN = /^clock_timestamp\s*\(\s*\)$/i;
+const TIMESTAMP_CAST_SUFFIX = /::timestamp(?:tz|\s+(?:with|without)\s+time\s+zone)?$/i;
+const TEXT_CAST_SUFFIX = /::text$/i;
+const NOW_LITERAL_PATTERN = /^'now'$/i;
+const UUID_PATTERN = /^gen_random_uuid\s*\(\s*\)$/i;
+const UUID_OSSP_PATTERN = /^uuid_generate_v4\s*\(\s*\)$/i;
+const NULL_PATTERN = /^NULL(?:::.+)?$/i;
+const TRUE_PATTERN = /^true$/i;
+const FALSE_PATTERN = /^false$/i;
+const NUMERIC_PATTERN = /^-?\d+(\.\d+)?$/;
+const JSON_CAST_SUFFIX = /::jsonb?$/i;
+const STRING_LITERAL_PATTERN = /^'((?:[^']|'')*)'(?:::(?:"[^"]+"|[\w\s]+)(?:\(\d+\))?)?$/;
+function canonicalizeTimestampDefault(expr) {
+	if (NOW_FUNCTION_PATTERN.test(expr)) return "now()";
+	if (CLOCK_TIMESTAMP_PATTERN.test(expr)) return "clock_timestamp()";
+	if (!TIMESTAMP_CAST_SUFFIX.test(expr)) return void 0;
+	let inner = expr.replace(TIMESTAMP_CAST_SUFFIX, "").trim();
+	if (inner.startsWith("(") && inner.endsWith(")")) inner = inner.slice(1, -1).trim();
+	if (NOW_FUNCTION_PATTERN.test(inner)) return "now()";
+	if (CLOCK_TIMESTAMP_PATTERN.test(inner)) return "clock_timestamp()";
+	inner = inner.replace(TEXT_CAST_SUFFIX, "").trim();
+	if (NOW_LITERAL_PATTERN.test(inner)) return "now()";
+}
+function parseRawDefault(rawDefault, nativeType) {
+	const trimmed = rawDefault.trim();
+	const normalizedType = nativeType?.toLowerCase();
+	if (NEXTVAL_PATTERN.test(trimmed)) return {
+		kind: "function",
+		expression: "autoincrement()"
+	};
+	const canonicalTimestamp = canonicalizeTimestampDefault(trimmed);
+	if (canonicalTimestamp) return {
+		kind: "function",
+		expression: canonicalTimestamp
+	};
+	if (UUID_PATTERN.test(trimmed) || UUID_OSSP_PATTERN.test(trimmed)) return {
+		kind: "function",
+		expression: "gen_random_uuid()"
+	};
+	if (NULL_PATTERN.test(trimmed)) return {
+		kind: "literal",
+		value: null
+	};
+	if (TRUE_PATTERN.test(trimmed)) return {
+		kind: "literal",
+		value: true
+	};
+	if (FALSE_PATTERN.test(trimmed)) return {
+		kind: "literal",
+		value: false
+	};
+	if (NUMERIC_PATTERN.test(trimmed)) return {
+		kind: "literal",
+		value: Number(trimmed)
+	};
+	const stringMatch = trimmed.match(STRING_LITERAL_PATTERN);
+	if (stringMatch?.[1] !== void 0) {
+		const unescaped = stringMatch[1].replace(/''/g, "'");
+		if (normalizedType === "json" || normalizedType === "jsonb") {
+			if (JSON_CAST_SUFFIX.test(trimmed)) return {
+				kind: "function",
+				expression: trimmed
+			};
+			try {
+				return {
+					kind: "literal",
+					value: JSON.parse(unescaped)
+				};
+			} catch {}
+		}
+		return {
+			kind: "literal",
+			value: unescaped
+		};
+	}
+	return {
+		kind: "function",
+		expression: trimmed
+	};
+}
+
+//#endregion
+//#region src/core/psl-contract-infer/relation-inference.ts
+const DEFAULT_ON_DELETE = "noAction";
+const DEFAULT_ON_UPDATE = "noAction";
+const REFERENTIAL_ACTION_PSL = {
+	noAction: "NoAction",
+	restrict: "Restrict",
+	cascade: "Cascade",
+	setNull: "SetNull",
+	setDefault: "SetDefault"
+};
+function inferRelations(tables, modelNameMap) {
+	const relationsByTable = /* @__PURE__ */ new Map();
+	const fkCountByPair = /* @__PURE__ */ new Map();
+	for (const table of Object.values(tables)) for (const fk of table.foreignKeys) {
+		const pairKey = `${table.name}→${fk.referencedTable}`;
+		fkCountByPair.set(pairKey, (fkCountByPair.get(pairKey) ?? 0) + 1);
+	}
+	const usedFieldNames = /* @__PURE__ */ new Map();
+	for (const table of Object.values(tables)) {
+		const names = /* @__PURE__ */ new Set();
+		for (const col of Object.values(table.columns)) names.add(col.name);
+		usedFieldNames.set(table.name, names);
+	}
+	for (const table of Object.values(tables)) for (const fk of table.foreignKeys) {
+		const childTableName = table.name;
+		const parentTableName = fk.referencedTable;
+		const childUsed = usedFieldNames.get(childTableName);
+		const childModelName = modelNameMap.get(childTableName) ?? childTableName;
+		const parentModelName = modelNameMap.get(parentTableName) ?? parentTableName;
+		const pairKey = `${childTableName}→${parentTableName}`;
+		const isSelfRelation = childTableName === parentTableName;
+		const needsRelationName = fkCountByPair.get(pairKey) > 1 || isSelfRelation;
+		const isOneToOne = detectOneToOne(fk, table);
+		const childRelFieldName = resolveUniqueFieldName(deriveRelationFieldName(fk.columns, parentTableName), childUsed, parentModelName);
+		const relationName = needsRelationName ? deriveRelationName(fk, childRelFieldName, parentModelName, isSelfRelation) : void 0;
+		addRelationField(relationsByTable, childTableName, buildChildRelationField(childRelFieldName, parentModelName, fk, fk.columns.some((columnName) => table.columns[columnName]?.nullable ?? false), relationName));
+		childUsed.add(childRelFieldName);
+		const parentUsed = usedFieldNames.get(parentTableName) ?? /* @__PURE__ */ new Set();
+		usedFieldNames.set(parentTableName, parentUsed);
+		const backRelFieldName = resolveUniqueFieldName(deriveBackRelationFieldName(childModelName, isOneToOne), parentUsed, childModelName);
+		addRelationField(relationsByTable, parentTableName, {
+			fieldName: backRelFieldName,
+			typeName: childModelName,
+			optional: isOneToOne,
+			list: !isOneToOne,
+			relationName
+		});
+		parentUsed.add(backRelFieldName);
+	}
+	return { relationsByTable };
+}
+function detectOneToOne(fk, table) {
+	const fkCols = [...fk.columns].sort();
+	if (table.primaryKey) {
+		const pkCols = [...table.primaryKey.columns].sort();
+		if (pkCols.length === fkCols.length && pkCols.every((c, i) => c === fkCols[i])) return true;
+	}
+	for (const unique of table.uniques) {
+		const uniqueCols = [...unique.columns].sort();
+		if (uniqueCols.length === fkCols.length && uniqueCols.every((c, i) => c === fkCols[i])) return true;
+	}
+	return false;
+}
+function deriveRelationName(fk, childRelationFieldName, parentModelName, isSelfRelation) {
+	if (fk.name) return fk.name;
+	if (isSelfRelation) return `${childRelationFieldName.charAt(0).toUpperCase() + childRelationFieldName.slice(1)}${pluralize(parentModelName)}`;
+	return fk.columns.join("_");
+}
+function buildChildRelationField(fieldName, parentModelName, fk, optional, relationName) {
+	const onDelete = fk.onDelete && fk.onDelete !== DEFAULT_ON_DELETE ? fk.onDelete : void 0;
+	const onUpdate = fk.onUpdate && fk.onUpdate !== DEFAULT_ON_UPDATE ? fk.onUpdate : void 0;
+	return {
+		fieldName,
+		typeName: parentModelName,
+		referencedTableName: fk.referencedTable,
+		optional,
+		list: false,
+		relationName,
+		fkName: fk.name,
+		fields: fk.columns,
+		references: fk.referencedColumns,
+		onDelete: onDelete ? REFERENTIAL_ACTION_PSL[onDelete] : void 0,
+		onUpdate: onUpdate ? REFERENTIAL_ACTION_PSL[onUpdate] : void 0
+	};
+}
+function resolveUniqueFieldName(desired, usedNames, fallbackSuffix) {
+	if (!usedNames.has(desired)) return desired;
+	const withSuffix = `${desired}${fallbackSuffix}`;
+	if (!usedNames.has(withSuffix)) return withSuffix;
+	let counter = 2;
+	while (usedNames.has(`${desired}${counter}`)) counter++;
+	return `${desired}${counter}`;
+}
+function addRelationField(map, tableName, field) {
+	const existing = map.get(tableName);
+	if (existing) existing.push(field);
+	else map.set(tableName, [field]);
+}
+
+//#endregion
+//#region src/core/psl-contract-infer/sql-schema-ir-to-psl-ast.ts
+const SYNTHETIC_SPAN = {
+	start: {
+		offset: 0,
+		line: 1,
+		column: 1
+	},
+	end: {
+		offset: 0,
+		line: 1,
+		column: 1
+	}
+};
+const PSL_SCALAR_TYPE_NAMES = new Set([
+	"String",
+	"Boolean",
+	"Int",
+	"BigInt",
+	"Float",
+	"Decimal",
+	"DateTime",
+	"Json",
+	"Bytes"
+]);
+/**
+* Converts a SQL schema IR into a PSL AST suitable for `printPsl`.
+*
+* This function owns all SQL-specific concerns: native type mapping (Postgres),
+* relation inference from foreign keys, enum extraction, and raw default parsing.
+* The output is a fully-formed `PslDocumentAst` with synthetic spans.
+*/
+function sqlSchemaIrToPslAst(schemaIR) {
+	const enumInfo = extractEnumInfo(schemaIR.annotations);
+	return buildPslDocumentAst(schemaIR, {
+		typeMap: createPostgresTypeMap(enumInfo.typeNames),
+		defaultMapping: createPostgresDefaultMapping(),
+		enumInfo,
+		parseRawDefault
+	});
+}
+function buildPslDocumentAst(schemaIR, options) {
+	const { typeMap, defaultMapping, enumInfo, parseRawDefault: rawDefaultParser } = options;
+	const { typeNames: enumTypeNames, definitions: enumDefinitions } = enumInfo ?? {
+		typeNames: /* @__PURE__ */ new Set(),
+		definitions: /* @__PURE__ */ new Map()
+	};
+	const modelNames = buildTopLevelNameMap(Object.keys(schemaIR.tables), toModelName, "model", "table");
+	const enumNames = buildTopLevelNameMap(enumTypeNames, toEnumName, "enum", "enum type");
+	assertNoCrossKindNameCollisions(modelNames, enumNames);
+	const modelNameMap = new Map([...modelNames].map(([tableName, result]) => [tableName, result.name]));
+	const enumNameMap = new Map([...enumNames].map(([pgTypeName, result]) => [pgTypeName, result.name]));
+	const reservedNamedTypeNames = createReservedNamedTypeNames(modelNames, enumNames);
+	const fieldNamesByTable = buildFieldNamesByTable(schemaIR.tables);
+	const { relationsByTable } = inferRelations(schemaIR.tables, modelNameMap);
+	const namedTypes = seedNamedTypeRegistry(schemaIR, typeMap, enumNameMap, reservedNamedTypeNames);
+	const models = [];
+	for (const table of Object.values(schemaIR.tables)) models.push(buildModel(table, typeMap, enumNameMap, fieldNamesByTable, namedTypes, defaultMapping, rawDefaultParser, relationsByTable.get(table.name) ?? []));
+	const sortedModels = topologicalSort(models, schemaIR.tables, modelNameMap);
+	const enums = [];
+	for (const [pgTypeName, values] of enumDefinitions) {
+		const enumName = enumNames.get(pgTypeName);
+		enums.push(buildEnum(enumName, values));
+	}
+	enums.sort((a, b) => a.name.localeCompare(b.name));
+	const namedTypeEntries = [...namedTypes.entriesByKey.values()].sort((a, b) => a.name.localeCompare(b.name));
+	const types = namedTypeEntries.length > 0 ? {
+		kind: "types",
+		declarations: namedTypeEntries.map(buildNamedTypeDeclaration),
+		span: SYNTHETIC_SPAN
+	} : void 0;
+	return {
+		kind: "document",
+		sourceId: "<sql-schema-ir>",
+		models: sortedModels,
+		enums,
+		compositeTypes: [],
+		...types ? { types } : {},
+		span: SYNTHETIC_SPAN
+	};
+}
+function buildModel(table, typeMap, enumNameMap, fieldNamesByTable, namedTypes, defaultMapping, rawDefaultParser, relationFields) {
+	const { name: modelName, map: mapName } = toModelName(table.name);
+	const fieldNameMap = fieldNamesByTable.get(table.name);
+	const pkColumns = new Set(table.primaryKey?.columns ?? []);
+	const isSinglePk = pkColumns.size === 1;
+	const singlePkConstraintName = isSinglePk ? table.primaryKey?.name : void 0;
+	const uniqueColumns = /* @__PURE__ */ new Map();
+	for (const unique of table.uniques) if (unique.columns.length === 1) {
+		const [columnName = ""] = unique.columns;
+		const existingConstraintName = uniqueColumns.get(columnName);
+		if (!uniqueColumns.has(columnName) || existingConstraintName === void 0 && unique.name) uniqueColumns.set(columnName, unique.name);
+	}
+	const fields = [];
+	for (const column of Object.values(table.columns)) fields.push(buildScalarField(column, table, typeMap, enumNameMap, fieldNameMap, namedTypes, defaultMapping, rawDefaultParser, pkColumns, isSinglePk, singlePkConstraintName, uniqueColumns));
+	const usedFieldNames = new Set(fields.map((field) => field.name));
+	for (const rel of relationFields) fields.push(buildRelationField(rel, table.name, fieldNamesByTable, usedFieldNames));
+	const modelAttributes = [];
+	if (table.primaryKey && table.primaryKey.columns.length > 1) {
+		const pkFieldNames = table.primaryKey.columns.map((columnName) => resolveColumnFieldName(fieldNamesByTable, table.name, columnName));
+		modelAttributes.push(buildModelConstraintAttribute("id", pkFieldNames, table.primaryKey.name));
+	}
+	for (const unique of table.uniques) if (unique.columns.length > 1) {
+		const uniqueFieldNames = unique.columns.map((columnName) => resolveColumnFieldName(fieldNamesByTable, table.name, columnName));
+		modelAttributes.push(buildModelConstraintAttribute("unique", uniqueFieldNames, unique.name));
+	}
+	for (const index of table.indexes) if (!index.unique) {
+		const indexFieldNames = index.columns.map((columnName) => resolveColumnFieldName(fieldNamesByTable, table.name, columnName));
+		modelAttributes.push(buildModelConstraintAttribute("index", indexFieldNames, index.name));
+	}
+	if (mapName) modelAttributes.push(buildMapAttribute("model", mapName));
+	const comment = table.primaryKey ? void 0 : "// WARNING: This table has no primary key in the database";
+	return {
+		kind: "model",
+		name: modelName,
+		fields,
+		attributes: modelAttributes,
+		span: SYNTHETIC_SPAN,
+		...comment !== void 0 ? { comment } : {}
+	};
+}
+function buildScalarField(column, table, typeMap, enumNameMap, fieldNameMap, namedTypes, defaultMapping, rawDefaultParser, pkColumns, isSinglePk, singlePkConstraintName, uniqueColumns) {
+	const resolvedField = fieldNameMap?.get(column.name);
+	const fieldName = resolvedField?.fieldName ?? toFieldName(column.name).name;
+	const fieldMap = resolvedField?.fieldMap;
+	const resolution = typeMap.resolve(column.nativeType, table.annotations);
+	if ("unsupported" in resolution) {
+		const attrs = [];
+		if (fieldMap !== void 0) attrs.push(buildMapAttribute("field", fieldMap));
+		return {
+			kind: "field",
+			name: fieldName,
+			typeName: `Unsupported("${escapePslString(resolution.nativeType)}")`,
+			optional: column.nullable,
+			list: false,
+			attributes: attrs,
+			span: SYNTHETIC_SPAN
+		};
+	}
+	let typeName = resolution.pslType;
+	const enumPslName = enumNameMap.get(column.nativeType);
+	if (enumPslName) typeName = enumPslName;
+	if (resolution.nativeTypeAttribute && !enumPslName) typeName = resolveNamedTypeName(namedTypes, resolution);
+	const attributes = [];
+	const isId = isSinglePk && pkColumns.has(column.name);
+	if (isId) attributes.push(buildSimpleConstraintFieldAttribute("id", singlePkConstraintName));
+	if (column.default !== void 0) {
+		const parsed = parseColumnDefault(column.default, column.nativeType, rawDefaultParser);
+		if (parsed) {
+			const result = mapDefault(parsed, defaultMapping);
+			if ("attribute" in result) attributes.push(parseDefaultAttributeString(result.attribute));
+		}
+	}
+	if (uniqueColumns.has(column.name) && !isId) {
+		const uniqueConstraintName = uniqueColumns.get(column.name);
+		attributes.push(buildSimpleConstraintFieldAttribute("unique", uniqueConstraintName));
+	}
+	if (fieldMap !== void 0) attributes.push(buildMapAttribute("field", fieldMap));
+	return {
+		kind: "field",
+		name: fieldName,
+		typeName,
+		optional: column.nullable,
+		list: false,
+		attributes,
+		span: SYNTHETIC_SPAN
+	};
+}
+function buildRelationField(rel, hostTableName, fieldNamesByTable, usedFieldNames) {
+	const fieldName = createUniqueFieldName(rel.fieldName, usedFieldNames);
+	usedFieldNames.add(fieldName);
+	const args = [];
+	if (rel.fields && rel.references) {
+		if (rel.relationName) args.push(namedArg("name", `"${escapePslString(rel.relationName)}"`));
+		args.push(namedArg("fields", `[${rel.fields.map((columnName) => resolveColumnFieldName(fieldNamesByTable, hostTableName, columnName)).join(", ")}]`));
+		args.push(namedArg("references", `[${rel.references.map((columnName) => resolveColumnFieldName(fieldNamesByTable, rel.referencedTableName ?? "", columnName)).join(", ")}]`));
+		if (rel.onDelete) args.push(namedArg("onDelete", rel.onDelete));
+		if (rel.onUpdate) args.push(namedArg("onUpdate", rel.onUpdate));
+		if (rel.fkName) args.push(namedArg("map", `"${escapePslString(rel.fkName)}"`));
+	} else if (rel.relationName) args.push(namedArg("name", `"${escapePslString(rel.relationName)}"`));
+	const attrs = args.length > 0 ? [buildAttribute("field", "relation", args)] : [];
+	return {
+		kind: "field",
+		name: fieldName,
+		typeName: rel.typeName,
+		optional: rel.optional,
+		list: rel.list,
+		attributes: attrs,
+		span: SYNTHETIC_SPAN
+	};
+}
+function buildModelConstraintAttribute(name, fields, constraintName) {
+	const args = [positionalArg(`[${fields.join(", ")}]`)];
+	if (constraintName !== void 0) args.push(namedArg("map", `"${escapePslString(constraintName)}"`));
+	return buildAttribute("model", name, args);
+}
+function buildSimpleConstraintFieldAttribute(name, constraintName) {
+	if (constraintName === void 0) return buildAttribute("field", name, []);
+	return buildAttribute("field", name, [namedArg("map", `"${escapePslString(constraintName)}"`)]);
+}
+function parseDefaultAttributeString(attributeText) {
+	return buildAttribute("field", "default", [positionalArg(attributeText.replace(/^@default\(/, "").replace(/\)$/, ""))]);
+}
+function buildMapAttribute(target, mapName) {
+	return buildAttribute(target, "map", [positionalArg(`"${escapePslString(mapName)}"`)]);
+}
+function buildAttribute(target, name, args) {
+	return {
+		kind: "attribute",
+		target,
+		name,
+		args,
+		span: SYNTHETIC_SPAN
+	};
+}
+function positionalArg(value) {
+	return {
+		kind: "positional",
+		value,
+		span: SYNTHETIC_SPAN
+	};
+}
+function namedArg(name, value) {
+	return {
+		kind: "named",
+		name,
+		value,
+		span: SYNTHETIC_SPAN
+	};
+}
+function buildEnum(name, values) {
+	const attrs = [];
+	if (name.map) attrs.push(buildMapAttribute("enum", name.map));
+	return {
+		kind: "enum",
+		name: name.name,
+		values: values.map((value) => ({
+			kind: "enumValue",
+			name: value,
+			span: SYNTHETIC_SPAN
+		})),
+		attributes: attrs,
+		span: SYNTHETIC_SPAN
+	};
+}
+function buildNamedTypeDeclaration(entry) {
+	const attribute = buildAttribute("namedType", entry.nativeTypeAttribute.name, (entry.nativeTypeAttribute.args ?? []).map(positionalArg));
+	return {
+		kind: "namedType",
+		name: entry.name,
+		baseType: entry.baseType,
+		attributes: [attribute],
+		span: SYNTHETIC_SPAN
+	};
+}
+function escapePslString(value) {
+	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+}
+/**
+* Resolves a `SqlColumnIR.default` value into a normalized {@link ColumnDefault}.
+*
+* `SqlSchemaIR` types the column default as `string` (a raw database default
+* expression). Some legacy fixtures and tests still pass already-normalized
+* `ColumnDefault` objects in the same slot, so we accept either shape
+* defensively at runtime.
+*/
+function parseColumnDefault(value, nativeType, rawDefaultParser) {
+	if (typeof value === "string") return rawDefaultParser ? rawDefaultParser(value, nativeType) : void 0;
+	if (value !== null && typeof value === "object" && "kind" in value) return value;
+}
+function buildFieldNamesByTable(tables) {
+	const fieldNamesByTable = /* @__PURE__ */ new Map();
+	for (const table of Object.values(tables)) {
+		const assignmentOrder = [...Object.values(table.columns).map((column, index) => {
+			const { name, map } = toFieldName(column.name);
+			return {
+				columnName: column.name,
+				desiredFieldName: name,
+				fieldMap: map,
+				index
+			};
+		})].sort((left, right) => {
+			const mapComparison = Number(left.fieldMap !== void 0) - Number(right.fieldMap !== void 0);
+			if (mapComparison !== 0) return mapComparison;
+			return left.index - right.index;
+		});
+		const usedFieldNames = /* @__PURE__ */ new Set();
+		const tableFieldNames = /* @__PURE__ */ new Map();
+		for (const column of assignmentOrder) {
+			const fieldName = createUniqueFieldName(column.desiredFieldName, usedFieldNames);
+			usedFieldNames.add(fieldName);
+			tableFieldNames.set(column.columnName, {
+				fieldName,
+				fieldMap: column.fieldMap
+			});
+		}
+		fieldNamesByTable.set(table.name, tableFieldNames);
+	}
+	return fieldNamesByTable;
+}
+function resolveColumnFieldName(fieldNamesByTable, tableName, columnName) {
+	return fieldNamesByTable.get(tableName)?.get(columnName)?.fieldName ?? toFieldName(columnName).name;
+}
+function createUniqueFieldName(desiredName, usedFieldNames) {
+	if (!usedFieldNames.has(desiredName)) return desiredName;
+	let counter = 2;
+	while (usedFieldNames.has(`${desiredName}${counter}`)) counter++;
+	return `${desiredName}${counter}`;
+}
+function buildTopLevelNameMap(sources, normalize, kind, sourceKind) {
+	const results = /* @__PURE__ */ new Map();
+	const normalizedToSources = /* @__PURE__ */ new Map();
+	for (const source of sources) {
+		const normalized = normalize(source);
+		results.set(source, normalized);
+		normalizedToSources.set(normalized.name, [...normalizedToSources.get(normalized.name) ?? [], source]);
+	}
+	const duplicates = [...normalizedToSources.entries()].filter(([, conflictingSources]) => conflictingSources.length > 1);
+	if (duplicates.length > 0) {
+		const details = duplicates.map(([normalizedName, conflictingSources]) => `- ${kind} "${normalizedName}" from ${sourceKind}s ${conflictingSources.map((source) => `"${source}"`).join(", ")}`);
+		throw new Error(`PSL ${kind} name collisions detected:\n${details.join("\n")}`);
+	}
+	return results;
+}
+function assertNoCrossKindNameCollisions(modelNames, enumNames) {
+	const enumSourceByName = new Map([...enumNames].map(([source, result]) => [result.name, source]));
+	const collisions = [...modelNames.entries()].map(([tableName, result]) => {
+		const enumSource = enumSourceByName.get(result.name);
+		return enumSource ? `- identifier "${result.name}" from table "${tableName}" collides with enum type "${enumSource}"` : void 0;
+	}).filter((detail) => detail !== void 0);
+	if (collisions.length > 0) throw new Error(`PSL top-level name collisions detected:\n${collisions.join("\n")}`);
+}
+function createReservedNamedTypeNames(modelNames, enumNames) {
+	const reservedNames = new Set(PSL_SCALAR_TYPE_NAMES);
+	for (const result of modelNames.values()) reservedNames.add(result.name);
+	for (const result of enumNames.values()) reservedNames.add(result.name);
+	return reservedNames;
+}
+function seedNamedTypeRegistry(schemaIR, typeMap, enumNameMap, reservedNames) {
+	const seeds = /* @__PURE__ */ new Map();
+	for (const tableName of Object.keys(schemaIR.tables).sort()) {
+		const table = schemaIR.tables[tableName];
+		if (!table) continue;
+		for (const columnName of Object.keys(table.columns).sort()) {
+			const column = table.columns[columnName];
+			if (!column) continue;
+			const resolution = typeMap.resolve(column.nativeType, table.annotations);
+			if ("unsupported" in resolution || enumNameMap.has(column.nativeType) || !resolution.nativeTypeAttribute) continue;
+			const signatureKey = createNamedTypeSignatureKey(resolution);
+			if (!seeds.has(signatureKey)) seeds.set(signatureKey, {
+				baseType: resolution.pslType,
+				desiredName: toNamedTypeName(column.name),
+				nativeTypeAttribute: resolution.nativeTypeAttribute
+			});
+		}
+	}
+	const registry = {
+		entriesByKey: /* @__PURE__ */ new Map(),
+		usedNames: new Set(reservedNames)
+	};
+	const sortedSeeds = [...seeds.entries()].sort((left, right) => {
+		const desiredNameComparison = left[1].desiredName.localeCompare(right[1].desiredName);
+		if (desiredNameComparison !== 0) return desiredNameComparison;
+		return left[0].localeCompare(right[0]);
+	});
+	for (const [signatureKey, seed] of sortedSeeds) {
+		const name = createUniqueFieldName(seed.desiredName, registry.usedNames);
+		registry.entriesByKey.set(signatureKey, {
+			name,
+			baseType: seed.baseType,
+			nativeTypeAttribute: seed.nativeTypeAttribute
+		});
+		registry.usedNames.add(name);
+	}
+	return registry;
+}
+function resolveNamedTypeName(registry, resolution) {
+	const key = createNamedTypeSignatureKey(resolution);
+	const existing = registry.entriesByKey.get(key);
+	if (existing) return existing.name;
+	throw new Error(`Named type registry was not seeded for native type "${resolution.nativeType}"`);
+}
+function createNamedTypeSignatureKey(resolution) {
+	return JSON.stringify({
+		baseType: resolution.pslType,
+		nativeTypeAttribute: resolution.nativeTypeAttribute ? {
+			name: resolution.nativeTypeAttribute.name,
+			args: resolution.nativeTypeAttribute.args ?? null
+		} : null
+	});
+}
+function topologicalSort(models, tables, modelNameMap) {
+	const modelByName = /* @__PURE__ */ new Map();
+	for (const model of models) modelByName.set(model.name, model);
+	const deps = /* @__PURE__ */ new Map();
+	const tableToModel = /* @__PURE__ */ new Map();
+	for (const tableName of Object.keys(tables)) {
+		const modelName = modelNameMap.get(tableName);
+		tableToModel.set(tableName, modelName);
+		deps.set(modelName, /* @__PURE__ */ new Set());
+	}
+	for (const [tableName, table] of Object.entries(tables)) {
+		const modelName = tableToModel.get(tableName);
+		for (const fk of table.foreignKeys) {
+			const refModelName = tableToModel.get(fk.referencedTable);
+			if (refModelName && refModelName !== modelName) deps.get(modelName).add(refModelName);
+		}
+	}
+	const result = [];
+	const visited = /* @__PURE__ */ new Set();
+	const visiting = /* @__PURE__ */ new Set();
+	const sortedNames = [...deps.keys()].sort();
+	function visit(name) {
+		if (visited.has(name)) return;
+		if (visiting.has(name)) return;
+		visiting.add(name);
+		const sortedDeps = [...deps.get(name)].sort();
+		for (const dep of sortedDeps) visit(dep);
+		visiting.delete(name);
+		visited.add(name);
+		result.push(modelByName.get(name));
+	}
+	for (const name of sortedNames) visit(name);
+	return result;
+}
+
+//#endregion
 //#region src/core/control-instance.ts
 function extractCodecTypeIdsFromContract(contract) {
 	const typeIds = /* @__PURE__ */ new Set();
@@ -49,7 +1055,7 @@ function createVerifyResult(options) {
 	return result;
 }
 function isSqlControlAdapter(value) {
-	return typeof value === "object" && value !== null && "introspect" in value && typeof value.introspect === "function";
+	return typeof value === "object" && value !== null && "introspect" in value && typeof value.introspect === "function" && "readMarker" in value && typeof value.readMarker === "function";
 }
 function buildSqlTypeMetadataRegistry(options) {
 	const { target, adapter, extensionPacks: extensions } = options;
@@ -83,6 +1089,11 @@ function createSqlFamilyInstance(stack) {
 		adapter,
 		extensionPacks: extensions
 	});
+	const getControlAdapter = () => {
+		const controlAdapter = adapter.create(stack);
+		if (!isSqlControlAdapter(controlAdapter)) throw new Error("Adapter does not implement SqlControlAdapter (missing introspect or readMarker)");
+		return controlAdapter;
+	};
 	return {
 		familyId: "sql",
 		codecTypeImports,
@@ -99,7 +1110,7 @@ function createSqlFamilyInstance(stack) {
 			const contractStorageHash = contract.storage.storageHash;
 			const contractProfileHash = contract.profileHash;
 			const contractTarget = contract.target;
-			const marker = await readMarker(driver);
+			const marker = await getControlAdapter().readMarker(driver);
 			let missingCodecs;
 			let codecCoverageSkipped = false;
 			const supportedTypeIds = collectSupportedCodecTypeIds([
@@ -186,8 +1197,7 @@ function createSqlFamilyInstance(stack) {
 		async schemaVerify(options) {
 			const { driver, contract: contractInput, strict, context, frameworkComponents } = options;
 			const contract = validateContract(contractInput, emptyCodecLookup);
-			const controlAdapter = adapter.create(stack);
-			if (!isSqlControlAdapter(controlAdapter)) throw new Error("Adapter does not implement SqlControlAdapter.introspect()");
+			const controlAdapter = getControlAdapter();
 			return verifySqlSchema({
 				contract,
 				schema: await controlAdapter.introspect(driver, contractInput),
@@ -208,7 +1218,7 @@ function createSqlFamilyInstance(stack) {
 			const contractTarget = contract.target;
 			await driver.query(ensureSchemaStatement.sql, ensureSchemaStatement.params);
 			await driver.query(ensureTableStatement.sql, ensureTableStatement.params);
-			const existingMarker = await readMarker(driver);
+			const existingMarker = await getControlAdapter().readMarker(driver);
 			let markerCreated = false;
 			let markerUpdated = false;
 			let previousHashes;
@@ -268,13 +1278,16 @@ function createSqlFamilyInstance(stack) {
 			};
 		},
 		async readMarker(options) {
-			return readMarker(options.driver);
+			return getControlAdapter().readMarker(options.driver);
 		},
 		async introspect(options) {
-			const { driver, contract } = options;
-			const controlAdapter = adapter.create(stack);
-			if (!isSqlControlAdapter(controlAdapter)) throw new Error("Adapter does not implement SqlControlAdapter.introspect()");
-			return controlAdapter.introspect(driver, contract);
+			return getControlAdapter().introspect(options.driver, options.contract);
+		},
+		inferPslContract(schemaIR) {
+			return sqlSchemaIrToPslAst(schemaIR);
+		},
+		toOperationPreview(operations) {
+			return sqlOperationsToPreview(operations);
 		},
 		toSchemaView(schema) {
 			const tableNodes = Object.entries(schema.tables).map(([tableName, table]) => {
@@ -597,6 +1610,7 @@ function createMigrationPlan(options) {
 		...options.origin !== void 0 ? { origin: options.origin ? Object.freeze({ ...options.origin }) : null } : {},
 		destination: Object.freeze({ ...options.destination }),
 		operations: freezeOperations(options.operations),
+		providedInvariants: Object.freeze([...options.providedInvariants]),
 		...options.meta ? { meta: cloneRecord(options.meta) } : {}
 	});
 }