@prisma-next/sql-contract-ts 0.16.0-dev.2 → 0.16.0-dev.21

package/package.json

@@ -1,27 +1,27 @@
 {
   "name": "@prisma-next/sql-contract-ts",
-  "version": "0.16.0-dev.2",
+  "version": "0.16.0-dev.21",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "SQL-specific TypeScript contract authoring surface for Prisma Next",
   "dependencies": {
-    "@prisma-next/config": "0.16.0-dev.2",
-    "@prisma-next/contract": "0.16.0-dev.2",
-    "@prisma-next/contract-authoring": "0.16.0-dev.2",
-    "@prisma-next/framework-components": "0.16.0-dev.2",
-    "@prisma-next/sql-contract": "0.16.0-dev.2",
-    "@prisma-next/utils": "0.16.0-dev.2",
+    "@prisma-next/config": "0.16.0-dev.21",
+    "@prisma-next/contract": "0.16.0-dev.21",
+    "@prisma-next/contract-authoring": "0.16.0-dev.21",
+    "@prisma-next/framework-components": "0.16.0-dev.21",
+    "@prisma-next/sql-contract": "0.16.0-dev.21",
+    "@prisma-next/utils": "0.16.0-dev.21",
     "arktype": "^2.2.2",
     "pathe": "^2.0.3",
     "ts-toolbelt": "^9.6.0"
   },
   "devDependencies": {
-    "@prisma-next/test-utils": "0.16.0-dev.2",
-    "@prisma-next/tsconfig": "0.16.0-dev.2",
+    "@prisma-next/test-utils": "0.16.0-dev.21",
+    "@prisma-next/tsconfig": "0.16.0-dev.21",
     "@types/pg": "8.20.0",
     "pg": "8.22.0",
-    "@prisma-next/tsdown": "0.16.0-dev.2",
+    "@prisma-next/tsdown": "0.16.0-dev.21",
     "tsdown": "0.22.8",
     "typescript": "5.9.3",
     "vitest": "4.1.10"

package/schemas/data-contract-sql-v1.json

@@ -26,12 +26,12 @@
     },
     "storageHash": {
       "type": "string",
-      "pattern": "^sha256:[a-f0-9]{64}$",
+      "pattern": "^[a-f0-9]{64}$",
       "description": "SHA-256 hash of the storage section (DB-satisfied expectations)"
     },
     "profileHash": {
       "type": "string",
-      "pattern": "^sha256:[a-f0-9]{64}$",
+      "pattern": "^[a-f0-9]{64}$",
       "description": "SHA-256 hash of the pinned capability profile (capability keys/variants and adapter pins)"
     },
     "capabilities": {
@@ -44,7 +44,7 @@
         }
       }
     },
