@prisma-next/framework-components 0.12.0 → 0.13.0-dev.1

package/src/control/control-migration-types.ts

@@ -13,7 +13,11 @@ import type { Contract } from '@prisma-next/contract/types';
 import type { ImportRequirement } from '@prisma-next/ts-render';
 import type { Result } from '@prisma-next/utils/result';
 import type { TargetBoundComponentDescriptor } from '../shared/framework-components';
-import type { ControlDriverInstance, ControlFamilyInstance } from './control-instances';
+import type {
+  ControlAdapterInstance,
+  ControlDriverInstance,
+  ControlFamilyInstance,
+} from './control-instances';
 import type { OperationContext } from './control-result-types';
 
 // ============================================================================
@@ -279,6 +283,7 @@ export interface MigrationPlannerConflict {
 export interface MigrationPlannerSuccessResult {
   readonly kind: 'success';
   readonly plan: MigrationPlanWithAuthoringSurface;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }
 
 /**
@@ -479,6 +484,17 @@ export interface MigrationRunnerPerSpaceOptions<
    * Paths and metadata forwarded to schema verification diagnostics.
    */
   readonly context?: OperationContext;
+  /**
+   * Per-edge breakdown from aggregate planning. Runners write one ledger row
+   * per edge in walk order.
+   */
+  readonly migrationEdges: ReadonlyArray<{
+    readonly migrationHash: string;
+    readonly dirName: string;
+    readonly from: string;
+    readonly to: string;
+    readonly operationCount: number;
+  }>;
 }
 
 export interface MigrationRunner<
