@prisma-next/family-sql 0.13.0-dev.3 → 0.13.0-dev.31

package/src/core/authoring-entity-types.ts

@@ -0,0 +1,178 @@
+import type { JsonValue } from '@prisma-next/contract/types';
+import type {
+  AuthoringEntityContext,
+  AuthoringEntityTypeDescriptor,
+  AuthoringEntityTypeNamespace,
+  AuthoringPslBlockDescriptorNamespace,
+  PslExtensionBlock,
+} from '@prisma-next/framework-components/authoring';
+import { type EnumTypeHandle, enumType } from '@prisma-next/sql-contract-ts/contract-builder';
+import { blindCast } from '@prisma-next/utils/casts';
+
+function parseQuotedString(raw: string): string | undefined {
+  if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
+    return raw.slice(1, -1);
+  }
+  return undefined;
+}
+
+export const sqlFamilyEnumEntityDescriptor = {
+  kind: 'entity' as const,
+  discriminator: 'enum',
+  output: {
+    factory: (
+      block: PslExtensionBlock,
+      ctx: AuthoringEntityContext,
+    ): EnumTypeHandle | undefined => {
+      const sourceId = ctx.sourceId ?? 'unknown';
+      const diagnostics = ctx.diagnostics;
+
+      const typeAttr = block.blockAttributes.find((a) => a.name === 'type');
+      if (!typeAttr) {
+        diagnostics?.push({
+          code: 'PSL_ENUM_MISSING_TYPE',
+          message: `enum "${block.name}" is missing a @@type("codecId") attribute`,
+          sourceId,
+          span: block.span,
+        });
+        return undefined;
+      }
+
+      const rawCodecArg = typeAttr.args[0]?.value;
+      const codecId = rawCodecArg !== undefined ? parseQuotedString(rawCodecArg) : undefined;
+      if (!codecId) {
+        diagnostics?.push({
+          code: 'PSL_ENUM_MISSING_TYPE',
+          message: `enum "${block.name}" @@type attribute must have a quoted codec id argument`,
+          sourceId,
+          span: typeAttr.span,
+        });
+        return undefined;
+      }
+
+      const nativeType = ctx.codecLookup?.targetTypesFor(codecId)?.[0];
+      if (nativeType === undefined) {
+        const typeArgSpan = typeAttr.args[0]?.span ?? typeAttr.span;
+        diagnostics?.push({
+          code: 'PSL_EXTENSION_INVALID_VALUE',
+          message: `enum "${block.name}" @@type references unknown codec "${codecId}"`,
+          sourceId,
+          span: typeArgSpan,
+        });
+        return undefined;
+      }
+
+      const codec = ctx.codecLookup?.get(codecId);
+      if (codec === undefined) {
+        const typeArgSpan = typeAttr.args[0]?.span ?? typeAttr.span;
+        diagnostics?.push({
+          code: 'PSL_EXTENSION_INVALID_VALUE',
+          message: `enum "${block.name}" @@type codec "${codecId}" resolves in targetTypesFor but is absent from codecLookup.get`,
+          sourceId,
+          span: typeArgSpan,
+        });
+        return undefined;
+      }
+
+      const seenValues = new Set<string>();
+      const members: { name: string; value: unknown }[] = [];
+      let memberError = false;
+
+      for (const [memberName, paramValue] of Object.entries(block.parameters)) {
+        let value: unknown;
+        if (paramValue.kind === 'bare') {
+          try {
+            value = codec.decodeJson(memberName);
+          } catch {
+            diagnostics?.push({
+              code: 'PSL_ENUM_BARE_MEMBER_NON_STRING_CODEC',
+              message: `enum "${block.name}" member "${memberName}" has no value and codec "${codecId}" does not accept a bare name as input`,
+              sourceId,
+              span: paramValue.span,
+            });
+            memberError = true;
+            continue;
+          }
+        } else if (paramValue.kind === 'value') {
+          let jsonValue: unknown;
+          try {
+            jsonValue = JSON.parse(paramValue.raw);
+          } catch {
+            diagnostics?.push({
+              code: 'PSL_EXTENSION_INVALID_VALUE',
+              message: `enum "${block.name}" member "${memberName}" value "${paramValue.raw}" is not valid JSON`,
+              sourceId,
+              span: paramValue.span,
+            });
+            memberError = true;
+            continue;
+          }
+          try {
+            value = codec.decodeJson(
+              blindCast<JsonValue, 'JSON.parse returns a JsonValue-compatible value'>(jsonValue),
+            );
+          } catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            diagnostics?.push({
+              code: 'PSL_EXTENSION_INVALID_VALUE',
+              message: `enum "${block.name}" member "${memberName}" was rejected by codec "${codecId}": ${reason}`,
+              sourceId,
+              span: paramValue.span,
+            });
+            memberError = true;
+            continue;
+          }
+        } else {
+          continue;
+        }
+
+        const valueKey = String(value);
+        if (seenValues.has(valueKey)) {
+          diagnostics?.push({
+            code: 'PSL_ENUM_DUPLICATE_MEMBER_VALUE',
+            message: `enum "${block.name}": duplicate member value "${valueKey}"`,
+            sourceId,
+            span: paramValue.span,
+          });
+          memberError = true;
+          continue;
+        }
+        seenValues.add(valueKey);
+        members.push({ name: memberName, value });
+      }
+
+      if (memberError) return undefined;
+
+      if (members.length === 0) {
+        diagnostics?.push({
+          code: 'PSL_ENUM_MISSING_TYPE',
+          message: `enum "${block.name}" must have at least one member`,
+          sourceId,
+          span: block.span,
+        });
+        return undefined;
+      }
+
+      return enumType(
+        block.name,
+        { codecId, nativeType },
+        ...members.map((m) => ({ name: m.name, value: m.value })),
+      );
+    },
+  },
+} satisfies AuthoringEntityTypeDescriptor;
+
+export const sqlFamilyEntityTypes: AuthoringEntityTypeNamespace = {
+  enum: sqlFamilyEnumEntityDescriptor,
+};
+
+export const sqlFamilyPslBlockDescriptors = {
+  enum: {
+    kind: 'pslBlock',
+    keyword: 'enum',
+    discriminator: 'enum',
+    name: { required: true },
+    parameters: {},
+    variadicParameters: true,
+  },
+} as const satisfies AuthoringPslBlockDescriptorNamespace;

