@prisma-next/family-sql 0.16.0-dev.30 → 0.16.0-dev.32

package/dist/control.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"control.d.mts","names":[],"sources":["../src/core/control-instance.ts","../src/core/control-descriptor.ts","../src/core/assembly.ts","../src/core/control-target-descriptor.ts","../src/core/migrations/contract-to-schema-ir.ts","../src/core/migrations/control-policy.ts","../src/core/migrations/field-event-planner.ts","../src/core/migrations/native-type-expander.ts","../src/core/migrations/plan-helpers.ts","../src/core/migrations/policies.ts","../src/core/timestamp-now-generator.ts","../src/exports/control.ts"],"mappings":";;;;;;;;;;;;;;UAuLU;WACC;WACA;WACA;WACA;;KAGN,0BAA0B,YAAY;UAEjC;WACC,kBAAkB,cAAc;WAChC,cAAc;WACd,sBAAsB;;UAGhB,iCACP,6BAA6B,kBACnC,kBAAkB,kBAClB,wBAAwB,kBACxB,yBACA;;;;;;;;;EASF,oBAAoB,wBAAwB;EAE5C,OAAO;aACI,QAAQ;aACR;aACA;aACA;aACA;MACP,QAAQ;;;;;;;;;;EAWZ,aAAa;aACF;aACA,QAAQ;aACR;aACA,qBAAqB,cAAc;MAC1C;;;;;;;;;;EAWJ,2BAA2B,OAAO,kBAAkB;;;;;;;;EASpD,mBAAmB,OAAO;EAE1B,KAAK;aACM,QAAQ;aACR;aACA;aACA;MACP,QAAQ;EAEZ,WAAW;aACA,QAAQ;aACR;MACP,QAAQ;EAEZ,iBAAiB,UAAU,kBAAkB;EAE7C,SACE,KAAK,cAAc,SACnB,SAAS,0BACR,QAAQ;;;;;;EAOX,WAAW;aACA,QAAQ;aACR;aACA;eACE;eACA;eACA;;MAET;;;;;EAMJ,aAAa;aACF,QAAQ;aACR;aACA;aACA;eACE;eACA;eACA;;MAET;;;;;EAMJ,iBAAiB;aACN,QAAQ;aACR;aACA;eACE;eACA;eACA;eACA;eACA;eACA;eACA;;MAET;EAEJ,yCAAyC;EAEzC,mBAAmB,qBAAqB,6BAA2B;;;;cC5TxD,+BACA,+BAA+B;WAEjC;WACA;WACA;WACA;WACA,UAAU;WACV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAOT,OAAO,0BACL,OAAO,oBAAoB,aAC1B;;;;iBCNW,yBACd,aAAa,cAAc,iDAC1B,YAAY;;;;;;;;;;;;;UCEE;WACN;WACA,UAAU,SAAS;;UAGb,2BACf,0BACA,gBACA,kBAAkB,SAAS,cAAc,SAAS,qBAC1C,kCAAkC,WAAW;WAC5C,wBAAwB;;;;;;;WAOxB,oBAAoB,mBAAmB;;;;;;;WAOvC,gBAAgB,eAAe,WAAW;;;;;;;;;;WAU1C,oBACP,QAAQ,iBACR,8BAA8B,gCAC3B;;;;;;;;WAQI,YAAY;;;;;;;;;;;WAWZ,6BAA6B,qBAAqB;;;;;;;;;;;;WAYlD,qBAAqB;EAC9B,cAAc,SAAS,kBAAkB,aAAa,oBAAoB;EAC1E,aAAa,QAAQ,2BAA2B,mBAAmB;;;;;;;;;;;;;;KCvDzD,sBAAsB;WACvB;WACA;WACA,aAAa;;;;;;;;;;;KAYZ,mBAAmB,KAAK,eAAe,QAAQ;;;;;;;;;;KAW/C,mBAAmB,KAAK,eAAe,+BAA+B;;;;;;;;;;;;;;KAetE,+BAA+B,SAAS,YAAY;iBAyIhD,sBACd;WAAgB;WAA8B;GAC9C,SAAS,YACT;;;;;;;;;;iBA8Mc,yBACd,MAAM,mBACN,IAAI,sBACM;UA8CK;WACN;WACA,mBAAmB;WACnB,gBAAgB;WAChB,iBAAiB;;;;;;;;WAQjB,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BxB,4BACd,SAAS,YACT,qBACA,SAAS,4BACR;iBAyBa,mBACd,UAAU,SAAS,oBACnB,SAAS,4BACR;;;;;;;;;;;;;;;UCphBc;WACN;WACA;WACA;WACA;WACA,4BAA4B;;;;;;;;WAQ5B;;;;;;;;;;;;;;;UAgBM;WACN,SAAS;WACT,QAAQ;WACR;WACA;;;;;;;;;iBAUK,qBACd,SAAS,kCACT,sBAAsB,4BACrB;;;;;;;;;;;;;;iBA6Ca,8BAA8B,OAAO;WAC1C,gBAAgB;WAChB,UAAU,SAAS;WACnB,8BAA8B,MAAM,UAAU;WAC9C,qBAAqB,MAAM;;WAE3B,eAAe;WACf,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmDlB,+BAA+B,QAAQ;WAC5C,iBAAiB;WACjB,UAAU,SAAS;;;;;WAKnB,8BAA8B,OAAO,WAAW;;;;;;;;;;;;WAYhD,6BAA6B,OAAO;;WAEpC,oBAAoB;WACpB,uBAAuB;;;;UClKjB;;;;;WAKN,eAAe,SAAS;;;;WAIxB,aAAa,SAAS;;;;;;;;;;WAUtB,YAAY,oBAAoB;;iBAa3B,yBACd,SAAS,2CACC;;;;;;;;;iBCtDI,wBACd,sBAAsB,cAAc,mDAA8C;WAOvE;WACA;WACA,aAAa;;;;iBC4EV,oBAAoB,gBAClC,SAAS,8BAA8B,kBACtC,iBAAiB;iBAcJ,eAAe,gBAC7B,MAAM,iBAAiB,iBACvB,oBAAoB,uBACnB,wBAAwB;iBAsBX,eAAe,oBAAoB,uBAAuB;;;;iBAoB1D,cAAc;EAC5B;EACA;IACE,GAAG;;;;iBAYS,cACd,MAAM,6BACN,iBACA;EAAY;EAAc,OAAO;IAChC,MAAM;;;;;;cC1KI,sBAAsB;;;;;;;;;;;;;;iBCsBnB,iCAAiC;;;;;;;;;;;iBAqBjC,+BACR,8BACA,2BACN;WAAkB,SAAS;WAAkB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsE3C,uCACR,8BACA,2BACN;WAAkB,SAAS;WAAkB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsB3C,0BACR,8BACA,2BACN;WAAkB,SAAS;WAAkB,YAAY"}
+{"version":3,"file":"control.d.mts","names":[],"sources":["../src/core/control-instance.ts","../src/core/control-descriptor.ts","../src/core/assembly.ts","../src/core/control-target-descriptor.ts","../src/core/migrations/contract-to-schema-ir.ts","../src/core/migrations/control-policy.ts","../src/core/migrations/field-event-planner.ts","../src/core/migrations/native-type-expander.ts","../src/core/migrations/plan-helpers.ts","../src/core/migrations/policies.ts","../src/core/timestamp-now-generator.ts","../src/exports/control.ts"],"mappings":"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"}

