@prisma-next/sql-contract-ts 0.14.0-dev.80 → 0.14.0-dev.82

package/package.json

@@ -1,27 +1,27 @@
 {
   "name": "@prisma-next/sql-contract-ts",
-  "version": "0.14.0-dev.80",
+  "version": "0.14.0-dev.82",
   "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.80",
-    "@prisma-next/contract": "0.14.0-dev.80",
-    "@prisma-next/contract-authoring": "0.14.0-dev.80",
-    "@prisma-next/framework-components": "0.14.0-dev.80",
-    "@prisma-next/sql-contract": "0.14.0-dev.80",
-    "@prisma-next/utils": "0.14.0-dev.80",
+    "@prisma-next/config": "0.14.0-dev.82",
+    "@prisma-next/contract": "0.14.0-dev.82",
+    "@prisma-next/contract-authoring": "0.14.0-dev.82",
+    "@prisma-next/framework-components": "0.14.0-dev.82",
+    "@prisma-next/sql-contract": "0.14.0-dev.82",
+    "@prisma-next/utils": "0.14.0-dev.82",
     "arktype": "^2.2.2",
     "pathe": "^2.0.3",
     "ts-toolbelt": "^9.6.0"
   },
   "devDependencies": {
-    "@prisma-next/test-utils": "0.14.0-dev.80",
-    "@prisma-next/tsconfig": "0.14.0-dev.80",
+    "@prisma-next/test-utils": "0.14.0-dev.82",
+    "@prisma-next/tsconfig": "0.14.0-dev.82",
     "@types/pg": "8.20.0",
     "pg": "8.22.0",
-    "@prisma-next/tsdown": "0.14.0-dev.80",
+    "@prisma-next/tsdown": "0.14.0-dev.82",
     "tsdown": "0.22.3",
     "typescript": "5.9.3",
     "vitest": "4.1.10"

package/src/build-contract.ts

@@ -281,14 +281,14 @@ function qualifyColumnDescriptor(
   };
 }
 
-type CollectedPackEntities = Record<string, Record<string, Record<string, unknown>>>;
+type CollectedColumnEntities = 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.
+ * accumulator (`namespaceId → entityKind → entityName`) — folded into the same
+ * namespace assembly `deriveEntityValueSets`/`entries.<kind>` step as the
+ * entities-channel attachments, so a column-collected entity gets its
+ * value-set the same way an entities-channel 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.
@@ -297,8 +297,8 @@ type CollectedPackEntities = Record<string, Record<string, Record<string, unknow
  * 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,
+function collectEntityFromColumn(
+  collected: CollectedColumnEntities,
   namespaceId: string,
   entityRef: NonNullable<ColumnTypeDescriptor['entityRef']>,
 ): void {
@@ -316,34 +316,36 @@ function collectPackEntityFromColumn(
 }
 
 /**
- * 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.
+ * Merges a namespace's entities-channel attachments (lowered from the
+ * `entities` handle list, carried on `ContractDefinition.attachedEntities`)
+ * with the entities collected from that namespace's deferred entity-ref
+ * columns. A column-collected entity that shadows a *different* attached
+ * entity of the same kind+name (or vice-versa) is the same name-collision bug
+ * `collectEntityFromColumn` guards against across columns, so it is rejected
+ * the same way — by entity identity, so the same handle attached and used by
+ * a column does not throw.
  */
-function mergeCollectedPackEntities(
+function mergeColumnAndAttachedEntities(
   namespaceId: string,
-  declared: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
-  collected: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+  attached: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+  columnCollected: 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)]);
+  if (attached === undefined) return columnCollected;
+  if (columnCollected === undefined) return attached;
+  const kinds = new Set([...Object.keys(attached), ...Object.keys(columnCollected)]);
   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];