package/src/core/authoring-field-presets.ts

@@ -9,6 +9,11 @@ import type { AuthoringFieldNamespace } from '@prisma-next/framework-components/
  * (`character`) regardless of target, and the PSL interpreter lets the
  * generator override the scalar descriptor.
  *
+ * The `uuidString` / `id.uuidv4String` / `id.uuidv7String` presets store UUID
+ * values as `character(36)` — portable across all SQL targets. For a native
+ * Postgres `uuid` column use `uuidNative` / `id.uuidv4Native` /
+ * `id.uuidv7Native` from `@prisma-next/target-postgres`.
+ *
  * Scalar presets that map to target-specific codecs (e.g. `text`, `int`,
  * `boolean`, `dateTime`) are contributed by the target pack (see
  * `postgresAuthoringFieldPresets` in `@prisma-next/target-postgres`) so the
@@ -34,7 +39,7 @@ const nanoidOptionsArgument = {
 } as const;
 
 export const sqlFamilyAuthoringFieldPresets = {
-  uuid: {
+  uuidString: {
     kind: 'fieldPreset',
     output: {
       codecId: CHARACTER_CODEC_ID,
@@ -91,7 +96,7 @@ export const sqlFamilyAuthoringFieldPresets = {
     },
   },
   id: {
-    uuidv4: {
+    uuidv4String: {
       kind: 'fieldPreset',
       output: {
         codecId: CHARACTER_CODEC_ID,
@@ -108,7 +113,7 @@ export const sqlFamilyAuthoringFieldPresets = {
         id: true,
       },
     },
-    uuidv7: {
+    uuidv7String: {
       kind: 'fieldPreset',
       output: {
         codecId: CHARACTER_CODEC_ID,

package/src/core/control-adapter.ts

@@ -1,22 +1,15 @@
-import type {
-  Contract,
-  ContractMarkerRecord,
-  LedgerEntryRecord,
-} from '@prisma-next/contract/types';
+import type { ContractMarkerRecord, LedgerEntryRecord } from '@prisma-next/contract/types';
 import type {
   ControlAdapterInstance,
   ControlStack,
 } from '@prisma-next/framework-components/control';
-import type {
-  PostgresEnumStorageEntry,
-  SqlControlDriverInstance,
-  SqlStorage,
-} from '@prisma-next/sql-contract/types';
+import type { SqlControlDriverInstance } from '@prisma-next/sql-contract/types';
 import type {
   AnyQueryAst,
   DdlNode,
   LoweredStatement,
   LowererContext,
+  SqlExecuteRequest,
 } from '@prisma-next/sql-relational-core/ast';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import type { DefaultNormalizer, NativeTypeNormalizer } from './schema-verify/verify-sql-schema';
@@ -32,6 +25,19 @@ export interface Lowerer {
   lower(ast: AnyQueryAst | DdlNode, context: LowererContext<unknown>): LoweredStatement;
 }
 
+/**
+ * Extends {@link Lowerer} with async codec-routed DDL lowering. Control
+ * adapters implement this; the planner's `CreateTableCall.toOp` and
+ * `CreateSchemaCall.toOp` accept it to produce executable DDL statements
+ * with literal defaults encoded through their codec.
+ */
+export interface ExecuteRequestLowerer extends Lowerer {
+  lowerToExecuteRequest(
+    ast: AnyQueryAst | DdlNode,
+    context?: LowererContext<unknown>,
+  ): Promise<SqlExecuteRequest>;
+}
+
 /**
  * SQL control adapter interface for control-plane operations.
  * Implemented by target-specific adapters (e.g., Postgres, MySQL).
@@ -39,7 +45,8 @@ export interface Lowerer {
  * @template TTarget - The target ID (e.g., 'postgres', 'mysql')
  */
 export interface SqlControlAdapter<TTarget extends string = string>
-  extends ControlAdapterInstance<'sql', TTarget> {
+  extends ControlAdapterInstance<'sql', TTarget>,
+    ExecuteRequestLowerer {
   /**
    * Reads the contract marker for `space` from the database, returning
    * `null` if no marker row exists for that space (or if the marker
@@ -181,33 +188,6 @@ export interface SqlControlAdapter<TTarget extends string = string>
    */
   readonly normalizeNativeType?: NativeTypeNormalizer;
 
-  /**
-   * Optional bridging adapter for resolving the existing values of a
-   * native enum type from the introspected schema IR. Targets supply
-   * this so the family-level schema verifier can walk
-   * `PostgresEnumStorageEntry` entries natively without needing to
-   * know the target-specific `schema.annotations` shape
-   * (e.g. `schema.annotations.pg.storageTypes`).
-   */
-  readonly resolveExistingEnumValues?: (
-    schema: SqlSchemaIR,
-    enumType: PostgresEnumStorageEntry,
-    namespaceId: string,
-  ) => readonly string[] | null;
-  /**
-   * Optional contract-scoped factory for {@link resolveExistingEnumValues}.
-   * Targets that need the contract storage to resolve namespace → DDL schema
-   * supply this; the family control instance prefers it over the bare adapter
-   * hook when present.
-   */
-  readonly resolveExistingEnumValuesForContract?: (
-    contract: Contract<SqlStorage>,
-  ) => (
-    schema: SqlSchemaIR,
-    enumType: PostgresEnumStorageEntry,
-    namespaceId: string,
-  ) => readonly string[] | null;
-
   /**
    * Ordered DDL queries that bootstrap marker/ledger control tables for migration
    * runners. Postgres includes `CREATE SCHEMA`; SQLite does not.
@@ -219,17 +199,6 @@ export interface SqlControlAdapter<TTarget extends string = string>
    * `sign` — excludes the ledger table.
    */
   bootstrapSignMarkerQueries(): readonly DdlNode[];
-
-  /**
-   * Lower a SQL query AST into a target-flavored `{ sql, params }` payload.
-   *
-   * Migration tooling (e.g. the `dataTransform` operation) needs to materialize
-   * SQL at emit/plan time without instantiating the runtime adapter. The control
-   * adapter's `lower` is byte-equivalent to the runtime adapter's `lower` for the
-   * same AST and contract, ensuring planned SQL matches what the runtime would
-   * emit.
-   */
-  lower(ast: AnyQueryAst | DdlNode, context: LowererContext<unknown>): LoweredStatement;
 }
 
 /**

package/src/core/control-descriptor.ts

@@ -4,6 +4,7 @@ import type {
 } from '@prisma-next/framework-components/control';
 import type { EmissionSpi } from '@prisma-next/framework-components/emission';
 import { sqlEmission } from '@prisma-next/sql-contract-emitter';
+import { sqlFamilyEntityTypes, sqlFamilyPslBlockDescriptors } from './authoring-entity-types';
 import { sqlFamilyAuthoringFieldPresets } from './authoring-field-presets';
 import { sqlFamilyAuthoringTypes } from './authoring-type-constructors';
 import { createSqlFamilyInstance, type SqlControlFamilyInstance } from './control-instance';
@@ -19,6 +20,8 @@ export class SqlFamilyDescriptor
   readonly authoring = {
     field: sqlFamilyAuthoringFieldPresets,
     type: sqlFamilyAuthoringTypes,
+    entityTypes: sqlFamilyEntityTypes,
+    pslBlockDescriptors: sqlFamilyPslBlockDescriptors,
   } as const;
 
   create<TTargetId extends string>(

package/src/core/control-instance.ts

@@ -35,8 +35,8 @@ import type { SqlControlDriverInstance, SqlStorage } from '@prisma-next/sql-cont
 import type {
   AnyQueryAst,
   DdlNode,
-  LoweredStatement,
   LowererContext,
+  SqlExecuteRequest,
 } from '@prisma-next/sql-relational-core/ast';
 import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
 import type { SqlSchemaIR, SqlTableIR } from '@prisma-next/sql-schema-ir/types';
@@ -68,10 +68,10 @@ function extractCodecTypeIdsFromContract(contract: unknown): readonly string[] {
   ) {
     const namespaces = contract.storage.namespaces as Record<
       string,
-      { readonly entries: { readonly table: Readonly<Record<string, unknown>> } }
+      { readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>> }
     >;
     for (const ns of Object.values(namespaces)) {
-      const tbls = ns.entries.table;
+      const tbls = ns.entries['table'];
       if (typeof tbls !== 'object' || tbls === null) continue;
       for (const table of Object.values(tbls)) {
         if (
@@ -240,7 +240,10 @@ export interface SqlControlFamilyInstance
 
   inferPslContract(schemaIR: SqlSchemaIR): PslDocumentAst;
 
-  lowerAst(ast: AnyQueryAst | DdlNode, context: LowererContext<unknown>): LoweredStatement;
+  lowerAst(
+    ast: AnyQueryAst | DdlNode,
+    context: LowererContext<unknown>,
+  ): Promise<SqlExecuteRequest>;
 
   /**
    * Inserts the initial marker row for `space` (upsert on `space`).
@@ -672,9 +675,6 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     }): VerifyDatabaseSchemaResult {
       const contract = deserializeWithTargetSerializer(options.contract) as Contract<SqlStorage>;
       const controlAdapter = getControlAdapter();
-      const resolveExistingEnumValues =
-        controlAdapter.resolveExistingEnumValuesForContract?.(contract) ??
-        controlAdapter.resolveExistingEnumValues;
       return verifySqlSchema({
         contract,
         schema: options.schema,
@@ -683,7 +683,6 @@ export function createSqlFamilyInstance<TTargetId extends string>(
         frameworkComponents: options.frameworkComponents,
         ...ifDefined('normalizeDefault', controlAdapter.normalizeDefault),
         ...ifDefined('normalizeNativeType', controlAdapter.normalizeNativeType),
-        ...ifDefined('resolveExistingEnumValues', resolveExistingEnumValues),
       });
     },
     async sign(options: {
@@ -707,7 +706,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       const controlAdapter = getControlAdapter();
       const lowererContext = { contract };
       for (const query of controlAdapter.bootstrapSignMarkerQueries()) {
-        const lowered = controlAdapter.lower(query, lowererContext);
+        const lowered = await controlAdapter.lowerToExecuteRequest(query, lowererContext);
         await driver.query(lowered.sql, lowered.params);
       }
 
@@ -857,8 +856,11 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       return sqlSchemaIrToPslAst(schemaIR);
     },
 
-    lowerAst(ast: AnyQueryAst | DdlNode, context: LowererContext<unknown>): LoweredStatement {
-      return getControlAdapter().lower(ast, context);
+    lowerAst(
+      ast: AnyQueryAst | DdlNode,
+      context: LowererContext<unknown>,
+    ): Promise<SqlExecuteRequest> {
+      return getControlAdapter().lowerToExecuteRequest(ast, context);
     },
 
     bootstrapControlTableQueries(): readonly DdlNode[] {

package/src/core/ir/sql-contract-serializer-base.ts

@@ -21,6 +21,7 @@ import {
 } from '@prisma-next/sql-contract/types';
 import {
   createSqlContractSchema,
+  createSqlEntrySchemaRegistry,
   validateSqlContractFully,
 } from '@prisma-next/sql-contract/validators';
 import { blindCast } from '@prisma-next/utils/casts';
@@ -72,18 +73,20 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
   private readonly contractSchema: Type<unknown> | undefined;
 
   constructor(
-    protected readonly entityTypeRegistry: ReadonlyMap<
+    protected readonly entityHydrationRegistry: ReadonlyMap<
       string,
       SqlEntityHydrationFactory
     > = new Map(),
-    validatorFragments?: ReadonlyMap<string, Type<unknown>>,
+    validatorRegistry: ReadonlyMap<string, Type<unknown>> = new Map(),
   ) {
-    // Only build a fragments-aware contract schema when pack contributions
-    // exist. The cached module-level default in `validators.ts` covers the
-    // no-contributions case and avoids per-instance schema compilation.
+    // One uniform registry: SQL core's kinds and pack contributions are
+    // composed into the same map. Only build a per-instance contract
+    // schema when pack contributions exist — the cached module-level
+    // default in `validators.ts` is the same composition with no pack
+    // entries and avoids per-instance schema compilation.
     this.contractSchema =
-      validatorFragments !== undefined && validatorFragments.size > 0
-        ? createSqlContractSchema(validatorFragments)
+      validatorRegistry.size > 0
+        ? createSqlContractSchema(createSqlEntrySchemaRegistry(validatorRegistry))
         : undefined;
   }
 
@@ -182,74 +185,87 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
       return raw;
     }
     const rawRecord = isPlainRecord(raw) ? raw : {};
-    if (
-      Object.hasOwn(rawRecord, 'tables') ||
-      Object.hasOwn(rawRecord, 'enum') ||
-      Object.hasOwn(rawRecord, 'collections')
-    ) {
-      throw new ContractValidationError(
-        'Namespace envelope uses deprecated flat slot keys; expected `entries: { table? }`',
-        'structural',
-      );
-    }
     const id = typeof rawRecord['id'] === 'string' ? rawRecord['id'] : nsId;
     const parsed = NamespaceRawSchema({ ...rawRecord, id });
     if (parsed instanceof type.errors) {
       const messages = parsed.map((p: { message: string }) => p.message).join('; ');
       throw new ContractValidationError(`Namespace hydration failed: ${messages}`, 'structural');
     }
-    // Default to empty table; overwritten below if raw entries carry a table slot.
-    const entriesInput: {
-      table: Record<string, StorageTable>;
-      valueSet?: Record<string, StorageValueSet>;
-    } = { table: {} };
+    const entriesOutput: Record<string, Record<string, unknown>> = {};
     const entriesRaw = parsed.entries;
     if (entriesRaw !== undefined && typeof entriesRaw === 'object' && entriesRaw !== null) {
       const rawEntries = entriesRaw as Record<string, unknown>;
-      const tableSlot = rawEntries['table'];
-      if (tableSlot !== null && typeof tableSlot === 'object' && !Array.isArray(tableSlot)) {
-        entriesInput.table = Object.fromEntries(
-          Object.entries(tableSlot as Record<string, unknown>).map(([tableName, table]) => [
-            tableName,
-            table instanceof StorageTable ? table : new StorageTable(table as StorageTableInput),
-          ]),
-        );
+      for (const [key, innerMap] of Object.entries(rawEntries)) {
+        const hydrated = this.hydrateEntriesKind(key, innerMap);
+        if (hydrated === undefined) {
+          throw new ContractValidationError(
+            `Unknown entries key "${key}" in namespace "${id}"; no hydration factory registered for this entity kind`,
+            'structural',
+          );
+        }
+        entriesOutput[key] = hydrated;
       }
-      const valueSetSlot = rawEntries['valueSet'];
-      if (
-        valueSetSlot !== null &&
-        typeof valueSetSlot === 'object' &&
-        !Array.isArray(valueSetSlot)
-      ) {
-        entriesInput.valueSet = Object.fromEntries(
-          Object.entries(
-            blindCast<
-              Record<string, unknown>,
-              'valueSet slot is a plain record after object check'
-            >(valueSetSlot),
-          ).map(([vsName, vs]) => [
-            vsName,
-            vs instanceof StorageValueSet
-              ? vs
-              : new StorageValueSet(
-                  blindCast<
-                    StorageValueSetInput,
-                    'non-instance valueSet entry is StorageValueSetInput'
-                  >(vs),
-                ),
-          ]),
-        );
-      }
-      // Target-specific slots (e.g. postgres `type`) are left for target
-      // overrides to extract from the original `raw` parameter.
+    }
+    // Always ensure a 'table' key is present (may be empty).
+    if (!Object.hasOwn(entriesOutput, 'table')) {
+      entriesOutput['table'] = {};
     }
 
-    return blindCast<SqlNamespaceTablesInput, 'hydrated namespace tables input'>({
+    return blindCast<SqlNamespaceTablesInput, 'hydrated namespace entries input'>({
       id,
-      entries: entriesInput,
+      entries: entriesOutput,
     });
   }
 
+  protected hydrateEntriesKind(
+    key: string,
+    innerMap: unknown,
+  ): Record<string, unknown> | undefined {
+    if (key === 'table') {
+      if (innerMap === null || typeof innerMap !== 'object' || Array.isArray(innerMap)) {
+        return {};
+      }
+      return Object.fromEntries(
+        Object.entries(
+          blindCast<
+            Record<string, unknown>,
+            'table inner map is a plain record after object check'
+          >(innerMap),
+        ).map(([tableName, table]) => [
+          tableName,
+          new StorageTable(
+            blindCast<
+              StorageTableInput,
+              'each table value is StorageTableInput by contract schema'
+            >(table),
+          ),
+        ]),
+      );
+    }
+    if (key === 'valueSet') {
+      if (innerMap === null || typeof innerMap !== 'object' || Array.isArray(innerMap)) {
+        return {};
+      }
+      return Object.fromEntries(
+        Object.entries(
+          blindCast<
+            Record<string, unknown>,
+            'valueSet inner map is a plain record after object check'
+          >(innerMap),
+        ).map(([vsName, vs]) => [
+          vsName,
+          new StorageValueSet(
+            blindCast<StorageValueSetInput, 'valueSet entry is StorageValueSetInput after parse'>(
+              vs,
+            ),
+          ),
+        ]),
+      );
+    }
+    // Delegate unknown keys to subclass — return undefined to fail closed.
+    return undefined;
+  }
+
   protected hydrateStorageTypeEntry(entry: SqlStorageTypeEntry): SqlStorageTypeEntry {
     if (typeof entry !== 'object' || entry === null) {
       return entry;
@@ -258,7 +274,7 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
     if (typeof kind !== 'string') {
       return entry;
     }
-    const factory = this.entityTypeRegistry.get(kind);
+    const factory = this.entityHydrationRegistry.get(kind);
     if (factory === undefined) {
       return entry;
     }