@prisma-next/family-sql 0.12.0-dev.4 → 0.12.0-dev.40

package/src/core/control-instance.ts

@@ -1,4 +1,8 @@
-import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import type {
+  Contract,
+  ContractMarkerRecord,
+  LedgerEntryRecord,
+} from '@prisma-next/contract/types';
 import type {
   TargetBoundComponentDescriptor,
   TargetDescriptor,
@@ -31,14 +35,10 @@ import { sqlContractCanonicalizationHooks } from '@prisma-next/sql-contract/cano
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type {
   AnyQueryAst,
+  DdlNode,
   LoweredStatement,
   LowererContext,
 } from '@prisma-next/sql-relational-core/ast';
-import {
-  ensureSchemaStatement,
-  ensureTableStatement,
-  writeContractMarker,
-} from '@prisma-next/sql-runtime';
 import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
 import type { SqlSchemaIR, SqlTableIR } from '@prisma-next/sql-schema-ir/types';
 import { ifDefined } from '@prisma-next/utils/defined';
@@ -241,30 +241,64 @@ export interface SqlControlFamilyInstance
 
   inferPslContract(schemaIR: SqlSchemaIR): PslDocumentAst;
 
-  lowerAst(ast: AnyQueryAst, context: LowererContext<unknown>): LoweredStatement;
+  lowerAst(ast: AnyQueryAst | DdlNode, context: LowererContext<unknown>): LoweredStatement;
+
+  /**
+   * Inserts the initial marker row for `space` (upsert on `space`).
+   * Delegates to the target control adapter's write SPI; see
+   * `SqlControlAdapter.initMarker`.
+   */
+  initMarker(options: {
+    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly space: string;
+    readonly destination: {
+      readonly storageHash: string;
+      readonly profileHash: string;
+      readonly invariants?: readonly string[];
+    };
+  }): Promise<void>;
+
+  /**
+   * Compare-and-swap advance of the marker row for `space`. Returns `true`
+   * when the swap matched a row; see `SqlControlAdapter.updateMarker`.
+   */
+  updateMarker(options: {
+    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly space: string;
+    readonly expectedFrom: string;
+    readonly destination: {
+      readonly storageHash: string;
+      readonly profileHash: string;
+      readonly invariants?: readonly string[];
+    };
+  }): Promise<boolean>;
+
+  /**
+   * Appends a ledger entry for `space`; see
+   * `SqlControlAdapter.writeLedgerEntry`.
+   */
+  writeLedgerEntry(options: {
+    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly space: string;
+    readonly entry: {
+      readonly edgeId: string;
+      readonly from: string;
+      readonly to: string;
+      readonly migrationName: string;
+      readonly migrationHash: string;
+      readonly operations: readonly unknown[];
+    };
+  }): Promise<void>;
+
+  bootstrapControlTableQueries(): readonly DdlNode[];
+
+  bootstrapSignMarkerQueries(): readonly DdlNode[];
 
   toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview;
 }
 
 export type SqlFamilyInstance = SqlControlFamilyInstance;
 
-function isSqlControlAdapter<TTargetId extends string>(
-  value: unknown,
-): value is SqlControlAdapter<TTargetId> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'introspect' in value &&
-    typeof (value as { introspect: unknown }).introspect === 'function' &&
-    'readMarker' in value &&
-    typeof (value as { readMarker: unknown }).readMarker === 'function' &&
-    'readAllMarkers' in value &&
-    typeof (value as { readAllMarkers: unknown }).readAllMarkers === 'function' &&
-    'lower' in value &&
-    typeof (value as { lower: unknown }).lower === 'function'
-  );
-}
-
 interface DescriptorWithStorageTypes {
   readonly targetId?: string | undefined;
   readonly types?:
@@ -361,19 +395,11 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     extensionPacks: extensions,
   });
 
-  // Family-instance methods accept `ControlDriverInstance<'sql', string>` —
-  // the family API isn't generic on the target id. Letting `isSqlControlAdapter`
-  // default its type parameter narrows the adapter to `SqlControlAdapter<string>`,
-  // which matches the family-level driver type without any cast at call sites.
-  const getControlAdapter = () => {
-    const controlAdapter = adapter.create(stack);
-    if (!isSqlControlAdapter(controlAdapter)) {
-      throw new Error(
-        'Adapter does not implement SqlControlAdapter (missing introspect, readMarker, or readAllMarkers)',
-      );
-    }
-    return controlAdapter;
-  };
+  // Family-instance methods accept `ControlDriverInstance<'sql', string>` — the
+  // family API isn't generic on the target id. The adapter descriptor's `create`
+  // returns the concrete `SqlControlAdapter<TTargetId>`; widening the target id to
+  // `string` here matches the family-level driver type without a per-method probe.
+  const getControlAdapter = (): SqlControlAdapter<string> => adapter.create(stack);
 
   const targetSerializer = (
     target as unknown as {
@@ -540,6 +566,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
         frameworkComponents: options.frameworkComponents,
         ...ifDefined('normalizeDefault', controlAdapter.normalizeDefault),
         ...ifDefined('normalizeNativeType', controlAdapter.normalizeNativeType),
+        ...ifDefined('columnsCompatible', controlAdapter.columnsCompatible),
         ...ifDefined('resolveExistingEnumValues', resolveExistingEnumValues),
       });
     },
