@prisma-next/family-sql 0.12.0 → 0.13.0-dev.1

package/src/core/migrations/contract-to-schema-ir.ts

@@ -2,6 +2,7 @@ import type { ColumnDefault, Contract } from '@prisma-next/contract/types';
 import type { MigrationPlannerConflict } from '@prisma-next/framework-components/control';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import {
+  type CheckConstraint,
   type ForeignKey,
   type Index,
   isPostgresEnumStorageEntry,
@@ -17,6 +18,7 @@ import {
 import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
 import type {
   SqlAnnotations,
+  SqlCheckConstraintIRInput,
   SqlColumnIR,
   SqlForeignKeyIR,
   SqlIndexIR,
@@ -24,6 +26,7 @@ import type {
   SqlTableIR,
   SqlUniqueIR,
 } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 
 /**
@@ -151,6 +154,58 @@ function resolveColumnTypeMetadata(
   );
 }
 
+/**
+ * Resolves a `ValueSetRef` to its permitted values from the contract storage.
+ *
+ * Throws when the referenced namespace or value-set is absent — this indicates
+ * the contract was built incorrectly (the check and the value-set must be
+ * co-emitted by the lowering step). Used by `convertCheck` (schema-IR
+ * projection), `verifyCheckConstraints` (verification), and
+ * `checkConstraintPlanCallStrategy` (migration planning) so all three agree on
+ * the resolved values and the error behavior on a missing reference.
+ */
+export function resolveValueSetValues(
+  ref: { readonly namespaceId: string; readonly name: string },
+  storage: SqlStorage,
+  contextLabel: string,
+): readonly string[] {
+  const ns = storage.namespaces[ref.namespaceId];
+  if (!ns) {
+    throw new Error(
+      `resolveValueSetValues: namespace "${ref.namespaceId}" not found in storage (${contextLabel})`,
+    );
+  }
+  const valueSet = ns.entries.valueSet?.[ref.name];
+  if (!valueSet) {
+    throw new Error(
+      `resolveValueSetValues: value-set "${ref.name}" not found in namespace "${ref.namespaceId}" (${contextLabel})`,
+    );
+  }
+  return valueSet.values;
+}
+
+/**
+ * Projects a `CheckConstraint` IR into an `SqlCheckConstraintIRInput` by
+ * resolving the permitted values from the storage value-set it references.
+ *
+ * The `CheckConstraint.valueSet` ref points to
+ * `storage.namespaces[namespaceId].entries.valueSet[name]`. The resolved
+ * values are lifted directly from `StorageValueSet.values` so verification
+ * compares value sets, not SQL predicate strings.
+ *
+ * Throws if the referenced namespace or value-set is absent — this
+ * indicates the contract was built incorrectly (the check and the
+ * value-set must be co-emitted by the lowering step).
+ */
+function convertCheck(check: CheckConstraint, storage: SqlStorage): SqlCheckConstraintIRInput {
+  const permittedValues = resolveValueSetValues(check.valueSet, storage, `check "${check.name}"`);
+  return {
+    name: check.name,
+    column: check.column,
+    permittedValues,
+  };
+}
+
 function convertUnique(unique: UniqueConstraint): SqlUniqueIR {
   return {
     columns: unique.columns,
@@ -184,6 +239,7 @@ function convertTable(
   storageTypes: ResolvedStorageTypes,
   expandNativeType: NativeTypeExpander | undefined,
   renderDefault: DefaultRenderer | undefined,
+  storage: SqlStorage,
 ): SqlTableIR {
   const columns: Record<string, SqlColumnIR> = {};
   for (const [colName, colDef] of Object.entries(table.columns)) {
@@ -214,13 +270,19 @@ function convertTable(
     satisfiedIndexColumns.add(key);
   }
 
+  const checks: SqlCheckConstraintIRInput[] | undefined =
+    table.checks && table.checks.length > 0
+      ? table.checks.map((c) => convertCheck(c, storage))
+      : undefined;
+
   return {
     name,
     columns,
     ...ifDefined('primaryKey', table.primaryKey),
-    foreignKeys: table.foreignKeys.map(convertForeignKey),
+    foreignKeys: table.foreignKeys.filter((fk) => fk.constraint !== false).map(convertForeignKey),
     uniques: table.uniques.map(convertUnique),
     indexes: [...table.indexes.map(convertIndex), ...fkBackingIndexes],
+    ...ifDefined('checks', checks),
   };
 }
 
@@ -250,11 +312,11 @@ export function detectDestructiveChanges(
   for (const namespaceId of namespaceIds) {
     const fromNs = from.namespaces[namespaceId];
     const toNs = to.namespaces[namespaceId];
-    const fromTables = fromNs?.tables;
+    const fromTables = fromNs?.entries.table;
     if (!fromTables) continue;
 
     for (const tableName of Object.keys(fromTables)) {
-      const toTableRaw = toNs?.tables[tableName];
+      const toTableRaw = toNs?.entries.table[tableName];
       if (!(toTableRaw instanceof StorageTable)) {
         conflicts.push({
           kind: 'tableRemoved',
@@ -327,20 +389,23 @@ export function contractToSchemaIR(
     ...((storage.types ?? {}) as ResolvedStorageTypes),
   };
   for (const ns of Object.values(storage.namespaces)) {
-    const nsEnums = (ns as { enum?: Record<string, PostgresEnumStorageEntry> }).enum;
+    const nsEnums = ns.entries['type'];
     if (nsEnums) {
       for (const [k, v] of Object.entries(nsEnums)) {
-        allTypes[k] = v;
+        allTypes[k] = blindCast<
+          PostgresEnumStorageEntry | StorageTypeInstance,
+          'entries.type holds postgres-specific enum entries at runtime'
+        >(v);
       }
     }
   }
   const storageTypes = allTypes as ResolvedStorageTypes;
   const tables: Record<string, SqlTableIR> = {};
   for (const ns of Object.values(storage.namespaces)) {
-    for (const [tableName, tableDefRaw] of Object.entries(ns.tables)) {
+    for (const [tableName, tableDefRaw] of Object.entries(ns.entries.table)) {
       if (!(tableDefRaw instanceof StorageTable)) {
         throw new Error(
-          `contractToSchemaIR: expected StorageTable at namespaces.${ns.id}.tables.${tableName}`,
+          `contractToSchemaIR: expected StorageTable at namespaces.${ns.id}.entries.table.${tableName}`,
         );
       }
       const tableDef = tableDefRaw;
@@ -355,6 +420,7 @@ export function contractToSchemaIR(
         storageTypes,
         options.expandNativeType,
         options.renderDefault,
+        storage,
       );
     }
   }
@@ -395,7 +461,7 @@ function deriveAnnotations(
 
   // Top-level `storage.types`: codec-typed entries (vector, decimal, …) keyed
   // by bare `nativeType` (unchanged). Post-S1.B enums live in
-  // `namespaces[*].enum`, not here; a defensive top-level enum is still
+  // `namespaces[*].entries.type`, not here; a defensive top-level enum is still
   // namespace/schema-qualified via the resolver under the unbound coordinate
   // so it never collides on a bare name.
   for (const typeInstance of Object.values((storage.types ?? {}) as ResolvedStorageTypes)) {
@@ -415,7 +481,7 @@ function deriveAnnotations(
   // `readExistingEnumValues` read side, so two namespaces sharing an enum name
   // (or native type) resolve to distinct live-database types.
   for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
-    const nsEnums = (ns as { enum?: Record<string, PostgresEnumStorageEntry> }).enum;
+    const nsEnums = ns.entries['type'];
     if (!nsEnums) continue;
     for (const entry of Object.values(nsEnums)) {
       if (!isPostgresEnumStorageEntry(entry)) continue;

package/src/core/migrations/control-policy.ts

@@ -0,0 +1,322 @@
+import {
+  type Contract,
+  type ControlPolicy,
+  effectiveControlPolicy,
+} from '@prisma-next/contract/types';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { SqlPlannerConflict } from './types';
+
+/**
+ * The target object a control policy governs for a single planner call,
+ * resolved from the target's own IR. `undefined` means the call's target
+ * object could not be positively established — a fail-closed signal: any
+ * policy stricter than `managed` drops such a call rather than emitting it.
+ */
+export interface ControlPolicySubject {
+  readonly namespaceId: string;
+  readonly explicitNodeControlPolicy?: ControlPolicy;
+  readonly table?: string;
+  readonly column?: string;
+  readonly typeName?: string;
+  /**
+   * Whether the call creates a whole, previously-absent top-level storage
+   * object (e.g. a table or an enum/type), as opposed to modifying an
+   * existing object. This is the only thing `tolerated` permits: it is a
+   * create-if-absent policy, so an op that touches an existing object — add
+   * column, add index/constraint, alter, drop — is never allowed under it.
+   */
+  readonly createsNewObject: boolean;
+}
+
+/**
+ * The control policy that governs a single call. The `external` default is an
+ * un-overridable namespace floor: when the contract default is `external`, no
+ * per-object `managed` override can escalate DDL above the floor, so the
+ * policy is forced to `external` regardless of the node's own declaration.
+ * Every other default defers to the node's effective control policy.
+ */
+export function controlPolicyForCall(
+  subject: ControlPolicySubject | undefined,
+  defaultControlPolicy: ControlPolicy | undefined,
+): ControlPolicy {
+  if (defaultControlPolicy === 'external') {
+    return 'external';
+  }
+  return effectiveControlPolicy(subject?.explicitNodeControlPolicy, defaultControlPolicy);
+}
+
+/**
+ * Whether a call is allowed to emit under a given control policy.
+ *
+ * - `managed` — full lifecycle, every op allowed.
+ * - `tolerated` — create-if-absent only: allowed iff the call creates a whole
+ *   new top-level object (and its subject was positively resolved). Anything
+ *   that modifies an existing object, and anything whose subject could not be
+ *   resolved, is suppressed.
+ * - `external` / `observed` — no DDL at all.
+ */
+function callAllowedUnderControlPolicy(
+  policy: ControlPolicy,
+  subject: ControlPolicySubject | undefined,
+): boolean {
+  switch (policy) {
+    case 'managed':
+      return true;
+    case 'tolerated':
+      return subject?.createsNewObject === true;
+    case 'external':
+    case 'observed':
+      return false;
+  }
+}
+
+function defaultSubjectLabel(
+  factoryName: string,
+  subject: ControlPolicySubject | undefined,
+): string {
+  if (subject?.table) {
+    return `${factoryName}(${subject.table})`;
+  }
+  if (subject?.typeName) {
+    return `${factoryName}(${subject.typeName})`;
+  }
+  return factoryName;
+}
+
+function suppressionSummary(
+  subjectLabel: string,
+  subject: ControlPolicySubject | undefined,
+  effectivePolicy: ControlPolicy,
+): string {
+  const namespace = subject?.namespaceId ?? 'unknown';
+  const declared = subject?.explicitNodeControlPolicy;
+  if (effectivePolicy === 'external' && declared === 'managed') {
+    return `control policy suppressed: ${subjectLabel} — namespace '${namespace}' has effective control 'external' but table declared 'managed'`;
+  }
+  const declaredSuffix = declared ? ` but table declared '${declared}'` : '';
+  return `control policy suppressed: ${subjectLabel} — namespace '${namespace}' has effective control '${effectivePolicy}'${declaredSuffix}`;
+}
+
+function buildSubjectSuppressionWarning(
+  subject: ControlPolicySubject | undefined,
+  effectivePolicy: ControlPolicy,
+  factoryName: string,
+  formatSubjectLabel: (factoryName: string, subject: ControlPolicySubject | undefined) => string,
+): SqlPlannerConflict {
+  const subjectLabel = formatSubjectLabel(factoryName, subject);
+  return {
+    kind: 'controlPolicySuppressedCall',
+    summary: suppressionSummary(subjectLabel, subject, effectivePolicy),
+    location: {
+      ...ifDefined('namespace', subject?.namespaceId),
+      ...ifDefined('table', subject?.table),
+      ...ifDefined('column', subject?.column),
+      ...ifDefined('type', subject?.typeName),
+    },
+    meta: {
+      controlPolicy: effectivePolicy,
+      factoryName,
+      ...ifDefined('declaredControlPolicy', subject?.explicitNodeControlPolicy),
+    },
+  };
+}
+
+function defaultModificationFactoryNameForSubject(subject: ControlPolicySubject): string {
+  if (subject.table) return 'alterTable';
+  if (subject.typeName) return 'alterType';
+  return 'alterSchema';
+}
+
+/**
+ * Partition the calls produced for a single set of subjects into those the
+ * effective control policy permits (`kept`) and a list of
+ * {@link SqlPlannerConflict} warnings describing the suppressed calls.
+ *
+ * **Prefer {@link partitionIssuesByControlPolicy}** for the schema-issue
+ * pipeline: it filters subjects out of the planner's *input* so the planner
+ * never has to reason about un-modeled state on `external`/`observed`
+ * subjects. This call-level helper remains for paths that bypass the issue
+ * pipeline — currently the codec-emitted field-event ops, which originate
+ * from declared contract fields rather than from introspected schema state
+ * and therefore cannot trip the diff engine.
+ */
+export function partitionCallsByControlPolicy<TCall>(options: {
+  readonly calls: readonly TCall[];
+  readonly contract: Contract<SqlStorage>;
+  readonly resolveControlPolicySubject: (call: TCall) => ControlPolicySubject | undefined;
+  readonly resolveFactoryName: (call: TCall) => string;
+  readonly formatSubjectLabel?: (
+    factoryName: string,
+    subject: ControlPolicySubject | undefined,
+  ) => string;
+}): {
+  readonly kept: readonly TCall[];
+  readonly warnings: readonly SqlPlannerConflict[];
+} {
+  const defaultControlPolicy = options.contract.defaultControlPolicy;
+  const formatSubjectLabel = options.formatSubjectLabel ?? defaultSubjectLabel;
+  const kept: TCall[] = [];
+  const warnings: SqlPlannerConflict[] = [];
+
+  for (const call of options.calls) {
+    const subject = options.resolveControlPolicySubject(call);
+    const policy = controlPolicyForCall(subject, defaultControlPolicy);
+    if (callAllowedUnderControlPolicy(policy, subject)) {
+      kept.push(call);
+    } else {
+      const factoryName = options.resolveFactoryName(call);
+      warnings.push(
+        buildSubjectSuppressionWarning(subject, policy, factoryName, formatSubjectLabel),
+      );
+    }
+  }
+
+  return Object.freeze({
+    kept: Object.freeze(kept),
+    warnings: Object.freeze(warnings),
+  });
+}
+
+/**
+ * Partition a list of schema-issue-shaped inputs by the effective control
+ * policy of each issue's subject *before* the planner is invoked.
+ *
+ * `plannable` is the list of issues whose subject's effective policy permits
+ * the planner to act on them (`managed`, or `tolerated` for whole-object
+ * creation issues only). Issues for `external`/`observed` subjects, and
+ * non-creation issues for `tolerated` subjects, are dropped from the planner's
+ * input entirely — they never enter introspection-driven planning, never feed
+ * the diff engine, and never produce DDL calls that would have to be
+ * post-filtered. This sidesteps a class of failure where the diff engine
+ * cannot reason about the live shape of a subject the user marked as
+ * out-of-scope (`external`).
+ *
+ * `warnings` is one {@link SqlPlannerConflict} per suppressed subject (not per
+ * suppressed issue). `factoryName` is inferred from the subject's issue mix:
+ * if any of the subject's issues is whole-object creation, the warning takes
+ * the corresponding creation factoryName (e.g. `createTable`,
+ * `createEnumType`, `createSchema`); otherwise it falls back to
+ * `defaultModificationFactoryName(subject)` — a synthetic label that names
+ * the *kind* of mutation that would have run, since no concrete DDL call was
+ * generated.
+ *
+ * Unresolved-subject issues (`resolveControlPolicySubject` returns
+ * `undefined`) emit one warning each; they cannot be deduplicated because
+ * they carry no subject coordinate.
+ */
+export function partitionIssuesByControlPolicy<TIssue>(options: {
+  readonly issues: readonly TIssue[];
+  readonly contract: Contract<SqlStorage>;
+  /**
+   * Resolve the subject targeted by this issue (or `undefined` to fail-closed:
+   * any policy stricter than `managed` drops the issue).
+   */
+  readonly resolveControlPolicySubject: (issue: TIssue) => ControlPolicySubject | undefined;
+  /**
+   * Resolve a creation factoryName for this issue if it represents the
+   * absence of the whole top-level object (e.g. `'createTable'` for a
+   * missing-table issue). When the issue describes a modification to an
+   * existing object, return `undefined`. Both decisions feed off this signal:
+   *
+   * 1. Under `tolerated`, only issues whose `resolveCreationFactoryName`
+   *    returns a value flow into the planner (create-if-absent).
+   * 2. Subjects that have at least one creation-flavoured issue use the
+   *    resolved creation factoryName for their suppression warning;
+   *    otherwise they fall back to `defaultModificationFactoryName`.
+   */
+  readonly resolveCreationFactoryName: (issue: TIssue) => string | undefined;
+  /**
+   * Default modification factoryName for a suppressed subject whose issues
+   * are all non-creation (the subject exists but has a different shape).
+   * Defaults to `'alterTable'` / `'alterType'` / `'alterSchema'` based on the
+   * subject's populated coordinates.
+   */
+  readonly defaultModificationFactoryName?: (subject: ControlPolicySubject) => string;
+  readonly formatSubjectLabel?: (
+    factoryName: string,
+    subject: ControlPolicySubject | undefined,
+  ) => string;
+}): {
+  readonly plannable: readonly TIssue[];
+  readonly warnings: readonly SqlPlannerConflict[];
+} {
+  const defaultControlPolicy = options.contract.defaultControlPolicy;
+  const formatSubjectLabel = options.formatSubjectLabel ?? defaultSubjectLabel;
+  const inferModificationFactoryName =
+    options.defaultModificationFactoryName ?? defaultModificationFactoryNameForSubject;
+
+  const plannable: TIssue[] = [];
+  // Resolved-subject suppressions are deduplicated by subject key so we emit
+  // one warning per suppressed subject, not one per suppressed issue.
+  // `creationFactoryName` upgrades from `undefined` to a concrete creation
+  // name the first time we see a creation-flavoured issue for the subject.
+  const suppressedSubjects = new Map<
+    string,
+    {
+      readonly subject: ControlPolicySubject;
+      readonly policy: ControlPolicy;
+      creationFactoryName?: string;
+    }
+  >();
+  const unresolvedSuppressions: SqlPlannerConflict[] = [];
+
+  for (const issue of options.issues) {
+    const subject = options.resolveControlPolicySubject(issue);
+    const policy = controlPolicyForCall(subject, defaultControlPolicy);
+    const creationFactoryName = options.resolveCreationFactoryName(issue);
+
+    if (policy === 'managed') {
+      plannable.push(issue);
+      continue;
+    }
+    if (
+      policy === 'tolerated' &&
+      subject !== undefined &&
+      creationFactoryName !== undefined &&
+      subject.createsNewObject
+    ) {
+      plannable.push(issue);
+      continue;
+    }
+
+    if (subject === undefined) {
+      const factoryName = creationFactoryName ?? 'unknown';
+      unresolvedSuppressions.push(
+        buildSubjectSuppressionWarning(undefined, policy, factoryName, formatSubjectLabel),
+      );
+      continue;
+    }
+
+    const key = subjectKey(subject);
+    const existing = suppressedSubjects.get(key);
+    if (existing) {
+      if (existing.creationFactoryName === undefined && creationFactoryName !== undefined) {
+        existing.creationFactoryName = creationFactoryName;
+      }
+    } else {
+      suppressedSubjects.set(key, {
+        subject,
+        policy,
+        ...ifDefined('creationFactoryName', creationFactoryName),
+      });
+    }
+  }
+
+  const warnings: SqlPlannerConflict[] = [...unresolvedSuppressions];
+  for (const entry of suppressedSubjects.values()) {
+    const factoryName = entry.creationFactoryName ?? inferModificationFactoryName(entry.subject);
+    warnings.push(
+      buildSubjectSuppressionWarning(entry.subject, entry.policy, factoryName, formatSubjectLabel),
+    );
+  }
+
+  return Object.freeze({
+    plannable: Object.freeze(plannable),
+    warnings: Object.freeze(warnings),
+  });
+}
+
+function subjectKey(subject: ControlPolicySubject): string {
+  return `${subject.namespaceId}\u0000${subject.table ?? ''}\u0000${subject.typeName ?? ''}`;
+}

package/src/core/migrations/field-event-planner.ts

@@ -77,8 +77,8 @@ export function planFieldEventOperations(
   for (const namespaceId of namespaceIds) {
     const priorNs = priorContract?.storage.namespaces[namespaceId];
     const newNs = newContract.storage.namespaces[namespaceId];
-    const priorTables = priorNs?.tables;
-    const newTables = newNs?.tables;
+    const priorTables = priorNs?.entries.table;
+    const newTables = newNs?.entries.table;
 
     const tableNames = unionSorted(
       priorTables ? Object.keys(priorTables) : [],

package/src/core/migrations/plan-helpers.ts

@@ -111,10 +111,26 @@ export function createMigrationPlan<TTargetDetails>(
 
 export function plannerSuccess<TTargetDetails>(
   plan: SqlMigrationPlan<TTargetDetails>,
+  warnings?: readonly SqlPlannerConflict[],
 ): SqlPlannerSuccessResult<TTargetDetails> {
   return Object.freeze({
     kind: 'success',
     plan,
+    ...(warnings && warnings.length > 0
+      ? {
+          warnings: Object.freeze(
+            warnings.map((conflict) =>
+              Object.freeze({
+                kind: conflict.kind,
+                summary: conflict.summary,
+                ...(conflict.why ? { why: conflict.why } : {}),
+                ...(conflict.location ? { location: Object.freeze({ ...conflict.location }) } : {}),
+                ...(conflict.meta ? { meta: cloneRecord(conflict.meta) } : {}),
+              }),
+            ),
+          ),
+        }
+      : {}),
   });
 }
 

package/src/core/migrations/types.ts

@@ -4,7 +4,6 @@ import type {
   ContractSerializer,
   ContractSpace,
   ControlAdapterDescriptor,
-  ControlDriverInstance,
   ControlExtensionDescriptor,
   MigratableTargetDescriptor,
   MigrationOperationPolicy,
@@ -22,7 +21,9 @@ import type {
   SchemaIssue,
   SchemaVerifier,
 } from '@prisma-next/framework-components/control';
+import type { AggregateMigrationEdgeRef } from '@prisma-next/migration-tools/aggregate';
 import type {
+  SqlControlDriverInstance,
   SqlStorage,
   StorageColumn,
   StorageTable,
@@ -31,6 +32,7 @@ import type {
 import type { SqlOperationDescriptors } from '@prisma-next/sql-operations';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import type { Result } from '@prisma-next/utils/result';
+import type { SqlControlAdapter } from '../control-adapter';
 import type { SqlControlFamilyInstance } from '../control-instance';
 
 export type AnyRecord = Readonly<Record<string, unknown>>;
@@ -115,7 +117,7 @@ export interface CodecControlHooks<TTargetDetails = unknown> {
     readonly schemaName?: string;
   }) => readonly SchemaIssue[];
   introspectTypes?: (options: {
-    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly driver: SqlControlDriverInstance<string>;
     readonly schemaName?: string;
   }) => Promise<Record<string, StorageTypeInstance>>;
   /**
@@ -174,7 +176,7 @@ export interface SqlControlExtensionDescriptor<TTargetId extends string>
 }
 
 export interface SqlControlAdapterDescriptor<TTargetId extends string>
-  extends ControlAdapterDescriptor<'sql', TTargetId> {
+  extends ControlAdapterDescriptor<'sql', TTargetId, SqlControlAdapter<TTargetId>> {
   readonly queryOperations?: () => SqlOperationDescriptors;
 }
 
@@ -268,9 +270,11 @@ export type SqlPlannerConflictKind =
   | 'indexIncompatible'
   | 'foreignKeyConflict'
   | 'missingButNonAdditive'
-  | 'unsupportedOperation';
+  | 'unsupportedOperation'
+  | 'controlPolicySuppressedCall';
 
 export interface SqlPlannerConflictLocation {
+  readonly namespace?: string;
   readonly table?: string;
   readonly column?: string;
   readonly index?: string;
@@ -349,7 +353,7 @@ export interface SqlMigrationRunnerExecuteCallbacks<TTargetDetails> {
 
 export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
   readonly plan: SqlMigrationPlan<TTargetDetails>;
-  readonly driver: ControlDriverInstance<'sql', string>;
+  readonly driver: SqlControlDriverInstance<string>;
   /**
    * Logical contract space this plan applies to. When omitted the
    * runner derives the space from {@link SqlMigrationPlan.spaceId};
@@ -384,12 +388,18 @@ export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
    * All components must have matching familyId ('sql') and targetId.
    */
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+  /**
+   * Per-edge breakdown from graph-walk planning. When present, the runner
+   * writes one ledger row per edge instead of one collapsed row per apply.
+   */
+  readonly migrationEdges: readonly AggregateMigrationEdgeRef[];
 }
 
 export type SqlMigrationRunnerErrorCode =
   | 'DESTINATION_CONTRACT_MISMATCH'
   | 'LEGACY_MARKER_SHAPE'
   | 'MARKER_ORIGIN_MISMATCH'
+  | 'MARKER_CAS_FAILURE'
   | 'POLICY_VIOLATION'
   | 'PRECHECK_FAILED'
   | 'POSTCHECK_FAILED'
@@ -424,7 +434,7 @@ export interface SqlMigrationRunner<TTargetDetails> {
    * (the connection the outer transaction is open on).
    */
   execute(options: {
-    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly driver: SqlControlDriverInstance<string>;
     readonly perSpaceOptions: ReadonlyArray<SqlMigrationRunnerExecuteOptions<TTargetDetails>>;
   }): Promise<MigrationRunnerResult>;
 
@@ -463,7 +473,7 @@ export interface SqlControlTargetDescriptor<
    * the base, the target-specific dispatch on the subclass.
    */
   readonly schemaVerifier: SchemaVerifier<TContract, SqlSchemaIR>;
-  createPlanner(family: SqlControlFamilyInstance): SqlMigrationPlanner<TTargetDetails>;
+  createPlanner(adapter: SqlControlAdapter<TTargetId>): SqlMigrationPlanner<TTargetDetails>;
   createRunner(family: SqlControlFamilyInstance): SqlMigrationRunner<TTargetDetails>;
 }
 

package/src/core/psl-contract-infer/sql-schema-ir-to-psl-ast.ts

@@ -12,7 +12,11 @@ import type {
   PslSpan,
   PslTypesBlock,
 } from '@prisma-next/framework-components/psl-ast';
-import { UNSPECIFIED_PSL_NAMESPACE_ID } from '@prisma-next/framework-components/psl-ast';
+import {
+  makePslNamespace,
+  makePslNamespaceEntries,
+  UNSPECIFIED_PSL_NAMESPACE_ID,
+} from '@prisma-next/framework-components/psl-ast';
 import type { SqlColumnIR, SqlSchemaIR, SqlTableIR } from '@prisma-next/sql-schema-ir/types';
 import type { DefaultMappingOptions } from './default-mapping';
 import { mapDefault } from './default-mapping';
@@ -164,14 +168,12 @@ function buildPslDocumentAst(schemaIR: SqlSchemaIR, options: PslPrinterOptions):
     kind: 'document',
     sourceId: '<sql-schema-ir>',
     namespaces: [
-      {
+      makePslNamespace({
         kind: 'namespace',
         name: UNSPECIFIED_PSL_NAMESPACE_ID,
-        models: sortedModels,
-        enums,
-        compositeTypes: [],
+        entries: makePslNamespaceEntries(sortedModels, enums, [], []),
         span: SYNTHETIC_SPAN,
-      },
+      }),
     ],
     ...(types ? { types } : {}),
     span: SYNTHETIC_SPAN,