@prisma-next/family-sql 0.5.0-dev.9 → 0.5.0

package/src/core/control-instance.ts

@@ -9,19 +9,26 @@ import type {
   ControlFamilyInstance,
   ControlStack,
   CoreSchemaView,
+  MigrationPlanOperation,
   OperationContext,
+  OperationPreview,
+  OperationPreviewCapable,
+  PslContractInferCapable,
   SchemaViewCapable,
   SignDatabaseResult,
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
 import {
+  APP_SPACE_ID,
   SchemaTreeNode,
   VERIFY_CODE_HASH_MISMATCH,
   VERIFY_CODE_MARKER_MISSING,
   VERIFY_CODE_TARGET_MISMATCH,
 } from '@prisma-next/framework-components/control';
 import type { TypesImportSpec } from '@prisma-next/framework-components/emission';
+import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
+import { assertDescriptorSelfConsistency } from '@prisma-next/migration-tools/spaces';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { validateContract as sqlValidateContract } from '@prisma-next/sql-contract/validate';
 import {
@@ -37,8 +44,10 @@ import type {
   SqlControlAdapterDescriptor,
   SqlControlExtensionDescriptor,
 } from './migrations/types';
+import { sqlOperationsToPreview } from './operation-preview';
+import { sqlSchemaIrToPslAst } from './psl-contract-infer/sql-schema-ir-to-psl-ast';
 import { verifySqlSchema } from './schema-verify/verify-sql-schema';
-import { collectSupportedCodecTypeIds, readMarker } from './verify';
+import { collectSupportedCodecTypeIds } from './verify';
 
 function extractCodecTypeIdsFromContract(contract: unknown): readonly string[] {
   const typeIds = new Set<string>();
@@ -162,7 +171,6 @@ type SqlTypeMetadataRegistry = Map<string, SqlTypeMetadata>;
 
 interface SqlFamilyInstanceState {
   readonly codecTypeImports: ReadonlyArray<TypesImportSpec>;
-  readonly operationTypeImports: ReadonlyArray<TypesImportSpec>;
   readonly extensionIds: ReadonlyArray<string>;
   readonly typeMetadataRegistry: SqlTypeMetadataRegistry;
 }
@@ -182,6 +190,8 @@ export interface SchemaVerifyOptions {
 export interface SqlControlFamilyInstance
   extends ControlFamilyInstance<'sql', SqlSchemaIR>,
     SchemaViewCapable<SqlSchemaIR>,
+    PslContractInferCapable<SqlSchemaIR>,
+    OperationPreviewCapable,
     SqlFamilyInstanceState {
   validateContract(contractJson: unknown): Contract;
 
@@ -195,6 +205,22 @@ export interface SqlControlFamilyInstance
 
   schemaVerify(options: SchemaVerifyOptions): Promise<VerifyDatabaseSchemaResult>;
 
+  /**
+   * Verify a contract against an already-introspected schema slice.
+   *
+   * Used by the aggregate verifier to invoke per-member verification
+   * with the live schema pre-projected to the member's claimed slice
+   * via `projectSchemaToSpace`. Closes F23 — without per-member
+   * pre-projection, single-contract verifiers see other-space tables
+   * as `extras`.
+   */
+  schemaVerifyAgainstSchema(options: {
+    readonly contract: unknown;
+    readonly schema: SqlSchemaIR;
+    readonly strict: boolean;
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+  }): VerifyDatabaseSchemaResult;
+
   sign(options: {
     readonly driver: ControlDriverInstance<'sql', string>;
     readonly contract: unknown;
@@ -206,6 +232,10 @@ export interface SqlControlFamilyInstance
     readonly driver: ControlDriverInstance<'sql', string>;
     readonly contract?: unknown;
   }): Promise<SqlSchemaIR>;
+
+  inferPslContract(schemaIR: SqlSchemaIR): PslDocumentAst;
+
+  toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview;
 }
 
 export type SqlFamilyInstance = SqlControlFamilyInstance;
@@ -217,7 +247,11 @@ function isSqlControlAdapter<TTargetId extends string>(
     typeof value === 'object' &&
     value !== null &&
     'introspect' in value &&
-    typeof (value as { introspect: unknown }).introspect === 'function'
+    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'
   );
 }
 
@@ -285,7 +319,30 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     stack.extensionPacks as unknown as readonly (SqlControlExtensionDescriptor<TTargetId> &
       DescriptorWithStorageTypes)[];
 
-  const { codecTypeImports, operationTypeImports, extensionIds } = stack;
+  // Descriptor self-consistency check.
+  // Each extension that exposes a `contractSpace` must publish a
+  // `headRef.hash` that matches the canonical hash recomputed from its
+  // `contractJson`. A stale value would silently corrupt every downstream
+  // boundary that trusts `headRef.hash` as the canonical identity (drift
+  // detection, on-disk artefact emission, runner marker writes). Failing
+  // fast at descriptor-load time turns "extension author shipped an
+  // inconsistent descriptor" into an explicit, actionable error
+  // (`MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH`) rather than a confusing
+  // mismatch surfacing several layers downstream.
+  for (const extension of extensions) {
+    if (extension.contractSpace) {
+      const { contractJson, headRef } = extension.contractSpace;
+      assertDescriptorSelfConsistency({
+        extensionId: extension.id,
+        target: contractJson.target,
+        targetFamily: contractJson.targetFamily,
+        storage: contractJson.storage,
+        headRefHash: headRef.hash,
+      });
+    }
+  }
+
+  const { codecTypeImports, extensionIds } = stack;
 
   const typeMetadataRegistry = buildSqlTypeMetadataRegistry({
     target,
@@ -293,10 +350,23 @@ 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;
+  };
+
   return {
     familyId: 'sql',
     codecTypeImports,
-    operationTypeImports,
     extensionIds,
     typeMetadataRegistry,
 
@@ -326,7 +396,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       const contractProfileHash = contract.profileHash;
       const contractTarget = contract.target;
 
-      const marker = await readMarker(driver);
+      const marker = await getControlAdapter().readMarker(driver, APP_SPACE_ID);
 
       let missingCodecs: readonly string[] | undefined;
       let codecCoverageSkipped = false;
@@ -435,10 +505,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
 
       const contract = sqlValidateContract<Contract<SqlStorage>>(contractInput, emptyCodecLookup);
 
-      const controlAdapter = adapter.create(stack);
-      if (!isSqlControlAdapter(controlAdapter)) {
-        throw new Error('Adapter does not implement SqlControlAdapter.introspect()');
-      }
+      const controlAdapter = getControlAdapter();
       const schemaIR = await controlAdapter.introspect(driver, contractInput);
 
       return verifySqlSchema({
@@ -453,6 +520,27 @@ export function createSqlFamilyInstance<TTargetId extends string>(
         ...ifDefined('normalizeNativeType', controlAdapter.normalizeNativeType),
       });
     },
+    schemaVerifyAgainstSchema(options: {
+      readonly contract: unknown;
+      readonly schema: SqlSchemaIR;
+      readonly strict: boolean;
+      readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+    }): VerifyDatabaseSchemaResult {
+      const contract = sqlValidateContract<Contract<SqlStorage>>(
+        options.contract,
+        emptyCodecLookup,
+      );
+      const controlAdapter = getControlAdapter();
+      return verifySqlSchema({
+        contract,
+        schema: options.schema,
+        strict: options.strict,
+        typeMetadataRegistry,
+        frameworkComponents: options.frameworkComponents,
+        ...ifDefined('normalizeDefault', controlAdapter.normalizeDefault),
+        ...ifDefined('normalizeNativeType', controlAdapter.normalizeNativeType),
+      });
+    },
     async sign(options: {
       readonly driver: ControlDriverInstance<'sql', string>;
       readonly contract: unknown;
@@ -474,7 +562,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       await driver.query(ensureSchemaStatement.sql, ensureSchemaStatement.params);
       await driver.query(ensureTableStatement.sql, ensureTableStatement.params);
 
-      const existingMarker = await readMarker(driver);
+      const existingMarker = await getControlAdapter().readMarker(driver, APP_SPACE_ID);
 
       let markerCreated = false;
       let markerUpdated = false;
@@ -482,6 +570,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
 
       if (!existingMarker) {
         const write = writeContractMarker({
+          space: APP_SPACE_ID,
           storageHash: contractStorageHash,
           profileHash: contractProfileHash,
           contractJson: contractInput,
@@ -502,6 +591,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
             profileHash: existingProfileHash,
           };
           const write = writeContractMarker({
+            space: APP_SPACE_ID,
             storageHash: contractStorageHash,
             profileHash: contractProfileHash,
             contractJson: contractInput,
@@ -550,20 +640,28 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     },
     async readMarker(options: {
       readonly driver: ControlDriverInstance<'sql', string>;
+      readonly space: string;
     }): Promise<ContractMarkerRecord | null> {
-      return readMarker(options.driver);
+      return getControlAdapter().readMarker(options.driver, options.space);
+    },
+    async readAllMarkers(options: {
+      readonly driver: ControlDriverInstance<'sql', string>;
+    }): Promise<ReadonlyMap<string, ContractMarkerRecord>> {
+      return getControlAdapter().readAllMarkers(options.driver);
     },
     async introspect(options: {
       readonly driver: ControlDriverInstance<'sql', string>;
       readonly contract?: unknown;
     }): Promise<SqlSchemaIR> {
-      const { driver, contract } = options;
+      return getControlAdapter().introspect(options.driver, options.contract);
+    },
 
-      const controlAdapter = adapter.create(stack);
-      if (!isSqlControlAdapter(controlAdapter)) {
-        throw new Error('Adapter does not implement SqlControlAdapter.introspect()');
-      }
-      return controlAdapter.introspect(driver, contract);
+    inferPslContract(schemaIR: SqlSchemaIR): PslDocumentAst {
+      return sqlSchemaIrToPslAst(schemaIR);
+    },
+
+    toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview {
+      return sqlOperationsToPreview(operations);
     },
 
     toSchemaView(schema: SqlSchemaIR): CoreSchemaView {

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

@@ -0,0 +1,192 @@
+/**
+ * Codec lifecycle hook planner — runs `onFieldEvent` for every per-field
+ * delta between two contracts and concatenates the returned ops in a
+ * deterministic order.
+ *
+ * Wired by each target's planner (`PostgresMigrationPlanner`,
+ * `SqliteMigrationPlanner`) so codec-emitted ops are inlined alongside
+ * structural DDL in the app-space migration's `ops.json`. Pure, target-
+ * agnostic, and only ever invoked at the app-space emitter; extension-space
+ * planning never reaches this helper.
+ *
+ * Ordering rules:
+ *
+ * - Events are grouped by phase: `'added'` → `'dropped'` → `'altered'`.
+ * - Within each phase, entries are sorted alphabetically by
+ *   `(tableName, fieldName)`.
+ * - The hook's returned ops are appended in the order the hook returned them.
+ *
+ * `'altered'` is suppressed when only `codecId` differs (codec rotation is a
+ * v1 non-goal).
+ */
+
+import type { Contract } from '@prisma-next/contract/types';
+import type { OpFactoryCall } from '@prisma-next/framework-components/control';
+import type { SqlStorage, StorageColumn, StorageTable } from '@prisma-next/sql-contract/types';
+import type { CodecControlHooks, FieldEvent, FieldEventContext } from './types';
+
+export interface PlanFieldEventOperationsOptions {
+  /**
+   * Prior contract the planner is diffing against. `null` for first emits
+   * (every field is treated as added).
+   */
+  readonly priorContract: Contract<SqlStorage> | null;
+  /**
+   * New contract the user just authored.
+   */
+  readonly newContract: Contract<SqlStorage>;
+  /**
+   * Codec-id keyed map of control hooks, as produced by
+   * {@link import('./assembly').extractCodecControlHooks}. Hooks carry
+   * `unknown` target details after extraction; the caller casts the
+   * helper's returned ops to its target's `SqlMigrationPlanOperation`
+   * specialisation at the integration boundary, mirroring how
+   * `storageTypePlanCallStrategy` lifts `planTypeOperations` results into
+   * `RawSqlCall`.
+   */
+  readonly codecHooks: ReadonlyMap<string, CodecControlHooks>;
+}
+
+interface FieldEntry {
+  readonly tableName: string;
+  readonly fieldName: string;
+  readonly priorTable: StorageTable | undefined;
+  readonly newTable: StorageTable | undefined;
+  readonly priorField: StorageColumn | undefined;
+  readonly newField: StorageColumn | undefined;
+}
+
+export function planFieldEventOperations(
+  options: PlanFieldEventOperationsOptions,
+): readonly OpFactoryCall[] {
+  const priorTables = options.priorContract?.storage.tables ?? {};
+  const newTables = options.newContract.storage.tables;
+
+  const added: FieldEntry[] = [];
+  const dropped: FieldEntry[] = [];
+  const altered: FieldEntry[] = [];
+
+  const tableNames = unionSorted(Object.keys(priorTables), Object.keys(newTables));
+  for (const tableName of tableNames) {
+    const priorTable = priorTables[tableName];
+    const newTable = newTables[tableName];
+    const fieldNames = unionSorted(
+      priorTable ? Object.keys(priorTable.columns) : [],
+      newTable ? Object.keys(newTable.columns) : [],
+    );
+    for (const fieldName of fieldNames) {
+      const priorField = priorTable?.columns[fieldName];
+      const newField = newTable?.columns[fieldName];
+      const entry: FieldEntry = {
+        tableName,
+        fieldName,
+        priorTable,
+        newTable,
+        priorField,
+        newField,
+      };
+      if (priorField === undefined && newField !== undefined) {
+        added.push(entry);
+      } else if (priorField !== undefined && newField === undefined) {
+        dropped.push(entry);
+      } else if (priorField !== undefined && newField !== undefined) {
+        if (isAlteration(priorField, newField)) altered.push(entry);
+      }
+    }
+  }
+
+  const calls: OpFactoryCall[] = [];
+  appendCalls('added', added, options.codecHooks, calls, (e) => e.newField?.codecId);
+  appendCalls('dropped', dropped, options.codecHooks, calls, (e) => e.priorField?.codecId);
+  appendCalls('altered', altered, options.codecHooks, calls, (e) => e.newField?.codecId);
+  return calls;
+}
+
+function appendCalls(
+  event: FieldEvent,
+  entries: readonly FieldEntry[],
+  codecHooks: ReadonlyMap<string, CodecControlHooks>,
+  calls: OpFactoryCall[],
+  pickCodecId: (entry: FieldEntry) => string | undefined,
+): void {
+  for (const entry of entries) {
+    const codecId = pickCodecId(entry);
+    if (codecId === undefined) continue;
+    const hook = codecHooks.get(codecId);
+    if (!hook?.onFieldEvent) continue;
+    const ctx = buildContext(event, entry);
+    const emitted = hook.onFieldEvent(event, ctx);
+    for (const call of emitted) calls.push(call);
+  }
+}
+
+/**
+ * The context's prior/new sides are scoped to the event:
+ *
+ * - `'added'`   — only `newTable` / `newField` populated.
+ * - `'dropped'` — only `priorTable` / `priorField` populated.
+ * - `'altered'` — both sides populated.
+ */
+function buildContext(event: FieldEvent, entry: FieldEntry): FieldEventContext {
+  const base = { tableName: entry.tableName, fieldName: entry.fieldName };
+  if (event === 'added') {
+    return {
+      ...base,
+      ...(entry.newTable !== undefined ? { newTable: entry.newTable } : {}),
+      ...(entry.newField !== undefined ? { newField: entry.newField } : {}),
+    };
+  }
+  if (event === 'dropped') {
+    return {
+      ...base,
+      ...(entry.priorTable !== undefined ? { priorTable: entry.priorTable } : {}),
+      ...(entry.priorField !== undefined ? { priorField: entry.priorField } : {}),
+    };
+  }
+  return {
+    ...base,
+    ...(entry.priorTable !== undefined ? { priorTable: entry.priorTable } : {}),
+    ...(entry.newTable !== undefined ? { newTable: entry.newTable } : {}),
+    ...(entry.priorField !== undefined ? { priorField: entry.priorField } : {}),
+    ...(entry.newField !== undefined ? { newField: entry.newField } : {}),
+  };
+}
+
+/**
+ * `'altered'` predicate. Returns `false` whenever `codecId` differs —
+ * any codec change suppresses the `altered` event entirely, including
+ * cases where another property also differs in the same diff. Codec
+ * rotation is a v1 non-goal (project spec § Non-goals); avoiding the
+ * mixed event keeps the migration semantics for codec changes explicit
+ * (out of scope) rather than smuggling them through as `altered`.
+ *
+ * For non-`codecId` diffs, returns `true` iff any other column property
+ * differs.
+ */
+function isAlteration(prior: StorageColumn, current: StorageColumn): boolean {
+  if (prior.codecId !== current.codecId) return false;
+  return !sameStorageColumn(prior, current);
+}
+
+function sameStorageColumn(a: StorageColumn, b: StorageColumn): boolean {
+  if (a === b) return true;
+  if (a.nativeType !== b.nativeType) return false;
+  if (a.nullable !== b.nullable) return false;
+  if (a.typeRef !== b.typeRef) return false;
+  if (!sameJson(a.typeParams, b.typeParams)) return false;
+  if (!sameJson(a.default, b.default)) return false;
+  return true;
+}
+
+function sameJson(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === undefined || b === undefined) return false;
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function unionSorted(a: readonly string[], b: readonly string[]): readonly string[] {
+  const set = new Set<string>();
+  for (const name of a) set.add(name);
+  for (const name of b) set.add(name);
+  return [...set].sort((x, y) => (x < y ? -1 : x > y ? 1 : 0));
+}

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

@@ -35,6 +35,7 @@ function freezeSteps(
       Object.freeze({
         description: step.description,
         sql: step.sql,
+        ...(step.params ? { params: Object.freeze([...step.params]) } : {}),
         ...(step.meta ? { meta: cloneRecord(step.meta) } : {}),
       }),
     ),
@@ -74,6 +75,7 @@ function freezeOperation<TTargetDetails>(
     label: operation.label,
     ...(operation.summary ? { summary: operation.summary } : {}),
     operationClass: operation.operationClass,
+    ...(operation.invariantId ? { invariantId: operation.invariantId } : {}),
     target: freezeTargetDetails(operation.target),
     precheck: freezeSteps(operation.precheck),
     execute: freezeSteps(operation.execute),
@@ -96,11 +98,13 @@ export function createMigrationPlan<TTargetDetails>(
 ): SqlMigrationPlan<TTargetDetails> {
   return Object.freeze({
     targetId: options.targetId,
+    spaceId: options.spaceId,
     ...(options.origin !== undefined
       ? { origin: options.origin ? Object.freeze({ ...options.origin }) : null }
       : {}),
     destination: Object.freeze({ ...options.destination }),
     operations: freezeOperations(options.operations),
+    providedInvariants: Object.freeze([...options.providedInvariants]),
     ...(options.meta ? { meta: cloneRecord(options.meta) } : {}),
   });
 }