@prisma-next/sql-contract-ts 0.14.0-dev.51 → 0.14.0-dev.52

package/package.json

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

package/src/build-contract.ts

@@ -22,9 +22,16 @@ import {
   type ValueSetRef,
 } from '@prisma-next/contract/types';
 import { type CapabilityMatrix, mergeCapabilityMatrices } from '@prisma-next/contract-authoring';
-import type { CodecLookup } from '@prisma-next/framework-components/codec';
+import type {
+  AuthoringContributions,
+  AuthoringEntityTypeDescriptor,
+  AuthoringEntityTypeNamespace,
+} from '@prisma-next/framework-components/authoring';
+import { isAuthoringEntityTypeDescriptor } from '@prisma-next/framework-components/authoring';
+import type { CodecLookup, ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import { sqlContractCanonicalizationHooks } from '@prisma-next/sql-contract/canonicalization-hooks';
+import { tableEntityKind, valueSetEntityKind } from '@prisma-next/sql-contract/entity-kinds';
 import { validateIndexTypes } from '@prisma-next/sql-contract/index-type-validation';
 import {
   createIndexTypeRegistry,
@@ -44,6 +51,7 @@ import {
   toStorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 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 type {
@@ -172,6 +180,174 @@ function isValueObjectField(
   return 'valueObjectName' in field;
 }
 
+/**
+ * Resolves a deferred entity-ref column descriptor (e.g. a `pg.enum(handle)`
+ * column) against the field's now-known owning namespace: attaches the
+ * storage `valueSet` ref the collected entity's derived value-set is stored
+ * under. `nativeType` / `typeParams.typeName` stay bare here — schema
+ * qualification (e.g. `auth.aal_level`) is a target concern applied in the
+ * next step, `qualifyColumnDescriptor`. A descriptor with no `entityRef` (the
+ * ordinary case) passes through unchanged.
+ */
+function resolveEntityRefDescriptor(
+  descriptor: ColumnTypeDescriptor,
+  namespaceId: string,
+): ColumnTypeDescriptor {
+  const entityRef = descriptor.entityRef;
+  if (entityRef === undefined) return descriptor;
+
+  return {
+    ...descriptor,
+    valueSet: {
+      plane: 'storage',
+      entityKind: 'valueSet',
+      namespaceId,
+      entityName: entityRef.entityName,
+    },
+  };
+}
+
+/**
+ * A target's contract-construction-time column-type qualifier, contributed
+ * through `target.authoring.qualifyColumnType`. Given a column's bare type
+ * info and its owning `namespaceId`, it returns the type info the target's
+ * schema semantics require (e.g. Postgres schema-qualifies a native-enum
+ * column's type name to `auth.aal_level`). The dispatch keys off the codec
+ * id, so every codec — including ones needing no change — is passed through
+ * and the caller stays codec-blind. Targets without the hook leave every
+ * column bare.
+ */
+type ColumnTypeQualifier = (
+  input: {
+    readonly codecId: string;
+    readonly nativeType: string;
+    readonly typeParams?: Record<string, unknown>;
+  },
+  namespaceId: string,
+) => { readonly nativeType: string; readonly typeParams?: Record<string, unknown> };
+
+/**
+ * Structural check for a target that contributes a `qualifyColumnType` hook
+ * on its authoring contributions. Duck-typed (mirroring
+ * `contract-psl`'s `hasColumnFromEntityHook`) so the SQL family stays blind
+ * to the target's qualification logic and no framework/family interface has
+ * to name the hook.
+ */
+function hasColumnTypeQualifier(
+  authoring: AuthoringContributions,
+): authoring is AuthoringContributions & { readonly qualifyColumnType: ColumnTypeQualifier } {
+  return 'qualifyColumnType' in authoring && typeof authoring.qualifyColumnType === 'function';
+}
+
+function resolveColumnTypeQualifier(
+  target: ContractDefinition['target'],
+): ColumnTypeQualifier | undefined {
+  const authoring = target.authoring;
+  if (authoring === undefined) return undefined;
+  return hasColumnTypeQualifier(authoring) ? authoring.qualifyColumnType : undefined;
+}
+
+/**
+ * Applies the target's `qualifyColumnType` hook to a scalar column descriptor
+ * at construction, so the storage column and the domain field (which derives
+ * its `type.typeParams` from the storage column) are both built already
+ * qualified in a single pass. A descriptor whose codec the target leaves
+ * unchanged passes through untouched.
+ */
+function qualifyColumnDescriptor(
+  descriptor: ColumnTypeDescriptor,
+  namespaceId: string,
+  qualify: ColumnTypeQualifier | undefined,
+): ColumnTypeDescriptor {
+  if (qualify === undefined) return descriptor;
+  const qualified = qualify(
+    {
+      codecId: descriptor.codecId,
+      nativeType: descriptor.nativeType,
+      ...ifDefined('typeParams', descriptor.typeParams),
+    },
+    namespaceId,
+  );
+  if (
+    qualified.nativeType === descriptor.nativeType &&
+    qualified.typeParams === descriptor.typeParams
+  ) {
+    return descriptor;
+  }
+  return {
+    ...descriptor,
+    nativeType: qualified.nativeType,
+    ...ifDefined('typeParams', qualified.typeParams),
+  };
+}
+
+type CollectedPackEntities = Record<string, Record<string, Record<string, unknown>>>;
+
+/**
+ * Records a deferred column's entity-ref into the namespace-scoped collection
+ * accumulator, keyed the same way author-declared `packEntities` are
+ * (`namespaceId → entityKind → entityName`) — folded into the same namespace
+ * assembly `derivePackEntityValueSets`/`entries.<kind>` step, so a collected
+ * entity gets its value-set the same way an author-declared one does.
+ *
+ * The same handle reused by many columns in one namespace is normal (a native
+ * enum type backs any number of columns) and records the identical entity once.
+ * Two *different* entity instances sharing a name+kind in one namespace is a
+ * name collision — the emitted `entries.valueSet.<name>` could only reflect one
+ * of them, silently mismatching the other column's type/cast. PSL hard-errors
+ * on the equivalent (`PSL_DUPLICATE_DECLARATION`); the TS path rejects it too.
+ */
+function collectPackEntityFromColumn(
+  collected: CollectedPackEntities,
+  namespaceId: string,
+  entityRef: NonNullable<ColumnTypeDescriptor['entityRef']>,
+): void {
+  const forNs = collected[namespaceId] ?? {};
+  const forKind = forNs[entityRef.entityKind] ?? {};
+  const existing = forKind[entityRef.entityName];
+  if (existing !== undefined && existing !== entityRef.entity) {
+    throw new Error(
+      `buildSqlContractFromDefinition: two different "${entityRef.entityKind}" entities named "${entityRef.entityName}" in namespace "${namespaceId}" — pack-entity names must be unique per namespace.`,
+    );
+  }
+  forKind[entityRef.entityName] = entityRef.entity;
+  forNs[entityRef.entityKind] = forKind;
+  collected[namespaceId] = forNs;
+}
+
+/**
+ * Merges the author-declared `packEntities` for one namespace with the entities
+ * collected from that namespace's deferred entity-ref columns. A collected
+ * entity that shadows a *different* declared entity of the same kind+name (or
+ * vice-versa) is the same name-collision bug `collectPackEntityFromColumn`
+ * guards against across columns, so it is rejected the same way — by entity
+ * identity, so the same handle declared and used by a column does not throw.
+ */
+function mergeCollectedPackEntities(
+  namespaceId: string,
+  declared: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+  collected: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+): Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined {
+  if (declared === undefined) return collected;
+  if (collected === undefined) return declared;
+  const kinds = new Set([...Object.keys(declared), ...Object.keys(collected)]);
+  const result: Record<string, Readonly<Record<string, unknown>>> = {};
+  for (const kind of kinds) {
+    const declaredForKind = declared[kind];
+    const collectedForKind = collected[kind];
+    for (const [name, entity] of Object.entries(collectedForKind ?? {})) {
+      const existing = declaredForKind?.[name];
+      if (existing !== undefined && existing !== entity) {
+        throw new Error(
+          `buildSqlContractFromDefinition: two different "${kind}" entities named "${name}" in namespace "${namespaceId}" — a collected pack entity conflicts with an author-declared one; pack-entity names must be unique per namespace.`,
+        );
+      }
+    }
+    result[kind] = { ...declaredForKind, ...collectedForKind };
+  }
+  return result;
+}
+
 const JSONB_CODEC_ID = 'pg/jsonb@1';
 const JSONB_NATIVE_TYPE = 'jsonb';
 
@@ -310,9 +486,122 @@ function collectStorageNamespaceCoordinateIds(definition: ContractDefinition): S
       ids.add(model.namespaceId);
     }
   }
+  for (const id of Object.keys(definition.packEntities ?? {})) {
+    if (id.length > 0) {
+      ids.add(id);
+    }
+  }
   return ids;
 }
 
+/**
+ * Entry kinds the framework assembler itself manages (`table` from models,
+ * `valueSet` from `enums` and pack-entity value-set derivation). An
+ * author-declared pack entity claiming one of these would silently clobber
+ * or be clobbered by the managed slot, so it is rejected outright.
+ */
+const MANAGED_ENTRY_KINDS = new Set([tableEntityKind.kind, valueSetEntityKind.kind]);
+
+function assertNoManagedPackEntityKinds(
+  namespaceId: string,
+  packEntitiesForNs: Readonly<Record<string, unknown>> | undefined,
+): void {
+  if (packEntitiesForNs === undefined) return;
+  for (const kind of Object.keys(packEntitiesForNs)) {
+    if (MANAGED_ENTRY_KINDS.has(kind)) {
+      throw new Error(
+        `buildSqlContractFromDefinition: packEntities in namespace "${namespaceId}" declares entry kind "${kind}", which is managed by the framework (table/valueSet) and cannot be supplied via packEntities.`,
+      );
+    }
+  }
+}
+
+/**
+ * Walks the flat `entityTypes` namespace tree contributed by the target pack
+ * and every extension pack, indexing descriptors by their `discriminator` —
+ * 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
+ * `AuthoringContributions` input to read the way the PSL interpreter does.
+ */
+function collectEntityTypeDescriptorsByDiscriminator(
+  definition: ContractDefinition,
+): ReadonlyMap<string, AuthoringEntityTypeDescriptor> {
+  const result = new Map<string, AuthoringEntityTypeDescriptor>();
+  const walk = (namespace: AuthoringEntityTypeNamespace): void => {
+    for (const value of Object.values(namespace)) {
+      if (isAuthoringEntityTypeDescriptor(value)) {
+        result.set(value.discriminator, value);
+      } else {
+        walk(value);
+      }
+    }
+  };
+  const components = [definition.target, ...Object.values(definition.extensionPacks ?? {})];
+  for (const component of components) {
+    const entityTypes = component.authoring?.entityTypes;
+    if (entityTypes !== undefined) {
+      walk(entityTypes);
+    }
+  }
+  return result;
+}
+
+/**
+ * Derives value-sets for every pack entity declared in one namespace,
+ * reusing the same `SqlValueSetDerivingEntityTypeOutput.deriveValueSet` hook
+ * `contract-psl`'s `lowerExtensionBlocksForNamespace` folds into
+ * `entries.valueSet` on the PSL path — so a TS-attached entity (e.g. a
+ * native enum) gets its value-set the same way. Entity kinds with no
+ * registered descriptor, or whose descriptor output doesn't derive a
+ * value-set, contribute nothing.
+ */
+function derivePackEntityValueSets(
+  packEntitiesForNs: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+  entityTypesByDiscriminator: ReadonlyMap<string, AuthoringEntityTypeDescriptor>,
+): Record<string, StorageValueSetInput> | undefined {
+  if (packEntitiesForNs === undefined) return undefined;
+  let result: Record<string, StorageValueSetInput> | undefined;
+  for (const [kind, entitiesByName] of Object.entries(packEntitiesForNs)) {
+    const descriptor = entityTypesByDiscriminator.get(kind);
+    if (descriptor === undefined) continue;
+    for (const [name, entity] of Object.entries(entitiesByName)) {
+      const derivedValueSet = deriveValueSetFromEntity(descriptor.output, entity);
+      if (derivedValueSet === undefined) continue;
+      result ??= {};
+      result[name] = derivedValueSet;
+    }
+  }
+  return result;
+}
+
+/**
+ * Merges a namespace's `enumType()`-derived value-sets with its pack-entity-
+ * derived value-sets. Both land in the same `entries.valueSet[name]` slot —
+ * which drives value-set → codec typing and the domain-enum CHECK — so a
+ * same-named entry in both would let one silently overwrite the other and
+ * corrupt whichever column resolves against it. The same collision class the
+ * `mergeCollectedPackEntities` guard rejects; the PSL path already hard-errors
+ * on the equivalent (`interpretPslDocumentToSqlContract`). Reject it here too.
+ */
+function mergeNamespaceValueSets(
+  namespaceId: string,
+  enumValueSets: Record<string, StorageValueSetInput> | undefined,
+  packValueSets: Record<string, StorageValueSetInput> | undefined,
+): Record<string, StorageValueSetInput> {
+  if (enumValueSets !== undefined && packValueSets !== undefined) {
+    for (const name of Object.keys(packValueSets)) {
+      if (Object.hasOwn(enumValueSets, name)) {
+        throw new Error(
+          `buildSqlContractFromDefinition: value-set "${name}" in namespace "${namespaceId}" is derived from both an enum and a pack entity — names must be unique per namespace.`,
+        );
+      }
+    }
+  }
+  return { ...enumValueSets, ...packValueSets };
+}
+
 function ensureUnboundNamespaceSlot(
   namespaces: SqlStorageInput['namespaces'],
   createNamespace: ContractDefinition['createNamespace'],
@@ -337,6 +626,7 @@ export function buildSqlContractFromDefinition(
 ): Contract<SqlStorage> {
   const target = definition.target.targetId;
   const defaultNamespaceId = definition.target.defaultNamespaceId;
+  const qualifyColumnType = resolveColumnTypeQualifier(definition.target);
   const targetFamily = 'sql';
   const resolveNamespaceId = (m: ModelNode): string =>
     m.namespaceId !== undefined && m.namespaceId.length > 0 ? m.namespaceId : defaultNamespaceId;
@@ -355,6 +645,7 @@ export function buildSqlContractFromDefinition(
   const modelNameToNamespaceId = new Map<string, string>();
   const executionDefaults: ExecutionMutationDefault[] = [];
   const modelsByNamespace: Record<string, Record<string, ContractModel>> = {};
+  const collectedPackEntities: CollectedPackEntities = {};
   const rootEntries: Array<{
     readonly tableName: string;
     readonly namespaceId: string;
@@ -427,7 +718,36 @@ export function buildSqlContractFromDefinition(
             }
           : undefined;
 
-      const column = buildStorageColumn(field, storageValueSetRef, codecLookup);
+      // A field authored through a deferred entity-ref column helper (e.g.
+      // `pg.enum(handle)`) carries `descriptor.entityRef`: the referenced
+      // entity is collected into `collectedPackEntities` (folded into the
+      // same `entries.<kind>` + `entries.valueSet` assembly an author-declared
+      // `packEntities` entry goes through) and the descriptor is resolved
+      // against this field's now-known `namespaceId` — the builder call that
+      // produced it ran before the enclosing model associated one. The
+      // descriptor is then handed to the target's `qualifyColumnType` hook,
+      // which schema-qualifies a native-enum column's type name for its
+      // namespace. Keying off the codec id (inside the hook) catches both the
+      // TS `pg.enum(handle)` path (via `entityRef`) and the PSL `pg.enum(Ref)`
+      // path (resolved inline in the interpreter, no `entityRef`). Because the
+      // storage column is built from this qualified descriptor and the domain
+      // field derives its `type.typeParams` from that column, both come out
+      // qualified in this single pass.
+      let resolvedField: FieldNode | ValueObjectFieldNode = field;
+      if (!isValueObjectField(field)) {
+        let descriptor = field.descriptor;
+        const entityRef = descriptor.entityRef;
+        if (entityRef !== undefined) {
+          collectPackEntityFromColumn(collectedPackEntities, namespaceId, entityRef);
+          descriptor = resolveEntityRefDescriptor(descriptor, namespaceId);
+        }
+        descriptor = qualifyColumnDescriptor(descriptor, namespaceId, qualifyColumnType);
+        if (descriptor !== field.descriptor) {
+          resolvedField = { ...field, descriptor };
+        }
+      }
+
+      const column = buildStorageColumn(resolvedField, storageValueSetRef, codecLookup);
       columns[field.columnName] = column;
       fieldToColumn[field.fieldName] = field.columnName;
 
@@ -749,13 +1069,31 @@ export function buildSqlContractFromDefinition(
   }
 
   const { createNamespace } = definition;
+  const entityTypesByDiscriminator = collectEntityTypeDescriptorsByDiscriminator(definition);
   const namespaces: SqlStorageInput['namespaces'] = Object.fromEntries(
     [...namespaceCoordinateIds].sort().map((id) => {
-      const valueSetEntries = storageValueSetsByNs[id];
+      const packEntitiesForNs = mergeCollectedPackEntities(
+        id,
+        definition.packEntities?.[id],
+        collectedPackEntities[id],
+      );
+      assertNoManagedPackEntityKinds(id, packEntitiesForNs);
+
+      const enumValueSetEntries = storageValueSetsByNs[id];
+      const packValueSetEntries = derivePackEntityValueSets(
+        packEntitiesForNs,
+        entityTypesByDiscriminator,
+      );
+      const valueSetEntries =
+        enumValueSetEntries !== undefined || packValueSetEntries !== undefined
+          ? mergeNamespaceValueSets(id, enumValueSetEntries, packValueSetEntries)
+          : undefined;
+
       const nsInput: SqlNamespaceInput = {
         id,
         entries: {
           table: tablesByNamespace[id] ?? {},
+          ...packEntitiesForNs,
           ...(valueSetEntries !== undefined && Object.keys(valueSetEntries).length > 0
             ? { valueSet: valueSetEntries }
             : {}),

package/src/contract-builder.ts

@@ -18,6 +18,7 @@ import {
   type ComposedAuthoringHelpers,
   createComposedAuthoringHelpers,
 } from './composed-authoring-helpers';
+import type { PackEntitiesInput } from './contract-definition';
 import {
   type ContractInput,
   type ContractModelBuilder,
@@ -76,6 +77,7 @@ type ContractDefinition<
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
   readonly enums?: Enums;
+  readonly packEntities?: PackEntitiesInput;
 };
 
 type ContractScaffold<
@@ -101,6 +103,7 @@ type ContractScaffold<
   readonly models?: never;
   readonly codecLookup?: CodecLookup;
   readonly enums?: Enums;
+  readonly packEntities?: PackEntitiesInput;
 };
 
 type ContractFactory<
@@ -114,6 +117,7 @@ type ContractFactory<
   readonly types?: Types;
   readonly models?: Models;
   readonly enums?: Enums;
+  readonly packEntities?: PackEntitiesInput;
 };
 
 function validateTargetPackRef(
@@ -322,6 +326,7 @@ type BoundDefinitionInput<
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
   readonly enums?: Record<string, EnumTypeHandle>;
+  readonly packEntities?: PackEntitiesInput;
 };
 
 // A bare `Record<string, EnumTypeHandle>` (no literal keys) is the widened
@@ -345,6 +350,60 @@ type WithFamilyTarget<
   T extends TargetPackRef<'sql', string>,
 > = Input & { readonly family: F; readonly target: T };
 
+// Deep-merges packEntities authored on the scaffold definition with those
+// returned from the factory callback — three levels deep (namespace, kind,
+// name), unlike `enums`' flat shallow merge, since a factory-declared
+// namespace/kind must not silently drop a scaffold-declared sibling entry
+// under the same namespace or kind. A same-name key present on both sides is
+// only merged when it is the identical entity instance; two *different*
+// entities of the same namespace/kind/name is a collision (the emitted
+// entry could reflect only one), rejected here the same way
+// `mergeCollectedPackEntities` in `build-contract.ts` rejects it.
+function mergePackEntityNames(
+  namespaceId: string,
+  kind: string,
+  a: Readonly<Record<string, unknown>> | undefined,
+  b: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, unknown>> {
+  if (a !== undefined && b !== undefined) {
+    for (const [name, entity] of Object.entries(b)) {
+      const existing = a[name];
+      if (existing !== undefined && existing !== entity) {
+        throw new Error(
+          `defineContract: two different "${kind}" entities named "${name}" in namespace "${namespaceId}" — a factory-returned pack entity conflicts with a scaffold-declared one; pack-entity names must be unique per namespace.`,
+        );
+      }
+    }
+  }
+  return { ...(a ?? {}), ...(b ?? {}) };
+}
+
+function mergePackEntityKinds(
+  namespaceId: string,
+  a: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+  b: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+): Readonly<Record<string, Readonly<Record<string, unknown>>>> {
+  const kinds = new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})]);
+  const result: Record<string, Readonly<Record<string, unknown>>> = {};
+  for (const kind of kinds) {
+    result[kind] = mergePackEntityNames(namespaceId, kind, a?.[kind], b?.[kind]);
+  }
+  return result;
+}
+
+function mergePackEntities(
+  a: PackEntitiesInput | undefined,
+  b: PackEntitiesInput | undefined,
+): PackEntitiesInput | undefined {
+  if (a === undefined && b === undefined) return undefined;
+  const namespaces = new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})]);
+  const result: Record<string, Readonly<Record<string, Readonly<Record<string, unknown>>>>> = {};
+  for (const namespaceId of namespaces) {
+    result[namespaceId] = mergePackEntityKinds(namespaceId, a?.[namespaceId], b?.[namespaceId]);
+  }
+  return result;
+}
+
 /**
  * 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;
@@ -390,6 +449,7 @@ export function buildBoundContract<
     readonly types?: Record<string, StorageTypeInstance>;
     readonly models?: Record<string, ModelLike>;
     readonly enums?: Record<string, EnumTypeHandle>;
+    readonly packEntities?: PackEntitiesInput;
   },
 >(
   family: F,
@@ -415,6 +475,7 @@ export function buildBoundContract(
         readonly types?: Record<string, StorageTypeInstance>;
         readonly models?: Record<string, ModelLike>;
         readonly enums?: Record<string, EnumTypeHandle>;
+        readonly packEntities?: PackEntitiesInput;
       })
     | undefined,
 ) {
@@ -429,11 +490,13 @@ export function buildBoundContract(
       }),
     );
     const mergedEnums = { ...(definition.enums ?? {}), ...built.enums };
+    const mergedPackEntities = mergePackEntities(definition.packEntities, built.packEntities);
     return buildContractFromDsl({
       ...full,
       ...ifDefined('types', built.types),
       ...ifDefined('models', built.models),
       ...ifDefined('enums', Object.keys(mergedEnums).length > 0 ? mergedEnums : undefined),
+      ...ifDefined('packEntities', mergedPackEntities),
     });
   }
 

package/src/contract-definition.ts

@@ -16,6 +16,20 @@ import type { EnumTypeHandle } from './enum-type';
 
 export type { ExecutionMutationDefaultPhases };
 
+/**
+ * An author-declared, namespace-scoped pack entity attachment: namespace id →
+ * entity kind (the discriminator the target/extension pack registered its
+ * `AuthoringContributions.entityTypes` descriptor under, e.g. `native_enum`)
+ * → entity name → the lowered entity instance. Generic on purpose — neither
+ * the framework nor `contract-ts` names a specific entity kind here; the
+ * shape mirrors `SqlNamespaceInput.entries` (`entries.<kind>[name]`), just
+ * namespace-nested so an author can target any declared namespace (default
+ * or named), not only the contract's default namespace.
+ */
+export type PackEntitiesInput = Readonly<
+  Record<string, Readonly<Record<string, Readonly<Record<string, unknown>>>>>
+>;
+
 export interface FieldNode {
   readonly fieldName: string;
   readonly columnName: string;
@@ -185,4 +199,13 @@ export interface ContractDefinition {
    * default namespace.
    */
   readonly enums?: Record<string, EnumTypeHandle>;
+  /**
+   * Author-declared pack entities, keyed by namespace then entity kind then
+   * name. Each entity lowers into `storage.namespaces[ns].entries.<kind>`;
+   * when the registered entity-type descriptor's factory output implements
+   * the `SqlValueSetDerivingEntityTypeOutput.deriveValueSet` hook, the
+   * derived value-set also folds into `entries.valueSet`, mirroring how
+   * `enums` flows there.
+   */
+  readonly packEntities?: PackEntitiesInput;
 }

package/src/contract-dsl.ts

@@ -1583,6 +1583,15 @@ export type ContractInput<
    * default namespace. Fields reference the enum via `field.namedType(handle)`.
    */
   readonly enums?: Record<string, import('./enum-type').EnumTypeHandle>;
+  /**
+   * Author-declared pack entities, keyed by namespace id then entity kind
+   * then name — e.g. `{ auth: { native_enum: { AalLevel: <entity> } } }`.
+   * Each entity lowers into `storage.namespaces[ns].entries.<kind>`; when its
+   * registered entity-type descriptor derives a value-set, that also folds
+   * into `entries.valueSet`, mirroring how `enums` flows there. Generic on
+   * purpose — neither this type nor the assembler names a specific kind.
+   */
+  readonly packEntities?: import('./contract-definition').PackEntitiesInput;
 };
 
 export function model<

package/src/contract-lowering.ts

@@ -882,6 +882,9 @@ export function buildContractDefinition(definition: ContractInput): ContractDefi
     ...(definition.enums && Object.keys(definition.enums).length > 0
       ? { enums: definition.enums }
       : {}),
+    ...(definition.packEntities && Object.keys(definition.packEntities).length > 0
+      ? { packEntities: definition.packEntities }
+      : {}),
     models,
   };
 }