@@ -525,7 +541,9 @@ export interface TargetMigrationsCapability<
     unknown
   >,
 > {
-  createPlanner(family: TFamilyInstance): MigrationPlanner<TFamilyId, TTargetId>;
+  createPlanner(
+    adapter: ControlAdapterInstance<TFamilyId, TTargetId>,
+  ): MigrationPlanner<TFamilyId, TTargetId>;
   createRunner(family: TFamilyInstance): MigrationRunner<TFamilyId, TTargetId>;
   /**
    * Synthesizes a family-specific schema IR from a contract for offline planning.

package/src/control/control-result-types.ts

@@ -58,7 +58,10 @@ export interface BaseSchemaIssue {
     | 'index_mismatch'
     | 'default_missing'
     | 'default_mismatch'
-    | 'extra_default';
+    | 'extra_default'
+    | 'check_missing'
+    | 'check_removed'
+    | 'check_mismatch';
   readonly table?: string;
   /**
    * Namespace coordinate of the issue's subject (e.g. the schema a SQL

package/src/control/control-stack.ts

@@ -1,15 +1,18 @@
+import { blindCast } from '@prisma-next/utils/casts';
 import type { Codec } from '../shared/codec';
 import type { CodecLookup, CodecMeta } from '../shared/codec-types';
 import type {
   AuthoringContributions,
   AuthoringEntityTypeNamespace,
   AuthoringFieldNamespace,
+  AuthoringPslBlockDescriptorNamespace,
   AuthoringTypeNamespace,
 } from '../shared/framework-authoring';
 import {
   assertNoCrossRegistryCollisions,
   isAuthoringEntityTypeDescriptor,
   isAuthoringFieldPresetDescriptor,
+  isAuthoringPslBlockDescriptor,
   isAuthoringTypeConstructorDescriptor,
   mergeAuthoringNamespaces,
 } from '../shared/framework-authoring';
@@ -32,6 +35,7 @@ export interface AssembledAuthoringContributions {
   readonly field: AuthoringFieldNamespace;
   readonly type: AuthoringTypeNamespace;
   readonly entityTypes: AuthoringEntityTypeNamespace;
+  readonly pslBlockDescriptors: AuthoringPslBlockDescriptorNamespace;
 }
 
 export interface ControlStack<
@@ -151,6 +155,7 @@ export function assembleAuthoringContributions(
   const field = {} as Record<string, unknown>;
   const type = {} as Record<string, unknown>;
   const entityTypes = {} as Record<string, unknown>;
+  const pslBlockDescriptors: Record<string, unknown> = {};
 
   for (const descriptor of descriptors) {
     if (descriptor.authoring?.field) {
@@ -180,17 +185,36 @@ export function assembleAuthoringContributions(
         'entity',
       );
     }
+    if (descriptor.authoring?.pslBlockDescriptors) {
+      mergeAuthoringNamespaces(
+        pslBlockDescriptors,
+        descriptor.authoring.pslBlockDescriptors,
+        [],
+        isAuthoringPslBlockDescriptor,
+        'pslBlock',
+      );
+    }
   }
 
   const fieldNamespace = field as AuthoringFieldNamespace;
   const typeNamespace = type as AuthoringTypeNamespace;
   const entityTypeNamespace = entityTypes as AuthoringEntityTypeNamespace;
-  assertNoCrossRegistryCollisions(typeNamespace, fieldNamespace, entityTypeNamespace);
+  const pslBlockDescriptorNamespace = blindCast<
+    AuthoringPslBlockDescriptorNamespace,
+    'merge target accumulator narrows to typed namespace post-merge'
+  >(pslBlockDescriptors);
+  assertNoCrossRegistryCollisions(
+    typeNamespace,
+    fieldNamespace,
+    entityTypeNamespace,
+    pslBlockDescriptorNamespace,
+  );
 
   return {
     field: fieldNamespace,
     type: typeNamespace,
     entityTypes: entityTypeNamespace,
+    pslBlockDescriptors: pslBlockDescriptorNamespace,
   };
 }
 
@@ -345,12 +369,107 @@ export function validateScalarTypeCodecIds(
   return errors;
 }
 
+interface DependencyDeclaringDescriptor {
+  readonly id: string;
+  readonly contractSpace?: {
+    readonly contractJson?: {
+      readonly extensionPacks?: Readonly<Record<string, unknown>>;
+    };
+  };
+}
+
+function readDeclaredDependencyIds(descriptor: DependencyDeclaringDescriptor): readonly string[] {
+  const packs = descriptor.contractSpace?.contractJson?.extensionPacks;
+  if (packs === null || typeof packs !== 'object') return [];
+  return Object.keys(packs);
+}
+
+/**
+ * Builds a dependency-respecting load order for the given extension descriptors
+ * using Kahn's topological sort algorithm. Dependencies (packs declared in
+ * `contractSpace.contractJson.extensionPacks`) are placed before the extensions
+ * that depend on them.
+ *
+ * Throws if the dependency graph contains a cycle, with an error message that
+ * names every extension involved in the cycle.
+ *
+ * Throws if any extension declares a dependency on a pack ID that is not present
+ * in the provided list — add the missing pack to the `extensionPacks` list to
+ * resolve the error.
+ */
+
+export function buildExtensionLoadOrder(
+  extensions: ReadonlyArray<DependencyDeclaringDescriptor>,
+): readonly string[] {
+  if (extensions.length === 0) return [];
+
+  const idSet = new Set(extensions.map((e) => e.id));
+  const inDegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>();
+
+  for (const ext of extensions) {
+    if (!inDegree.has(ext.id)) inDegree.set(ext.id, 0);
+    if (!dependents.has(ext.id)) dependents.set(ext.id, []);
+  }
+
+  for (const ext of extensions) {
+    for (const depId of readDeclaredDependencyIds(ext)) {
+      if (!idSet.has(depId)) {
+        throw new Error(
+          `Extension "${ext.id}" declares a dependency on "${depId}", but "${depId}" is not in the provided extension set. Add the missing space to extensionPacks.`,
+        );
+      }
+      inDegree.set(ext.id, (inDegree.get(ext.id) ?? 0) + 1);
+      const list = dependents.get(depId);
+      if (list !== undefined) list.push(ext.id);
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [id, deg] of inDegree) {
+    if (deg === 0) queue.push(id);
+  }
+  queue.sort();
+
+  const result: string[] = [];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    if (id === undefined) break;
+    result.push(id);
+    const children = dependents.get(id) ?? [];
+    children.sort();
+    for (const childId of children) {
+      const newDeg = (inDegree.get(childId) ?? 1) - 1;
+      inDegree.set(childId, newDeg);
+      if (newDeg === 0) queue.push(childId);
+    }
+  }
+
+  if (result.length < extensions.length) {
+    const cycleMembers = extensions
+      .map((e) => e.id)
+      .filter((id) => !result.includes(id))
+      .sort();
+    throw new Error(
+      `Extension dependency cycle detected. Cycle members: ${cycleMembers.map((id) => `"${id}"`).join(', ')}.`,
+    );
+  }
+
+  return result;
+}
+
 export function createControlStack<TFamilyId extends string, TTargetId extends string>(
   input: CreateControlStackInput<TFamilyId, TTargetId>,
 ): ControlStack<TFamilyId, TTargetId> {
   const { family, target, adapter, driver, extensionPacks = [] } = input;
 
-  const allDescriptors = [family, target, ...(adapter ? [adapter] : []), ...extensionPacks];
+  const orderedIds = buildExtensionLoadOrder(extensionPacks);
+  const extensionById = new Map(extensionPacks.map((ext) => [ext.id, ext]));
+  const orderedExtensionPacks = orderedIds
+    .map((id) => extensionById.get(id))
+    .filter((ext): ext is ControlExtensionDescriptor<TFamilyId, TTargetId> => ext !== undefined);
+
+  const allDescriptors = [family, target, ...(adapter ? [adapter] : []), ...orderedExtensionPacks];
 
   const codecLookup = extractCodecLookup(allDescriptors);
   const scalarTypeDescriptors = assembleScalarTypeDescriptors(allDescriptors);
@@ -360,11 +479,11 @@ export function createControlStack<TFamilyId extends string, TTargetId extends s
     target,
     adapter,
     driver,
-    extensionPacks: extensionPacks as readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[],
+    extensionPacks: orderedExtensionPacks,
 
     codecTypeImports: extractCodecTypeImports(allDescriptors),
     queryOperationTypeImports: extractQueryOperationTypeImports(allDescriptors),
-    extensionIds: extractComponentIds(family, target, adapter, extensionPacks),
+    extensionIds: extractComponentIds(family, target, adapter, orderedExtensionPacks),
     codecLookup,
     authoringContributions: assembleAuthoringContributions(allDescriptors),
     scalarTypeDescriptors,

package/src/control/psl-ast.ts

@@ -1,28 +1,25 @@
-export interface PslPosition {
-  readonly offset: number;
-  readonly line: number;
-  readonly column: number;
-}
-
-export interface PslSpan {
-  readonly start: PslPosition;
-  readonly end: PslPosition;
-}
-
-export type PslDiagnosticCode =
-  | 'PSL_UNTERMINATED_BLOCK'
-  | 'PSL_UNSUPPORTED_TOP_LEVEL_BLOCK'
-  | 'PSL_INVALID_NAMESPACE_BLOCK'
-  | 'PSL_INVALID_ATTRIBUTE_SYNTAX'
-  | 'PSL_INVALID_MODEL_MEMBER'
-  | 'PSL_UNSUPPORTED_MODEL_ATTRIBUTE'
-  | 'PSL_UNSUPPORTED_FIELD_ATTRIBUTE'
-  | 'PSL_INVALID_RELATION_ATTRIBUTE'
-  | 'PSL_INVALID_REFERENTIAL_ACTION'
-  | 'PSL_INVALID_DEFAULT_VALUE'
-  | 'PSL_INVALID_ENUM_MEMBER'
-  | 'PSL_INVALID_TYPES_MEMBER'
-  | 'PSL_INVALID_QUALIFIED_TYPE';
+export type { AuthoringPslBlockDescriptorNamespace } from '../shared/framework-authoring';
+export type {
+  PslBlockParam,
+  PslBlockParamList,
+  PslBlockParamOption,
+  PslBlockParamRef,
+  PslBlockParamValue,
+  PslDiagnosticCode,
+  PslExtensionBlock,
+  PslExtensionBlockParamList,
+  PslExtensionBlockParamOption,
+  PslExtensionBlockParamRef,
+  PslExtensionBlockParamScalarValue,
+  PslExtensionBlockParamValue,
+  PslPosition,
+  PslSpan,
+} from '../shared/psl-extension-block';
+
+import { blindCast } from '@prisma-next/utils/casts';
+import type { CodecLookup } from '../shared/codec-types';
+import type { AuthoringPslBlockDescriptorNamespace } from '../shared/framework-authoring';
+import type { PslDiagnosticCode, PslExtensionBlock, PslSpan } from '../shared/psl-extension-block';
 
 export interface PslDiagnostic {
   readonly code: PslDiagnosticCode;
@@ -82,10 +79,19 @@ export type PslFieldAttribute = PslAttribute;
 export interface PslField {
   readonly kind: 'field';
   readonly name: string;
-  /** Unqualified type name, e.g. `"User"` for both `User` and `auth.User`. */
+  /** Unqualified type name, e.g. `"User"` for both `User`, `auth.User`, and `supabase:auth.User`. */
   readonly typeName: string;
-  /** Namespace qualifier from a dot-qualified type reference, e.g. `"auth"` for `auth.User`. Absent for unqualified types. */
+  /** Namespace qualifier from a dot-qualified type reference, e.g. `"auth"` for `auth.User` or `supabase:auth.User`. Absent for unqualified types. */
   readonly typeNamespaceId?: string;
+  /**
+   * Contract-space qualifier from a colon-prefix type reference, e.g. `"supabase"` for
+   * `supabase:auth.User` or `supabase:User`. Absent for local (same-space) type references.
+   *
+   * When present, the field references a model from a different contract space. The namespace
+   * (`typeNamespaceId`) and model name (`typeName`) identify the target within that space.
+   * Physical table resolution against the extension contract is deferred to the aggregate stage (M3).
+   */
+  readonly typeContractSpaceId?: string;
   readonly typeConstructor?: PslTypeConstructorCall;
   readonly optional: boolean;
   readonly list: boolean;
@@ -148,6 +154,11 @@ export interface PslEnum {
   readonly span: PslSpan;
 }
 
+/**
+ * A reusable group of fields embedded in a model (a `type Name { … }` block) —
+ * e.g. a MongoDB embedded document or a Postgres composite type. Unlike
+ * {@link PslModel} it has no storage or identity of its own.
+ */
 export interface PslCompositeType {
   readonly kind: 'compositeType';
   readonly name: string;
@@ -190,22 +201,135 @@ export interface PslTypesBlock {
  */
 export const UNSPECIFIED_PSL_NAMESPACE_ID = '__unspecified__';
 
+/** A value in {@link PslNamespace.entries}: a built-in entity node or an extension-contributed {@link PslExtensionBlock}. */
+export type PslNamespaceEntry = PslModel | PslEnum | PslCompositeType | PslExtensionBlock;
+
 /**
- * A named namespace block from a PSL document, or the parser's synthesised
- * `__unspecified__` bucket for declarations that appear outside any
- * `namespace { … }` block. Multiple `namespace foo { … }` blocks for the
- * same name across one or more files reopen-merge into a single entry;
+ * A namespace block, or the parser's synthesised `__unspecified__` bucket for
+ * declarations outside any `namespace { … }`. Same-name blocks reopen-merge;
  * `span` points at the first opening.
+ *
+ * Entities are stored canonically (ADR 224) in `entries[kind][name]`, where
+ * `kind` is the PSL keyword for built-ins or the block discriminator for
+ * extension kinds, e.g. `entries['policy_select']['ReadPosts']`.
  */
 export interface PslNamespace {
   readonly kind: 'namespace';
   readonly name: string;
+  /** Canonical store: a frozen container of frozen per-kind maps. The accessors below derive from it. */
+  readonly entries: Readonly<Record<string, Readonly<Record<string, PslNamespaceEntry>>>>;
+  /** Built-in models, from `entries['model']`. Extension kinds: {@link namespacePslExtensionBlocks}. */
   readonly models: readonly PslModel[];
+  /** Built-in enums, from `entries['enum']`. */
   readonly enums: readonly PslEnum[];
+  /** Built-in composite types, from `entries['compositeType']`. */
   readonly compositeTypes: readonly PslCompositeType[];
   readonly span: PslSpan;
 }
 
+/**
+ * Stores `entries`; exposes `models`/`enums`/`compositeTypes` as getters over
+ * it. The getters are prototype members (non-enumerable), so spreading or
+ * `JSON.stringify`-ing a namespace copies only `entries`, never a duplicate view.
+ */
+class PslNamespaceNode implements PslNamespace {
+  readonly kind = 'namespace' as const;
+  readonly name: string;
+  readonly entries: Readonly<Record<string, Readonly<Record<string, PslNamespaceEntry>>>>;
+  readonly span: PslSpan;
+
+  constructor(init: {
+    readonly name: string;
+    readonly entries: Readonly<Record<string, Readonly<Record<string, PslNamespaceEntry>>>>;
+    readonly span: PslSpan;
+  }) {
+    this.name = init.name;
+    this.entries = init.entries;
+    this.span = init.span;
+    Object.freeze(this);
+  }
+
+  get models(): readonly PslModel[] {
+    return blindCast<readonly PslModel[], 'entries[model] holds only PslModel by construction'>(
+      Object.values(this.entries['model'] ?? {}),
+    );
+  }
+
+  get enums(): readonly PslEnum[] {
+    return blindCast<readonly PslEnum[], 'entries[enum] holds only PslEnum by construction'>(
+      Object.values(this.entries['enum'] ?? {}),
+    );
+  }
+
+  get compositeTypes(): readonly PslCompositeType[] {
+    return blindCast<
+      readonly PslCompositeType[],
+      'entries[compositeType] holds only PslCompositeType by construction'
+    >(Object.values(this.entries['compositeType'] ?? {}));
+  }
+}
+
+/** Constructs a {@link PslNamespace}. Use this, never a namespace literal — the accessors must derive from `entries`. */
+export function makePslNamespace(init: {
+  readonly kind: 'namespace';
+  readonly name: string;
+  readonly entries: Readonly<Record<string, Readonly<Record<string, PslNamespaceEntry>>>>;
+  readonly span: PslSpan;
+}): PslNamespace {
+  return new PslNamespaceNode(init);
+}
+
+/**
+ * Builds the frozen `entries[kind][name]` container from per-kind arrays.
+ * Built-ins key on their PSL keyword; extension blocks key on their `kind`
+ * discriminator. Call this rather than hand-building the literal.
+ */
+export function makePslNamespaceEntries(
+  models: readonly PslModel[],
+  enums: readonly PslEnum[],
+  compositeTypes: readonly PslCompositeType[],
+  extensionBlocks: readonly PslExtensionBlock[],
+): Readonly<Record<string, Readonly<Record<string, PslNamespaceEntry>>>> {
+  const container: Record<string, Readonly<Record<string, PslNamespaceEntry>>> = {};
+
+  if (models.length > 0) {
+    const map: Record<string, PslModel> = {};
+    for (const m of models) {
+      map[m.name] = m;
+    }
+    container['model'] = Object.freeze(map);
+  }
+
+  if (enums.length > 0) {
+    const map: Record<string, PslEnum> = {};
+    for (const e of enums) {
+      map[e.name] = e;
+    }
+    container['enum'] = Object.freeze(map);
+  }
+
+  if (compositeTypes.length > 0) {
+    const map: Record<string, PslCompositeType> = {};
+    for (const ct of compositeTypes) {
+      map[ct.name] = ct;
+    }
+    container['compositeType'] = Object.freeze(map);
+  }
+
+  for (const block of extensionBlocks) {
+    const existing = container[block.kind];
+    const newMap: Record<string, PslExtensionBlock> = existing
+      ? blindCast<Record<string, PslExtensionBlock>, 'kind map holds only PslExtensionBlock'>({
+          ...existing,
+        })
+      : {};
+    newMap[block.name] = block;
+    container[block.kind] = Object.freeze(newMap);
+  }
+
+  return Object.freeze(container);
+}
+
 export interface PslDocumentAst {
   readonly kind: 'document';
   readonly sourceId: string;
@@ -219,26 +343,102 @@ export interface PslDocumentAst {
  * for consumers that don't (yet) need namespace-awareness.
  */
 export function flatPslModels(ast: PslDocumentAst): readonly PslModel[] {
-  return ast.namespaces.flatMap((ns) => ns.models);
+  return ast.namespaces.flatMap((ns) =>
+    blindCast<PslModel[], 'model kind map contains only PslModel by construction'>(
+      Object.values(ns.entries['model'] ?? {}),
+    ),
+  );
 }
 
 /**
  * Returns all enums from every namespace in document order.
  */
 export function flatPslEnums(ast: PslDocumentAst): readonly PslEnum[] {
-  return ast.namespaces.flatMap((ns) => ns.enums);
+  return ast.namespaces.flatMap((ns) =>
+    blindCast<PslEnum[], 'enum kind map contains only PslEnum by construction'>(
+      Object.values(ns.entries['enum'] ?? {}),
+    ),
+  );
 }
 
 /**
  * Returns all composite types from every namespace in document order.
  */
 export function flatPslCompositeTypes(ast: PslDocumentAst): readonly PslCompositeType[] {
-  return ast.namespaces.flatMap((ns) => ns.compositeTypes);
+  return ast.namespaces.flatMap((ns) =>
+    blindCast<
+      PslCompositeType[],
+      'compositeType kind map contains only PslCompositeType by construction'
+    >(Object.values(ns.entries['compositeType'] ?? {})),
+  );
+}
+
+/**
+ * The set of `entries` kind keys that the framework parser reserves for
+ * built-in PSL entity kinds. Any own-enumerable key on `PslNamespace.entries`
+ * that is **not** in this set was contributed by an extension-block descriptor.
+ *
+ * Built-in keys match the PSL keyword used on each block type:
+ * `'model'`, `'enum'`, `'compositeType'`.
+ */
+export const BUILTIN_PSL_KIND_KEYS: ReadonlySet<string> = new Set([
+  'model',
+  'enum',
+  'compositeType',
+]);
+
+/**
+ * Returns all extension-contributed blocks in the given namespace, in
+ * insertion order (the order the parser encountered them in the source).
+ *
+ * Reads from `namespace.entries`, skipping the three built-in kind keys
+ * (`'model'`, `'enum'`, `'compositeType'`). All remaining kind maps contain
+ * only `PslExtensionBlock` nodes by construction (see `makePslNamespaceEntries`).
+ */
+export function namespacePslExtensionBlocks(ns: PslNamespace): readonly PslExtensionBlock[] {
+  const result: PslExtensionBlock[] = [];
+  for (const [kindKey, kindMap] of Object.entries(ns.entries)) {
+    if (BUILTIN_PSL_KIND_KEYS.has(kindKey)) continue;
+    for (const entry of Object.values(kindMap)) {
+      result.push(
+        blindCast<
+          PslExtensionBlock,
+          'non-builtin kind maps contain only PslExtensionBlock by construction'
+        >(entry),
+      );
+    }
+  }
+  return result;
 }
 
 export interface ParsePslDocumentInput {
   readonly schema: string;
   readonly sourceId: string;
+  /**
+   * Registry of declarative block descriptors, keyed by arbitrary path
+   * segments with {@link AuthoringPslBlockDescriptor} leaves. The registry
+   * teaches the parser which top-level keywords belong to extension
+   * contributions: when the parser encounters an unknown keyword, it looks
+   * it up here and, when found, reads the block generically into a
+   * {@link PslExtensionBlock} node. Absent or undefined means no extension
+   * blocks are registered and any unknown keyword yields
+   * `PSL_UNSUPPORTED_TOP_LEVEL_BLOCK`.
+   *
+   * Contrast with the parsed block nodes themselves, which live in
+   * {@link PslNamespace.entries} under their discriminator key (read them with
+   * {@link namespacePslExtensionBlocks}); this field holds the registry of
+   * descriptors that teach the parser how to read those blocks.
+   */
+  readonly pslBlockDescriptors?: AuthoringPslBlockDescriptorNamespace;
+  /**
+   * Codec lookup for validating `value`-kind extension block parameters.
+   * When provided alongside `pslBlockDescriptors`, the generic validator runs
+   * over every parsed extension block after the full AST is assembled,
+   * appending any diagnostics to the parse result. Absent or undefined means
+   * no codec validation runs; `ref` resolution still runs when namespace
+   * context is available (built from the assembled namespaces).
+   */
+  readonly codecLookup?: CodecLookup;
 }
 
 export interface ParsePslDocumentResult {