@prisma-next/sql-contract-ts 0.12.0 → 0.13.0-dev.10

package/dist/contract-builder.d.mts

@@ -1,19 +1,156 @@
-import { ColumnDefault, ColumnDefaultLiteralInputValue, Contract, ContractRelation, ExecutionMutationDefaultPhases, ExecutionMutationDefaultPhases as ExecutionMutationDefaultPhases$1, ExecutionMutationDefaultValue, NamespaceId, StorageHashBase } from "@prisma-next/contract/types";
+import { ColumnDefault, ColumnDefaultLiteralInputValue, Contract, ContractRelation, ControlPolicy, ExecutionMutationDefaultPhases, ExecutionMutationDefaultPhases as ExecutionMutationDefaultPhases$1, ExecutionMutationDefaultValue, NamespaceId, StorageHashBase } from "@prisma-next/contract/types";
 import { EntityHelpersFromNamespace, ExtractAuthoringNamespaceFromPack, ForeignKeyDefaultsState, MergeExtensionAuthoringNamespaces } from "@prisma-next/contract-authoring";
-import { Namespace } from "@prisma-next/framework-components/ir";
+import { Namespace, StorageType } from "@prisma-next/framework-components/ir";
 import { IndexTypeRegistration } from "@prisma-next/sql-contract/index-types";
 import { ContractWithTypeMaps, Index as Index$1, PostgresEnumStorageEntry, ReferentialAction, SqlNamespaceTablesInput, SqlStorage, StorageTypeInstance, TypeMaps } from "@prisma-next/sql-contract/types";
 import { AuthoringArgumentDescriptor, AuthoringFieldPresetDescriptor, AuthoringTypeConstructorDescriptor } from "@prisma-next/framework-components/authoring";
 import { ExtensionPackRef, FamilyPackRef, TargetPackRef } from "@prisma-next/framework-components/components";
 import { CodecLookup, ColumnTypeDescriptor } from "@prisma-next/framework-components/codec";
 
