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

package/src/resolve-storage-table.ts

@@ -0,0 +1,61 @@
+import type { SqlNamespace, SqlStorage } from './ir/sql-storage';
+import type { StorageTable } from './ir/storage-table';
+
+export interface ResolvedStorageTable {
+  readonly namespaceId: string;
+  readonly table: StorageTable;
+}
+
+function tableInNamespace(
+  namespace: SqlNamespace | undefined,
+  tableName: string,
+): StorageTable | undefined {
+  if (namespace === undefined) {
+    return undefined;
+  }
+  const tables = namespace.entries.table;
+  if (!Object.hasOwn(tables, tableName)) {
+    return undefined;
+  }
+  return tables[tableName];
+}
+
+/**
+ * Resolve a bare storage table name to its namespace coordinate and table IR.
+ *
+ * When `namespaceId` is supplied, the table is resolved strictly within that
+ * namespace (no scan). When omitted, a bare name unique across namespaces
+ * resolves to its sole namespace; a bare name declared in more than one
+ * namespace throws a fail-fast diagnostic naming the candidate namespaces
+ * rather than silently selecting the first match.
+ */
+export function resolveStorageTable(
+  storage: SqlStorage,
+  tableName: string,
+  namespaceId?: string,
+): ResolvedStorageTable | undefined {
+  if (namespaceId !== undefined) {
+    const table = tableInNamespace(storage.namespaces[namespaceId], tableName);
+    return table === undefined ? undefined : { namespaceId, table };
+  }
+
+  const matches: ResolvedStorageTable[] = [];
+  for (const candidateNamespaceId of Object.keys(storage.namespaces)) {
+    const table = tableInNamespace(storage.namespaces[candidateNamespaceId], tableName);
+    if (table !== undefined) {
+      matches.push({ namespaceId: candidateNamespaceId, table });
+    }
+  }
+
+  if (matches.length > 1) {
+    const candidates = matches
+      .map((match) => match.namespaceId)
+      .sort()
+      .join(', ');
+    throw new Error(
+      `Storage table "${tableName}" is ambiguous across namespaces [${candidates}]; qualify it with a namespace coordinate.`,
+    );
+  }
+
+  return matches[0];
+}

package/src/types.ts

@@ -1,7 +1,17 @@
 import type { CodecTrait } from '@prisma-next/framework-components/codec';
+import type { ControlDriverInstance } from '@prisma-next/framework-components/control';
 import type { ReferentialAction } from './ir/foreign-key';
 
+export interface SqlControlDriverInstance<T extends string = string>
+  extends ControlDriverInstance<'sql', T> {
+  query<Row = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<{ readonly rows: Row[] }>;
+}
+
 export { buildSqlNamespace, buildSqlNamespaceMap } from './ir/build-sql-namespace';