@@ -561,24 +588,24 @@ export function createSqlFamilyInstance<TTargetId extends string>(
           : contractStorageHash;
       const contractTarget = contract.target;
 
-      await driver.query(ensureSchemaStatement.sql, ensureSchemaStatement.params);
-      await driver.query(ensureTableStatement.sql, ensureTableStatement.params);
+      const controlAdapter = getControlAdapter();
+      const lowererContext = { contract };
+      for (const query of controlAdapter.bootstrapSignMarkerQueries()) {
+        const lowered = controlAdapter.lower(query, lowererContext);
+        await driver.query(lowered.sql, lowered.params);
+      }
 
-      const existingMarker = await getControlAdapter().readMarker(driver, APP_SPACE_ID);
+      const existingMarker = await controlAdapter.readMarker(driver, APP_SPACE_ID);
 
       let markerCreated = false;
       let markerUpdated = false;
       let previousHashes: { storageHash?: string; profileHash?: string } | undefined;
 
       if (!existingMarker) {
-        const write = writeContractMarker({
-          space: APP_SPACE_ID,
+        await controlAdapter.insertMarker(driver, APP_SPACE_ID, {
           storageHash: contractStorageHash,
           profileHash: contractProfileHash,
-          contractJson: contractInput,
-          canonicalVersion: 1,
         });
-        await driver.query(write.insert.sql, write.insert.params);
         markerCreated = true;
       } else {
         const existingStorageHash = existingMarker.storageHash;
@@ -592,14 +619,18 @@ export function createSqlFamilyInstance<TTargetId extends string>(
             storageHash: existingStorageHash,
             profileHash: existingProfileHash,
           };
-          const write = writeContractMarker({
-            space: APP_SPACE_ID,
-            storageHash: contractStorageHash,
-            profileHash: contractProfileHash,
-            contractJson: contractInput,
-            canonicalVersion: existingMarker.canonicalVersion ?? 1,
-          });
-          await driver.query(write.update.sql, write.update.params);
+          const updated = await controlAdapter.updateMarker(
+            driver,
+            APP_SPACE_ID,
+            existingStorageHash,
+            {
+              storageHash: contractStorageHash,
+              profileHash: contractProfileHash,
+            },
+          );
+          if (!updated) {
+            throw new Error('CAS conflict: marker was modified by another process during sign');
+          }
           markerUpdated = true;
         }
       }
@@ -651,6 +682,54 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     }): Promise<ReadonlyMap<string, ContractMarkerRecord>> {
       return getControlAdapter().readAllMarkers(options.driver);
     },
+    async readLedger(options: {
+      readonly driver: ControlDriverInstance<'sql', string>;
+      readonly space?: string;
+    }): Promise<readonly LedgerEntryRecord[]> {
+      return getControlAdapter().readLedger(options.driver, options.space);
+    },
+    async initMarker(options: {
+      readonly driver: ControlDriverInstance<'sql', string>;
+      readonly space: string;
+      readonly destination: {
+        readonly storageHash: string;
+        readonly profileHash: string;
+        readonly invariants?: readonly string[];
+      };
+    }): Promise<void> {
+      return getControlAdapter().initMarker(options.driver, options.space, options.destination);
+    },
+    async updateMarker(options: {
+      readonly driver: ControlDriverInstance<'sql', string>;
+      readonly space: string;
+      readonly expectedFrom: string;
+      readonly destination: {
+        readonly storageHash: string;
+        readonly profileHash: string;
+        readonly invariants?: readonly string[];
+      };
+    }): Promise<boolean> {
+      return getControlAdapter().updateMarker(
+        options.driver,
+        options.space,
+        options.expectedFrom,
+        options.destination,
+      );
+    },
+    async writeLedgerEntry(options: {
+      readonly driver: ControlDriverInstance<'sql', string>;
+      readonly space: string;
+      readonly entry: {
+        readonly edgeId: string;
+        readonly from: string;
+        readonly to: string;
+        readonly migrationName: string;
+        readonly migrationHash: string;
+        readonly operations: readonly unknown[];
+      };
+    }): Promise<void> {
+      return getControlAdapter().writeLedgerEntry(options.driver, options.space, options.entry);
+    },
     async introspect(options: {
       readonly driver: ControlDriverInstance<'sql', string>;
       readonly contract?: unknown;
@@ -662,10 +741,18 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       return sqlSchemaIrToPslAst(schemaIR);
     },
 
-    lowerAst(ast: AnyQueryAst, context: LowererContext<unknown>): LoweredStatement {
+    lowerAst(ast: AnyQueryAst | DdlNode, context: LowererContext<unknown>): LoweredStatement {
       return getControlAdapter().lower(ast, context);
     },
 
+    bootstrapControlTableQueries(): readonly DdlNode[] {
+      return getControlAdapter().bootstrapControlTableQueries();
+    },
+
+    bootstrapSignMarkerQueries(): readonly DdlNode[] {
+      return getControlAdapter().bootstrapSignMarkerQueries();
+    },
+
     toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview {
       return sqlOperationsToPreview(operations);
     },

package/src/core/default-namespace.ts

@@ -0,0 +1,9 @@
+export {
+  type ResolvedDomainModel,
+  resolveDomainModel,
+  UNBOUND_DOMAIN_NAMESPACE_ID,
+} from '@prisma-next/contract/types';
+export {
+  type ResolvedStorageTable,
+  resolveStorageTable,
+} from '@prisma-next/sql-contract/resolve-storage-table';

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/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

@@ -22,6 +22,7 @@ import type {
   SchemaIssue,
   SchemaVerifier,
 } from '@prisma-next/framework-components/control';
+import type { AggregateMigrationEdgeRef } from '@prisma-next/migration-tools/aggregate';
 import type {
   SqlStorage,
   StorageColumn,
@@ -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>>;
@@ -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;
@@ -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'