+    const attachedForKind = attached[kind];
+    const columnForKind = columnCollected[kind];
+    for (const [name, entity] of Object.entries(columnForKind ?? {})) {
+      const existing = attachedForKind?.[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.`,
+          `buildSqlContractFromDefinition: two different "${kind}" entities named "${name}" in namespace "${namespaceId}" — a column-referenced entity conflicts with an attached one; pack-entity names must be unique per namespace.`,
         );
       }
     }
-    result[kind] = { ...declaredForKind, ...collectedForKind };
+    result[kind] = { ...attachedForKind, ...columnForKind };
   }
   return result;
 }
@@ -486,7 +488,7 @@ function collectStorageNamespaceCoordinateIds(definition: ContractDefinition): S
       ids.add(model.namespaceId);
     }
   }
-  for (const id of Object.keys(definition.packEntities ?? {})) {
+  for (const id of Object.keys(definition.attachedEntities ?? {})) {
     if (id.length > 0) {
       ids.add(id);
     }
@@ -496,21 +498,21 @@ function collectStorageNamespaceCoordinateIds(definition: ContractDefinition): S
 
 /**
  * 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.
+ * `valueSet` from `enums` and attached-entity value-set derivation). A
+ * pack-attached 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(
+function assertNoManagedEntityKinds(
   namespaceId: string,
-  packEntitiesForNs: Readonly<Record<string, unknown>> | undefined,
+  entitiesForNs: Readonly<Record<string, unknown>> | undefined,
 ): void {
-  if (packEntitiesForNs === undefined) return;
-  for (const kind of Object.keys(packEntitiesForNs)) {
+  if (entitiesForNs === undefined) return;
+  for (const kind of Object.keys(entitiesForNs)) {
     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.`,
+        `buildSqlContractFromDefinition: attached entity in namespace "${namespaceId}" declares entry kind "${kind}", which is managed by the framework (table/valueSet) and cannot be attached.`,
       );
     }
   }