package/dist/control.mjs

@@ -1,7 +1,8 @@
 import { i as sqlFamilyPslBlockDescriptors, n as sqlFamilyAuthoringFieldPresets, r as sqlFamilyEntityTypes, t as sqlFamilyAuthoringTypes } from "./authoring-type-constructors-CXd-8ydc.mjs";
 import { n as classifyDiffSubjectGranularity, o as verifySqlSchemaByDiff, s as extractCodecControlHooks, t as classifyDiffEntityKind } from "./schema-verify-DY21bMwy.mjs";
-import { t as SqlContractSerializer } from "./sql-contract-serializer-C75cfMSS.mjs";
-import { t as collectSupportedCodecTypeIds } from "./verify-C-G0obRm.mjs";
+import { t as sqlFamilyError } from "./errors-ZGKTAYsm.mjs";
+import { t as SqlContractSerializer } from "./sql-contract-serializer-othnJUZ_.mjs";
+import { t as collectSupportedCodecTypeIds } from "./verify-DuuJFiTm.mjs";
 import { a as timestampNowControlDescriptor, i as temporalCodecPresetWithPrecision, n as temporalAuthoringPresets, r as temporalCodecPreset } from "./timestamp-now-generator-DRXygu32.mjs";
 import { sqlEmission } from "@prisma-next/sql-contract-emitter";
 import { blindCast } from "@prisma-next/utils/casts";