+//#region src/enum-type.d.ts
+/**
+ * A single enum member produced by `member()`. The `Name` and `Value` generics
+ * are preserved as literal types so `enumType()` can carry the ordered value
+ * tuple in its return type. `Value` is whatever the codec dictates — its type
+ * is constrained at `enumType` against the codec's input type, not here.
+ */
+interface EnumMember<Name extends string, Value> {
+  readonly name: Name;
+  readonly value: Value;
+}
+/**
+ * Declare an enum member. The `value` defaults to `name` when omitted. The
+ * value is an unconstrained literal here; `enumType` constrains it against the
+ * codec's input type. Both generics are preserved as literals so downstream
+ * `enumType` carries the value union in its type; the value is serialized to its
+ * codec string form only at lowering.
+ */
+declare function member<const Name extends string>(name: Name): EnumMember<Name, Name>;
+declare function member<const Name extends string, const Value>(name: Name, value: Value): EnumMember<Name, Value>;
+type MembersToValues<Members extends readonly EnumMember<string, unknown>[]> = { readonly [K in keyof Members]: Members[K] extends EnumMember<string, infer V> ? V : never };
+type MembersToNames<Members extends readonly EnumMember<string, unknown>[]> = { readonly [K in keyof Members]: Members[K] extends EnumMember<infer N, unknown> ? N : never };
+type MembersAccessorMap<Members extends readonly EnumMember<string, unknown>[]> = { readonly [M in Members[number] as M['name']]: M['value'] };
+/**
+ * Internal brand that identifies an EnumTypeHandle in the lowering pipeline.
+ * Not exported — callers only interact with `EnumTypeHandle`.
+ */
+declare const ENUM_TYPE_HANDLE_BRAND: unique symbol;
+/**
+ * Authoring handle returned by `enumType()`. Carries:
+ *
+ * - The ordered literal value tuple (`.values`) and name tuple (`.names`)
+ *   so downstream type-tests can assert literal preservation.
+ * - A namespaced member accessor map (`.members`) to avoid collisions with
+ *   `.values` / `.has` / `.nameOf` / `.ordinalOf`.
+ * - Runtime helpers `.has()`, `.nameOf()`, `.ordinalOf()`.
+ * - Internal metadata (`enumName`, `codecId`, `nativeType`,
+ *   `enumMembers`) for the lowering pipeline.
+ *
+ * The type is generic over the ordered value tuple so callers that assign
+ * `const Role = enumType(...)` retain the literal tuple on `.values`.
+ */
+interface EnumTypeHandle<Name extends string = string, Values extends readonly unknown[] = readonly unknown[], Names extends readonly string[] = readonly string[], MembersMap extends Record<string, unknown> = Record<string, unknown>> {
+  /** Internal brand for lowering-pipeline detection. */
+  readonly [ENUM_TYPE_HANDLE_BRAND]: true;
+  /** The enum's declared name (used as the key in domain `enum` / storage `valueSet`). */
+  readonly enumName: Name;
+  /** codecId from the codec passed to `enumType`. */
+  readonly codecId: string;
+  /** nativeType from the codec passed to `enumType`. */
+  readonly nativeType: string;
+  /** Ordered member list for lowering (name + value pairs). */
+  readonly enumMembers: readonly {
+    readonly name: string;
+    readonly value: Values[number];
+  }[];
+  /** Ordered literal value tuple. Declaration order is preserved. */
+  readonly values: Values;
+  /** Ordered literal name tuple. Declaration order is preserved. */
+  readonly names: Names;
+  /**
+   * Namespaced accessor map: `Role.members.User === 'user'`.
+   * Namespaced under `.members` to avoid collisions with `.values` / `.has`.
+   */
+  readonly members: MembersMap;
+  /** Returns `true` if `v` is a declared member value. */
+  has(v: Values[number]): boolean;
+  /** Returns the member name for a value, or `undefined` if not found. */
+  nameOf(v: Values[number]): string | undefined;
+  /** Returns the zero-based declaration index of a value, or `-1` if not found. */
+  ordinalOf(v: Values[number]): number;
+}
+/**
+ * A codec typemap: codecId → `{ input, output }`, the same shape the query
+ * lanes consume (e.g. `{ 'pg/text@1': { input: string }, 'pg/int4@1': { input: number } }`).
+ * The bound `enumType` wrappers supply the target pack's typemap; the core
+ * defaults to an empty map (no codec is known), so member values stay
+ * unconstrained.
+ */
+type CodecTypeMap = Record<string, {
+  readonly input?: unknown;
+}>;
+/**
+ * The application input type the codec dictates for an enum's member values:
+ * looks `Codec['codecId']` up in the supplied codec typemap. When the codecId
+ * isn't in the map (the core's empty default, or an unknown codec) the input is
+ * unconstrained, so any member-value literal is accepted and inferred verbatim.
+ */
+type CodecInput<CodecTypes extends CodecTypeMap, Codec extends {
+  readonly codecId: string;
+}> = Codec['codecId'] extends keyof CodecTypes ? CodecTypes[Codec['codecId']] extends {
+  readonly input: infer In;
+} ? In : unknown : unknown;
+/**
+ * Declare a domain enum for use in TS-authoring contracts.
+ *
+ * - The codec is an explicit required argument — the `codecId` and
+ *   `nativeType` are taken from the passed `ColumnTypeDescriptor` (e.g.
+ *   `{ codecId: 'pg/text@1', nativeType: 'text' }` from a field preset
+ *   output or a direct inline object).
+ * - `const` generics on the members spread preserve the ordered literal
+ *   value tuple so `Role.values` is `readonly ['user','admin']`, not
+ *   `string[]`.
+ * - Well-formedness assertions at construction: non-empty member list;
+ *   unique names; unique values.
+ *
+ * The returned handle wires into `field.namedType(handle)` to set
+ * `valueSet` refs on both the domain field and the storage column.
+ *
+ * @example
+ * ```ts
+ * const Role = enumType('Role', { codecId: 'pg/text@1', nativeType: 'text' },
+ *   member('User', 'user'),
+ *   member('Admin', 'admin'),
+ * );
+ * // Role.values → readonly ['user', 'admin']
+ * // Role.members.User → 'user'
+ * ```
+ */
+declare function enumType<CodecTypes extends CodecTypeMap = Record<string, never>, const Name extends string = string, const Codec extends Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'> = Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'>, const Members extends readonly [EnumMember<string, CodecInput<CodecTypes, Codec>>, ...EnumMember<string, CodecInput<CodecTypes, Codec>>[]] = readonly [EnumMember<string, CodecInput<CodecTypes, Codec>>]>(name: Name, codec: Codec, ...members: Members): EnumTypeHandle<Name, MembersToValues<[...Members]>, MembersToNames<[...Members]>, MembersAccessorMap<[...Members]>>;
+declare function enumType(name: string, codec: Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'>, ...members: EnumMember<string, unknown>[]): EnumTypeHandle;
+/**
+ * The signature of an `enumType` whose codec typemap is already bound — the
+ * shape a target-bound wrapper (e.g. `@prisma-next/postgres/contract-builder`)
+ * exposes. The member values are constrained to the codec's input type drawn
+ * from `CodecTypes` (so a `pg/text@1` codec rejects numeric members, etc.),
+ * while `Name`, `Codec`, and the member tuple still infer from the call.
+ */
+type BoundEnumType<CodecTypes extends CodecTypeMap> = <const Name extends string, const Codec extends Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'>, const Members extends readonly [EnumMember<string, CodecInput<CodecTypes, Codec>>, ...EnumMember<string, CodecInput<CodecTypes, Codec>>[]]>(name: Name, codec: Codec, ...members: Members) => EnumTypeHandle<Name, MembersToValues<[...Members]>, MembersToNames<[...Members]>, MembersAccessorMap<[...Members]>>;
+/**
+ * Bind `enumType` to a target's codec typemap. The returned function is the
+ * same runtime `enumType`, retyped so member values are constrained to the
+ * codec's input type. Target packages call this with their pack's
+ * `ExtractCodecTypesFromPack<Pack>` to expose a codec-aware `enumType`.
+ */
+declare function bindEnumType<CodecTypes extends CodecTypeMap>(): BoundEnumType<CodecTypes>;
+//#endregion
 //#region src/contract-dsl.d.ts
 type NamingStrategy = 'identity' | 'snake_case';
 type NamingConfig = {
   readonly tables?: NamingStrategy;
   readonly columns?: NamingStrategy;
 };
-type NamedStorageTypeRef = string | StorageTypeInstance | PostgresEnumStorageEntry;
+type NamedStorageTypeRef = string | StorageTypeInstance | PostgresEnumStorageEntry | EnumTypeHandle;
 type NamedConstraintNameSpec<Name extends string = string> = {
   readonly name: Name;
 };
@@ -78,6 +215,13 @@ declare class ScalarFieldBuilder<State extends AnyScalarFieldState = AnyScalarFi
   private readonly state;
   readonly __state: State;
   constructor(state: State);
+  /**
+   * Returns the physical column name when `.column(name)` was called, or
+   * `undefined` when the field uses the default (logical field name) mapping.
+   * Used by cross-space FK lowering to stamp the physical column name onto
+   * `TargetFieldRef.columnName` so FK target columns are resolved correctly.
+   */
+  get physicalColumnName(): string | undefined;
   optional(): ScalarFieldBuilder<State extends ScalarFieldState<infer CodecId, infer TypeRef, boolean, infer ColumnName, infer IdSpec, infer UniqueSpec> ? ScalarFieldState<CodecId, TypeRef, true, ColumnName, IdSpec, UniqueSpec> : never>;
   column<ColumnName extends string>(name: ColumnName): ScalarFieldBuilder<State extends ScalarFieldState<infer CodecId, infer TypeRef, infer Nullable, string | undefined, infer IdSpec, infer UniqueSpec> ? ScalarFieldState<CodecId, TypeRef, Nullable, ColumnName, IdSpec, UniqueSpec> : never>;
   default(value: ColumnDefaultLiteralInputValue | ColumnDefault): ScalarFieldBuilder<State>;
@@ -94,6 +238,7 @@ declare function generatedField<Descriptor extends ColumnTypeDescriptor>(spec: G
 declare function namedTypeField<TypeRef extends string>(typeRef: TypeRef): ScalarFieldBuilder<ScalarFieldState<string, TypeRef, false, undefined>>;
 declare function namedTypeField<TypeRef extends StorageTypeInstance>(typeRef: TypeRef): ScalarFieldBuilder<ScalarFieldState<TypeRef['codecId'], TypeRef, false, undefined>>;
 declare function namedTypeField<TypeRef extends PostgresEnumStorageEntry>(typeRef: TypeRef): ScalarFieldBuilder<ScalarFieldState<string, TypeRef, false, undefined>>;
+declare function namedTypeField<Handle extends EnumTypeHandle>(typeRef: Handle): ScalarFieldBuilder<ScalarFieldState<Handle['codecId'], Handle, false, undefined>>;
 type RelationModelRefSource = 'string' | 'token' | 'lazyToken';
 type TargetFieldRefSource = 'string' | 'token';
 type EagerRelationModelName<ModelName extends string = string, Source extends Exclude<RelationModelRefSource, 'lazyToken'> = Exclude<RelationModelRefSource, 'lazyToken'>> = {
@@ -113,6 +258,22 @@ type BelongsToRelation<ToModel extends string = string, FromField extends string
   readonly from: FromField;
   readonly to: ToField;
   readonly sql?: SqlSpec;
+  /**
+   * Contract-space identity of the target model. Populated when
+   * `belongsTo` receives a cross-space branded handle. Absent for
+   * local (same-space) relations.
+   */
+  readonly spaceId?: string;
+  /**
+   * Physical table name of the cross-space target model. Only set
+   * when `spaceId` is present; read from the handle's `tableName`.
+   */
+  readonly tableName?: string;
+  /**
+   * Namespace coordinate of the cross-space target model.
+   * Only set when `spaceId` is present.
+   */
+  readonly namespaceId?: string;
 };
 type HasManyRelation<ToModel extends string = string, ByField extends string | readonly string[] = string | readonly string[]> = {
   readonly kind: 'hasMany';
@@ -142,17 +303,58 @@ declare class RelationBuilder<State extends RelationState = AnyRelationState> {
   sql<const SqlSpec extends BelongsToRelationSqlSpec>(this: State extends BelongsToRelation<string, string | readonly string[], string | readonly string[], BelongsToRelationSqlSpec | undefined> ? RelationBuilder<State> : never, spec: SqlSpec): RelationBuilder<ApplyBelongsToRelationSqlSpec<State, SqlSpec>>;
   build(): State;
 }
+/**
+ * Reference to a column on the current (local) model.
+ *
+ * Source columns are always local to the contract being authored. The
+ * cross-space brand lives on `TargetFieldRef` (the target side of a foreign
+ * key), not here.
+ */
 type ColumnRef<FieldName extends string = string> = {
   readonly kind: 'columnRef';
   readonly fieldName: FieldName;
 };
-type TargetFieldRef<ModelName extends string = string, FieldName extends string = string, Source extends TargetFieldRefSource = TargetFieldRefSource> = {
+/**
+ * Reference to a field on a target model, produced by model `.refs` and
+ * `constraints.ref(modelName, fieldName)`.
+ *
+ * The `TSpaceId` phantom parameter carries the contract-space identity of the
+ * target model. Local model handles produce `TSpaceId = '<self>'`; extension
+ * handles carry the extension's `spaceId`. The brand is propagated from the
+ * parent `ContractModelBuilder` via the `spaceId?` property: absent means local
+ * (`'<self>'`), present means cross-space.
+ */
+type TargetFieldRef<ModelName extends string = string, FieldName extends string = string, TSpaceId extends string = string> = {
   readonly kind: 'targetFieldRef';
-  readonly source: Source;
+  readonly source: TargetFieldRefSource;
   readonly modelName: ModelName;
   readonly fieldName: FieldName;
+  /**
+   * Cross-space discriminator. When present, the referenced model lives in a
+   * different contract space identified by this value. Absent for local refs.
+   */
+  readonly spaceId?: TSpaceId extends '<self>' ? never : TSpaceId;
+  /**
+   * Namespace id of the cross-space target model (e.g. `'auth'` for
+   * `supabase` `auth.User`). Only present for cross-space refs.
+   */
+  readonly namespaceId?: string;
+  /**
+   * Physical table name of the cross-space target model. Only present for
+   * cross-space refs; allows the lowering path to bypass the local model
+   * registry.
+   */
+  readonly tableName?: string;
+  /**
+   * Physical column name of the target field. Populated for cross-space refs
+   * when the extension handle's field used `.column(name)` to rename the
+   * physical column. When absent the logical `fieldName` is used as the column
+   * name. Only relevant for cross-space FK lowering — local FKs resolve column
+   * names via the local `fieldToColumn` map.
+   */
+  readonly columnName?: string;
 };
-type ModelTokenRefs<ModelName extends string, Fields extends Record<string, ScalarFieldBuilder>> = { readonly [K in keyof Fields]: TargetFieldRef<ModelName, K & string> };
+type ModelTokenRefs<ModelName extends string, Fields extends Record<string, ScalarFieldBuilder>, TSpaceId extends string = '<self>'> = { readonly [K in keyof Fields]: TargetFieldRef<ModelName, K & string, TSpaceId> };
 type ConstraintOptions<Name extends string | undefined = string | undefined> = {
   readonly name?: Name;
 };
@@ -198,6 +400,22 @@ type ForeignKeyConstraint<SourceFieldNames extends readonly string[] = readonly
   readonly targetModel: TargetModelName;
   readonly targetFields: TargetFieldNames;
   readonly targetSource?: TargetFieldRefSource;
+  /**
+   * Cross-space discriminator. When present, the FK target lives in a
+   * different contract space identified by this value. Absent for local FKs.
+   */
+  readonly targetSpaceId?: string;
+  /**
+   * Namespace coordinate of the cross-space target model. Populated when
+   * the target model handle carries a `namespace` (e.g. `auth` for supabase
+   * `auth.User`). Absent for local FKs.
+   */
+  readonly targetNamespaceId?: string;
+  /**
+   * Table name of the cross-space target. Populated for cross-space FKs
+   * so the lowering path doesn't need a local model lookup.
+   */
+  readonly targetTableName?: string;
   readonly name?: Name;
   readonly onDelete?: 'noAction' | 'restrict' | 'cascade' | 'setNull' | 'setDefault';
   readonly onUpdate?: 'noAction' | 'restrict' | 'cascade' | 'setNull' | 'setDefault';
@@ -227,6 +445,7 @@ type ModelAttributesSpec = {
 };
 type SqlStageSpec = {
   readonly table?: string;
+  readonly control?: ControlPolicy;
   readonly indexes?: readonly IndexConstraint[];
   readonly foreignKeys?: readonly ForeignKeyConstraint[];
 };
@@ -271,7 +490,7 @@ type SqlForeignKeys<SqlSpec extends SqlStageSpec> = SqlSpec extends {
 type SqlNamedObjects<SqlSpec extends SqlStageSpec> = [...SqlIndexes<SqlSpec>, ...SqlForeignKeys<SqlSpec>];
 type ValidateSqlStageSpec<Fields extends Record<string, ScalarFieldBuilder>, AttributesSpec extends ModelAttributesSpec | undefined, SqlSpec extends SqlStageSpec> = [DuplicateLiteralNames<SqlNamedObjects<SqlSpec>>] extends [never] ? [Extract<ModelIdLiteralName<Fields, AttributesSpec>, NamedConstraintLiteralName<SqlNamedObjects<SqlSpec>[number]>>] extends [never] ? SqlSpec : never : never;
 type ValidateAttributesStageSpec<Fields extends Record<string, ScalarFieldBuilder>, SqlSpec extends SqlStageSpec | undefined, AttributesSpec extends ModelAttributesSpec> = SqlSpec extends SqlStageSpec ? [Extract<ModelIdLiteralName<Fields, AttributesSpec>, NamedConstraintLiteralName<SqlNamedObjects<SqlSpec>[number]>>] extends [never] ? AttributesSpec : never : AttributesSpec;
-declare class ContractModelBuilder<ModelName extends string | undefined, Fields extends Record<string, ScalarFieldBuilder>, Relations extends Record<string, AnyRelationBuilder> = Record<never, never>, AttributesSpec extends ModelAttributesSpec | undefined = undefined, SqlSpec extends SqlStageSpec | undefined = undefined, IndexTypes extends IndexTypeMap = Record<never, never>> {
+declare class ContractModelBuilder<ModelName extends string | undefined, Fields extends Record<string, ScalarFieldBuilder>, Relations extends Record<string, AnyRelationBuilder> = Record<never, never>, AttributesSpec extends ModelAttributesSpec | undefined = undefined, SqlSpec extends SqlStageSpec | undefined = undefined, IndexTypes extends IndexTypeMap = Record<never, never>, TSpaceId extends string = '<self>'> {
   readonly stageOne: {
     readonly modelName?: ModelName;
     readonly namespace?: string;
@@ -280,23 +499,26 @@ declare class ContractModelBuilder<ModelName extends string | undefined, Fields
   };
   readonly attributesFactory?: StageInput<AttributeContext<Fields>, AttributesSpec> | undefined;
   readonly sqlFactory?: StageInput<SqlContext<Fields, IndexTypes>, SqlSpec> | undefined;
+  readonly spaceId?: TSpaceId | undefined;
+  readonly tableName?: string | undefined;
   readonly __name: ModelName;
   readonly __fields: Fields;
   readonly __relations: Relations;
   readonly __attributes: AttributesSpec;
   readonly __sql: SqlSpec;
   readonly __indexTypes: IndexTypes;
-  readonly refs: ModelName extends string ? ModelTokenRefs<ModelName, Fields> : never;
+  readonly __spaceId: TSpaceId;
+  readonly refs: ModelName extends string ? ModelTokenRefs<ModelName, Fields, TSpaceId> : never;
   constructor(stageOne: {
     readonly modelName?: ModelName;
     readonly namespace?: string;
     readonly fields: Fields;
     readonly relations: Relations;
-  }, attributesFactory?: StageInput<AttributeContext<Fields>, AttributesSpec> | undefined, sqlFactory?: StageInput<SqlContext<Fields, IndexTypes>, SqlSpec> | undefined);
+  }, attributesFactory?: StageInput<AttributeContext<Fields>, AttributesSpec> | undefined, sqlFactory?: StageInput<SqlContext<Fields, IndexTypes>, SqlSpec> | undefined, spaceId?: TSpaceId | undefined, tableName?: string | undefined);
   ref<FieldName extends keyof Fields & string>(this: ModelName extends string ? ContractModelBuilder<ModelName, Fields, Relations, AttributesSpec, SqlSpec, IndexTypes> : never, fieldName: FieldName): TargetFieldRef<ModelName & string, FieldName>;
-  relations<const NextRelations extends Record<string, AnyRelationBuilder>>(relations: NextRelations): ContractModelBuilder<ModelName, Fields, Relations & NextRelations, AttributesSpec, SqlSpec, IndexTypes>;
-  attributes<const NextAttributesSpec extends ModelAttributesSpec>(specOrFactory: StageInput<AttributeContext<Fields>, ValidateAttributesStageSpec<Fields, SqlSpec, NextAttributesSpec>>): ContractModelBuilder<ModelName, Fields, Relations, NextAttributesSpec, SqlSpec, IndexTypes>;
-  sql<const NextSqlSpec extends SqlStageSpec>(specOrFactory: StageInput<SqlContext<Fields, IndexTypes>, NextSqlSpec>): [ValidateSqlStageSpec<Fields, AttributesSpec, NextSqlSpec>] extends [never] ? ContractModelBuilder<ModelName, Fields, Relations, AttributesSpec, never, IndexTypes> : ContractModelBuilder<ModelName, Fields, Relations, AttributesSpec, NextSqlSpec, IndexTypes>;
+  relations<const NextRelations extends Record<string, AnyRelationBuilder>>(relations: NextRelations): ContractModelBuilder<ModelName, Fields, Relations & NextRelations, AttributesSpec, SqlSpec, IndexTypes, TSpaceId>;
+  attributes<const NextAttributesSpec extends ModelAttributesSpec>(specOrFactory: StageInput<AttributeContext<Fields>, ValidateAttributesStageSpec<Fields, SqlSpec, NextAttributesSpec>>): ContractModelBuilder<ModelName, Fields, Relations, NextAttributesSpec, SqlSpec, IndexTypes, TSpaceId>;
+  sql<const NextSqlSpec extends SqlStageSpec>(specOrFactory: StageInput<SqlContext<Fields, IndexTypes>, NextSqlSpec>): [ValidateSqlStageSpec<Fields, AttributesSpec, NextSqlSpec>] extends [never] ? ContractModelBuilder<ModelName, Fields, Relations, AttributesSpec, never, IndexTypes, TSpaceId> : ContractModelBuilder<ModelName, Fields, Relations, AttributesSpec, NextSqlSpec, IndexTypes, TSpaceId>;
   buildAttributesSpec(): AttributesSpec;
   buildSqlSpec(): SqlSpec;
 }
@@ -318,6 +540,7 @@ type ContractInput<Family extends FamilyPackRef<string> = FamilyPackRef<string>,
   readonly naming?: NamingConfig;
   readonly storageHash?: string;
   readonly foreignKeyDefaults?: ForeignKeyDefaultsState;
+  readonly defaultControlPolicy?: ControlPolicy;
   /**
    * Declared namespace coordinates the contract recognises. Per-model
    * `namespace` references must reference an entry in this list (or the
@@ -366,6 +589,12 @@ type ContractInput<Family extends FamilyPackRef<string> = FamilyPackRef<string>,
   readonly types?: Types;
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
+  /**
+   * Domain enum handles authored via `enumType()`. Each handle lowers to a
+   * domain `enum` entry and a storage `valueSet` entry in the target's
+   * default namespace. Fields reference the enum via `field.namedType(handle)`.
+   */
+  readonly enums?: Record<string, EnumTypeHandle>;
 };
 declare function model<const ModelName extends string, Fields extends Record<string, ScalarFieldBuilder>, Relations extends Record<string, AnyRelationBuilder> = Record<never, never>>(modelName: ModelName, input: {
   readonly fields: Fields;
@@ -377,6 +606,26 @@ declare function model<Fields extends Record<string, ScalarFieldBuilder>, Relati
   readonly relations?: Relations;
   readonly namespace?: string;
 }): ContractModelBuilder<undefined, Fields, Relations>;
+/**
+ * Factory for building a standalone branded extension model handle.
+ *
+ * Use this instead of `new ContractModelBuilder(…)` when constructing handles
+ * for models that live in a foreign contract space (e.g. a Supabase extension
+ * model referenced by a user's contract). The `spaceId` brands the returned
+ * handle so `refs.<field>.spaceId` carries the foreign space identifier.
+ *
+ * @param name - The domain model name as declared in the foreign contract
+ *   (e.g. `'AuthUser'`, not a bare table alias like `'User'`).
+ * @param input.namespace - The namespace within the foreign space (e.g. `'auth'`).
+ * @param input.fields - Field definitions (use `field.column(…)`).
+ * @param input.table - The physical table name in the foreign schema.
+ * @param spaceId - The extension space identifier (e.g. `'supabase'`).
+ */
+declare function extensionModel<const ModelName extends string, Fields extends Record<string, ScalarFieldBuilder>, const TSpaceId extends string>(name: ModelName, input: {
+  readonly namespace: string;
+  readonly fields: Fields;
+  readonly table: string;
+}, spaceId: TSpaceId): ContractModelBuilder<ModelName, Fields, Record<never, never>, undefined, undefined, Record<never, never>, TSpaceId>;
 declare function belongsTo<Token extends AnyNamedModelToken, FromField extends string | readonly string[], ToField extends RelationFieldSelection<RelationModelFieldNames<Token>>>(toModel: Token | LazyNamedModelToken<Token>, options: {
   readonly from: FromField;
   readonly to: ToField;
@@ -513,7 +762,7 @@ type DefinitionNamespaces<Definition> = Definition extends {
 } ? string[] extends Names ? never : readonly string[] extends Names ? never : Names[number] : never;
 type DefinitionTypes<Definition> = Definition extends {
   readonly types?: unknown;
-} ? Present<Definition['types']> extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry> ? Present<Definition['types']> : Record<never, never> : Record<never, never>;
+} ? Present<Definition['types']> extends Record<string, StorageType> ? Present<Definition['types']> : Record<never, never> : Record<never, never>;
 type DefinitionTableNaming<Definition> = Definition extends {
   readonly naming?: {
     readonly tables?: infer Strategy extends string;
@@ -577,11 +826,19 @@ type DescriptorTypeParams<Descriptor> = Descriptor extends {
 type DescriptorTypeRef<Descriptor> = Descriptor extends {
   readonly typeRef: infer TypeRef extends string;
 } ? TypeRef : undefined;
-type LookupNamedStorageTypeKeyByValue<Definition, TypeRef extends StorageTypeInstance | PostgresEnumStorageEntry> = { [TypeName in keyof DefinitionTypes<Definition> & string]: [TypeRef] extends [DefinitionTypes<Definition>[TypeName]] ? [DefinitionTypes<Definition>[TypeName]] extends [TypeRef] ? TypeName : never : never }[keyof DefinitionTypes<Definition> & string];
-type ResolveNamedStorageTypeKey<Definition, TypeRef> = TypeRef extends string ? TypeRef : TypeRef extends StorageTypeInstance | PostgresEnumStorageEntry ? [LookupNamedStorageTypeKeyByValue<Definition, TypeRef>] extends [never] ? string : LookupNamedStorageTypeKeyByValue<Definition, TypeRef> : never;
+type LookupNamedStorageTypeKeyByValue<Definition, TypeRef extends StorageType> = { [TypeName in keyof DefinitionTypes<Definition> & string]: [TypeRef] extends [DefinitionTypes<Definition>[TypeName]] ? [DefinitionTypes<Definition>[TypeName]] extends [TypeRef] ? TypeName : never : never }[keyof DefinitionTypes<Definition> & string];
+type ResolveNamedStorageTypeKey<Definition, TypeRef> = TypeRef extends string ? TypeRef : TypeRef extends StorageType ? [LookupNamedStorageTypeKeyByValue<Definition, TypeRef>] extends [never] ? string : LookupNamedStorageTypeKeyByValue<Definition, TypeRef> : never;
 type ResolveNamedStorageType<Definition, TypeRef> = ResolveNamedStorageTypeKey<Definition, TypeRef> extends infer TypeName extends string ? TypeName extends keyof DefinitionTypes<Definition> ? DefinitionTypes<Definition>[TypeName] : StorageTypeInstance : StorageTypeInstance;
-type ResolveFieldDescriptor<Definition, FieldState> = [FieldDescriptorOf<FieldState>] extends [never] ? ResolveNamedStorageType<Definition, FieldTypeRefOf<FieldState>> : FieldDescriptorOf<FieldState>;
-type ResolveFieldColumnTypeRef<Definition, FieldState> = [FieldTypeRefOf<FieldState>] extends [never] ? DescriptorTypeRef<FieldDescriptorOf<FieldState>> : ResolveNamedStorageTypeKey<Definition, FieldTypeRefOf<FieldState>>;
+type EnumFieldHandle<FieldState> = [FieldTypeRefOf<FieldState>] extends [never] ? never : FieldTypeRefOf<FieldState> extends EnumTypeHandle ? FieldTypeRefOf<FieldState> : never;
+type EnumHandleDescriptor<Handle> = Handle extends {
+  readonly codecId: infer CodecId extends string;
+  readonly nativeType: infer NativeType extends string;
+} ? {
+  readonly codecId: CodecId;
+  readonly nativeType: NativeType;
+} : never;
+type ResolveFieldDescriptor<Definition, FieldState> = [EnumFieldHandle<FieldState>] extends [never] ? [FieldDescriptorOf<FieldState>] extends [never] ? ResolveNamedStorageType<Definition, FieldTypeRefOf<FieldState>> : FieldDescriptorOf<FieldState> : EnumHandleDescriptor<EnumFieldHandle<FieldState>>;
+type ResolveFieldColumnTypeRef<Definition, FieldState> = [EnumFieldHandle<FieldState>] extends [never] ? [FieldTypeRefOf<FieldState>] extends [never] ? DescriptorTypeRef<FieldDescriptorOf<FieldState>> : ResolveNamedStorageTypeKey<Definition, FieldTypeRefOf<FieldState>> : undefined;
 type ResolveFieldColumnTypeParams<Definition, FieldState> = [ResolveFieldColumnTypeRef<Definition, FieldState>] extends [string] ? undefined : DescriptorTypeParams<FieldDescriptorOf<FieldState>>;
 type ModelTableName<Definition, ModelName extends ModelNames<Definition>> = [Present<ModelSql<Definition, ModelName> extends {
   readonly table?: infer TableName;
@@ -648,6 +905,7 @@ type BuiltStorageTables<Definition> = { readonly [ModelName in ModelNames<Defini
     };
     readonly target: {
       readonly namespaceId: NamespaceId;
+      readonly spaceId?: string;
       readonly tableName: string;
       readonly columns: readonly string[];
     };
@@ -663,7 +921,19 @@ type BuiltStorageTables<Definition> = { readonly [ModelName in ModelNames<Defini
     readonly name?: ModelIdName<Definition, ModelName>;
   };
 } : Record<string, never>) };
-type BuiltDocumentScopedTypes<Definition> = { readonly [K in keyof DefinitionTypes<Definition> as DefinitionTypes<Definition>[K] extends PostgresEnumStorageEntry ? never : K]: DefinitionTypes<Definition>[K] };
+type DefinitionEnums<Definition> = Definition extends {
+  readonly enums?: infer E;
+} ? Present<E> extends Record<string, EnumTypeHandle> ? string extends keyof Present<E> ? Record<never, never> : Present<E> : Record<never, never> : Record<never, never>;
+type EnumHandleAccessorType<Handle> = Handle extends EnumTypeHandle<infer _Name, infer Values, infer Names, infer MembersMap> ? {
+  readonly values: Values;
+  readonly names: Names;
+  readonly members: MembersMap;
+  has(v: Values[number]): boolean;
+  nameOf(v: Values[number]): string | undefined;
+  ordinalOf(v: Values[number]): number;
+} : never;
+type BuiltEnumAccessors<Definition> = { readonly [K in keyof DefinitionEnums<Definition>]: EnumHandleAccessorType<DefinitionEnums<Definition>[K]> };
+type BuiltDocumentScopedTypes<Definition> = { readonly [K in keyof DefinitionTypes<Definition> as DefinitionTypes<Definition>[K] extends StorageTypeInstance ? K : never]: DefinitionTypes<Definition>[K] };
 type BuiltDomain<Definition> = BuiltDocumentScopedTypes<Definition> extends Record<never, never> ? Record<string, never> : {
   readonly __unbound__: {
     readonly types: BuiltDocumentScopedTypes<Definition>;
@@ -676,23 +946,21 @@ type BuiltStorage<Definition> = {
   readonly namespaces: { readonly [K in DefaultStorageNamespaceId<Definition>]: {
     readonly id: K;
     readonly kind: string;
-    readonly tables: BuiltStorageTables<Definition>;
-    readonly enum?: Readonly<Record<string, PostgresEnumStorageEntry>>;
+    readonly entries: {
+      readonly table: BuiltStorageTables<Definition>;
+    };
   } } & { readonly [Ns in Exclude<DefinitionNamespaces<Definition>, DefaultStorageNamespaceId<Definition>>]: {
     readonly id: Ns;
     readonly kind: string;
-    readonly tables: Record<never, never>;
-    readonly enum?: Readonly<Record<string, PostgresEnumStorageEntry>>;
+    readonly entries: {
+      readonly table: Record<never, never>;
+    };
   } };
 };
-type FieldOutputType<Definition, ModelName extends ModelNames<Definition>, FieldName extends ModelFieldNames<Definition, ModelName>> = ModelStorageColumn<Definition, ModelName, FieldName> extends infer Col ? Col extends {
-  readonly codecId: infer Id extends string;
-} ? Id extends keyof CodecTypesFromDefinition<Definition> ? CodecTypesFromDefinition<Definition>[Id] extends {
-  readonly output: infer O;
-} ? Col extends {
-  readonly nullable: true;
-} ? O | null : O : unknown : unknown : unknown : unknown;
-type FieldOutputTypes<Definition> = { readonly [ModelName in ModelNames<Definition>]: { readonly [FieldName in ModelFieldNames<Definition, ModelName>]: FieldOutputType<Definition, ModelName, FieldName> } };
+type EnumValueUnion<FieldState> = [FieldTypeRefOf<FieldState>] extends [EnumTypeHandle<string, infer Values>] ? readonly unknown[] extends Values ? never : Values[number] : never;
+type CodecChannelType<Definition, ModelName extends ModelNames<Definition>, FieldName extends ModelFieldNames<Definition, ModelName>, Channel extends 'output' | 'input'> = ModelStorageColumn<Definition, ModelName, FieldName>['codecId'] extends infer Id extends keyof CodecTypesFromDefinition<Definition> ? CodecTypesFromDefinition<Definition>[Id] extends { readonly [K in Channel]: infer T } ? T : unknown : unknown;
+type FieldChannelType<Definition, ModelName extends ModelNames<Definition>, FieldName extends ModelFieldNames<Definition, ModelName>, Channel extends 'output' | 'input'> = ([EnumValueUnion<ModelFieldState<Definition, ModelName, FieldName>>] extends [never] ? CodecChannelType<Definition, ModelName, FieldName, Channel> : EnumValueUnion<ModelFieldState<Definition, ModelName, FieldName>>) | (FieldNullableOf<ModelFieldState<Definition, ModelName, FieldName>> extends true ? null : never);
+type FieldChannelTypes<Definition, Channel extends 'output' | 'input'> = { readonly [ModelName in ModelNames<Definition>]: { readonly [FieldName in ModelFieldNames<Definition, ModelName>]: FieldChannelType<Definition, ModelName, FieldName, Channel> } };
 type SqlContractResult<Definition> = ContractWithTypeMaps<Contract<BuiltStorage<Definition>, BuiltModels<Definition>> & {
   readonly target: DefinitionTargetId<Definition>;
   readonly targetFamily: 'sql';
@@ -701,7 +969,8 @@ type SqlContractResult<Definition> = ContractWithTypeMaps<Contract<BuiltStorage<
 } & {
   readonly extensionPacks: keyof DefinitionExtensionPacks<Definition> extends never ? Record<string, never> : DefinitionExtensionPacks<Definition>;
   readonly capabilities: DerivedCapabilities<Definition>;
-}, TypeMaps<CodecTypesFromDefinition<Definition>, Record<string, never>, Record<string, never>, FieldOutputTypes<Definition>>>;
+  readonly enumAccessors: BuiltEnumAccessors<Definition>;
+}, TypeMaps<CodecTypesFromDefinition<Definition>, Record<string, never>, FieldChannelTypes<Definition, 'output'>, FieldChannelTypes<Definition, 'input'>>>;
 //#endregion
 //#region src/composed-authoring-helpers.d.ts
 type ExtractTypeNamespaceFromPack<Pack> = ExtractAuthoringNamespaceFromPack<Pack, 'type', Record<never, never>>;
@@ -758,6 +1027,8 @@ interface FieldNode {
   readonly default?: ColumnDefault;
   readonly executionDefaults?: ExecutionMutationDefaultPhases$1;
   readonly many?: boolean;
+  /** Present when the field was authored with `field.namedType(enumHandle)`. */
+  readonly enumTypeHandle?: EnumTypeHandle;
 }
 interface PrimaryKeyNode {
   readonly columns: readonly string[];
@@ -786,6 +1057,12 @@ interface ForeignKeyNode {
      * know the target namespace can stamp it explicitly.
      */
     readonly namespaceId?: string;
+    /**
+     * Contract-space identity of the referenced table. When present, the
+     * table lives in a different contract space (identified by this value)
+     * rather than the current contract. Absent for local FKs.
+     */
+    readonly spaceId?: string;
   };
   readonly name?: string;
   readonly onDelete?: ReferentialAction;
@@ -797,7 +1074,26 @@ interface RelationNode {
   readonly fieldName: string;
   readonly toModel: string;
   readonly toTable: string;
+  /**
+   * Namespace coordinate of the related model. When omitted the assembler
+   * resolves the coordinate from the referenced model node's own
+   * `namespaceId`; the field exists so authoring paths that already know the
+   * target namespace can stamp it explicitly — required to disambiguate a
+   * relation to a model whose bare name also exists in another namespace.
+   */
+  readonly toNamespaceId?: string;
   readonly cardinality: '1:1' | '1:N' | 'N:1' | 'N:M';
+  /**
+   * Contract-space identity of the related model. When present, the
+   * related model lives in a different contract space. Absent for local
+   * (same-space) relations.
+   */
+  readonly spaceId?: string;
+  /**
+   * Namespace coordinate of the related model in the foreign space.
+   * Only set when `spaceId` is present.
+   */
+  readonly namespaceId?: string;
   readonly on: {
     readonly parentTable: string;
     readonly parentColumns: readonly string[];
@@ -843,9 +1139,19 @@ interface ModelNode {
   readonly indexes?: readonly IndexNode[];
   readonly foreignKeys?: readonly ForeignKeyNode[];
   readonly relations?: readonly RelationNode[];
+  readonly control?: ControlPolicy;
+  /**
+   * Single-table-inheritance variants share their base model's storage table:
+   * the variant's columns are materialised onto the base `ModelNode`, and this
+   * model contributes a domain model but no storage table of its own. When set,
+   * the assembler builds the domain model but skips creating a (shadow) storage
+   * table and a root for this model — the base owns both.
+   */
+  readonly sharesBaseTable?: boolean;
 }
 interface ContractDefinition {
   readonly target: TargetPackRef<'sql', string>;
+  readonly defaultControlPolicy?: ControlPolicy;
   readonly extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>;
   readonly storageHash?: string;
   readonly foreignKeyDefaults?: ForeignKeyDefaultsState;
@@ -853,7 +1159,7 @@ interface ContractDefinition {
   /**
    * Enum types declared inside a named `namespace { enum … }` block,
    * keyed first by namespace id then by type name. These are routed to
-   * `storage.namespaces[nsId].enum` rather than the implicit fallback
+   * `storage.namespaces[nsId].entries.type` rather than the implicit fallback
    * namespace used for top-level `storageTypes` enums.
    */
   readonly namespaceTypes?: Readonly<Record<string, Readonly<Record<string, PostgresEnumStorageEntry>>>>;
@@ -866,10 +1172,19 @@ interface ContractDefinition {
    * Target-supplied factory that materialises a `Namespace` concretion
    * for a declared namespace coordinate. Mirrors
    * `ContractInput.createNamespace`.
+   *
+   * The optional second argument carries target-specific enum types for the
+   * namespace (e.g. postgres enum registrations keyed by type name).
    */
-  readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
+  readonly createNamespace?: (input: SqlNamespaceTablesInput, enumTypes?: Readonly<Record<string, PostgresEnumStorageEntry>>) => Namespace;
   readonly models: readonly ModelNode[];
   readonly valueObjects?: readonly ValueObjectNode[];
+  /**
+   * Domain enum handles authored via `enumType()`. Each entry lowers to a
+   * domain `enum` entry and a storage `valueSet` entry in the contract's
+   * default namespace.
+   */
+  readonly enums?: Record<string, EnumTypeHandle>;
 }
 //#endregion
 //#region src/build-contract.d.ts
@@ -888,38 +1203,79 @@ type ModelLike = {
   buildAttributesSpec(): ModelAttributesSpec | undefined;
   buildSqlSpec(): SqlStageSpec | undefined;
 };
-type ContractDefinition$1<Family extends FamilyPackRef<string>, Target extends TargetPackRef<'sql', string>, Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry>, Models extends Record<string, ModelLike>, ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined, Naming extends ContractInput['naming'] | undefined, StorageHash extends string | undefined, ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined, Namespaces extends readonly string[] | undefined = undefined> = {
+type ContractDefinition$1<Family extends FamilyPackRef<string>, Target extends TargetPackRef<'sql', string>, Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry>, Models extends Record<string, ModelLike>, ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined, Naming extends ContractInput['naming'] | undefined, StorageHash extends string | undefined, ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined, Namespaces extends readonly string[] | undefined = undefined, Enums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>> = {
   readonly family: Family;
   readonly target: Target;
   readonly extensionPacks?: ExtensionPacks;
   readonly naming?: Naming;
   readonly storageHash?: StorageHash;
   readonly foreignKeyDefaults?: ForeignKeyDefaults;
+  readonly defaultControlPolicy?: ControlPolicy;
   readonly namespaces?: Namespaces;
   readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
   readonly types?: Types;
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
+  readonly enums?: Enums;
 };
-type ContractScaffold<Family extends FamilyPackRef<string>, Target extends TargetPackRef<'sql', string>, ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined, Naming extends ContractInput['naming'] | undefined, StorageHash extends string | undefined, ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined, Namespaces extends readonly string[] | undefined = undefined> = {
+type ContractScaffold<Family extends FamilyPackRef<string>, Target extends TargetPackRef<'sql', string>, ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined, Naming extends ContractInput['naming'] | undefined, StorageHash extends string | undefined, ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined, Namespaces extends readonly string[] | undefined = undefined, Enums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>> = {
   readonly family: Family;
   readonly target: Target;
   readonly extensionPacks?: ExtensionPacks;
   readonly naming?: Naming;
   readonly storageHash?: StorageHash;
   readonly foreignKeyDefaults?: ForeignKeyDefaults;
+  readonly defaultControlPolicy?: ControlPolicy;
   readonly namespaces?: Namespaces;
   readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
   readonly types?: never;
   readonly models?: never;
   readonly codecLookup?: CodecLookup;
+  readonly enums?: Enums;
 };
-type ContractFactory<Family extends FamilyPackRef<string>, Target extends TargetPackRef<'sql', string>, Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry>, Models extends Record<string, ModelLike>, ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined> = (helpers: ComposedAuthoringHelpers<Family, Target, ExtensionPacks>) => {
+type ContractFactory<Family extends FamilyPackRef<string>, Target extends TargetPackRef<'sql', string>, Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry>, Models extends Record<string, ModelLike>, ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined, Enums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>> = (helpers: ComposedAuthoringHelpers<Family, Target, ExtensionPacks>) => {
   readonly types?: Types;
   readonly models?: Models;
+  readonly enums?: Enums;
+};
+type BoundDefinitionInput<Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = Record<never, never>, Models extends Record<string, ModelLike> = Record<never, never>, ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined = undefined, Naming extends ContractInput['naming'] | undefined = undefined, StorageHash extends string | undefined = undefined, ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined, Namespaces extends readonly string[] | undefined = undefined> = {
+  readonly extensionPacks?: ExtensionPacks;
+  readonly naming?: Naming;
+  readonly storageHash?: StorageHash;
+  readonly foreignKeyDefaults?: ForeignKeyDefaults;
+  readonly defaultControlPolicy?: ControlPolicy;
+  readonly namespaces?: Namespaces;
+  readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
+  readonly types?: Types;
+  readonly models?: Models;
+  readonly codecLookup?: CodecLookup;
+  readonly enums?: Record<string, EnumTypeHandle>;
+};
+type LiteralEnums<E extends Record<string, EnumTypeHandle>> = string extends keyof E ? Record<never, never> : E;
+type MergeEnums<ScaffoldEnums extends Record<string, EnumTypeHandle>, FactoryEnums extends Record<string, EnumTypeHandle>> = LiteralEnums<ScaffoldEnums> & LiteralEnums<FactoryEnums>;
+type WithFamilyTarget<Input, F extends FamilyPackRef<string>, T extends TargetPackRef<'sql', string>> = Input & {
+  readonly family: F;
+  readonly target: T;
 };
-declare function defineContract<const Family extends FamilyPackRef<string>, const Target extends TargetPackRef<'sql', string>, const Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = Record<never, never>, const Models extends Record<string, ModelLike> = Record<never, never>, const ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined = undefined, const Naming extends ContractInput['naming'] | undefined = undefined, const StorageHash extends string | undefined = undefined, const ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined, const Namespaces extends readonly string[] | undefined = undefined>(definition: ContractDefinition$1<Family, Target, Types, Models, ExtensionPacks, Naming, StorageHash, ForeignKeyDefaults, Namespaces>): SqlContractResult<ContractDefinition$1<Family, Target, Types, Models, ExtensionPacks, Naming, StorageHash, ForeignKeyDefaults, Namespaces>>;
-declare function defineContract<const Family extends FamilyPackRef<string>, const Target extends TargetPackRef<'sql', string>, const Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = Record<never, never>, const Models extends Record<string, ModelLike> = Record<never, never>, const ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined = undefined, const Naming extends ContractInput['naming'] | undefined = undefined, const StorageHash extends string | undefined = undefined, const ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined, const Namespaces extends readonly string[] | undefined = undefined>(definition: ContractScaffold<Family, Target, ExtensionPacks, Naming, StorageHash, ForeignKeyDefaults, Namespaces>, factory: ContractFactory<Family, Target, Types, Models, ExtensionPacks>): SqlContractResult<ContractDefinition$1<Family, Target, Types, Models, ExtensionPacks, Naming, StorageHash, ForeignKeyDefaults, Namespaces>>;
+/**
+ * Shared builder that assembles a SqlContract with pre-bound family and target.
+ * Extension wrappers keep their own public overloads and delegate their impl body here;
+ * this is a plain overloaded function (not a factory returning an overloaded function)
+ * so no overloaded-function-return cast is needed.
+ *
+ * Overload 1: definition form (no factory).
+ */
+declare function buildBoundContract<const F extends FamilyPackRef<string>, const T extends TargetPackRef<'sql', string>, const Definition extends BoundDefinitionInput<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>, Record<string, ModelLike>, Record<string, ExtensionPackRef<'sql', string>> | undefined, ContractInput['naming'] | undefined, string | undefined, ForeignKeyDefaultsState | undefined, readonly string[] | undefined>>(family: F, target: T, definition: Definition, factory?: undefined): SqlContractResult<WithFamilyTarget<Definition, F, T>>;
+/**
+ * Overload 2: factory form.
+ */
+declare function buildBoundContract<const F extends FamilyPackRef<string>, const T extends TargetPackRef<'sql', string>, const Definition extends BoundDefinitionInput<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>, Record<string, ModelLike>, Record<string, ExtensionPackRef<'sql', string>> | undefined, ContractInput['naming'] | undefined, string | undefined, ForeignKeyDefaultsState | undefined, readonly string[] | undefined>, const Built extends {
+  readonly types?: Record<string, StorageTypeInstance | PostgresEnumStorageEntry>;
+  readonly models?: Record<string, ModelLike>;
+  readonly enums?: Record<string, EnumTypeHandle>;
+}>(family: F, target: T, definition: Definition, factory: (helpers: ComposedAuthoringHelpers<F, T, NonNullable<Definition['extensionPacks']>>) => Built): SqlContractResult<WithFamilyTarget<Definition & Built, F, T>>;
+declare function defineContract<const Family extends FamilyPackRef<string>, const Target extends TargetPackRef<'sql', string>, const Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = Record<never, never>, const Models extends Record<string, ModelLike> = Record<never, never>, const ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined = undefined, const Naming extends ContractInput['naming'] | undefined = undefined, const StorageHash extends string | undefined = undefined, const ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined, const Namespaces extends readonly string[] | undefined = undefined, const Enums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>>(definition: ContractDefinition$1<Family, Target, Types, Models, ExtensionPacks, Naming, StorageHash, ForeignKeyDefaults, Namespaces, Enums>): SqlContractResult<ContractDefinition$1<Family, Target, Types, Models, ExtensionPacks, Naming, StorageHash, ForeignKeyDefaults, Namespaces, Enums>>;
+declare function defineContract<const Family extends FamilyPackRef<string>, const Target extends TargetPackRef<'sql', string>, const Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = Record<never, never>, const Models extends Record<string, ModelLike> = Record<never, never>, const ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined = undefined, const Naming extends ContractInput['naming'] | undefined = undefined, const StorageHash extends string | undefined = undefined, const ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined, const Namespaces extends readonly string[] | undefined = undefined, const ScaffoldEnums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>, const FactoryEnums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>>(definition: ContractScaffold<Family, Target, ExtensionPacks, Naming, StorageHash, ForeignKeyDefaults, Namespaces, ScaffoldEnums>, factory: ContractFactory<Family, Target, Types, Models, ExtensionPacks, FactoryEnums>): SqlContractResult<ContractDefinition$1<Family, Target, Types, Models, ExtensionPacks, Naming, StorageHash, ForeignKeyDefaults, Namespaces, MergeEnums<ScaffoldEnums, FactoryEnums>>>;
 //#endregion
-export { type ComposedAuthoringHelpers, type ContractDefinition, type ContractInput, type ContractModelBuilder, type FieldNode, type ForeignKeyNode, type IndexNode, type ModelLike, type ModelNode, type PrimaryKeyNode, type RelationNode, type ScalarFieldBuilder, type UniqueConstraintNode, buildSqlContractFromDefinition, defineContract, field, model, rel };
+export { type BoundEnumType, type CodecInput, type CodecTypeMap, type ComposedAuthoringHelpers, type ContractDefinition, type ContractInput, type ContractModelBuilder, type EnumMember, type EnumTypeHandle, type ExtractCodecTypesFromPack, type FieldNode, type ForeignKeyNode, type IndexNode, type MergeEnums, type ModelLike, type ModelNode, type PrimaryKeyNode, type RelationNode, type ScalarFieldBuilder, type TargetFieldRef, type UniqueConstraintNode, bindEnumType, buildBoundContract, buildSqlContractFromDefinition, defineContract, enumType, extensionModel, field, member, model, rel };
 //# sourceMappingURL=contract-builder.d.mts.map