@prisma-next/sql-contract-ts 0.3.0-pr.93.5 → 0.3.0-pr.94.2

package/dist/contract-CbxDA5bF.mjs

@@ -0,0 +1,331 @@
+import { type } from "arktype";
+
+//#region src/contract.ts
+/**
+* Structural validation schema for SqlContract using Arktype.
+* This validates the shape and types of the contract structure.
+*/
+const StorageColumnSchema = type.declare().type({
+	nativeType: "string",
+	codecId: "string",
+	nullable: "boolean"
+});
+const PrimaryKeySchema = type.declare().type({
+	columns: type.string.array().readonly(),
+	"name?": "string"
+});
+const UniqueConstraintSchema = type.declare().type({
+	columns: type.string.array().readonly(),
+	"name?": "string"
+});
+const IndexSchema = type.declare().type({
+	columns: type.string.array().readonly(),
+	"name?": "string"
+});
+const ForeignKeyReferencesSchema = type.declare().type({
+	table: "string",
+	columns: type.string.array().readonly()
+});
+const ForeignKeySchema = type.declare().type({
+	columns: type.string.array().readonly(),
+	references: ForeignKeyReferencesSchema,
+	"name?": "string"
+});
+const StorageTableSchema = type.declare().type({
+	columns: type({ "[string]": StorageColumnSchema }),
+	"primaryKey?": PrimaryKeySchema,
+	uniques: UniqueConstraintSchema.array().readonly(),
+	indexes: IndexSchema.array().readonly(),
+	foreignKeys: ForeignKeySchema.array().readonly()
+});
+const StorageSchema = type.declare().type({ tables: type({ "[string]": StorageTableSchema }) });
+const ModelFieldSchema = type.declare().type({ column: "string" });
+const ModelStorageSchema = type.declare().type({ table: "string" });
+const ModelSchema = type.declare().type({
+	storage: ModelStorageSchema,
+	fields: type({ "[string]": ModelFieldSchema }),
+	relations: type({ "[string]": "unknown" })
+});
+/**
+* Complete SqlContract schema for structural validation.
+* This validates the entire contract structure at once.
+*/
+const SqlContractSchema = type({
+	"schemaVersion?": "'1'",
+	target: "string",
+	targetFamily: "'sql'",
+	coreHash: "string",
+	"profileHash?": "string",
+	"capabilities?": "Record<string, Record<string, boolean>>",
+	"extensionPacks?": "Record<string, unknown>",
+	"meta?": "Record<string, unknown>",
+	"sources?": "Record<string, unknown>",
+	models: type({ "[string]": ModelSchema }),
+	storage: StorageSchema
+});
+/**
+* Validates the structural shape of a SqlContract using Arktype.
+*
+* **Responsibility: Validation Only**
+* This function validates that the contract has the correct structure and types.
+* It does NOT normalize the contract - normalization must happen in the contract builder.
+*
+* The contract passed to this function must already be normalized (all required fields present).
+* If normalization is needed, it should be done by the contract builder before calling this function.
+*
+* This ensures all required fields are present and have the correct types.
+*
+* @param value - The contract value to validate (typically from a JSON import)
+* @returns The validated contract if structure is valid
+* @throws Error if the contract structure is invalid
+*/
+function validateContractStructure(value) {
+	const rawValue = value;
+	if (rawValue.targetFamily !== void 0 && rawValue.targetFamily !== "sql")
+ /* c8 ignore next */
+	throw new Error(`Unsupported target family: ${rawValue.targetFamily}`);
+	const contractResult = SqlContractSchema(value);
+	if (contractResult instanceof type.errors) {
+		const messages = contractResult.map((p) => p.message).join("; ");
+		throw new Error(`Contract structural validation failed: ${messages}`);
+	}
+	return contractResult;
+}
+/**
+* Computes mapping dictionaries from models and storage structures.
+* Assumes valid input - validation happens separately in validateContractLogic().
+*
+* @param models - Models object from contract
+* @param storage - Storage object from contract
+* @param existingMappings - Existing mappings from contract input (optional)
+* @returns Computed mappings dictionary
+*/
+function computeMappings(models, _storage, existingMappings) {
+	const modelToTable = {};
+	const tableToModel = {};
+	const fieldToColumn = {};
+	const columnToField = {};
+	for (const [modelName, model] of Object.entries(models)) {
+		const tableName = model.storage.table;
+		modelToTable[modelName] = tableName;
+		tableToModel[tableName] = modelName;
+		const modelFieldToColumn = {};
+		for (const [fieldName, field] of Object.entries(model.fields)) {
+			const columnName = field.column;
+			modelFieldToColumn[fieldName] = columnName;
+			if (!columnToField[tableName]) columnToField[tableName] = {};
+			columnToField[tableName][columnName] = fieldName;
+		}
+		fieldToColumn[modelName] = modelFieldToColumn;
+	}
+	return {
+		modelToTable: existingMappings?.modelToTable ?? modelToTable,
+		tableToModel: existingMappings?.tableToModel ?? tableToModel,
+		fieldToColumn: existingMappings?.fieldToColumn ?? fieldToColumn,
+		columnToField: existingMappings?.columnToField ?? columnToField,
+		codecTypes: existingMappings?.codecTypes ?? {},
+		operationTypes: existingMappings?.operationTypes ?? {}
+	};
+}
+/**
+* Validates logical consistency of a **structurally validated** SqlContract.
+* This checks that references (e.g., foreign keys, primary keys, uniques) point to storage objects that already exist.
+* Structural validation is expected to have already completed before this helper runs.
+*
+* @param structurallyValidatedContract - The contract whose structure has already been validated
+* @throws Error if logical validation fails
+*/
+function validateContractLogic(structurallyValidatedContract) {
+	const { storage, models } = structurallyValidatedContract;
+	const tableNames = new Set(Object.keys(storage.tables));
+	for (const [modelName, modelUnknown] of Object.entries(models)) {
+		const model = modelUnknown;
+		if (!model.storage?.table)
+ /* c8 ignore next */
+		throw new Error(`Model "${modelName}" is missing storage.table`);
+		const tableName = model.storage.table;
+		if (!tableNames.has(tableName))
+ /* c8 ignore next */
+		throw new Error(`Model "${modelName}" references non-existent table "${tableName}"`);
+		const table = storage.tables[tableName];
+		if (!table)
+ /* c8 ignore next */
+		throw new Error(`Model "${modelName}" references non-existent table "${tableName}"`);
+		if (!table.primaryKey)
+ /* c8 ignore next */
+		throw new Error(`Model "${modelName}" table "${tableName}" is missing a primary key`);
+		const columnNames = new Set(Object.keys(table.columns));
+		if (!model.fields)
+ /* c8 ignore next */
+		throw new Error(`Model "${modelName}" is missing fields`);
+		for (const [fieldName, fieldUnknown] of Object.entries(model.fields)) {
+			const field = fieldUnknown;
+			if (!field.column)
+ /* c8 ignore next */
+			throw new Error(`Model "${modelName}" field "${fieldName}" is missing column property`);
+			if (!columnNames.has(field.column))
+ /* c8 ignore next */
+			throw new Error(`Model "${modelName}" field "${fieldName}" references non-existent column "${field.column}" in table "${tableName}"`);
+		}
+		if (model.relations) {
+			for (const [relationName, relation] of Object.entries(model.relations)) if (typeof relation === "object" && relation !== null && "on" in relation && "to" in relation) {
+				const on = relation.on;
+				const cardinality = relation.cardinality;
+				if (on.parentCols && on.childCols) {
+					if (cardinality === "1:N") continue;
+					if (!table.foreignKeys?.some((fk) => {
+						return fk.columns.length === on.childCols?.length && fk.columns.every((col, i) => col === on.childCols?.[i]) && fk.references.table && fk.references.columns.length === on.parentCols?.length && fk.references.columns.every((col, i) => col === on.parentCols?.[i]);
+					}))
+ /* c8 ignore next */
+					throw new Error(`Model "${modelName}" relation "${relationName}" does not have a corresponding foreign key in table "${tableName}"`);
+				}
+			}
+		}
+	}
+	for (const [tableName, table] of Object.entries(storage.tables)) {
+		const columnNames = new Set(Object.keys(table.columns));
+		if (table.primaryKey) {
+			for (const colName of table.primaryKey.columns) if (!columnNames.has(colName))
+ /* c8 ignore next */
+			throw new Error(`Table "${tableName}" primaryKey references non-existent column "${colName}"`);
+		}
+		for (const unique of table.uniques) for (const colName of unique.columns) if (!columnNames.has(colName))
+ /* c8 ignore next */
+		throw new Error(`Table "${tableName}" unique constraint references non-existent column "${colName}"`);
+		for (const index of table.indexes) for (const colName of index.columns) if (!columnNames.has(colName))
+ /* c8 ignore next */
+		throw new Error(`Table "${tableName}" index references non-existent column "${colName}"`);
+		for (const fk of table.foreignKeys) {
+			for (const colName of fk.columns) if (!columnNames.has(colName))
+ /* c8 ignore next */
+			throw new Error(`Table "${tableName}" foreignKey references non-existent column "${colName}"`);
+			if (!tableNames.has(fk.references.table))
+ /* c8 ignore next */
+			throw new Error(`Table "${tableName}" foreignKey references non-existent table "${fk.references.table}"`);
+			const referencedTable = storage.tables[fk.references.table];
+			if (!referencedTable)
+ /* c8 ignore next */
+			throw new Error(`Table "${tableName}" foreignKey references non-existent table "${fk.references.table}"`);
+			const referencedColumnNames = new Set(Object.keys(referencedTable.columns));
+			for (const colName of fk.references.columns) if (!referencedColumnNames.has(colName))
+ /* c8 ignore next */
+			throw new Error(`Table "${tableName}" foreignKey references non-existent column "${colName}" in table "${fk.references.table}"`);
+			if (fk.columns.length !== fk.references.columns.length)
+ /* c8 ignore next */
+			throw new Error(`Table "${tableName}" foreignKey column count (${fk.columns.length}) does not match referenced column count (${fk.references.columns.length})`);
+		}
+	}
+}
+function normalizeContract(contract) {
+	const contractObj = contract;
+	let normalizedStorage = contractObj["storage"];
+	if (normalizedStorage && typeof normalizedStorage === "object" && normalizedStorage !== null) {
+		const storage = normalizedStorage;
+		const tables = storage["tables"];
+		if (tables) {
+			const normalizedTables = {};
+			for (const [tableName, table] of Object.entries(tables)) {
+				const tableObj = table;
+				const columns = tableObj["columns"];
+				if (columns) {
+					const normalizedColumns = {};
+					for (const [columnName, column] of Object.entries(columns)) {
+						const columnObj = column;
+						normalizedColumns[columnName] = {
+							...columnObj,
+							nullable: columnObj["nullable"] ?? false
+						};
+					}
+					normalizedTables[tableName] = {
+						...tableObj,
+						columns: normalizedColumns,
+						uniques: tableObj["uniques"] ?? [],
+						indexes: tableObj["indexes"] ?? [],
+						foreignKeys: tableObj["foreignKeys"] ?? []
+					};
+				} else normalizedTables[tableName] = tableObj;
+			}
+			normalizedStorage = {
+				...storage,
+				tables: normalizedTables
+			};
+		}
+	}
+	let normalizedModels = contractObj["models"];
+	if (normalizedModels && typeof normalizedModels === "object" && normalizedModels !== null) {
+		const models = normalizedModels;
+		const normalizedModelsObj = {};
+		for (const [modelName, model] of Object.entries(models)) {
+			const modelObj = model;
+			normalizedModelsObj[modelName] = {
+				...modelObj,
+				relations: modelObj["relations"] ?? {}
+			};
+		}
+		normalizedModels = normalizedModelsObj;
+	}
+	return {
+		...contractObj,
+		models: normalizedModels,
+		relations: contractObj["relations"] ?? {},
+		storage: normalizedStorage,
+		extensionPacks: contractObj["extensionPacks"] ?? {},
+		capabilities: contractObj["capabilities"] ?? {},
+		meta: contractObj["meta"] ?? {},
+		sources: contractObj["sources"] ?? {}
+	};
+}
+/**
+* Validates that a JSON import conforms to the SqlContract structure
+* and returns a fully typed SqlContract.
+*
+* This function is specifically for validating JSON imports (e.g., from contract.json).
+* Contracts created via the builder API (defineContract) are already valid and should
+* not be passed to this function - use them directly without validation.
+*
+* Performs both structural validation (using Arktype) and logical validation
+* (ensuring all references are valid).
+*
+*
+* The type parameter `TContract` must be a fully-typed contract type (e.g., from `contract.d.ts`),
+* NOT a generic `SqlContract<SqlStorage>`.
+*
+* **Correct:**
+* ```typescript
+* import type { Contract } from './contract.d';
+* const contract = validateContract<Contract>(contractJson);
+* ```
+*
+* **Incorrect:**
+* ```typescript
+* import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+* const contract = validateContract<SqlContract<SqlStorage>>(contractJson);
+* // ❌ Types will be inferred as 'unknown' - this won't work!
+* ```
+*
+* The type parameter provides the specific table structure, column types, and model definitions.
+* This function validates the runtime structure matches the type, but does not infer types
+* from JSON (as JSON imports lose literal type information).
+*
+* @param value - The contract value to validate (must be from a JSON import, not a builder)
+* @returns A validated contract matching the TContract type
+* @throws Error if the contract structure or logic is invalid
+*/
+function validateContract(value) {
+	const structurallyValid = validateContractStructure(normalizeContract(value));
+	const contractForValidation = structurallyValid;
+	validateContractLogic(contractForValidation);
+	const existingMappings = contractForValidation.mappings;
+	const mappings = computeMappings(contractForValidation.models, contractForValidation.storage, existingMappings);
+	return {
+		...structurallyValid,
+		models: contractForValidation.models,
+		relations: contractForValidation.relations,
+		storage: contractForValidation.storage,
+		mappings
+	};
+}
+
+//#endregion
+export { validateContract as n, computeMappings as t };
+//# sourceMappingURL=contract-CbxDA5bF.mjs.map