@@ -10,6 +11,7 @@ import { isPlainRecord } from "@prisma-next/framework-components/ir";
 import { assertDescriptorSelfConsistency } from "@prisma-next/migration-tools/spaces";
 import { sqlContractCanonicalizationHooks } from "@prisma-next/sql-contract/canonicalization-hooks";
 import { ifDefined } from "@prisma-next/utils/defined";
+import { InternalError } from "@prisma-next/utils/internal-error";
 import { effectiveControlPolicy } from "@prisma-next/contract/types";
 import { StorageTable, isStorageTypeInstance } from "@prisma-next/sql-contract/types";
 import { RelationalSchemaNodeKind, SqlSchemaIR, SqlTableIR } from "@prisma-next/sql-schema-ir/types";
@@ -48,6 +50,16 @@ function sqlOperationsToPreview(operations) {
 }
 //#endregion
 //#region src/core/control-instance.ts
+function missingDescriptorOperationError(targetId, operation) {
+	return sqlFamilyError("CONTRACT.PACK_CONTRIBUTION_INVALID", `SQL target "${targetId}" is missing the required ${operation} descriptor operation`, {
+		why: `The target descriptor does not contribute the ${operation} operation the SQL family requires for this call.`,
+		fix: `Use a target package whose control descriptor implements ${operation}.`,
+		meta: {
+			targetId,
+			operation
+		}
+	});
+}
 function extractCodecTypeIdsFromContract(contract) {
 	const typeIds = /* @__PURE__ */ new Set();
 	if (typeof contract === "object" && contract !== null && "storage" in contract && typeof contract.storage === "object" && contract.storage !== null && "namespaces" in contract.storage && typeof contract.storage.namespaces === "object" && contract.storage.namespaces !== null) {
@@ -176,7 +188,14 @@ function assertNoCrossSpaceFkReverseReferences(extensions) {
 						if (target["spaceId"] === void 0) continue;
 						const targetSpaceId = target["spaceId"];
 						if (typeof targetSpaceId !== "string") continue;
-						if (dependsOnMap.get(targetSpaceId)?.has(ext.id)) throw new Error(`Cross-space FK reverse-reference detected: extension "${ext.id}" has a cross-space FK targeting space "${targetSpaceId}", but "${targetSpaceId}" depends on "${ext.id}". Cross-space FKs must follow the dependency direction (a space can only reference spaces it depends on, not spaces that depend on it).`);
+						if (dependsOnMap.get(targetSpaceId)?.has(ext.id)) throw sqlFamilyError("CONTRACT.FOREIGN_KEY_INVALID", `Cross-space FK reverse-reference detected: extension "${ext.id}" has a cross-space FK targeting space "${targetSpaceId}", but "${targetSpaceId}" depends on "${ext.id}". Cross-space FKs must follow the dependency direction (a space can only reference spaces it depends on, not spaces that depend on it).`, {
+							why: "The foreign key points against the contract-space dependency direction.",
+							fix: "Move the foreign key to the depending space, or restructure the extension dependencies so the referencing space depends on the referenced one.",
+							meta: {
+								extensionId: ext.id,
+								targetSpaceId
+							}
+						});
 					}
 				}
 			}