-    "extensionPacks": {
+    "extensions": {
       "type": "object",
       "description": "Extension packs and their configuration",
       "additionalProperties": true
@@ -104,7 +104,7 @@
       "properties": {
         "executionHash": {
           "type": "string",
-          "pattern": "^sha256:[a-f0-9]{64}$",
+          "pattern": "^[a-f0-9]{64}$",
           "description": "SHA-256 hash of the execution section (client-side behavior)"
         },
         "mutations": {

package/src/authoring-helper-runtime.ts

@@ -10,6 +10,7 @@ import {
   validateAuthoringHelperArguments,
 } from '@prisma-next/framework-components/authoring';
 import { type StorageTypeInstance, toStorageTypeInstance } from '@prisma-next/sql-contract/types';
+import { contractError } from './contract-errors';
 
 export type RuntimeNamedConstraintSpec = {
   readonly name?: string;
@@ -33,8 +34,10 @@ const blockedSegments = new Set(['__proto__', 'constructor', 'prototype']);
 
 function assertSafeHelperKey(key: string, path: readonly string[]): void {
   if (blockedSegments.has(key)) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.PACK_CONTRIBUTION_INVALID',
       `Invalid authoring helper "${[...path, key].join('.')}". Helper path segments must not use "${key}".`,
+      { meta: { helperPath: [...path, key].join('.'), segment: key } },
     );
   }
 }
@@ -83,8 +86,16 @@ export function createFieldPresetHelper<Result>(options: {
     const declaredArguments = options.descriptor.args ?? [];
 
     if (acceptsNamedConstraintOptions && rawArgs.length > declaredArguments.length + 1) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.ARGUMENT_INVALID',
         `${options.helperPath} expects at most ${declaredArguments.length + 1} argument(s), received ${rawArgs.length}`,
+        {
+          meta: {
+            helperPath: options.helperPath,
+            expected: declaredArguments.length + 1,
+            received: rawArgs.length,
+          },
+        },
       );
     }
 
@@ -94,8 +105,10 @@ export function createFieldPresetHelper<Result>(options: {
     if (acceptsNamedConstraintOptions && rawArgs.length === declaredArguments.length + 1) {
       const maybeNamedConstraintOptions = rawArgs.at(-1);
       if (!isNamedConstraintOptionsLike(maybeNamedConstraintOptions)) {
-        throw new Error(
+        throw contractError(
+          'CONTRACT.ARGUMENT_INVALID',
           `${options.helperPath} accepts an optional trailing { name?: string } constraint options object`,
+          { meta: { helperPath: options.helperPath } },
         );
       }
       namedConstraintOptions = maybeNamedConstraintOptions;

package/src/build-contract.ts

@@ -58,6 +58,7 @@ import { validateStorageSemantics } from '@prisma-next/sql-contract/validators';
 import { deriveValueSetFromEntity } from '@prisma-next/sql-contract/value-set-derivation-hook';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import type {
   ContractDefinition,
   FieldNode,
@@ -65,6 +66,7 @@ import type {
   RelationNode,
   ValueObjectFieldNode,
 } from './contract-definition';
+import { contractError } from './contract-errors';
 
 type DomainFieldRef =
   | { readonly kind: 'scalar'; readonly many?: boolean }
@@ -92,7 +94,7 @@ function encodeColumnDefault(
   }
   if (many) {
     if (!Array.isArray(defaultInput.value)) {
-      throw new Error(
+      throw new InternalError(
         `Literal default on a list column must be an array; received ${typeof defaultInput.value}. ` +
           'A scalar default on a list field must be rejected at the authoring surface.',
       );
@@ -114,13 +116,17 @@ function assertStorageSemantics(
 ): void {
   const semanticErrors = validateStorageSemantics(contract.storage);
   if (semanticErrors.length > 0) {
-    throw new Error(`Contract semantic validation failed: ${semanticErrors.join('; ')}`);
+    throw contractError(
+      'CONTRACT.VALIDATION_FAILED',
+      `Contract semantic validation failed: ${semanticErrors.join('; ')}`,
+      { meta: { errors: semanticErrors } },
+    );
   }
 
   const indexTypeRegistry = createIndexTypeRegistry();
   const packsToRegister: ReadonlyArray<{ readonly id?: string; readonly indexTypes?: unknown }> = [
     definition.target,
-    ...Object.values(definition.extensionPacks ?? {}),
+    ...Object.values(definition.extensions ?? {}),
   ];
   for (const pack of packsToRegister) {
     const registration = pack.indexTypes;
@@ -130,8 +136,10 @@ function assertStorageSemantics(
       registration === null ||
       !Array.isArray((registration as { entries?: unknown }).entries)
     ) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.PACK_CONTRIBUTION_INVALID',
         `Pack "${pack.id ?? '<unknown>'}" declares "indexTypes" but its value is not an IndexTypeRegistration (expected an object with an "entries" array; got ${typeof registration}).`,
+        { meta: { packId: pack.id, contribution: 'indexTypes', reason: 'invalid-shape' } },
       );
     }
     for (const entry of (registration as IndexTypeRegistration<IndexTypeMap>).entries) {
@@ -158,8 +166,10 @@ function assertKnownTargetModel(
       targetNamespaceId !== undefined && targetNamespaceId.length > 0
         ? `${targetNamespaceId}.${targetModelName}`
         : targetModelName;
-    throw new Error(
+    throw contractError(
+      'CONTRACT.MODEL_UNKNOWN',
       `${context} on model "${sourceModelName}" references unknown model "${qualified}"`,
+      { meta: { sourceModel: sourceModelName, targetModel: qualified, context } },
     );
   }
   return targetModel;
@@ -172,8 +182,17 @@ function assertTargetTableMatches(
   context: string,
 ): void {
   if (targetModel.tableName !== referencedTableName) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.TABLE_MISMATCH',
       `${context} on model "${sourceModelName}" references table "${referencedTableName}" but model "${targetModel.modelName}" maps to "${targetModel.tableName}"`,
+      {
+        meta: {
+          sourceModel: sourceModelName,
+          referencedTable: referencedTableName,
+          mappedTable: targetModel.tableName,
+          context,
+        },
+      },
     );
   }
 }
@@ -310,8 +329,10 @@ function collectEntityFromColumn(
   const forKind = forNs[entityRef.entityKind] ?? {};
   const existing = forKind[entityRef.entityName];
   if (existing !== undefined && existing !== entityRef.entity) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.NAME_DUPLICATE',
       `buildSqlContractFromDefinition: two different "${entityRef.entityKind}" entities named "${entityRef.entityName}" in namespace "${namespaceId}" — pack-entity names must be unique per namespace.`,
+      { meta: { kind: entityRef.entityKind, name: entityRef.entityName, namespaceId } },
     );
   }
   forKind[entityRef.entityName] = entityRef.entity;
@@ -344,8 +365,10 @@ function mergeColumnAndAttachedEntities(
     for (const [name, entity] of Object.entries(columnForKind ?? {})) {
       const existing = attachedForKind?.[name];
       if (existing !== undefined && existing !== entity) {
-        throw new Error(
+        throw contractError(
+          'CONTRACT.NAME_DUPLICATE',
           `buildSqlContractFromDefinition: two different "${kind}" entities named "${name}" in namespace "${namespaceId}" — a column-referenced entity conflicts with an attached one; pack-entity names must be unique per namespace.`,
+          { meta: { kind, name, namespaceId } },
         );
       }
     }
@@ -377,8 +400,10 @@ function buildThroughDescriptor(
   defaultNamespaceId: string,
 ): ContractRelationThrough {
   if (!tableNamespaceByName.has(through.table)) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.MODEL_UNKNOWN',
       `buildSqlContractFromDefinition: junction table "${through.table}" for relation "${modelName}.${fieldName}" is not a declared model.`,
+      { meta: { sourceModel: modelName, relationName: fieldName, junctionTable: through.table } },
     );
   }
   // Junction table names are unique per namespace, not globally. Prefer the
@@ -405,8 +430,10 @@ function targetColumnsForJunction(targetModel: ModelNode, fieldName: string): re
   if (firstUnique) {
     return firstUnique.columns;
   }
-  throw new Error(
+  throw contractError(
+    'CONTRACT.IDENTITY_INVALID',
     `M:N target model "${targetModel.modelName}" (relation field "${fieldName}") has no primary id or unique key to derive junction targetColumns.`,
+    { meta: { modelName: targetModel.modelName, reason: 'no-key-for-junction-target-columns' } },
   );
 }
 
@@ -515,8 +542,10 @@ function assertNoManagedEntityKinds(
   if (entitiesForNs === undefined) return;
   for (const kind of Object.keys(entitiesForNs)) {
     if (MANAGED_ENTRY_KINDS.has(kind)) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.ENTITY_KIND_INVALID',
         `buildSqlContractFromDefinition: attached entity in namespace "${namespaceId}" declares entry kind "${kind}", which is managed by the framework (table/valueSet) and cannot be attached.`,
+        { meta: { entityKind: kind, namespaceId } },
       );
     }
   }
@@ -528,7 +557,7 @@ function assertNoManagedEntityKinds(
  * the same string a pack entity's entries-map key (`entries.<kind>`) uses.
  * Mirrors `contract-psl`'s `buildEntityTypesByDiscriminator`, recomposed here
  * from the packs `ContractDefinition` already carries (`target` +
- * `extensionPacks`) since the TS assembler has no single pre-merged
+ * `extensions`) since the TS assembler has no single pre-merged
  * `AuthoringContributions` input to read the way the PSL interpreter does.
  */
 function collectEntityTypeDescriptorsByDiscriminator(
@@ -544,7 +573,7 @@ function collectEntityTypeDescriptorsByDiscriminator(
       }
     }
   };
-  const components = [definition.target, ...Object.values(definition.extensionPacks ?? {})];
+  const components = [definition.target, ...Object.values(definition.extensions ?? {})];
   for (const component of components) {
     const entityTypes = component.authoring?.entityTypes;
     if (entityTypes !== undefined) {
@@ -599,8 +628,10 @@ function mergeNamespaceValueSets(
   if (enumValueSets !== undefined && packValueSets !== undefined) {
     for (const name of Object.keys(packValueSets)) {
       if (Object.hasOwn(enumValueSets, name)) {
-        throw new Error(
+        throw contractError(
+          'CONTRACT.NAME_DUPLICATE',
           `buildSqlContractFromDefinition: value-set "${name}" in namespace "${namespaceId}" is derived from both an enum and a pack entity — names must be unique per namespace.`,
+          { meta: { kind: 'valueSet', name, namespaceId } },
         );
       }
     }
@@ -690,13 +721,29 @@ export function buildSqlContractFromDefinition(
           : undefined;
       if (executionDefaultPhases) {
         if (field.default !== undefined) {
-          throw new Error(
+          throw contractError(
+            'CONTRACT.DEFAULT_INVALID',
             `Field "${semanticModel.modelName}.${field.fieldName}" cannot define both default and executionDefaults.`,
+            {
+              meta: {
+                modelName: semanticModel.modelName,
+                fieldName: field.fieldName,
+                reason: 'default-and-executionDefaults',
+              },
+            },
           );
         }
         if (field.nullable) {
-          throw new Error(
+          throw contractError(
+            'CONTRACT.DEFAULT_INVALID',
             `Field "${semanticModel.modelName}.${field.fieldName}" cannot be nullable when executionDefaults are present.`,
+            {
+              meta: {
+                modelName: semanticModel.modelName,
+                fieldName: field.fieldName,
+                reason: 'nullable-with-executionDefaults',
+              },
+            },
           );
         }
       }
@@ -914,8 +961,10 @@ export function buildSqlContractFromDefinition(
         tablesByNamespace[namespaceId] = nsTables;
       }
       if (nsTables[tableName] !== undefined) {
-        throw new Error(
+        throw contractError(
+          'CONTRACT.NAME_DUPLICATE',
           `buildSqlContractFromDefinition: duplicate table "${tableName}" in namespace "${namespaceId}".`,
+          { meta: { kind: 'table', name: tableName, namespaceId } },
         );
       }
       nsTables[tableName] = tableInput;
@@ -978,8 +1027,16 @@ export function buildSqlContractFromDefinition(
 
       if (relation.cardinality === 'N:M') {
         if (!relation.through) {
-          throw new Error(
+          throw contractError(
+            'CONTRACT.RELATION_INVALID',
             `Relation "${semanticModel.modelName}.${relation.fieldName}" with cardinality "N:M" requires through metadata`,
+            {
+              meta: {
+                modelName: semanticModel.modelName,
+                relationName: relation.fieldName,
+                reason: 'many-to-many-missing-through',
+              },
+            },
           );
         }
         modelRelations[relation.fieldName] = {
@@ -1062,8 +1119,16 @@ export function buildSqlContractFromDefinition(
   const storageValueSetsByNs: Record<string, Record<string, StorageValueSetInput>> = {};
   for (const [enumName, handle] of Object.entries(definition.enums ?? {})) {
     if (enumName !== handle.enumName) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.ENUM_INVALID',
         `enum declaration key "${enumName}" must match enumType name "${handle.enumName}". Aliases are not supported.`,
+        {
+          meta: {
+            enumName: handle.enumName,
+            declarationKey: enumName,
+            reason: 'key-name-mismatch',
+          },
+        },
       );
     }
     const nsId = defaultNamespaceId;
@@ -1154,21 +1219,21 @@ export function buildSqlContractFromDefinition(
         }
       : undefined;
 
-  const extensionNamespaces = definition.extensionPacks
-    ? Object.values(definition.extensionPacks).map((pack) => pack.id)
+  const extensionNamespaces = definition.extensions
+    ? Object.values(definition.extensions).map((pack) => pack.id)
     : undefined;
 
-  const extensionPacks: Record<string, unknown> = { ...(definition.extensionPacks || {}) };
+  const extensions: Record<string, unknown> = { ...(definition.extensions || {}) };
   if (extensionNamespaces) {
     for (const namespace of extensionNamespaces) {
-      if (!Object.hasOwn(extensionPacks, namespace)) {
-        extensionPacks[namespace] = {};
+      if (!Object.hasOwn(extensions, namespace)) {
+        extensions[namespace] = {};
       }
     }
   }
 
-  const extensionPackCapabilitySources = definition.extensionPacks
-    ? Object.values(definition.extensionPacks).map(
+  const extensionPackCapabilitySources = definition.extensions
+    ? Object.values(definition.extensions).map(
         (pack) => pack.capabilities as CapabilityMatrix | undefined,
       )
     : [];
@@ -1258,7 +1323,7 @@ export function buildSqlContractFromDefinition(
     roots,
     storage,
     ...(executionWithHash ? { execution: executionWithHash } : {}),
-    extensionPacks,
+    extensions,
     capabilities,
     profileHash,
     meta: {},

package/src/composed-authoring-helpers.ts

@@ -37,6 +37,7 @@ import type {
   ScalarFieldBuilder,
 } from './contract-dsl';
 import { buildFieldPreset, field, model, rel } from './contract-dsl';
+import { contractError } from './contract-errors';
 import type { MergeExtensionIndexTypes } from './contract-types';
 
 type ExtractTypeNamespaceFromPack<Pack> = ExtractAuthoringNamespaceFromPack<
@@ -55,16 +56,16 @@ type ExtractEntitiesNamespaceFromPack<Pack> = ExtractAuthoringNamespaceFromPack<
   Record<never, never>
 >;
 
-type MergeExtensionTypeNamespaces<ExtensionPacks> = MergeExtensionAuthoringNamespaces<
-  ExtensionPacks,
+type MergeExtensionTypeNamespaces<Extensions> = MergeExtensionAuthoringNamespaces<
+  Extensions,
   'type'
 >;
-type MergeExtensionFieldNamespaces<ExtensionPacks> = MergeExtensionAuthoringNamespaces<
-  ExtensionPacks,
+type MergeExtensionFieldNamespaces<Extensions> = MergeExtensionAuthoringNamespaces<
+  Extensions,
   'field'
 >;
-type MergeExtensionEntityNamespaces<ExtensionPacks> = MergeExtensionAuthoringNamespaces<
-  ExtensionPacks,
+type MergeExtensionEntityNamespaces<Extensions> = MergeExtensionAuthoringNamespaces<
+  Extensions,
   'entityTypes'
 >;
 
@@ -100,12 +101,12 @@ type TypeHelpersFromNamespace<Namespace> = {
 
 type CoreFieldHelpers = Pick<typeof field, 'column' | 'generated' | 'namedType'>;
 
-type MergeAllPackIndexTypes<Family, Target, ExtensionPacks> = MergeExtensionIndexTypes<
-  { readonly __family: Family; readonly __target: Target } & (ExtensionPacks extends Record<
+type MergeAllPackIndexTypes<Family, Target, Extensions> = MergeExtensionIndexTypes<
+  { readonly __family: Family; readonly __target: Target } & (Extensions extends Record<
     string,
     unknown
   >
-    ? ExtensionPacks
+    ? Extensions
     : Record<never, never>)
 >;
 
@@ -131,24 +132,24 @@ type PackAwareModel<IndexTypes extends IndexTypeMap> = {
 export type ComposedAuthoringHelpers<
   Family extends FamilyPackRef<string>,
   Target extends TargetPackRef<'sql', string>,
-  ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
+  Extensions extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
 > = EntityHelpersFromNamespace<
   ExtractEntitiesNamespaceFromPack<Family> &
     ExtractEntitiesNamespaceFromPack<Target> &
-    MergeExtensionEntityNamespaces<ExtensionPacks>
+    MergeExtensionEntityNamespaces<Extensions>
 > & {
   readonly field: CoreFieldHelpers &
     FieldHelpersFromNamespace<
       ExtractFieldNamespaceFromPack<Family> &
         ExtractFieldNamespaceFromPack<Target> &
-        MergeExtensionFieldNamespaces<ExtensionPacks>
+        MergeExtensionFieldNamespaces<Extensions>
     >;
-  readonly model: PackAwareModel<MergeAllPackIndexTypes<Family, Target, ExtensionPacks>>;
+  readonly model: PackAwareModel<MergeAllPackIndexTypes<Family, Target, Extensions>>;
   readonly rel: typeof rel;
   readonly type: TypeHelpersFromNamespace<
     ExtractTypeNamespaceFromPack<Family> &
       ExtractTypeNamespaceFromPack<Target> &
-      MergeExtensionTypeNamespaces<ExtensionPacks>
+      MergeExtensionTypeNamespaces<Extensions>
   >;
 };
 
@@ -224,8 +225,10 @@ const RESERVED_HELPER_KEYS: readonly string[] = ['field', 'model', 'rel', 'type'
 function assertNoBuiltInEntityCollisions(namespace: AuthoringEntityTypeNamespace): void {
   const collisions = Object.keys(namespace).filter((name) => RESERVED_HELPER_KEYS.includes(name));
   if (collisions.length > 0) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.PACK_CONTRIBUTION_INVALID',
       `Pack-contributed entity type(s) ${collisions.map((c) => `"${c}"`).join(', ')} collide with the reserved built-in helper key(s) on the composed helpers surface. Reserved keys: ${RESERVED_HELPER_KEYS.map((k) => `"${k}"`).join(', ')}.`,
+      { meta: { collisions, reservedKeys: RESERVED_HELPER_KEYS } },
     );
   }
 }
@@ -252,8 +255,10 @@ function createComposedFieldHelpers(
   const coreHelperNames = new Set(Object.keys(coreFieldHelpers));
   for (const helperName of Object.keys(helperNamespace)) {
     if (coreHelperNames.has(helperName)) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.PACK_CONTRIBUTION_INVALID',
         `Duplicate authoring field helper "${helperName}". Core field helpers reserve that name.`,
+        { meta: { helperName } },
       );
     }
   }
@@ -267,14 +272,14 @@ function createComposedFieldHelpers(
 export function createComposedAuthoringHelpers<
   Family extends FamilyPackRef<string>,
   Target extends TargetPackRef<'sql', string>,
-  ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
+  Extensions extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
 >(options: {
   readonly family: Family;
   readonly target: Target;
-  readonly extensionPacks?: ExtensionPacks;
-}): ComposedAuthoringHelpers<Family, Target, ExtensionPacks> {
+  readonly extensions?: Extensions;
+}): ComposedAuthoringHelpers<Family, Target, Extensions> {
   const extensionValues: readonly ExtensionPackRef<'sql', string>[] = Object.values(
-    (options.extensionPacks ?? {}) as Record<string, ExtensionPackRef<'sql', string>>,
+    (options.extensions ?? {}) as Record<string, ExtensionPackRef<'sql', string>>,
   );
   const components: readonly AuthoringComponent[] = [
     options.family,
@@ -298,5 +303,5 @@ export function createComposedAuthoringHelpers<
     model,
     rel,
     type: createTypeHelpersFromNamespace(typeNamespace),
-  } as ComposedAuthoringHelpers<Family, Target, ExtensionPacks>;
+  } as ComposedAuthoringHelpers<Family, Target, Extensions>;
 }

package/src/config-types.ts

@@ -5,9 +5,11 @@ import type { Contract, ControlPolicy } from '@prisma-next/contract/types';
 import type { TargetPackRef } from '@prisma-next/framework-components/components';
 import type { SqlNamespaceBase, SqlNamespaceInput } from '@prisma-next/sql-contract/types';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { ok } from '@prisma-next/utils/result';
 import { extname } from 'pathe';
 import { buildSqlContractFromDefinition } from './build-contract';
+import { contractError } from './contract-errors';
 
 /**
  * Derives the emit output path from the TS contract input so artefacts land
@@ -33,7 +35,7 @@ export function emptyContract(options: {
 }): ContractConfig {
   return {
     source: {
-      sourceFormat: 'typescript',
+      format: 'typescript',
       load: async () => {
         const built = buildSqlContractFromDefinition({
           target: options.target,
@@ -54,7 +56,7 @@ export function typescriptContract(
 ): ContractConfig {
   return {
     source: {
-      sourceFormat: 'typescript',
+      format: 'typescript',
       load: async () =>
         ok(applySpecifierDefaultControlPolicy(contract, options?.defaultControlPolicy)),
     },
@@ -71,20 +73,22 @@ export function typescriptContractFromPath(
 ): ContractConfig {
   return {
     source: {
-      sourceFormat: 'typescript',
+      format: 'typescript',
       inputs: [contractPath],
       load: async (context) => {
         const [absolutePath] = context.resolvedInputs;
         if (absolutePath === undefined) {
-          throw new Error(
+          throw new InternalError(
             'typescriptContractFromPath: context.resolvedInputs is empty. The CLI config loader should populate it positional-matched with source.inputs.',
           );
         }
         const mod = await import(pathToFileURL(absolutePath).href);
         const contract: Contract | undefined = mod.default ?? mod.contract;
         if (contract === undefined) {
-          throw new Error(
+          throw contractError(
+            'CONTRACT.MODULE_EXPORT_MISSING',
             `typescriptContractFromPath: module at "${absolutePath}" has no "default" or "contract" export.`,
+            { meta: { path: absolutePath } },
           );
         }
         return ok(applySpecifierDefaultControlPolicy(contract, options?.defaultControlPolicy));