+export { CheckConstraint, type CheckConstraintInput } from './ir/check-constraint';
 export {
   ForeignKey,
   type ForeignKeyInput,
@@ -24,6 +34,7 @@ export {
   SqlStorage,
   type SqlStorageInput,
   type SqlStorageTypeEntry,
+  storageTableAt,
 } from './ir/sql-storage';
 export { SqlUnboundNamespace } from './ir/sql-unbound-namespace';
 export { StorageColumn, type StorageColumnInput } from './ir/storage-column';
@@ -35,6 +46,7 @@ export {
   type StorageTypeInstanceInput,
   toStorageTypeInstance,
 } from './ir/storage-type-instance';
+export { StorageValueSet, type StorageValueSetInput } from './ir/storage-value-set';
 export {
   UniqueConstraint,
   type UniqueConstraintInput,
@@ -54,6 +66,7 @@ export type SqlModelFieldStorage = {
 
 export type SqlModelStorage = {
   readonly table: string;
+  readonly namespaceId: string;
   readonly fields: Record<string, SqlModelFieldStorage>;
 };
 

package/src/validators.ts

@@ -33,6 +33,7 @@ type ColumnDefaultFunction = { readonly kind: 'function'; readonly expression: s
 const literalKindSchema = type("'literal'");
 const functionKindSchema = type("'function'");
 const generatorKindSchema = type("'generator'");
+const ControlPolicySchema = type("'managed' | 'tolerated' | 'external' | 'observed'");
 const generatorIdSchema = type('string').narrow((value, ctx) => {
   return /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value) ? true : ctx.mustBe('a flat generator id');
 });
@@ -76,6 +77,14 @@ const ExecutionSchema = type({
   },
 });
 
+const ValueSetRefSchema = type({
+  plane: "'domain' | 'storage'",
+  namespaceId: 'string',
+  entityKind: "'enum' | 'value-set'",
+  name: 'string',
+  'spaceId?': 'string',
+});
+
 const StorageColumnSchema = type({
   '+': 'reject',
   nativeType: 'string',
@@ -84,6 +93,8 @@ const StorageColumnSchema = type({
   'typeParams?': 'Record<string, unknown>',
   'typeRef?': 'string',
   'default?': ColumnDefaultSchema,
+  'control?': ControlPolicySchema,
+  'valueSet?': ValueSetRefSchema,
 }).narrow((col, ctx) => {
   if (col.typeParams !== undefined && col.typeRef !== undefined) {
     return ctx.mustBe('a column with either typeParams or typeRef, not both');
@@ -103,11 +114,11 @@ const StorageTypeInstanceSchema = type
     kind: "'codec-instance'",
     codecId: 'string',
     nativeType: 'string',
-    typeParams: 'Record<string, unknown>',
+    'typeParams?': 'Record<string, unknown>',
   });
 
 /**
- * Postgres native enum entry under `storage.namespaces[namespaceId].enum[name]`.
+ * Postgres native enum entry under `storage.namespaces[namespaceId].entries.type[name]`.
  * Document-scoped `storage.types` carries codec aliases only
  * (`DocumentScopedStorageTypeSchema`).
  */
@@ -116,11 +127,37 @@ const PostgresEnumTypeSchema = type({
   'name?': 'string',
   'nativeType?': 'string',
   values: type.string.array().readonly(),
+  'control?': ControlPolicySchema,
 });
 
 /** Document-scoped `storage.types`: codec triples only. */
 const DocumentScopedStorageTypeSchema = StorageTypeInstanceSchema;
 
+/**
+ * Storage value-set entry under `storage.namespaces[id].entries.valueSet[name]`.
+ * Carries a `kind: 'value-set'` discriminator (enumerable, survives JSON) and an
+ * ordered `values` array of codec-encoded permitted values.
+ */
+export const StorageValueSetSchema = type({
+  kind: "'value-set'",
+  values: type.string.array().readonly(),
+});
+
+/**
+ * Domain enum entry under `domain.namespaces[id].enum[name]`.
+ * Carries the codec id and an ordered `members` array of `{name, value}` pairs.
+ */
+export const ContractEnumSchema = type({
+  '+': 'reject',
+  codecId: 'string',
+  members: type({
+    name: 'string',
+    value: 'string',
+  })
+    .array()
+    .readonly(),
+});
+
 const PrimaryKeySchema = type.declare<PrimaryKeyInput>().type({
   columns: type.string.array().readonly(),
   'name?': 'string',
@@ -143,6 +180,14 @@ export const ForeignKeyReferenceSchema = type({
   namespaceId: 'string',
   tableName: 'string',
   columns: type.string.array().readonly(),
+  'spaceId?': 'string',
+}) satisfies Type<ForeignKeyReferenceInput>;
+
+export const ForeignKeySourceSchema = type({
+  '+': 'reject',
+  namespaceId: 'string',
+  tableName: 'string',
+  columns: type.string.array().readonly(),
 }) satisfies Type<ForeignKeyReferenceInput>;
 
 export const ReferentialActionSchema = type
@@ -150,7 +195,7 @@ export const ReferentialActionSchema = type
   .type("'noAction' | 'restrict' | 'cascade' | 'setNull' | 'setDefault'");
 
 export const ForeignKeySchema = type.declare<ForeignKeyInput>().type({
-  source: ForeignKeyReferenceSchema,
+  source: ForeignKeySourceSchema,
   target: ForeignKeyReferenceSchema,
   'name?': 'string',
   'onDelete?': ReferentialActionSchema,
@@ -159,6 +204,13 @@ export const ForeignKeySchema = type.declare<ForeignKeyInput>().type({
   index: 'boolean',
 });
 
+export const CheckConstraintSchema = type({
+  '+': 'reject',
+  name: 'string',
+  column: 'string',
+  valueSet: ValueSetRefSchema,
+});
+
 const StorageTableSchema = type({
   '+': 'reject',
   columns: type({ '[string]': StorageColumnSchema }),
@@ -166,6 +218,8 @@ const StorageTableSchema = type({
   uniques: UniqueConstraintSchema.array().readonly(),
   indexes: IndexSchema.array().readonly(),
   foreignKeys: ForeignKeySchema.array().readonly(),
+  'control?': ControlPolicySchema,
+  'checks?': CheckConstraintSchema.array().readonly(),
 });
 
 /**
@@ -236,7 +290,7 @@ function namespaceSlotEntrySchema(
  * Builds the per-namespace entry schema for `storage.namespaces[id]`.
  * Pack-contributed `validatorSchema` fragments — keyed by the
  * descriptor's `discriminator` — validate each entry by matching the
- * entry's `kind` field on the `'enum?'` slot.
+ * entry's `kind` field on the `'entries.type'` slot.
  */
 export function createNamespaceEntrySchema(
   fragments?: ReadonlyMap<string, Type<unknown>>,
@@ -245,9 +299,13 @@ export function createNamespaceEntrySchema(
     '+': 'reject',
     id: 'string',
     'kind?': 'string',
-    'tables?': type({ '[string]': StorageTableSchema }),
-    'enum?': type({
-      '[string]': namespaceSlotEntrySchema(PostgresEnumTypeSchema, 'postgres-enum', fragments),
+    entries: type({
+      '+': 'reject',
+      'table?': type({ '[string]': StorageTableSchema }),
+      'type?': type({
+        '[string]': namespaceSlotEntrySchema(PostgresEnumTypeSchema, 'postgres-enum', fragments),
+      }),
+      'valueSet?': type({ '[string]': StorageValueSetSchema }),
     }),
   }) as Type<unknown>;
 }
@@ -277,20 +335,22 @@ export function createSqlStorageSchema(
 
 const StorageSchema = createSqlStorageSchema();
 
-// SQL-specific namespace walk shape (`tables` is the SQL family's idiom —
-// the framework `Namespace` interface no longer carries it). The wider
-// `object` table value keeps this helper structurally compatible with
-// `SqlNamespace` (whose tables narrow to `StorageTable`) and the JSON
-// envelope variants that lose class identity.
+// SQL-specific namespace walk shape (`entries.table` is the SQL family's
+// idiom). The wider `object` table value keeps this helper structurally
+// compatible with `SqlNamespace` and JSON envelope variants that lose class
+// identity.
 type NamespacedStorageWalk = {
   readonly namespaces: Readonly<
-    Record<string, Namespace & { readonly tables?: Readonly<Record<string, object>> }>
+    Record<
+      string,
+      Namespace & { readonly entries: { readonly table: Readonly<Record<string, object>> } }
+    >
   >;
 };
 
 function eachStorageTable(storage: NamespacedStorageWalk) {
   return Object.entries(storage.namespaces).flatMap(([namespaceId, ns]) =>
-    Object.entries(ns.tables ?? {}).map(([tableName, table]) => ({
+    Object.entries(ns.entries.table).map(([tableName, table]) => ({
       namespaceId,
       tableName,
       table,
@@ -298,16 +358,6 @@ function eachStorageTable(storage: NamespacedStorageWalk) {
   );
 }
 
-function findStorageTableByTableName(storage: NamespacedStorageWalk, tableName: string): unknown {
-  for (const ns of Object.values(storage.namespaces)) {
-    const t = ns.tables?.[tableName];
-    if (t !== undefined) {
-      return t;
-    }
-  }
-  return undefined;
-}
-
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -353,6 +403,7 @@ const ModelFieldSchema = type({
   type: ContractFieldTypeSchema,
   'many?': 'true',
   'dict?': 'true',
+  'valueSet?': ValueSetRefSchema,
 });
 
 const ModelStorageFieldSchema = type({
@@ -363,20 +414,44 @@ const ModelStorageFieldSchema = type({
 
 const ModelStorageSchema = type({
   table: 'string',
+  namespaceId: 'string',
   fields: type({ '[string]': ModelStorageFieldSchema }),
 });
 
-const ContractReferenceRelationSchema = type({
+const ContractRelationThroughSchema = type({
+  '+': 'reject',
+  table: 'string',
+  namespaceId: 'string',
+  parentColumns: type.string.array().readonly(),
+  childColumns: type.string.array().readonly(),
+  targetColumns: type.string.array().readonly(),
+});
+
+const ContractRelationOnSchema = type({
+  '+': 'reject',
+  localFields: type.string.array().readonly(),
+  targetFields: type.string.array().readonly(),
+});
+
+const ContractManyToManyRelationSchema = type({
+  '+': 'reject',
+  to: CrossReferenceSchema,
+  cardinality: "'N:M'",
+  on: ContractRelationOnSchema,
+  through: ContractRelationThroughSchema,
+});
+
+const ContractNonJunctionRelationSchema = type({
   '+': 'reject',
   to: CrossReferenceSchema,
   cardinality: "'1:1' | '1:N' | 'N:1'",
-  on: type({
-    '+': 'reject',
-    localFields: type.string.array().readonly(),
-    targetFields: type.string.array().readonly(),
-  }),
+  on: ContractRelationOnSchema,
 });
 
+const ContractReferenceRelationSchema = ContractManyToManyRelationSchema.or(
+  ContractNonJunctionRelationSchema,
+);
+
 const ContractEmbedRelationSchema = type({
   '+': 'reject',
   to: CrossReferenceSchema,
@@ -417,12 +492,14 @@ export function createSqlContractSchema(
     'capabilities?': 'Record<string, Record<string, boolean>>',
     'extensionPacks?': 'Record<string, unknown>',
     'meta?': ContractMetaSchema,
+    'defaultControlPolicy?': ControlPolicySchema,
     'roots?': type({ '[string]': CrossReferenceSchema }),
     domain: type({
       namespaces: type({
         '[string]': type({
           models: type({ '[string]': ModelSchema }),
           'valueObjects?': 'Record<string, unknown>',
+          'enum?': type({ '[string]': ContractEnumSchema }),
         }),
       }),
     }),
@@ -557,6 +634,9 @@ export function validateStorageSemantics(storage: SqlStorage): string[] {
     for (const fk of table.foreignKeys) {
       registerNamedObject('foreign key', fk.name);
     }
+    for (const check of table.checks ?? []) {
+      registerNamedObject('check constraint', check.name);
+    }
 
     for (const [name, kinds] of namedObjects) {
       if (kinds.length > 1) {
@@ -675,6 +755,18 @@ export function validateStorageSemantics(storage: SqlStorage): string[] {
         }
       }
     }
+
+    const seenCheckDefinitions = new Set<string>();
+    for (const check of table.checks ?? []) {
+      const signature = JSON.stringify({ column: check.column, valueSet: check.valueSet });
+      if (seenCheckDefinitions.has(signature)) {
+        errors.push(
+          `Namespace "${namespaceId}" table "${tableName}": duplicate check constraint definition on column "${check.column}"`,
+        );
+        continue;
+      }
+      seenCheckDefinitions.add(signature);
+    }
   }
 
   return errors;
@@ -691,12 +783,19 @@ export function validateModelStorageReferences(contract: Contract<SqlStorage>):
     const models = namespace.models as Record<string, ContractModel<SqlModelStorage>>;
     for (const [modelName, model] of Object.entries(models)) {
       const qualifiedName = `${namespaceId}:${modelName}`;
-      const storageTable = model.storage.table;
+      const storageNamespaceId = model.storage.namespaceId;
+      if (storageNamespaceId !== namespaceId) {
+        throw new ContractValidationError(
+          `Model "${qualifiedName}" storage.namespaceId "${storageNamespaceId}" does not match domain namespace "${namespaceId}"`,
+          'storage',
+        );
+      }
 
-      const rawTable = findStorageTableByTableName(contract.storage, storageTable);
+      const storageTable = model.storage.table;
+      const rawTable = contract.storage.namespaces[storageNamespaceId]?.entries.table[storageTable];
       if (rawTable === undefined) {
         throw new ContractValidationError(
-          `Model "${qualifiedName}" references non-existent table "${storageTable}"`,
+          `Model "${qualifiedName}" references non-existent table "${storageNamespaceId}.${storageTable}"`,
           'storage',
         );
       }
@@ -776,6 +875,15 @@ export function validateSqlStorageConsistency(contract: Contract<SqlStorage>): v
       }
     }
 
+    for (const check of table.checks ?? []) {
+      if (!columnNames.has(check.column)) {
+        throw new ContractValidationError(
+          `Namespace "${namespaceId}" table "${tableName}" check constraint "${check.name}" references non-existent column "${check.column}"`,
+          'storage',
+        );
+      }
+    }
+
     for (const [colName, column] of Object.entries(table.columns)) {
       if (!column.nullable && column.default?.kind === 'literal' && column.default.value === null) {
         throw new ContractValidationError(
@@ -802,23 +910,25 @@ export function validateSqlStorageConsistency(contract: Contract<SqlStorage>): v
         }
       }
 
-      const targetNamespace = contract.storage.namespaces[fk.target.namespaceId];
-      const referencedRaw = targetNamespace?.tables?.[fk.target.tableName];
-      if (referencedRaw === undefined) {
-        throw new ContractValidationError(
-          `Namespace "${namespaceId}" table "${tableName}" foreignKey references non-existent table "${fk.target.namespaceId}.${fk.target.tableName}"`,
-          'storage',
-        );
-      }
-      const referencedTable = referencedRaw as StorageTable;
-      const referencedColumnNames = new Set(Object.keys(referencedTable.columns));
-      for (const colName of fk.target.columns) {
-        if (!referencedColumnNames.has(colName)) {
+      if (fk.target.spaceId === undefined) {
+        const targetNamespace = contract.storage.namespaces[fk.target.namespaceId];
+        const referencedRaw = targetNamespace?.entries.table[fk.target.tableName];
+        if (referencedRaw === undefined) {
           throw new ContractValidationError(
-            `Namespace "${namespaceId}" table "${tableName}" foreignKey references non-existent column "${colName}" in table "${fk.target.tableName}"`,
+            `Namespace "${namespaceId}" table "${tableName}" foreignKey references non-existent table "${fk.target.namespaceId}.${fk.target.tableName}"`,
             'storage',
           );
         }
+        const referencedTable = referencedRaw as StorageTable;
+        const referencedColumnNames = new Set(Object.keys(referencedTable.columns));
+        for (const colName of fk.target.columns) {
+          if (!referencedColumnNames.has(colName)) {
+            throw new ContractValidationError(
+              `Namespace "${namespaceId}" table "${tableName}" foreignKey references non-existent column "${colName}" in table "${fk.target.tableName}"`,
+              'storage',
+            );
+          }
+        }
       }
 
       if (fk.source.columns.length !== fk.target.columns.length) {