@@ -184,7 +203,7 @@ function assertNoCrossSpaceFkReverseReferences(extensions) {
 	}
 }
 function createSqlFamilyInstance(stack) {
-	if (!stack.adapter) throw new Error("SQL family requires an adapter descriptor in ControlStack");
+	if (!stack.adapter) throw new InternalError("SQL family requires an adapter descriptor in ControlStack");
 	const target = stack.target;
 	const adapter = stack.adapter;
 	const extensions = stack.extensions;
@@ -323,8 +342,8 @@ function createSqlFamilyInstance(stack) {
 		},
 		verifySchema(options) {
 			const contract = deserializeWithTargetSerializer(options.contract);
-			if (!diffSchema) throw new Error(`SQL target "${target.targetId}" is missing the required diffSchema descriptor operation`);
-			if (!targetGranularityOf) throw new Error(`SQL target "${target.targetId}" is missing the required classifySubjectGranularity descriptor operation`);
+			if (!diffSchema) throw missingDescriptorOperationError(target.targetId, "diffSchema");
+			if (!targetGranularityOf) throw missingDescriptorOperationError(target.targetId, "classifySubjectGranularity");
 			return verifySqlSchemaByDiff({
 				contract,
 				schema: options.schema,
@@ -344,7 +363,7 @@ function createSqlFamilyInstance(stack) {
 		* cannot read; nothing is stamped on the issue or the node.
 		*/
 		classifySubjectGranularity(issue) {
-			if (!targetGranularityOf) throw new Error(`SQL target "${target.targetId}" is missing the required classifySubjectGranularity descriptor operation`);
+			if (!targetGranularityOf) throw missingDescriptorOperationError(target.targetId, "classifySubjectGranularity");
 			return classifyDiffSubjectGranularity(issue, targetGranularityOf);
 		},
 		/**
@@ -355,7 +374,7 @@ function createSqlFamilyInstance(stack) {
 		* capability.
 		*/
 		classifyEntityKind(issue) {
-			if (!targetEntityKindOf) throw new Error(`SQL target "${target.targetId}" is missing the required classifyEntityKind descriptor operation`);
+			if (!targetEntityKindOf) throw missingDescriptorOperationError(target.targetId, "classifyEntityKind");
 			return classifyDiffEntityKind(issue, targetEntityKindOf);
 		},
 		async sign(options) {
@@ -392,7 +411,11 @@ function createSqlFamilyInstance(stack) {
 					if (!await controlAdapter.updateMarker(driver, APP_SPACE_ID, existingStorageHash, {
 						storageHash: contractStorageHash,
 						profileHash: contractProfileHash
-					})) throw new Error("CAS conflict: marker was modified by another process during sign");
+					})) throw sqlFamilyError("MIGRATION.MARKER_CAS_FAILURE", "CAS conflict: marker was modified by another process during sign", {
+						why: "Another process updated the contract marker between the read and the compare-and-swap write.",
+						fix: "Re-run the sign command; if it keeps failing, make sure only one migration process runs at a time.",
+						meta: { space: APP_SPACE_ID }
+					});
 					markerUpdated = true;
 				}
 			}
@@ -446,7 +469,11 @@ function createSqlFamilyInstance(stack) {
 			return getControlAdapter().introspect(options.driver, options.contract);
 		},
 		inferPslContract(schemaIR) {
-			if (!targetInferPslContract) throw new Error(`Target "${target.targetId}" does not support contract infer (no inferPslContract on its descriptor).`);
+			if (!targetInferPslContract) throw sqlFamilyError("CONTRACT.INFER_UNSUPPORTED", `Target "${target.targetId}" does not support contract infer (no inferPslContract on its descriptor).`, {
+				why: "The target descriptor does not provide the inferPslContract hook, so a PSL contract cannot be inferred from the database schema.",
+				fix: "Use a target package that supports contract infer, or author the contract instead of inferring it.",
+				meta: { targetId: target.targetId }
+			});
 			return targetInferPslContract(schemaIR, describedContracts);
 		},
 		lowerAst(ast, context) {
@@ -613,13 +640,17 @@ function buildColumnCodecRef(resolved, many) {
 function resolveColumnTypeMetadata(column, storageTypes) {
 	if (!column.typeRef) return column;
 	const referenced = storageTypes[column.typeRef];
-	if (!referenced) throw new Error(`Column references storage type "${column.typeRef}" but it is not defined in storage.types.`);
+	if (!referenced) throw sqlFamilyError("CONTRACT.TYPE_UNKNOWN", `Column references storage type "${column.typeRef}" but it is not defined in storage.types.`, {
+		why: "The column typeRef does not resolve to any entry in the contract storage.types map.",
+		fix: "Regenerate the contract from its authoring source; do not hand-edit contract JSON.",
+		meta: { typeRef: column.typeRef }
+	});
 	if (isStorageTypeInstance(referenced)) return {
 		codecId: referenced.codecId,
 		nativeType: referenced.nativeType,
 		typeParams: referenced.typeParams
 	};
-	throw new Error(`Storage type "${column.typeRef}" has an unknown polymorphic kind; expected a codec-typed StorageTypeInstance.`);
+	throw new InternalError(`Storage type "${column.typeRef}" has an unknown polymorphic kind; expected a codec-typed StorageTypeInstance.`);
 }
 /**
 * Resolves a `ValueSetRef` to its permitted values from the contract storage.
@@ -636,11 +667,34 @@ function allStrings(values) {
 }
 function resolveValueSetValues(ref, storage, contextLabel) {
 	const ns = storage.namespaces[ref.namespaceId];
-	if (!ns) throw new Error(`resolveValueSetValues: namespace "${ref.namespaceId}" not found in storage (${contextLabel})`);
+	if (!ns) throw sqlFamilyError("CONTRACT.NAMESPACE_UNKNOWN", `resolveValueSetValues: namespace "${ref.namespaceId}" not found in storage (${contextLabel})`, {
+		why: "A value-set reference names a namespace the contract storage does not declare.",
+		fix: "Regenerate the contract from its authoring source; do not hand-edit contract JSON.",
+		meta: {
+			namespaceId: ref.namespaceId,
+			context: contextLabel
+		}
+	});
 	const valueSet = ns.entries.valueSet?.[ref.entityName];
-	if (!valueSet) throw new Error(`resolveValueSetValues: value-set "${ref.entityName}" not found in namespace "${ref.namespaceId}" (${contextLabel})`);
+	if (!valueSet) throw sqlFamilyError("CONTRACT.ENUM_UNKNOWN", `resolveValueSetValues: value-set "${ref.entityName}" not found in namespace "${ref.namespaceId}" (${contextLabel})`, {
+		why: "A value-set reference names an entry its namespace does not declare.",
+		fix: "Regenerate the contract from its authoring source; do not hand-edit contract JSON.",
+		meta: {
+			valueSet: ref.entityName,
+			namespaceId: ref.namespaceId,
+			context: contextLabel
+		}
+	});
 	const values = valueSet.values;
-	if (!allStrings(values)) throw new Error(`resolveValueSetValues: value-set "${ref.entityName}" in namespace "${ref.namespaceId}" has a non-string value; numeric-enum CHECK constraints are not yet supported (${contextLabel})`);
+	if (!allStrings(values)) throw sqlFamilyError("CONTRACT.ENUM_INVALID", `resolveValueSetValues: value-set "${ref.entityName}" in namespace "${ref.namespaceId}" has a non-string value; numeric-enum CHECK constraints are not yet supported (${contextLabel})`, {
+		why: "Only string value-sets can be rendered as CHECK constraints; this value-set carries a non-string value.",
+		fix: "Use string enum values, or drop the CHECK-constrained enum until numeric enums are supported.",
+		meta: {
+			valueSet: ref.entityName,
+			namespaceId: ref.namespaceId,
+			context: contextLabel
+		}
+	});
 	return values;
 }
 /**
@@ -844,7 +898,11 @@ function detectDestructiveChanges(from, to) {
 * per-table fields.
 */
 function contractNamespaceToSchemaIR(storage, namespaceId, options) {
-	if (options.annotationNamespace.length === 0) throw new Error("annotationNamespace must be a non-empty string");
+	if (options.annotationNamespace.length === 0) throw sqlFamilyError("CONTRACT.PACK_CONTRIBUTION_INVALID", "annotationNamespace must be a non-empty string", {
+		why: "The calling target pack passed an empty annotationNamespace to the contract-to-schema-IR projection.",
+		fix: "Fix the target pack to pass its non-empty annotation namespace (e.g. \"pg\").",
+		meta: { option: "annotationNamespace" }
+	});
 	const namespace = storage.namespaces[namespaceId];
 	if (!namespace) return new SqlSchemaIR({ tables: {} });
 	const storageTypes = { ...storage.types ?? {} };
@@ -856,7 +914,11 @@ function contractNamespaceToSchemaIR(storage, namespaceId, options) {
 	return new SqlSchemaIR({ tables });
 }
 function contractToSchemaIR(contract, options) {
-	if (options.annotationNamespace.length === 0) throw new Error("annotationNamespace must be a non-empty string");
+	if (options.annotationNamespace.length === 0) throw sqlFamilyError("CONTRACT.PACK_CONTRIBUTION_INVALID", "annotationNamespace must be a non-empty string", {
+		why: "The calling target pack passed an empty annotationNamespace to the contract-to-schema-IR projection.",
+		fix: "Fix the target pack to pass its non-empty annotation namespace (e.g. \"pg\").",
+		meta: { option: "annotationNamespace" }
+	});
 	if (!contract) return new SqlSchemaIR({ tables: {} });
 	const storage = contract.storage;
 	const storageTypes = { ...storage.types ?? {} };
@@ -864,7 +926,11 @@ function contractToSchemaIR(contract, options) {
 	for (const ns of Object.values(storage.namespaces)) for (const [tableName, tableDefRaw] of Object.entries(ns.entries.table ?? {})) {
 		StorageTable.assert(tableDefRaw, `namespaces.${ns.id}.entries.table.${tableName}`);
 		const tableDef = tableDefRaw;
-		if (tables[tableName] !== void 0) throw new Error(`contractToSchemaIR: duplicate SQL table name "${tableName}" across namespaces (ambiguous for flat SqlSchemaIR.tables).`);
+		if (tables[tableName] !== void 0) throw sqlFamilyError("CONTRACT.TABLE_AMBIGUOUS", `contractToSchemaIR: duplicate SQL table name "${tableName}" across namespaces (ambiguous for flat SqlSchemaIR.tables).`, {
+			why: "Two namespaces declare a table with the same name, which is ambiguous for the flat schema-IR table map.",
+			fix: "Rename one of the tables so every table name is unique across namespaces.",
+			meta: { table: tableName }
+		});
 		tables[tableName] = convertTable(tableName, tableDef, storageTypes, options.expandNativeType, options.renderDefault, options.resolveDefault, storage);
 	}
 	return new SqlSchemaIR({