@@ -557,13 +559,13 @@ function collectEntityTypeDescriptorsByDiscriminator(
  * 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,
+function deriveEntityValueSets(
+  entitiesForNs: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
   entityTypesByDiscriminator: ReadonlyMap<string, AuthoringEntityTypeDescriptor>,
 ): Record<string, StorageValueSetInput> | undefined {
-  if (packEntitiesForNs === undefined) return undefined;
+  if (entitiesForNs === undefined) return undefined;
   let result: Record<string, StorageValueSetInput> | undefined;
-  for (const [kind, entitiesByName] of Object.entries(packEntitiesForNs)) {
+  for (const [kind, entitiesByName] of Object.entries(entitiesForNs)) {
     const descriptor = entityTypesByDiscriminator.get(kind);
     if (descriptor === undefined) continue;
     for (const [name, entity] of Object.entries(entitiesByName)) {
@@ -582,7 +584,7 @@ function derivePackEntityValueSets(
  * 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
+ * `mergeColumnAndAttachedEntities` guard rejects; the PSL path already hard-errors
  * on the equivalent (`interpretPslDocumentToSqlContract`). Reject it here too.
  */
 function mergeNamespaceValueSets(
@@ -645,7 +647,7 @@ export function buildSqlContractFromDefinition(
   const modelNameToNamespaceId = new Map<string, string>();
   const executionDefaults: ExecutionMutationDefault[] = [];
   const modelsByNamespace: Record<string, Record<string, ContractModel>> = {};
-  const collectedPackEntities: CollectedPackEntities = {};
+  const collectedColumnEntities: CollectedColumnEntities = {};
   const rootEntries: Array<{
     readonly tableName: string;
     readonly namespaceId: string;
@@ -720,9 +722,9 @@ export function buildSqlContractFromDefinition(
 
       // 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
+      // entity is collected into `collectedColumnEntities` (folded into the
+      // same `entries.<kind>` + `entries.valueSet` assembly an entities-channel
+      // attachment 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,
@@ -738,7 +740,7 @@ export function buildSqlContractFromDefinition(
         let descriptor = field.descriptor;
         const entityRef = descriptor.entityRef;
         if (entityRef !== undefined) {
-          collectPackEntityFromColumn(collectedPackEntities, namespaceId, entityRef);
+          collectEntityFromColumn(collectedColumnEntities, namespaceId, entityRef);
           descriptor = resolveEntityRefDescriptor(descriptor, namespaceId);
         }
         descriptor = qualifyColumnDescriptor(descriptor, namespaceId, qualifyColumnType);
@@ -1072,18 +1074,15 @@ export function buildSqlContractFromDefinition(
   const entityTypesByDiscriminator = collectEntityTypeDescriptorsByDiscriminator(definition);
   const namespaces: SqlStorageInput['namespaces'] = Object.fromEntries(
     [...namespaceCoordinateIds].sort().map((id) => {
-      const packEntitiesForNs = mergeCollectedPackEntities(
+      const entitiesForNs = mergeColumnAndAttachedEntities(
         id,
-        definition.packEntities?.[id],
-        collectedPackEntities[id],
+        definition.attachedEntities?.[id],
+        collectedColumnEntities[id],
       );
-      assertNoManagedPackEntityKinds(id, packEntitiesForNs);
+      assertNoManagedEntityKinds(id, entitiesForNs);
 
       const enumValueSetEntries = storageValueSetsByNs[id];
-      const packValueSetEntries = derivePackEntityValueSets(
-        packEntitiesForNs,
-        entityTypesByDiscriminator,
-      );
+      const packValueSetEntries = deriveEntityValueSets(entitiesForNs, entityTypesByDiscriminator);
       const valueSetEntries =
         enumValueSetEntries !== undefined || packValueSetEntries !== undefined
           ? mergeNamespaceValueSets(id, enumValueSetEntries, packValueSetEntries)
@@ -1093,7 +1092,7 @@ export function buildSqlContractFromDefinition(
         id,
         entries: {
           table: tablesByNamespace[id] ?? {},
-          ...packEntitiesForNs,
+          ...entitiesForNs,
           ...(valueSetEntries !== undefined && Object.keys(valueSetEntries).length > 0
             ? { valueSet: valueSetEntries }
             : {}),

package/src/contract-builder.ts

@@ -6,6 +6,7 @@ import type {
   FamilyPackRef,
   TargetPackRef,
 } from '@prisma-next/framework-components/components';
+import type { PackEntityHandle } from '@prisma-next/sql-contract/entity-handle-lowering-hook';
 import type {
   SqlNamespaceBase,
   SqlNamespaceInput,
@@ -18,7 +19,6 @@ import {
   type ComposedAuthoringHelpers,
   createComposedAuthoringHelpers,
 } from './composed-authoring-helpers';
-import type { PackEntitiesInput } from './contract-definition';
 import {
   type ContractInput,
   type ContractModelBuilder,
@@ -77,7 +77,7 @@ type ContractDefinition<
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
   readonly enums?: Enums;
-  readonly packEntities?: PackEntitiesInput;
+  readonly entities?: readonly PackEntityHandle[];
 };
 
 type ContractScaffold<
@@ -103,7 +103,7 @@ type ContractScaffold<
   readonly models?: never;
   readonly codecLookup?: CodecLookup;
   readonly enums?: Enums;
-  readonly packEntities?: PackEntitiesInput;
+  readonly entities?: readonly PackEntityHandle[];
 };
 
 type ContractFactory<
@@ -117,7 +117,7 @@ type ContractFactory<
   readonly types?: Types;
   readonly models?: Models;
   readonly enums?: Enums;
-  readonly packEntities?: PackEntitiesInput;
+  readonly entities?: readonly PackEntityHandle[];
 };
 
 function validateTargetPackRef(
@@ -326,7 +326,7 @@ type BoundDefinitionInput<
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
   readonly enums?: Record<string, EnumTypeHandle>;
-  readonly packEntities?: PackEntitiesInput;
+  readonly entities?: readonly PackEntityHandle[];
 };
 
 // A bare `Record<string, EnumTypeHandle>` (no literal keys) is the widened
@@ -350,60 +350,6 @@ 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;
@@ -449,7 +395,7 @@ export function buildBoundContract<
     readonly types?: Record<string, StorageTypeInstance>;
     readonly models?: Record<string, ModelLike>;
     readonly enums?: Record<string, EnumTypeHandle>;
-    readonly packEntities?: PackEntitiesInput;
+    readonly entities?: readonly PackEntityHandle[];
   },
 >(
   family: F,
@@ -475,7 +421,7 @@ export function buildBoundContract(
         readonly types?: Record<string, StorageTypeInstance>;
         readonly models?: Record<string, ModelLike>;
         readonly enums?: Record<string, EnumTypeHandle>;
-        readonly packEntities?: PackEntitiesInput;
+        readonly entities?: readonly PackEntityHandle[];
       })
     | undefined,
 ) {
@@ -490,13 +436,13 @@ export function buildBoundContract(
       }),
     );
     const mergedEnums = { ...(definition.enums ?? {}), ...built.enums };
-    const mergedPackEntities = mergePackEntities(definition.packEntities, built.packEntities);
+    const mergedEntities = [...(definition.entities ?? []), ...(built.entities ?? [])];
     return buildContractFromDsl({
       ...full,
       ...ifDefined('types', built.types),
       ...ifDefined('models', built.models),
       ...ifDefined('enums', Object.keys(mergedEnums).length > 0 ? mergedEnums : undefined),
-      ...ifDefined('packEntities', mergedPackEntities),
+      ...ifDefined('entities', mergedEntities.length > 0 ? mergedEntities : undefined),
     });
   }
 

package/src/contract-definition.ts

@@ -17,16 +17,19 @@ 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
+ * Namespace-scoped pack-entity attachments, the internal build IR carrying
+ * the lowered `entities` handle list: 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.
+ * namespace-nested so an attachment can target any declared namespace
+ * (default or named), not only the contract's default namespace. Produced by
+ * the generic entity-handle walk in `buildContractDefinition`; never an
+ * author-facing input.
  */
-export type PackEntitiesInput = Readonly<
+export type AttachedEntities = Readonly<
   Record<string, Readonly<Record<string, Readonly<Record<string, unknown>>>>>
 >;
 
@@ -200,12 +203,14 @@ export interface ContractDefinition {
    */
   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.
+   * Pack-entity attachments lowered from the `entities` handle list, keyed by
+   * namespace then entity kind then name. Each entity lands in
+   * `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. Internal build IR — populated by `buildContractDefinition`, not an
+   * author input.
    */
-  readonly packEntities?: PackEntitiesInput;
+  readonly attachedEntities?: AttachedEntities;
 }

package/src/contract-dsl.ts

@@ -1615,14 +1615,14 @@ export type ContractInput<
    */
   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.
+   * Author-declared pack-entity handles, lowered by the pack that registered
+   * each handle's `entityKind` (through the SQL-family batch lowering hook)
+   * into namespace-scoped entry attachments at build time. Generic on
+   * purpose — neither this type nor the walk names a specific kind; a handle
+   * whose kind no composed pack registers is a build error. This is the only
+   * public channel for attaching pack entities.
    */
-  readonly packEntities?: import('./contract-definition').PackEntitiesInput;
+  readonly entities?: readonly import('@prisma-next/sql-contract/entity-handle-lowering-hook').PackEntityHandle[];
 };
 
 export function model<
@@ -1744,7 +1744,7 @@ type CrossSpaceHandle = {
   readonly stageOne: { readonly namespace?: string };
 };
 
-function isCrossSpaceHandle(value: unknown): value is CrossSpaceHandle {
+export function isCrossSpaceHandle(value: unknown): value is CrossSpaceHandle {
   if (typeof value !== 'object' || value === null) {
     return false;
   }