package/dist/contract-CbxDA5bF.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-CbxDA5bF.mjs","names":["modelToTable: Record<string, string>","tableToModel: Record<string, string>","fieldToColumn: Record<string, Record<string, string>>","columnToField: Record<string, Record<string, string>>","modelFieldToColumn: Record<string, string>","normalizedTables: Record<string, unknown>","normalizedColumns: Record<string, unknown>","normalizedModelsObj: Record<string, unknown>"],"sources":["../src/contract.ts"],"sourcesContent":["import type {\n  ForeignKey,\n  ForeignKeyReferences,\n  Index,\n  ModelDefinition,\n  ModelField,\n  ModelStorage,\n  PrimaryKey,\n  SqlContract,\n  SqlMappings,\n  SqlStorage,\n  StorageColumn,\n  StorageTable,\n  UniqueConstraint,\n} from '@prisma-next/sql-contract/types';\nimport { type } from 'arktype';\nimport type { O } from 'ts-toolbelt';\n\n/**\n * Structural validation schema for SqlContract using Arktype.\n * This validates the shape and types of the contract structure.\n */\nconst StorageColumnSchema = type.declare<StorageColumn>().type({\n  nativeType: 'string',\n  codecId: 'string',\n  nullable: 'boolean',\n});\n\nconst PrimaryKeySchema = type.declare<PrimaryKey>().type({\n  columns: type.string.array().readonly(),\n  'name?': 'string',\n});\n\nconst UniqueConstraintSchema = type.declare<UniqueConstraint>().type({\n  columns: type.string.array().readonly(),\n  'name?': 'string',\n});\n\nconst IndexSchema = type.declare<Index>().type({\n  columns: type.string.array().readonly(),\n  'name?': 'string',\n});\n\nconst ForeignKeyReferencesSchema = type.declare<ForeignKeyReferences>().type({\n  table: 'string',\n  columns: type.string.array().readonly(),\n});\n\nconst ForeignKeySchema = type.declare<ForeignKey>().type({\n  columns: type.string.array().readonly(),\n  references: ForeignKeyReferencesSchema,\n  'name?': 'string',\n});\n\nconst StorageTableSchema = type.declare<StorageTable>().type({\n  columns: type({ '[string]': StorageColumnSchema }),\n  'primaryKey?': PrimaryKeySchema,\n  uniques: UniqueConstraintSchema.array().readonly(),\n  indexes: IndexSchema.array().readonly(),\n  foreignKeys: ForeignKeySchema.array().readonly(),\n});\n\nconst StorageSchema = type.declare<SqlStorage>().type({\n  tables: type({ '[string]': StorageTableSchema }),\n});\n\nconst ModelFieldSchema = type.declare<ModelField>().type({\n  column: 'string',\n});\n\nconst ModelStorageSchema = type.declare<ModelStorage>().type({\n  table: 'string',\n});\n\nconst ModelSchema = type.declare<ModelDefinition>().type({\n  storage: ModelStorageSchema,\n  fields: type({ '[string]': ModelFieldSchema }),\n  relations: type({ '[string]': 'unknown' }),\n});\n\n/**\n * Complete SqlContract schema for structural validation.\n * This validates the entire contract structure at once.\n */\nconst SqlContractSchema = type({\n  'schemaVersion?': \"'1'\",\n  target: 'string',\n  targetFamily: \"'sql'\",\n  coreHash: 'string',\n  'profileHash?': 'string',\n  'capabilities?': 'Record<string, Record<string, boolean>>',\n  'extensionPacks?': 'Record<string, unknown>',\n  'meta?': 'Record<string, unknown>',\n  'sources?': 'Record<string, unknown>',\n  models: type({ '[string]': ModelSchema }),\n  storage: StorageSchema,\n});\n\n/**\n * Validates the structural shape of a SqlContract using Arktype.\n *\n * **Responsibility: Validation Only**\n * This function validates that the contract has the correct structure and types.\n * It does NOT normalize the contract - normalization must happen in the contract builder.\n *\n * The contract passed to this function must already be normalized (all required fields present).\n * If normalization is needed, it should be done by the contract builder before calling this function.\n *\n * This ensures all required fields are present and have the correct types.\n *\n * @param value - The contract value to validate (typically from a JSON import)\n * @returns The validated contract if structure is valid\n * @throws Error if the contract structure is invalid\n */\nfunction validateContractStructure<T extends SqlContract<SqlStorage>>(\n  value: unknown,\n): O.Overwrite<T, { targetFamily: 'sql' }> {\n  // Check targetFamily first to provide a clear error message for unsupported target families\n  const rawValue = value as { targetFamily?: string };\n  if (rawValue.targetFamily !== undefined && rawValue.targetFamily !== 'sql') {\n    /* c8 ignore next */\n    throw new Error(`Unsupported target family: ${rawValue.targetFamily}`);\n  }\n\n  const contractResult = SqlContractSchema(value);\n\n  if (contractResult instanceof type.errors) {\n    const messages = contractResult.map((p: { message: string }) => p.message).join('; ');\n    throw new Error(`Contract structural validation failed: ${messages}`);\n  }\n\n  // After validation, contractResult matches the schema and preserves the input structure\n  // TypeScript needs an assertion here due to exactOptionalPropertyTypes differences\n  // between Arktype's inferred type and the generic T, but runtime-wise they're compatible\n  return contractResult as O.Overwrite<T, { targetFamily: 'sql' }>;\n}\n\n/**\n * Computes mapping dictionaries from models and storage structures.\n * Assumes valid input - validation happens separately in validateContractLogic().\n *\n * @param models - Models object from contract\n * @param storage - Storage object from contract\n * @param existingMappings - Existing mappings from contract input (optional)\n * @returns Computed mappings dictionary\n */\nexport function computeMappings(\n  models: Record<string, ModelDefinition>,\n  _storage: SqlStorage,\n  existingMappings?: Partial<SqlMappings>,\n): SqlMappings {\n  const modelToTable: Record<string, string> = {};\n  const tableToModel: Record<string, string> = {};\n  const fieldToColumn: Record<string, Record<string, string>> = {};\n  const columnToField: Record<string, Record<string, string>> = {};\n\n  for (const [modelName, model] of Object.entries(models)) {\n    const tableName = model.storage.table;\n    modelToTable[modelName] = tableName;\n    tableToModel[tableName] = modelName;\n\n    const modelFieldToColumn: Record<string, string> = {};\n    for (const [fieldName, field] of Object.entries(model.fields)) {\n      const columnName = field.column;\n      modelFieldToColumn[fieldName] = columnName;\n\n      if (!columnToField[tableName]) {\n        columnToField[tableName] = {};\n      }\n      columnToField[tableName][columnName] = fieldName;\n    }\n    fieldToColumn[modelName] = modelFieldToColumn;\n  }\n\n  // Preserve existing mappings if provided, otherwise use computed ones\n  return {\n    modelToTable: existingMappings?.modelToTable ?? modelToTable,\n    tableToModel: existingMappings?.tableToModel ?? tableToModel,\n    fieldToColumn: existingMappings?.fieldToColumn ?? fieldToColumn,\n    columnToField: existingMappings?.columnToField ?? columnToField,\n    codecTypes: existingMappings?.codecTypes ?? {},\n    operationTypes: existingMappings?.operationTypes ?? {},\n  };\n}\n\n/**\n * Validates logical consistency of a **structurally validated** SqlContract.\n * This checks that references (e.g., foreign keys, primary keys, uniques) point to storage objects that already exist.\n * Structural validation is expected to have already completed before this helper runs.\n *\n * @param structurallyValidatedContract - The contract whose structure has already been validated\n * @throws Error if logical validation fails\n */\nfunction validateContractLogic(structurallyValidatedContract: SqlContract<SqlStorage>): void {\n  const { storage, models } = structurallyValidatedContract;\n  const tableNames = new Set(Object.keys(storage.tables));\n\n  // Validate models\n  for (const [modelName, modelUnknown] of Object.entries(models)) {\n    const model = modelUnknown as ModelDefinition;\n    // Validate model has storage.table\n    if (!model.storage?.table) {\n      /* c8 ignore next */\n      throw new Error(`Model \"${modelName}\" is missing storage.table`);\n    }\n\n    const tableName = model.storage.table;\n\n    // Validate model's table exists in storage\n    if (!tableNames.has(tableName)) {\n      /* c8 ignore next */\n      throw new Error(`Model \"${modelName}\" references non-existent table \"${tableName}\"`);\n    }\n\n    const table = storage.tables[tableName];\n    if (!table) {\n      /* c8 ignore next */\n      throw new Error(`Model \"${modelName}\" references non-existent table \"${tableName}\"`);\n    }\n\n    // Validate model's table has a primary key\n    if (!table.primaryKey) {\n      /* c8 ignore next */\n      throw new Error(`Model \"${modelName}\" table \"${tableName}\" is missing a primary key`);\n    }\n\n    const columnNames = new Set(Object.keys(table.columns));\n\n    // Validate model fields\n    if (!model.fields) {\n      /* c8 ignore next */\n      throw new Error(`Model \"${modelName}\" is missing fields`);\n    }\n\n    for (const [fieldName, fieldUnknown] of Object.entries(model.fields)) {\n      const field = fieldUnknown as { column: string };\n      // Validate field has column property\n      if (!field.column) {\n        /* c8 ignore next */\n        throw new Error(`Model \"${modelName}\" field \"${fieldName}\" is missing column property`);\n      }\n\n      // Validate field's column exists in the model's backing table\n      if (!columnNames.has(field.column)) {\n        /* c8 ignore next */\n        throw new Error(\n          `Model \"${modelName}\" field \"${fieldName}\" references non-existent column \"${field.column}\" in table \"${tableName}\"`,\n        );\n      }\n    }\n\n    // Validate model relations have corresponding foreign keys\n    if (model.relations) {\n      for (const [relationName, relation] of Object.entries(model.relations)) {\n        // For now, we'll do basic validation. Full FK validation can be added later\n        // This would require checking that the relation's on.parentCols/childCols match FKs\n        if (\n          typeof relation === 'object' &&\n          relation !== null &&\n          'on' in relation &&\n          'to' in relation\n        ) {\n          const on = relation.on as { parentCols?: string[]; childCols?: string[] };\n          const cardinality = (relation as { cardinality?: string }).cardinality;\n          if (on.parentCols && on.childCols) {\n            // For 1:N relations, the foreign key is on the child table\n            // For N:1 relations, the foreign key is on the parent table (this table)\n            // For now, we'll skip validation for 1:N relations as the FK is on the child table\n            // and we'll validate it when we process the child model\n            if (cardinality === '1:N') {\n              // Foreign key is on the child table, skip validation here\n              // It will be validated when we process the child model\n              continue;\n            }\n\n            // For N:1 relations, check that there's a foreign key matching this relation\n            const hasMatchingFk = table.foreignKeys?.some((fk) => {\n              return (\n                fk.columns.length === on.childCols?.length &&\n                fk.columns.every((col, i) => col === on.childCols?.[i]) &&\n                fk.references.table &&\n                fk.references.columns.length === on.parentCols?.length &&\n                fk.references.columns.every((col, i) => col === on.parentCols?.[i])\n              );\n            });\n\n            if (!hasMatchingFk) {\n              /* c8 ignore next */\n              throw new Error(\n                `Model \"${modelName}\" relation \"${relationName}\" does not have a corresponding foreign key in table \"${tableName}\"`,\n              );\n            }\n          }\n        }\n      }\n    }\n  }\n\n  for (const [tableName, table] of Object.entries(storage.tables)) {\n    const columnNames = new Set(Object.keys(table.columns));\n\n    // Validate primaryKey references existing columns\n    if (table.primaryKey) {\n      for (const colName of table.primaryKey.columns) {\n        if (!columnNames.has(colName)) {\n          /* c8 ignore next */\n          throw new Error(\n            `Table \"${tableName}\" primaryKey references non-existent column \"${colName}\"`,\n          );\n        }\n      }\n    }\n\n    // Validate unique constraints reference existing columns\n    for (const unique of table.uniques) {\n      for (const colName of unique.columns) {\n        if (!columnNames.has(colName)) {\n          /* c8 ignore next */\n          throw new Error(\n            `Table \"${tableName}\" unique constraint references non-existent column \"${colName}\"`,\n          );\n        }\n      }\n    }\n\n    // Validate indexes reference existing columns\n    for (const index of table.indexes) {\n      for (const colName of index.columns) {\n        if (!columnNames.has(colName)) {\n          /* c8 ignore next */\n          throw new Error(`Table \"${tableName}\" index references non-existent column \"${colName}\"`);\n        }\n      }\n    }\n\n    // Validate foreignKeys reference existing tables and columns\n    for (const fk of table.foreignKeys) {\n      // Validate FK columns exist in the referencing table\n      for (const colName of fk.columns) {\n        if (!columnNames.has(colName)) {\n          /* c8 ignore next */\n          throw new Error(\n            `Table \"${tableName}\" foreignKey references non-existent column \"${colName}\"`,\n          );\n        }\n      }\n\n      // Validate referenced table exists\n      if (!tableNames.has(fk.references.table)) {\n        /* c8 ignore next */\n        throw new Error(\n          `Table \"${tableName}\" foreignKey references non-existent table \"${fk.references.table}\"`,\n        );\n      }\n\n      // Validate referenced columns exist in the referenced table\n      const referencedTable = storage.tables[fk.references.table];\n      if (!referencedTable) {\n        /* c8 ignore next */\n        throw new Error(\n          `Table \"${tableName}\" foreignKey references non-existent table \"${fk.references.table}\"`,\n        );\n      }\n      const referencedColumnNames = new Set(Object.keys(referencedTable.columns));\n\n      for (const colName of fk.references.columns) {\n        if (!referencedColumnNames.has(colName)) {\n          /* c8 ignore next */\n          throw new Error(\n            `Table \"${tableName}\" foreignKey references non-existent column \"${colName}\" in table \"${fk.references.table}\"`,\n          );\n        }\n      }\n\n      if (fk.columns.length !== fk.references.columns.length) {\n        /* c8 ignore next */\n        throw new Error(\n          `Table \"${tableName}\" foreignKey column count (${fk.columns.length}) does not match referenced column count (${fk.references.columns.length})`,\n        );\n      }\n    }\n  }\n}\n\nexport function normalizeContract(contract: unknown): SqlContract<SqlStorage> {\n  const contractObj = contract as Record<string, unknown>;\n\n  // Only normalize if storage exists (validation will catch if it's missing)\n  let normalizedStorage = contractObj['storage'];\n  if (normalizedStorage && typeof normalizedStorage === 'object' && normalizedStorage !== null) {\n    const storage = normalizedStorage as Record<string, unknown>;\n    const tables = storage['tables'] as Record<string, unknown> | undefined;\n\n    if (tables) {\n      // Normalize storage tables\n      const normalizedTables: Record<string, unknown> = {};\n      for (const [tableName, table] of Object.entries(tables)) {\n        const tableObj = table as Record<string, unknown>;\n        const columns = tableObj['columns'] as Record<string, unknown> | undefined;\n\n        if (columns) {\n          // Normalize columns: add nullable: false if missing\n          const normalizedColumns: Record<string, unknown> = {};\n          for (const [columnName, column] of Object.entries(columns)) {\n            const columnObj = column as Record<string, unknown>;\n            const normalizedColumn: Record<string, unknown> = {\n              ...columnObj,\n              nullable: columnObj['nullable'] ?? false,\n            };\n\n            normalizedColumns[columnName] = normalizedColumn;\n          }\n\n          // Normalize table arrays: add empty arrays if missing\n          normalizedTables[tableName] = {\n            ...tableObj,\n            columns: normalizedColumns,\n            uniques: tableObj['uniques'] ?? [],\n            indexes: tableObj['indexes'] ?? [],\n            foreignKeys: tableObj['foreignKeys'] ?? [],\n          };\n        } else {\n          normalizedTables[tableName] = tableObj;\n        }\n      }\n\n      normalizedStorage = {\n        ...storage,\n        tables: normalizedTables,\n      };\n    }\n  }\n\n  // Only normalize if models exists (validation will catch if it's missing)\n  let normalizedModels = contractObj['models'];\n  if (normalizedModels && typeof normalizedModels === 'object' && normalizedModels !== null) {\n    const models = normalizedModels as Record<string, unknown>;\n    const normalizedModelsObj: Record<string, unknown> = {};\n    for (const [modelName, model] of Object.entries(models)) {\n      const modelObj = model as Record<string, unknown>;\n      normalizedModelsObj[modelName] = {\n        ...modelObj,\n        relations: modelObj['relations'] ?? {},\n      };\n    }\n    normalizedModels = normalizedModelsObj;\n  }\n\n  // Normalize top-level fields: add empty objects if missing\n  return {\n    ...contractObj,\n    models: normalizedModels,\n    relations: contractObj['relations'] ?? {},\n    storage: normalizedStorage,\n    extensionPacks: contractObj['extensionPacks'] ?? {},\n    capabilities: contractObj['capabilities'] ?? {},\n    meta: contractObj['meta'] ?? {},\n    sources: contractObj['sources'] ?? {},\n  } as SqlContract<SqlStorage>;\n}\n\n/**\n * Validates that a JSON import conforms to the SqlContract structure\n * and returns a fully typed SqlContract.\n *\n * This function is specifically for validating JSON imports (e.g., from contract.json).\n * Contracts created via the builder API (defineContract) are already valid and should\n * not be passed to this function - use them directly without validation.\n *\n * Performs both structural validation (using Arktype) and logical validation\n * (ensuring all references are valid).\n *\n *\n * The type parameter `TContract` must be a fully-typed contract type (e.g., from `contract.d.ts`),\n * NOT a generic `SqlContract<SqlStorage>`.\n *\n * **Correct:**\n * ```typescript\n * import type { Contract } from './contract.d';\n * const contract = validateContract<Contract>(contractJson);\n * ```\n *\n * **Incorrect:**\n * ```typescript\n * import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';\n * const contract = validateContract<SqlContract<SqlStorage>>(contractJson);\n * // ❌ Types will be inferred as 'unknown' - this won't work!\n * ```\n *\n * The type parameter provides the specific table structure, column types, and model definitions.\n * This function validates the runtime structure matches the type, but does not infer types\n * from JSON (as JSON imports lose literal type information).\n *\n * @param value - The contract value to validate (must be from a JSON import, not a builder)\n * @returns A validated contract matching the TContract type\n * @throws Error if the contract structure or logic is invalid\n */\nexport function validateContract<TContract extends SqlContract<SqlStorage>>(\n  value: unknown,\n): TContract {\n  // Normalize contract first (add defaults for missing fields)\n  const normalized = normalizeContract(value);\n\n  const structurallyValid = validateContractStructure<SqlContract<SqlStorage>>(normalized);\n\n  const contractForValidation = structurallyValid as SqlContract<SqlStorage>;\n\n  // Validate contract logic (contracts must already have fully qualified type IDs)\n  validateContractLogic(contractForValidation);\n\n  // Extract existing mappings (optional - will be computed if missing)\n  const existingMappings = (contractForValidation as { mappings?: Partial<SqlMappings> }).mappings;\n\n  // Compute mappings from models and storage\n  const mappings = computeMappings(\n    contractForValidation.models as Record<string, ModelDefinition>,\n    contractForValidation.storage,\n    existingMappings,\n  );\n\n  // Add default values for optional metadata fields if missing\n  const contractWithMappings = {\n    ...structurallyValid,\n    models: contractForValidation.models,\n    relations: contractForValidation.relations,\n    storage: contractForValidation.storage,\n    mappings,\n  };\n\n  // Type assertion: The caller provides the strict type via TContract.\n  // We validate the structure matches, but the precise types come from contract.d.ts\n  return contractWithMappings as TContract;\n}\n"],"mappings":"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"}

