@prisma-next/family-sql 0.12.0-dev.5 → 0.12.0-dev.51

package/src/core/control-instance.ts

@@ -1,10 +1,13 @@
-import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import type {
+  Contract,
+  ContractMarkerRecord,
+  LedgerEntryRecord,
+} from '@prisma-next/contract/types';
 import type {
   TargetBoundComponentDescriptor,
   TargetDescriptor,
 } from '@prisma-next/framework-components/components';
 import type {
-  ControlDriverInstance,
   ControlFamilyInstance,
   ControlStack,
   CoreSchemaView,
@@ -28,17 +31,13 @@ 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 { sqlContractCanonicalizationHooks } from '@prisma-next/sql-contract/canonicalization-hooks';
-import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import type { SqlControlDriverInstance, 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';
@@ -69,10 +68,10 @@ function extractCodecTypeIdsFromContract(contract: unknown): readonly string[] {
   ) {
     const namespaces = contract.storage.namespaces as Record<
       string,
-      { readonly tables?: Readonly<Record<string, unknown>> }
+      { readonly entries: { readonly table: Readonly<Record<string, unknown>> } }
     >;
     for (const ns of Object.values(namespaces)) {
-      const tbls = ns.tables;
+      const tbls = ns.entries.table;
       if (typeof tbls !== 'object' || tbls === null) continue;
       for (const table of Object.values(tbls)) {
         if (
@@ -203,7 +202,7 @@ export interface SqlControlFamilyInstance
   deserializeContract(contractJson: unknown): Contract;
 
   verify(options: {
-    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly driver: SqlControlDriverInstance<string>;
     readonly contract: unknown;
     readonly expectedTargetId: string;
     readonly contractPath: string;
@@ -228,43 +227,77 @@ export interface SqlControlFamilyInstance
   }): VerifyDatabaseSchemaResult;
 
   sign(options: {
-    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly driver: SqlControlDriverInstance<string>;
     readonly contract: unknown;
     readonly contractPath: string;
     readonly configPath?: string;
   }): Promise<SignDatabaseResult>;
 
   introspect(options: {
-    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly driver: SqlControlDriverInstance<string>;
     readonly contract?: unknown;
   }): Promise<SqlSchemaIR>;
 
   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: SqlControlDriverInstance<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: SqlControlDriverInstance<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: SqlControlDriverInstance<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 +394,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 `SqlControlDriverInstance<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 {
@@ -396,7 +421,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     },
 
     async verify(verifyOptions: {
-      readonly driver: ControlDriverInstance<'sql', string>;
+      readonly driver: SqlControlDriverInstance<string>;
       readonly contract: unknown;
       readonly expectedTargetId: string;
       readonly contractPath: string;
@@ -544,7 +569,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       });
     },
     async sign(options: {
-      readonly driver: ControlDriverInstance<'sql', string>;
+      readonly driver: SqlControlDriverInstance<string>;
       readonly contract: unknown;
       readonly contractPath: string;
       readonly configPath?: string;
@@ -561,24 +586,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 +617,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;
         }
       }
@@ -641,18 +670,66 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       };
     },
     async readMarker(options: {
-      readonly driver: ControlDriverInstance<'sql', string>;
+      readonly driver: SqlControlDriverInstance<string>;
       readonly space: string;
     }): Promise<ContractMarkerRecord | null> {
       return getControlAdapter().readMarker(options.driver, options.space);
     },
     async readAllMarkers(options: {
-      readonly driver: ControlDriverInstance<'sql', string>;
+      readonly driver: SqlControlDriverInstance<string>;
     }): Promise<ReadonlyMap<string, ContractMarkerRecord>> {
       return getControlAdapter().readAllMarkers(options.driver);
     },
+    async readLedger(options: {
+      readonly driver: SqlControlDriverInstance<string>;
+      readonly space?: string;
+    }): Promise<readonly LedgerEntryRecord[]> {
+      return getControlAdapter().readLedger(options.driver, options.space);
+    },
+    async initMarker(options: {
+      readonly driver: SqlControlDriverInstance<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: SqlControlDriverInstance<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: SqlControlDriverInstance<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 driver: SqlControlDriverInstance<string>;
       readonly contract?: unknown;
     }): Promise<SqlSchemaIR> {
       return getControlAdapter().introspect(options.driver, options.contract);
@@ -662,10 +739,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/ir/sql-contract-serializer-base.ts

@@ -29,16 +29,16 @@ import { type Type, type } from 'arktype';
 const NamespaceRawSchema = type({
   id: 'string',
   'kind?': 'string',
-  // Undeclared keys (`tables`, `enum`, and any pack-contributed slot maps)
-  // intentionally pass through; the slot loop below iterates them by name.
-  '+': 'ignore',
+  entries: type({
+    '+': 'ignore',
+  }),
 });
 
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-export type SqlEntityHydrationFactory = (entry: unknown) => SqlStorageTypeEntry;
+export type SqlEntityHydrationFactory = (entry: unknown) => unknown;
 
 /**
  * SQL family `ContractSerializer` abstract base. Carries the SQL-shared
@@ -70,7 +70,10 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
   private readonly contractSchema: Type<unknown> | undefined;
 
   constructor(
-    private readonly entityTypeRegistry: ReadonlyMap<string, SqlEntityHydrationFactory> = new Map(),
+    protected readonly entityTypeRegistry: ReadonlyMap<
+      string,
+      SqlEntityHydrationFactory
+    > = new Map(),
     validatorFragments?: ReadonlyMap<string, Type<unknown>>,
   ) {
     // Only build a fragments-aware contract schema when pack contributions
@@ -158,7 +161,12 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
         const namespaceMaterialised =
           namespaceHydrated instanceof NamespaceBase
             ? namespaceHydrated
-            : buildSqlNamespace(namespaceHydrated);
+            : buildSqlNamespace(
+                blindCast<
+                  SqlNamespaceTablesInput,
+                  'hydrateSqlNamespaceEntry returns SqlNamespaceTablesInput when raw is not a NamespaceBase'
+                >(namespaceHydrated),
+              );
         return [nsId, namespaceMaterialised];
       }),
     );
@@ -172,69 +180,43 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
       return raw;
     }
     const rawRecord = isPlainRecord(raw) ? raw : {};
+    if (
+      Object.hasOwn(rawRecord, 'tables') ||
+      Object.hasOwn(rawRecord, 'enum') ||
+      Object.hasOwn(rawRecord, 'collections')
+    ) {
+      throw new ContractValidationError(
+        'Namespace envelope uses deprecated flat slot keys; expected `entries: { table? }`',
+        'structural',
+      );
+    }
     const id = typeof rawRecord['id'] === 'string' ? rawRecord['id'] : nsId;
     const parsed = NamespaceRawSchema({ ...rawRecord, id });
     if (parsed instanceof type.errors) {
       const messages = parsed.map((p: { message: string }) => p.message).join('; ');
       throw new ContractValidationError(`Namespace hydration failed: ${messages}`, 'structural');
     }
-    const result: Record<string, unknown> = { id };
-
-    for (const [propertyKey, slotValue] of Object.entries(parsed)) {
-      if (propertyKey === 'id') continue;
-      if (slotValue === null || typeof slotValue !== 'object') continue;
-
-      if (propertyKey === 'tables') {
-        result['tables'] = Object.fromEntries(
-          Object.entries(slotValue as Record<string, unknown>).map(([tableName, table]) => [
+    // Default to empty table; overwritten below if raw entries carry a table slot.
+    const entriesInput: { table: Record<string, StorageTable> } = { table: {} };
+    const entriesRaw = parsed.entries;
+    if (entriesRaw !== undefined && typeof entriesRaw === 'object' && entriesRaw !== null) {
+      const tableSlot = (entriesRaw as Record<string, unknown>)['table'];
+      if (tableSlot !== null && typeof tableSlot === 'object' && !Array.isArray(tableSlot)) {
+        entriesInput.table = Object.fromEntries(
+          Object.entries(tableSlot as Record<string, unknown>).map(([tableName, table]) => [
             tableName,
             table instanceof StorageTable ? table : new StorageTable(table as StorageTableInput),
           ]),
         );
-        continue;
-      }
-
-      const hydratedSlot = Object.fromEntries(
-        Object.entries(slotValue as Record<string, unknown>).map(([entryName, entry]) => {
-          if (typeof entry !== 'object' || entry === null) {
-            return [entryName, entry];
-          }
-          const kind = (entry as { kind?: unknown }).kind;
-          if (typeof kind === 'string') {
-            const factory = this.entityTypeRegistry.get(kind);
-            if (factory !== undefined) {
-              return [entryName, factory(entry)];
-            }
-          }
-          return [entryName, entry];
-        }),
-      );
-      if (Object.keys(hydratedSlot).length > 0) {
-        result[propertyKey] = hydratedSlot;
-      }
-    }
-
-    const enumRaw = rawRecord['enum'];
-    if (enumRaw !== undefined && typeof enumRaw === 'object' && enumRaw !== null) {
-      for (const entry of Object.values(enumRaw as Record<string, unknown>)) {
-        if (typeof entry !== 'object' || entry === null) continue;
-        const kind = (entry as { kind?: unknown }).kind;
-        if (typeof kind === 'string' && this.entityTypeRegistry.get(kind) === undefined) {
-          throw new ContractValidationError(
-            `Entry kind '${kind}' has no registered hydration factory.`,
-            'structural',
-          );
-        }
       }
+      // Target-specific slots (e.g. postgres `type`) are left for target
+      // overrides to extract from the original `raw` parameter.
     }
 
-    const tables = (result['tables'] ?? {}) as Record<string, StorageTable>;
-    const enumSlot = result['enum'] as NonNullable<SqlNamespaceTablesInput['enum']> | undefined;
-    return {
-      ...result,
-      tables,
-      ...(enumSlot !== undefined ? { enum: enumSlot } : {}),
-    } as SqlNamespaceTablesInput;
+    return blindCast<SqlNamespaceTablesInput, 'hydrated namespace tables input'>({
+      id,
+      entries: entriesInput,
+    });
   }
 
   protected hydrateStorageTypeEntry(entry: SqlStorageTypeEntry): SqlStorageTypeEntry {
@@ -249,7 +231,10 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
     if (factory === undefined) {
       return entry;
     }
-    return factory(entry);
+    return blindCast<
+      SqlStorageTypeEntry,
+      'entity registry factory returns SqlStorageTypeEntry for storage.types entries'
+    >(factory(entry));
   }
 
   protected constructTargetContract(hydrated: Contract<SqlStorage>): TContract {

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

@@ -24,6 +24,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';
 
 /**
@@ -250,11 +251,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 +328,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;
@@ -395,7 +399,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 +419,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;