@prisma-next/sql-contract-ts 0.3.0-dev.15 → 0.3.0-dev.162

package/src/contract-builder.ts

@@ -1,561 +1,267 @@
-import type { ExtensionPackRef, TargetPackRef } from '@prisma-next/contract/framework-components';
+import type { ForeignKeyDefaultsState } from '@prisma-next/contract-authoring';
+import type { CodecLookup } from '@prisma-next/framework-components/codec';
 import type {
-  ColumnBuilderState,
-  ModelBuilderState,
-  RelationDefinition,
-  TableBuilderState,
-} from '@prisma-next/contract-authoring';
+  ExtensionPackRef,
+  FamilyPackRef,
+  TargetPackRef,
+} from '@prisma-next/framework-components/components';
+import type { StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import { buildSqlContractFromDefinition } from './build-contract';
 import {
-  type BuildModels,
-  type BuildRelations,
-  type BuildStorageColumn,
-  ContractBuilder,
-  type ExtractColumns,
-  type ExtractPrimaryKey,
-  ModelBuilder,
-  type Mutable,
-  TableBuilder,
-} from '@prisma-next/contract-authoring';
-import type {
-  ModelDefinition,
-  ModelField,
-  SqlContract,
-  SqlMappings,
-  SqlStorage,
-} from '@prisma-next/sql-contract/types';
-import { computeMappings } from './contract';
-
-/**
- * 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;
+  type ComposedAuthoringHelpers,
+  createComposedAuthoringHelpers,
+} from './composed-authoring-helpers';
+import {
+  type ContractInput,
+  type ContractModelBuilder,
+  field,
+  isContractInput,
+  type ModelAttributesSpec,
+  model,
+  type RelationBuilder,
+  type RelationState,
+  rel,
+  type ScalarFieldBuilder,
+  type SqlStageSpec,
+} from './contract-dsl';
+import { buildContractDefinition } from './contract-lowering';
+import type { SqlContractResult } from './contract-types';
+
+export { buildSqlContractFromDefinition } from './build-contract';
+
+type ModelLike = {
+  readonly stageOne: {
+    readonly modelName?: string;
+    readonly fields: Record<string, ScalarFieldBuilder>;
+    readonly relations: Record<string, RelationBuilder<RelationState>>;
   };
-  readonly uniques: ReadonlyArray<never>;
-  readonly indexes: ReadonlyArray<never>;
-  readonly foreignKeys: ReadonlyArray<never>;
-} & (PK extends readonly string[]
-  ? { readonly primaryKey: { readonly columns: PK } }
-  : Record<string, never>);
+  readonly __attributes: ModelAttributesSpec | undefined;
+  readonly __sql: SqlStageSpec | undefined;
+  buildAttributesSpec(): ModelAttributesSpec | undefined;
+  buildSqlSpec(): SqlStageSpec | undefined;
+};
 
-type BuildStorage<
-  Tables extends Record<
-    string,
-    TableBuilderState<
-      string,
-      Record<string, ColumnBuilderState<string, boolean, string>>,
-      readonly string[] | undefined
-    >
-  >,
+type ContractDefinition<
+  Family extends FamilyPackRef<string>,
+  Target extends TargetPackRef<'sql', string>,
+  Types extends Record<string, StorageTypeInstance>,
+  Models extends Record<string, ModelLike>,
+  ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
+  Capabilities extends Record<string, Record<string, boolean>> | undefined,
+  Naming extends ContractInput['naming'] | undefined,
+  StorageHash extends string | undefined,
+  ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined,
 > = {
-  readonly tables: {
-    readonly [K in keyof Tables]: BuildStorageTable<
-      K & string,
-      ExtractColumns<Tables[K]>,
-      ExtractPrimaryKey<Tables[K]>
-    >;
-  };
+  readonly family: Family;
+  readonly target: Target;
+  readonly extensionPacks?: ExtensionPacks;
+  readonly naming?: Naming;
+  readonly storageHash?: StorageHash;
+  readonly foreignKeyDefaults?: ForeignKeyDefaults;
+  readonly capabilities?: Capabilities;
+  readonly types?: Types;
+  readonly models?: Models;
+  readonly codecLookup?: CodecLookup;
 };
 
-type BuildStorageTables<
-  Tables extends Record<
-    string,
-    TableBuilderState<
-      string,
-      Record<string, ColumnBuilderState<string, boolean, string>>,
-      readonly string[] | undefined
-    >
-  >,
+type ContractScaffold<
+  Family extends FamilyPackRef<string>,
+  Target extends TargetPackRef<'sql', string>,
+  ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
+  Capabilities extends Record<string, Record<string, boolean>> | undefined,
+  Naming extends ContractInput['naming'] | undefined,
+  StorageHash extends string | undefined,
+  ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined,
 > = {
-  readonly [K in keyof Tables]: BuildStorageTable<
-    K & string,
-    ExtractColumns<Tables[K]>,
-    ExtractPrimaryKey<Tables[K]>
-  >;
+  readonly family: Family;
+  readonly target: Target;
+  readonly extensionPacks?: ExtensionPacks;
+  readonly naming?: Naming;
+  readonly storageHash?: StorageHash;
+  readonly foreignKeyDefaults?: ForeignKeyDefaults;
+  readonly capabilities?: Capabilities;
+  readonly codecLookup?: CodecLookup;
 };
 
-export 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>;
-}
-
-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 {
-    // Type helper to ensure literal types are preserved in return type
-    type BuiltContract = 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;
-    if (!this.state.target) {
-      throw new Error('target is required. Call .target() before .build()');
-    }
-
-    const target = this.state.target as Target & string;
-
-    const storageTables = {} as Partial<Mutable<BuildStorageTables<Tables>>>;
-
-    for (const tableName of Object.keys(this.state.tables) as Array<keyof Tables & string>) {
-      const tableState = this.state.tables[tableName];
-      if (!tableState) continue;
-
-      type TableKey = typeof tableName;
-      type ColumnDefs = ExtractColumns<Tables[TableKey]>;
-      type PrimaryKey = ExtractPrimaryKey<Tables[TableKey]>;
-
-      const columns = {} as Partial<{
-        [K in keyof ColumnDefs]: BuildStorageColumn<
-          ColumnDefs[K]['nullable'] & boolean,
-          ColumnDefs[K]['type']
-        >;
-      }>;
-
-      for (const columnName in tableState.columns) {
-        const columnState = tableState.columns[columnName];
-        if (!columnState) continue;
-        const codecId = columnState.type;
-        const nativeType = columnState.nativeType;
-
-        columns[columnName as keyof ColumnDefs] = {
-          nativeType,
-          codecId,
-          nullable: (columnState.nullable ?? false) as ColumnDefs[keyof ColumnDefs]['nullable'] &
-            boolean,
-        } as BuildStorageColumn<
-          ColumnDefs[keyof ColumnDefs]['nullable'] & boolean,
-          ColumnDefs[keyof ColumnDefs]['type']
-        >;
-      }
-
-      const table = {
-        columns: columns as {
-          [K in keyof ColumnDefs]: BuildStorageColumn<
-            ColumnDefs[K]['nullable'] & boolean,
-            ColumnDefs[K]['type']
-          >;
-        },
-        uniques: [],
-        indexes: [],
-        foreignKeys: [],
-        ...(tableState.primaryKey
-          ? {
-              primaryKey: {
-                columns: tableState.primaryKey,
-              },
-            }
-          : {}),
-      } as unknown as BuildStorageTable<TableKey & string, ColumnDefs, PrimaryKey>;
-
-      (storageTables as Mutable<BuildStorageTables<Tables>>)[tableName] = table;
-    }
-
-    const storage = { tables: storageTables as BuildStorageTables<Tables> } as BuildStorage<Tables>;
-
-    // Build models - construct as partial first, then assert full type
-    const modelsPartial: Partial<BuildModels<Models>> = {};
-
-    // Iterate over models - TypeScript will see keys as string, but type assertion preserves literals
-    for (const modelName in this.state.models) {
-      const modelState = this.state.models[modelName];
-      if (!modelState) continue;
+type ContractFactory<
+  Family extends FamilyPackRef<string>,
+  Target extends TargetPackRef<'sql', string>,
+  Types extends Record<string, StorageTypeInstance>,
+  Models extends Record<string, ModelLike>,
+  ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
+> = (helpers: ComposedAuthoringHelpers<Family, Target, ExtensionPacks>) => {
+  readonly types?: Types;
+  readonly models?: Models;
+};
 
-      const modelStateTyped = modelState as unknown as {
-        name: string;
-        table: string;
-        fields: Record<string, string>;
-      };
+function validateTargetPackRef(
+  family: FamilyPackRef<string>,
+  target: TargetPackRef<'sql', string>,
+): void {
+  if (family.familyId !== 'sql') {
+    throw new Error(
+      `defineContract only accepts SQL family packs. Received family "${family.familyId}".`,
+    );
+  }
 
-      // Build fields object
-      const fields: Partial<Record<string, ModelField>> = {};
+  if (target.familyId !== family.familyId) {
+    throw new Error(
+      `target pack "${target.id}" targets family "${target.familyId}" but contract family is "${family.familyId}".`,
+    );
+  }
+}
 
-      // Iterate over fields
-      for (const fieldName in modelStateTyped.fields) {
-        const columnName = modelStateTyped.fields[fieldName];
-        if (columnName) {
-          fields[fieldName] = {
-            column: columnName,
-          };
-        }
-      }
+function validateExtensionPackRefs(
+  target: TargetPackRef<'sql', string>,
+  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
+): void {
+  if (!extensionPacks) {
+    return;
+  }
 
-      // Assign to models - type assertion preserves literal keys
-      (modelsPartial as unknown as Record<string, ModelDefinition>)[modelName] = {
-        storage: {
-          table: modelStateTyped.table,
-        },
-        fields: fields as Record<string, ModelField>,
-        relations: {},
-      };
+  for (const packRef of Object.values(extensionPacks)) {
+    if (packRef.kind !== 'extension') {
+      throw new Error(
+        `defineContract only accepts extension pack refs in extensionPacks. Received kind "${packRef.kind}".`,
+      );
     }
 
-    // Build relations object - organized by table name
-    const relationsPartial: Partial<Record<string, Record<string, RelationDefinition>>> = {};
-
-    // Iterate over models to collect relations
-    for (const modelName in this.state.models) {
-      const modelState = this.state.models[modelName];
-      if (!modelState) continue;
-
-      const modelStateTyped = modelState as unknown as {
-        name: string;
-        table: string;
-        fields: Record<string, string>;
-        relations: Record<string, RelationDefinition>;
-      };
-
-      const tableName = modelStateTyped.table;
-      if (!tableName) continue;
-
-      // Only initialize relations object for this table if it has relations
-      if (modelStateTyped.relations && Object.keys(modelStateTyped.relations).length > 0) {
-        if (!relationsPartial[tableName]) {
-          relationsPartial[tableName] = {};
-        }
-
-        // Add relations from this model to the table's relations
-        const tableRelations = relationsPartial[tableName];
-        if (tableRelations) {
-          for (const relationName in modelStateTyped.relations) {
-            const relation = modelStateTyped.relations[relationName];
-            if (relation) {
-              tableRelations[relationName] = relation;
-            }
-          }
-        }
-      }
+    if (packRef.familyId !== target.familyId) {
+      throw new Error(
+        `extension pack "${packRef.id}" targets family "${packRef.familyId}" but contract target family is "${target.familyId}".`,
+      );
     }
 
-    const models = modelsPartial as unknown as BuildModels<Models>;
-
-    const baseMappings = computeMappings(
-      models as unknown as Record<string, ModelDefinition>,
-      storage as SqlStorage,
-    );
-
-    const mappings = {
-      ...baseMappings,
-      codecTypes: {} as CodecTypes,
-      operationTypes: {} as Record<string, never>,
-    } as ContractBuilderMappings<CodecTypes>;
-
-    const extensionNamespaces = this.state.extensionNamespaces ?? [];
-    const extensionPacks: Record<string, unknown> = { ...(this.state.extensionPacks || {}) };
-    for (const namespace of extensionNamespaces) {
-      if (!Object.hasOwn(extensionPacks, namespace)) {
-        extensionPacks[namespace] = {};
-      }
+    if (packRef.targetId && packRef.targetId !== target.targetId) {
+      throw new Error(
+        `extension pack "${packRef.id}" targets "${packRef.targetId}" but contract target is "${target.targetId}".`,
+      );
     }
+  }
+}
 
-    // Construct contract with explicit type that matches the generic parameters
-    // This ensures TypeScript infers literal types from the generics, not runtime values
-    // Always include relations, even if empty (normalized to empty object)
-    const contract = {
-      schemaVersion: '1' as const,
-      target,
-      targetFamily: 'sql' as const,
-      coreHash: this.state.coreHash || 'sha256:ts-builder-placeholder',
-      models,
-      relations: relationsPartial,
-      storage,
-      mappings,
-      extensionPacks,
-      capabilities: this.state.capabilities || {},
-      meta: {},
-      sources: {},
-    } as unknown as BuiltContract;
+function buildContractFromDsl<Definition extends ContractInput>(
+  definition: Definition,
+): SqlContractResult<Definition>;
 
-    return contract as unknown as ReturnType<
-      SqlContractBuilder<
-        CodecTypes,
-        Target,
-        Tables,
-        Models,
-        CoreHash,
-        ExtensionPacks,
-        Capabilities
-      >['build']
-    >;
-  }
+function buildContractFromDsl(
+  definition: ContractInput,
+): ReturnType<typeof buildSqlContractFromDefinition> {
+  validateTargetPackRef(definition.family, definition.target);
+  validateExtensionPackRefs(definition.target, definition.extensionPacks);
 
-  override target<T extends string>(
-    packRef: TargetPackRef<'sql', T>,
-  ): SqlContractBuilder<CodecTypes, T, Tables, Models, CoreHash, ExtensionPacks, Capabilities> {
-    return new SqlContractBuilder<
-      CodecTypes,
-      T,
-      Tables,
-      Models,
-      CoreHash,
-      ExtensionPacks,
-      Capabilities
-    >({
-      ...this.state,
-      target: packRef.targetId,
-    });
-  }
+  return buildSqlContractFromDefinition(
+    buildContractDefinition(definition),
+    definition.codecLookup,
+  );
+}
 
-  extensionPacks(
-    packs: Record<string, ExtensionPackRef<'sql', string>>,
-  ): SqlContractBuilder<
-    CodecTypes,
+export function defineContract<
+  const Family extends FamilyPackRef<string>,
+  const Target extends TargetPackRef<'sql', string>,
+  const Types extends Record<string, StorageTypeInstance> = Record<never, never>,
+  const Models extends Record<string, ModelLike> = Record<never, never>,
+  const ExtensionPacks extends
+    | Record<string, ExtensionPackRef<'sql', string>>
+    | undefined = undefined,
+  const Capabilities extends Record<string, Record<string, boolean>> | undefined = undefined,
+  const Naming extends ContractInput['naming'] | undefined = undefined,
+  const StorageHash extends string | undefined = undefined,
+  const ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined,
+>(
+  definition: ContractDefinition<
+    Family,
     Target,
-    Tables,
+    Types,
     Models,
-    CoreHash,
     ExtensionPacks,
-    Capabilities
-  > {
-    if (!this.state.target) {
-      throw new Error('extensionPacks() requires target() to be called first');
-    }
-
-    const namespaces = new Set(this.state.extensionNamespaces ?? []);
-
-    for (const packRef of Object.values(packs)) {
-      if (!packRef) continue;
-
-      if (packRef.kind !== 'extension') {
-        throw new Error(
-          `extensionPacks() only accepts extension pack refs. Received kind "${packRef.kind}".`,
-        );
-      }
-
-      if (packRef.familyId !== 'sql') {
-        throw new Error(
-          `extension pack "${packRef.id}" targets family "${packRef.familyId}" but this builder targets "sql".`,
-        );
-      }
-
-      if (packRef.targetId && packRef.targetId !== this.state.target) {
-        throw new Error(
-          `extension pack "${packRef.id}" targets "${packRef.targetId}" but builder target is "${this.state.target}".`,
-        );
-      }
-
-      namespaces.add(packRef.id);
-    }
-
-    return new SqlContractBuilder<
-      CodecTypes,
-      Target,
-      Tables,
-      Models,
-      CoreHash,
-      ExtensionPacks,
-      Capabilities
-    >({
-      ...this.state,
-      extensionNamespaces: [...namespaces],
-    });
-  }
-
-  override capabilities<C extends Record<string, Record<string, boolean>>>(
-    capabilities: C,
-  ): SqlContractBuilder<CodecTypes, Target, Tables, Models, CoreHash, ExtensionPacks, C> {
-    return new SqlContractBuilder<CodecTypes, Target, Tables, Models, CoreHash, ExtensionPacks, C>({
-      ...this.state,
-      capabilities,
-    });
-  }
-
-  override coreHash<H extends string>(
-    hash: H,
-  ): SqlContractBuilder<CodecTypes, Target, Tables, Models, H, ExtensionPacks, Capabilities> {
-    return new SqlContractBuilder<
-      CodecTypes,
-      Target,
-      Tables,
-      Models,
-      H,
-      ExtensionPacks,
-      Capabilities
-    >({
-      ...this.state,
-      coreHash: hash,
-    });
-  }
-
-  override 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,
+    Capabilities,
+    Naming,
+    StorageHash,
+    ForeignKeyDefaults
+  >,
+): SqlContractResult<
+  ContractDefinition<
+    Family,
     Target,
-    Tables & Record<TableName, ReturnType<T['build']>>,
+    Types,
     Models,
-    CoreHash,
     ExtensionPacks,
-    Capabilities
-  > {
-    const tableBuilder = new TableBuilder<TableName>(name);
-    const result = callback(tableBuilder);
-    const finalBuilder = result instanceof TableBuilder ? result : tableBuilder;
-    const tableState = finalBuilder.build();
-
-    return new SqlContractBuilder<
-      CodecTypes,
-      Target,
-      Tables & Record<TableName, ReturnType<T['build']>>,
-      Models,
-      CoreHash,
-      ExtensionPacks,
-      Capabilities
-    >({
-      ...this.state,
-      tables: { ...this.state.tables, [name]: tableState } as Tables &
-        Record<TableName, ReturnType<T['build']>>,
-    });
-  }
-
-  override 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,
+    Capabilities,
+    Naming,
+    StorageHash,
+    ForeignKeyDefaults
+  >
+>;
+export function defineContract<
+  const Family extends FamilyPackRef<string>,
+  const Target extends TargetPackRef<'sql', string>,
+  const Types extends Record<string, StorageTypeInstance> = Record<never, never>,
+  const Models extends Record<string, ModelLike> = Record<never, never>,
+  const ExtensionPacks extends
+    | Record<string, ExtensionPackRef<'sql', string>>
+    | undefined = undefined,
+  const Capabilities extends Record<string, Record<string, boolean>> | undefined = undefined,
+  const Naming extends ContractInput['naming'] | undefined = undefined,
+  const StorageHash extends string | undefined = undefined,
+  const ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined,
+>(
+  definition: ContractScaffold<
+    Family,
+    Target,
+    ExtensionPacks,
+    Capabilities,
+    Naming,
+    StorageHash,
+    ForeignKeyDefaults
+  >,
+  factory: ContractFactory<Family, Target, Types, Models, ExtensionPacks>,
+): SqlContractResult<
+  ContractDefinition<
+    Family,
     Target,
-    Tables,
-    Models & Record<ModelName, ReturnType<M['build']>>,
-    CoreHash,
+    Types,
+    Models,
     ExtensionPacks,
-    Capabilities
-  > {
-    const modelBuilder = new ModelBuilder<ModelName, TableName>(name, table);
-    const result = callback(modelBuilder);
-    const finalBuilder = result instanceof ModelBuilder ? result : modelBuilder;
-    const modelState = finalBuilder.build();
+    Capabilities,
+    Naming,
+    StorageHash,
+    ForeignKeyDefaults
+  >
+>;
+export function defineContract(
+  definition: ContractInput,
+  factory?: ContractFactory<
+    FamilyPackRef<string>,
+    TargetPackRef<'sql', string>,
+    Record<string, StorageTypeInstance>,
+    Record<string, ModelLike>,
+    Record<string, ExtensionPackRef<'sql', string>> | undefined
+  >,
+): SqlContractResult<ContractInput> {
+  if (!isContractInput(definition)) {
+    throw new TypeError(
+      'defineContract expects a contract definition object. Define your contract with defineContract({ family, target, models, ... }).',
+    );
+  }
 
-    return new SqlContractBuilder<
-      CodecTypes,
-      Target,
-      Tables,
-      Models & Record<ModelName, ReturnType<M['build']>>,
-      CoreHash,
-      ExtensionPacks,
-      Capabilities
-    >({
-      ...this.state,
-      models: { ...this.state.models, [name]: modelState } as Models &
-        Record<ModelName, ReturnType<M['build']>>,
-    });
+  if (!factory) {
+    return buildContractFromDsl(definition);
   }
-}
 
-export function defineContract<
-  CodecTypes extends Record<string, { output: unknown }> = Record<string, never>,
->(): SqlContractBuilder<CodecTypes> {
-  return new SqlContractBuilder<CodecTypes>();
+  const builtDefinition = {
+    ...definition,
+    ...factory(
+      createComposedAuthoringHelpers({
+        family: definition.family,
+        target: definition.target,
+        extensionPacks: definition.extensionPacks,
+      }),
+    ),
+  };
+
+  return buildContractFromDsl(builtDefinition);
 }
+
+export { field, model, rel };
+export type { ComposedAuthoringHelpers, ContractInput, ContractModelBuilder, ScalarFieldBuilder };