package/dist/contract-builder.d.mts

@@ -0,0 +1,100 @@
+import { BuildModels, BuildRelations, BuildStorageColumn, ColumnBuilderState, ContractBuilder, ExtractColumns, ExtractPrimaryKey, ModelBuilder, ModelBuilderState, RelationDefinition, TableBuilder, TableBuilderState } from "@prisma-next/contract-authoring";
+import { ExtensionPackRef, TargetPackRef } from "@prisma-next/contract/framework-components";
+import { SqlContract, SqlMappings } from "@prisma-next/sql-contract/types";
+
+//#region src/contract-builder.d.ts
+
+/**
+ * Type-level mappings structure for contracts built via `defineContract()`.
+ *
+ * Compile-time type helper (not a runtime object) that ensures mappings match what the builder
+ * produces. `codecTypes` uses the generic `CodecTypes` parameter; `operationTypes` is always
+ * empty since operations are added via extensions at runtime.
+ *
+ * **Difference from RuntimeContext**: This is a compile-time type for contract construction.
+ * `RuntimeContext` is a runtime object with populated registries for query execution.
+ *
+ * @template C - The `CodecTypes` generic parameter passed to `defineContract<CodecTypes>()`
+ */
+type ContractBuilderMappings<C extends Record<string, {
+  output: unknown;
+}>> = Omit<SqlMappings, 'codecTypes' | 'operationTypes'> & {
+  readonly codecTypes: C;
+  readonly operationTypes: Record<string, never>;
+};
+type BuildStorageTable<_TableName extends string, Columns extends Record<string, ColumnBuilderState<string, boolean, string>>, PK extends readonly string[] | undefined> = {
+  readonly columns: { readonly [K in keyof Columns]: Columns[K] extends ColumnBuilderState<string, infer Null, infer TType> ? BuildStorageColumn<Null & boolean, TType> : never };
+  readonly uniques: ReadonlyArray<{
+    readonly columns: readonly string[];
+    readonly name?: string;
+  }>;
+  readonly indexes: ReadonlyArray<{
+    readonly columns: readonly string[];
+    readonly name?: string;
+  }>;
+  readonly foreignKeys: ReadonlyArray<{
+    readonly columns: readonly string[];
+    readonly references: {
+      readonly table: string;
+      readonly columns: readonly string[];
+    };
+    readonly name?: string;
+  }>;
+} & (PK extends readonly string[] ? {
+  readonly primaryKey: {
+    readonly columns: PK;
+    readonly name?: string;
+  };
+} : Record<string, never>);
+type BuildStorage<Tables extends Record<string, TableBuilderState<string, Record<string, ColumnBuilderState<string, boolean, string>>, readonly string[] | undefined>>> = {
+  readonly tables: { readonly [K in keyof Tables]: BuildStorageTable<K & string, ExtractColumns<Tables[K]>, ExtractPrimaryKey<Tables[K]>> };
+};
+interface ColumnBuilder<Name extends string, Nullable extends boolean, Type extends string> {
+  nullable<Value extends boolean>(value?: Value): ColumnBuilder<Name, Value, Type>;
+  type<Id extends string>(id: Id): ColumnBuilder<Name, Nullable, Id>;
+  build(): ColumnBuilderState<Name, Nullable, Type>;
+}
+declare class SqlContractBuilder<CodecTypes extends Record<string, {
+  output: unknown;
+}> = Record<string, never>, Target extends string | undefined = undefined, Tables extends Record<string, TableBuilderState<string, Record<string, ColumnBuilderState<string, boolean, string>>, readonly string[] | undefined>> = Record<never, never>, Models extends Record<string, ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>> = Record<never, never>, CoreHash extends string | undefined = undefined, ExtensionPacks extends Record<string, unknown> | undefined = undefined, Capabilities extends Record<string, Record<string, boolean>> | undefined = undefined> extends ContractBuilder<Target, Tables, Models, CoreHash, ExtensionPacks, Capabilities> {
+  /**
+   * This method is responsible for normalizing the contract IR by setting default values
+   * for all required fields:
+   * - `nullable`: defaults to `false` if not provided
+   * - `uniques`: defaults to `[]` (empty array)
+   * - `indexes`: defaults to `[]` (empty array)
+   * - `foreignKeys`: defaults to `[]` (empty array)
+   * - `relations`: defaults to `{}` (empty object) for both model-level and contract-level
+   * - `nativeType`: required field set from column type descriptor when columns are defined
+   *
+   * The contract builder is the **only** place where normalization should occur.
+   * Validators, parsers, and emitters should assume the contract is already normalized.
+   *
+   * **Required**: Use column type descriptors (e.g., `int4Column`, `textColumn`) when defining columns.
+   * This ensures `nativeType` is set correctly at build time.
+   *
+   * @returns A normalized SqlContract with all required fields present
+   */
+  build(): Target extends string ? SqlContract<BuildStorage<Tables>, BuildModels<Models>, BuildRelations<Models>, ContractBuilderMappings<CodecTypes>> & {
+    readonly schemaVersion: '1';
+    readonly target: Target;
+    readonly targetFamily: 'sql';
+    readonly coreHash: CoreHash extends string ? CoreHash : string;
+  } & (ExtensionPacks extends Record<string, unknown> ? {
+    readonly extensionPacks: ExtensionPacks;
+  } : Record<string, never>) & (Capabilities extends Record<string, Record<string, boolean>> ? {
+    readonly capabilities: Capabilities;
+  } : Record<string, never>) : never;
+  target<T extends string>(packRef: TargetPackRef<'sql', T>): SqlContractBuilder<CodecTypes, T, Tables, Models, CoreHash, ExtensionPacks, Capabilities>;
+  extensionPacks(packs: Record<string, ExtensionPackRef<'sql', string>>): SqlContractBuilder<CodecTypes, Target, Tables, Models, CoreHash, ExtensionPacks, Capabilities>;
+  capabilities<C extends Record<string, Record<string, boolean>>>(capabilities: C): SqlContractBuilder<CodecTypes, Target, Tables, Models, CoreHash, ExtensionPacks, C>;
+  coreHash<H extends string>(hash: H): SqlContractBuilder<CodecTypes, Target, Tables, Models, H, ExtensionPacks, Capabilities>;
+  table<TableName extends string, T extends TableBuilder<TableName, Record<string, ColumnBuilderState<string, boolean, string>>, readonly string[] | undefined>>(name: TableName, callback: (t: TableBuilder<TableName>) => T | undefined): SqlContractBuilder<CodecTypes, Target, Tables & Record<TableName, ReturnType<T['build']>>, Models, CoreHash, ExtensionPacks, Capabilities>;
+  model<ModelName extends string, TableName extends string, M extends ModelBuilder<ModelName, TableName, Record<string, string>, Record<string, RelationDefinition>>>(name: ModelName, table: TableName, callback: (m: ModelBuilder<ModelName, TableName, Record<string, string>, Record<never, never>>) => M | undefined): SqlContractBuilder<CodecTypes, Target, Tables, Models & Record<ModelName, ReturnType<M['build']>>, CoreHash, ExtensionPacks, Capabilities>;
+}
+declare function defineContract<CodecTypes extends Record<string, {
+  output: unknown;
+}> = Record<string, never>>(): SqlContractBuilder<CodecTypes>;
+//#endregion
+export { type ColumnBuilder, defineContract };
+//# sourceMappingURL=contract-builder.d.mts.map

package/dist/contract-builder.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-builder.d.mts","names":[],"sources":["../src/contract-builder.ts"],"sourcesContent":[],"mappings":";;;;;;;AAyByC;;;;;;;AAoBR;;;;KAL5B,uBAc8B,CAAA,UAdI,MAcJ,CAAA,MAAA,EAAA;EAAQ,MAAA,EAAA,OAAA;CAAW,CAAA,CAAA,GAdwB,IAcxB,CAbpD,WAaoD,EAAA,YAAA,GAAA,gBAAA,CAAA,GAAA;EAK3B,SAAA,UAAA,EAfJ,CAeI;EAAgB,SAAA,cAAA,EAdhB,MAcgB,CAAA,MAAA,EAAA,KAAA,CAAA;CAAnC;KAXH,iBAce,CAAA,mBAAA,MAAA,EAAA,gBAZF,MAYE,CAAA,MAAA,EAZa,kBAYb,CAAA,MAAA,EAAA,OAAA,EAAA,MAAA,CAAA,CAAA,EAAA,WAAA,SAAA,MAAA,EAAA,GAAA,SAAA,CAAA,GAAA;EACA,SAAA,OAAA,EAAA,iBACI,MAVC,OAUD,GAVW,OAUX,CAVmB,CAUnB,CAAA,SAV8B,kBAU9B,CAAA,MAAA,EAAA,KAAA,KAAA,EAAA,KAAA,MAAA,CAAA,GALhB,kBAKgB,CALG,IAKH,GAAA,OAAA,EALmB,KAKnB,CAAA,GAAA,KAAA,EAKnB;EAC0C,SAAA,OAAA,EAR3B,aAQ2B,CAAA;IAC3C,SAAA,OAAA,EAAA,SAAA,MAAA,EAAA;IAAM,SAAA,IAAA,CAAA,EAAA,MAAA;EAEL,CAAA,CAAA;EAKgB,SAAA,OAAA,EAfD,aAeC,CAAA;IAAf,SAAA,OAAA,EAAA,SAAA,MAAA,EAAA;IAFF,SAAA,IAAA,CAAA,EAAA,MAAA;EAFa,CAAA,CAAA;EAUQ,SAAA,WAAA,EApBD,aAoBC,CAAA;IACnB,SAAA,OAAA,EAAA,SAAA,MAAA,EAAA;IACe,SAAA,UAAA,EAAA;MAAO,SAAA,KAAA,EAAA,MAAA;MAAtB,SAAA,OAAA,EAAA,SAAA,MAAA,EAAA;IACkB,CAAA;IAAO,SAAA,IAAA,CAAA,EAAA,MAAA;EAAzB,CAAA,CAAA;CAH4B,GAAA,CAf7B,EAe6B,SAAA,SAAA,MAAA,EAAA,GAAA;EAAiB,SAAA,UAAA,EAAA;IAyBlC,SAAA,OAAa,EAvCiB,EAuCjB;IACY,SAAA,IAAA,CAAA,EAAA,MAAA;EAAsB,CAAA;CAAM,GAvClE,MAuCkE,CAAA,MAAA,EAAA,KAAA,CAAA,CAAA;KArCjE,YAqCwE,CAAA,eApC5D,MAoC4D,CAAA,MAAA,EAlCzE,iBAkCyE,CAAA,MAAA,EAhCvE,MAgCuE,CAAA,MAAA,EAhCxD,kBAgCwD,CAAA,MAAA,EAAA,OAAA,EAAA,MAAA,CAAA,CAAA,EAAA,SAAA,MAAA,EAAA,GAAA,SAAA,CAAA,CAAA,CAAA,GAAA;EAA3B,SAAA,MAAA,EAAA,iBACpB,MA3BL,MA2BK,GA3BI,iBA2BJ,CA1BxB,CA0BwB,GAAA,MAAA,EAzBxB,cAyBwB,CAzBT,MAyBS,CAzBF,CAyBE,CAAA,CAAA,EAxBxB,iBAwBwB,CAxBN,MAwBM,CAxBC,CAwBD,CAAA,CAAA,CAAA,EAAmB;CAAM;AAAU,UAFhD,aAEgD,CAAA,aAAA,MAAA,EAAA,iBAAA,OAAA,EAAA,aAAA,MAAA,CAAA,CAAA;EAA9B,QAAA,CAAA,cAAA,OAAA,CAAA,CAAA,KAAA,CAAA,EADO,KACP,CAAA,EADe,aACf,CAD6B,IAC7B,EADmC,KACnC,EAD0C,IAC1C,CAAA;EACL,IAAA,CAAA,WAAA,MAAA,CAAA,CAAA,EAAA,EADA,EACA,CAAA,EADK,aACL,CADmB,IACnB,EADyB,QACzB,EADmC,EACnC,CAAA;EAAM,KAAA,EAAA,EAAzB,kBAAyB,CAAN,IAAM,EAAA,QAAA,EAAU,IAAV,CAAA;;cAG9B,kBAHK,CAAA,mBAIU,MAJV,CAAA,MAAA,EAAA;EAAkB,MAAA,EAAA,OAAA;AAC5B,CAAA,CAAA,GAG0D,MADrD,CAAA,MAAA,EAAA,KAAkB,CAAA,EAAA,eAAA,MAAA,GAAA,SAAA,GAAA,SAAA,EAAA,eAGP,MAHO,CAAA,MAAA,EAKpB,iBALoB,CAAA,MAAA,EAOlB,MAPkB,CAAA,MAAA,EAOH,kBAPG,CAAA,MAAA,EAAA,OAAA,EAAA,MAAA,CAAA,CAAA,EAAA,SAAA,MAAA,EAAA,GAAA,SAAA,CAAA,CAAA,GAUlB,MAVkB,CAAA,KAAA,EAAA,KAAA,CAAA,EAAA,eAWP,MAXO,CAAA,MAAA,EAapB,iBAboB,CAAA,MAAA,EAAA,MAAA,EAac,MAbd,CAAA,MAAA,EAAA,MAAA,CAAA,EAasC,MAbtC,CAAA,MAAA,EAaqD,kBAbrD,CAAA,CAAA,CAAA,GAclB,MAdkB,CAAA,KAAA,EAAA,KAAA,CAAA,EAAA,iBAAA,MAAA,GAAA,SAAA,GAAA,SAAA,EAAA,uBAgBC,MAhBD,CAAA,MAAA,EAAA,OAAA,CAAA,GAAA,SAAA,GAAA,SAAA,EAAA,qBAiBD,MAjBC,CAAA,MAAA,EAiBc,MAjBd,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,GAAA,SAAA,GAAA,SAAA,CAAA,SAkBd,eAlBc,CAkBE,MAlBF,EAkBU,MAlBV,EAkBkB,MAlBlB,EAkB0B,QAlB1B,EAkBoC,cAlBpC,EAkBoD,YAlBpD,CAAA,CAAA;EACH;;;;;;;;;;;;;;;;;;EAiBqB,KAAA,CAAA,CAAA,EAmB/B,MAnB+B,SAAA,MAAA,GAoBpC,WApBoC,CAqBlC,YArBkC,CAqBrB,MArBqB,CAAA,EAsBlC,WAtBkC,CAsBtB,MAtBsB,CAAA,EAuBlC,cAvBkC,CAuBnB,MAvBmB,CAAA,EAwBlC,uBAxBkC,CAwBV,UAxBU,CAAA,CAAA,GAAA;IAAQ,SAAA,aAAA,EAAA,GAAA;IAAU,SAAA,MAAA,EA2BnC,MA3BmC;IAAgB,SAAA,YAAA,EAAA,KAAA;IAmBjE,SAAA,QAAA,EAUgB,QAVhB,SAAA,MAAA,GAU0C,QAV1C,GAAA,MAAA;EAEU,CAAA,GAAA,CASV,cATU,SASa,MATb,CAAA,MAAA,EAAA,OAAA,CAAA,GAAA;IAAb,SAAA,cAAA,EAU+B,cAV/B;EACY,CAAA,GAUR,MAVQ,CAAA,MAAA,EAAA,KAAA,CAAA,CAAA,GAAA,CAWX,YAXW,SAWU,MAXV,CAAA,MAAA,EAWyB,MAXzB,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,GAAA;IAAZ,SAAA,YAAA,EAY6B,YAZ7B;EACe,CAAA,GAYX,MAZW,CAAA,MAAA,EAAA,KAAA,CAAA,CAAA,GAAA,KAAA;EAAf,MAAA,CAAA,UAAA,MAAA,CAAA,CAAA,OAAA,EAoPK,aApPL,CAAA,KAAA,EAoP0B,CApP1B,CAAA,CAAA,EAqPH,kBArPG,CAqPgB,UArPhB,EAqP4B,CArP5B,EAqP+B,MArP/B,EAqPuC,MArPvC,EAqP+C,QArP/C,EAqPyD,cArPzD,EAqPyE,YArPzE,CAAA;EACwB,cAAA,CAAA,KAAA,EAoQrB,MApQqB,CAAA,MAAA,EAoQN,gBApQM,CAAA,KAAA,EAAA,MAAA,CAAA,CAAA,CAAA,EAqQ3B,kBArQ2B,CAsQ5B,UAtQ4B,EAuQ5B,MAvQ4B,EAwQ5B,MAxQ4B,EAyQ5B,MAzQ4B,EA0Q5B,QA1Q4B,EA2Q5B,cA3Q4B,EA4Q5B,YA5Q4B,CAAA;EAAxB,YAAA,CAAA,UA0T0B,MA1T1B,CAAA,MAAA,EA0TyC,MA1TzC,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,CAAA,CAAA,YAAA,EA2TU,CA3TV,CAAA,EA4TH,kBA5TG,CA4TgB,UA5ThB,EA4T4B,MA5T5B,EA4ToC,MA5TpC,EA4T4C,MA5T5C,EA4ToD,QA5TpD,EA4T8D,cA5T9D,EA4T8E,CA5T9E,CAAA;EAJF,QAAA,CAAA,UAAA,MAAA,CAAA,CAAA,IAAA,EAwUI,CAxUJ,CAAA,EAyUD,kBAzUC,CAyUkB,UAzUlB,EAyU8B,MAzU9B,EAyUsC,MAzUtC,EAyU8C,MAzU9C,EAyUsD,CAzUtD,EAyUyD,cAzUzD,EAyUyE,YAzUzE,CAAA;EAOmB,KAAA,CAAA,kBAAA,MAAA,EAAA,UAmVX,YAnVW,CAoVnB,SApVmB,EAqVnB,MArVmB,CAAA,MAAA,EAqVJ,kBArVI,CAAA,MAAA,EAAA,OAAA,EAAA,MAAA,CAAA,CAAA,EAAA,SAAA,MAAA,EAAA,GAAA,SAAA,CAAA,CAAA,CAAA,IAAA,EAyVf,SAzVe,EAAA,QAAA,EAAA,CAAA,CAAA,EA0VP,YA1VO,CA0VM,SA1VN,CAAA,EAAA,GA0VqB,CA1VrB,GAAA,SAAA,CAAA,EA2VpB,kBA3VoB,CA4VrB,UA5VqB,EA6VrB,MA7VqB,EA8VrB,MA9VqB,GA8VZ,MA9VY,CA8VL,SA9VK,EA8VM,UA9VN,CA8ViB,CA9VjB,CAAA,OAAA,CAAA,CAAA,CAAA,EA+VrB,MA/VqB,EAgWrB,QAhWqB,EAiWrB,cAjWqB,EAkWrB,YAlWqB,CAAA;EAEE,KAAA,CAAA,kBAAA,MAAA,EAAA,kBAAA,MAAA,EAAA,UAyXb,YAzXa,CA0XrB,SA1XqB,EA2XrB,SA3XqB,EA4XrB,MA5XqB,CAAA,MAAA,EAAA,MAAA,CAAA,EA6XrB,MA7XqB,CAAA,MAAA,EA6XN,kBA7XM,CAAA,CAAA,CAAA,CAAA,IAAA,EAgYjB,SAhYiB,EAAA,KAAA,EAiYhB,SAjYgB,EAAA,QAAA,EAAA,CAAA,CAAA,EAmYlB,YAnYkB,CAmYL,SAnYK,EAmYM,SAnYN,EAmYiB,MAnYjB,CAAA,MAAA,EAAA,MAAA,CAAA,EAmYyC,MAnYzC,CAAA,KAAA,EAAA,KAAA,CAAA,CAAA,EAAA,GAoYlB,CApYkB,GAAA,SAAA,CAAA,EAqYtB,kBArYsB,CAsYvB,UAtYuB,EAuYvB,MAvYuB,EAwYvB,MAxYuB,EAyYvB,MAzYuB,GAyYd,MAzYc,CAyYP,SAzYO,EAyYI,UAzYJ,CAyYe,CAzYf,CAAA,OAAA,CAAA,CAAA,CAAA,EA0YvB,QA1YuB,EA2YvB,cA3YuB,EA4YvB,YA5YuB,CAAA;;AAChB,iBAkaK,cAlaL,CAAA,mBAmaU,MAnaV,CAAA,MAAA,EAAA;EAAuB,MAAA,EAAA,OAAA;CACK,CAAA,GAkaoB,MAlapB,CAAA,MAAA,EAAA,KAAA,CAAA,CAAA,CAAA,CAAA,EAmalC,kBAnakC,CAmaf,UAnae,CAAA"}