@prisma-next/contract 0.3.0-dev.15 → 0.3.0-dev.150

package/src/types.ts

@@ -1,16 +1,60 @@
-import type { OperationRegistry } from '@prisma-next/operations';
-import type { ContractIR } from './ir';
+/**
+ * Unique symbol used as the key for branding types.
+ */
+export const $: unique symbol = Symbol('__prisma_next_brand__');
 
-export interface ContractBase {
-  readonly schemaVersion: string;
-  readonly target: string;
-  readonly targetFamily: string;
-  readonly coreHash: string;
-  readonly profileHash?: string;
-  readonly capabilities: Record<string, Record<string, boolean>>;
-  readonly extensionPacks: Record<string, unknown>;
-  readonly meta: Record<string, unknown>;
-  readonly sources: Record<string, Source>;
+/**
+ * A helper type to brand a given type with a unique identifier.
+ *
+ * @template TKey Text used as the brand key.
+ * @template TValue Optional value associated with the brand key. Defaults to `true`.
+ */
+export type Brand<TKey extends string | number | symbol, TValue = true> = {
+  [$]: {
+    [K in TKey]: TValue;
+  };
+};
+
+/**
+ * Base type for storage contract hashes.
+ * Emitted contract.d.ts files use this with the hash value as a type parameter:
+ * `type StorageHash = StorageHashBase<'sha256:abc123...'>`
+ */
+export type StorageHashBase<THash extends string> = THash & Brand<'StorageHash'>;
+
+/**
+ * Base type for execution contract hashes.
+ * Emitted contract.d.ts files use this with the hash value as a type parameter:
+ * `type ExecutionHash = ExecutionHashBase<'sha256:def456...'>`
+ */
+export type ExecutionHashBase<THash extends string> = THash & Brand<'ExecutionHash'>;
+
+export function executionHash<const T extends string>(value: T): ExecutionHashBase<T> {
+  return value as ExecutionHashBase<T>;
+}
+
+export function coreHash<const T extends string>(value: T): StorageHashBase<T> {
+  return value as StorageHashBase<T>;
+}
+
+/**
+ * Base type for profile contract hashes.
+ * Emitted contract.d.ts files use this with the hash value as a type parameter:
+ * `type ProfileHash = ProfileHashBase<'sha256:def456...'>`
+ */
+export type ProfileHashBase<THash extends string> = THash & Brand<'ProfileHash'>;
+
+export function profileHash<const T extends string>(value: T): ProfileHashBase<T> {
+  return value as ProfileHashBase<T>;
+}
+
+/**
+ * Base type for family-specific storage blocks.
+ * Family storage types (SqlStorage, MongoStorage, etc.) extend this to carry the
+ * storage hash alongside family-specific data (tables, collections, etc.).
+ */
+export interface StorageBase<THash extends string = string> {
+  readonly storageHash: StorageHashBase<THash>;
 }
 
 export interface FieldType {
@@ -20,6 +64,48 @@ export interface FieldType {
   readonly properties?: Record<string, FieldType>;
 }
 
+export type GeneratedValueSpec = {
+  readonly id: string;
+  readonly params?: Record<string, unknown>;
+};
+
+export type JsonPrimitive = string | number | boolean | null;
+
+export type JsonValue =
+  | JsonPrimitive
+  | { readonly [key: string]: JsonValue }
+  | readonly JsonValue[];
+
+export type ColumnDefaultLiteralValue = JsonValue;
+
+export type ColumnDefaultLiteralInputValue = ColumnDefaultLiteralValue | Date;
+
+export type ColumnDefault =
+  | {
+      readonly kind: 'literal';
+      readonly value: ColumnDefaultLiteralInputValue;
+    }
+  | { readonly kind: 'function'; readonly expression: string };
+
+export type ExecutionMutationDefaultValue = {
+  readonly kind: 'generator';
+  readonly id: GeneratedValueSpec['id'];
+  readonly params?: Record<string, unknown>;
+};
+
+export type ExecutionMutationDefault = {
+  readonly ref: { readonly table: string; readonly column: string };
+  readonly onCreate?: ExecutionMutationDefaultValue;
+  readonly onUpdate?: ExecutionMutationDefaultValue;
+};
+
+export type ExecutionSection<THash extends string = string> = {
+  readonly executionHash: ExecutionHashBase<THash>;
+  readonly mutations: {
+    readonly defaults: ReadonlyArray<ExecutionMutationDefault>;
+  };
+};
+
 export interface Source {
   readonly readOnly: boolean;
   readonly projection: Record<string, FieldType>;
@@ -42,25 +128,13 @@ export type Expr =
 export interface DocCollection {
   readonly name: string;
   readonly id?: {
-    readonly strategy: 'auto' | 'client' | 'uuid' | 'cuid' | 'objectId';
+    readonly strategy: 'auto' | 'client' | 'uuid' | 'objectId';
   };
   readonly fields: Record<string, FieldType>;
   readonly indexes?: ReadonlyArray<DocIndex>;
   readonly readOnly?: boolean;
 }
 
-export interface DocumentStorage {
-  readonly document: {
-    readonly collections: Record<string, DocCollection>;
-  };
-}
-
-export interface DocumentContract extends ContractBase {
-  // Accept string to work with JSON imports; runtime validation ensures 'document'
-  readonly targetFamily: string;
-  readonly storage: DocumentStorage;
-}
-
 // Plan types - target-family agnostic execution types
 export interface ParamDescriptor {
   readonly index?: number;
@@ -68,7 +142,7 @@ export interface ParamDescriptor {
   readonly codecId?: string;
   readonly nativeType?: string;
   readonly nullable?: boolean;
-  readonly source: 'dsl' | 'raw';
+  readonly source: 'dsl' | 'raw' | 'lane';
   readonly refs?: { table: string; column: string };
 }
 
@@ -85,7 +159,7 @@ export interface PlanRefs {
 export interface PlanMeta {
   readonly target: string;
   readonly targetFamily?: string;
-  readonly coreHash: string;
+  readonly storageHash: string;
   readonly profileHash?: string;
   readonly lane: string;
   readonly annotations?: {
@@ -134,24 +208,12 @@ export interface ExecutionPlan<Row = unknown, Ast = unknown> {
 export type ResultType<P> =
   P extends ExecutionPlan<infer R, unknown> ? R : P extends { readonly _Row?: infer R } ? R : never;
 
-/**
- * Type guard to check if a contract is a Document contract
- */
-export function isDocumentContract(contract: unknown): contract is DocumentContract {
-  return (
-    typeof contract === 'object' &&
-    contract !== null &&
-    'targetFamily' in contract &&
-    contract.targetFamily === 'document'
-  );
-}
-
 /**
  * Contract marker record stored in the database.
  * Represents the current contract identity for a database.
  */
 export interface ContractMarkerRecord {
-  readonly coreHash: string;
+  readonly storageHash: string;
   readonly profileHash: string;
   readonly contractJson: unknown | null;
   readonly canonicalVersion: number | null;
@@ -159,84 +221,3 @@ export interface ContractMarkerRecord {
   readonly appTag: string | null;
   readonly meta: Record<string, unknown>;
 }
-
-// Emitter types - moved from @prisma-next/emitter to shared location
-/**
- * Specifies how to import TypeScript types from a package.
- * Used in extension pack manifests to declare codec and operation type imports.
- */
-export interface TypesImportSpec {
-  readonly package: string;
-  readonly named: string;
-  readonly alias: string;
-}
-
-/**
- * Validation context passed to TargetFamilyHook.validateTypes().
- * Contains pre-assembled operation registry, type imports, and extension IDs.
- */
-export interface ValidationContext {
-  readonly operationRegistry?: OperationRegistry;
-  readonly codecTypeImports?: ReadonlyArray<TypesImportSpec>;
-  readonly operationTypeImports?: ReadonlyArray<TypesImportSpec>;
-  readonly extensionIds?: ReadonlyArray<string>;
-}
-
-/**
- * SPI interface for target family hooks that extend emission behavior.
- * Implemented by family-specific emitter hooks (e.g., SQL family).
- */
-export interface TargetFamilyHook {
-  readonly id: string;
-
-  /**
-   * Validates that all type IDs in the contract come from referenced extension packs.
-   * @param ir - Contract IR to validate
-   * @param ctx - Validation context with operation registry and extension IDs
-   */
-  validateTypes(ir: ContractIR, ctx: ValidationContext): void;
-
-  /**
-   * Validates family-specific contract structure.
-   * @param ir - Contract IR to validate
-   */
-  validateStructure(ir: ContractIR): void;
-
-  /**
-   * Generates contract.d.ts file content.
-   * @param ir - Contract IR
-   * @param codecTypeImports - Array of codec type import specs
-   * @param operationTypeImports - Array of operation type import specs
-   * @returns Generated TypeScript type definitions as string
-   */
-  generateContractTypes(
-    ir: ContractIR,
-    codecTypeImports: ReadonlyArray<TypesImportSpec>,
-    operationTypeImports: ReadonlyArray<TypesImportSpec>,
-  ): string;
-}
-
-// Extension pack manifest types - moved from @prisma-next/core-control-plane to shared location
-export type ArgSpecManifest =
-  | { readonly kind: 'typeId'; readonly type: string }
-  | { readonly kind: 'param' }
-  | { readonly kind: 'literal' };
-
-export type ReturnSpecManifest =
-  | { readonly kind: 'typeId'; readonly type: string }
-  | { readonly kind: 'builtin'; readonly type: 'number' | 'boolean' | 'string' };
-
-export interface LoweringSpecManifest {
-  readonly targetFamily: 'sql';
-  readonly strategy: 'infix' | 'function';
-  readonly template: string;
-}
-
-export interface OperationManifest {
-  readonly for: string;
-  readonly method: string;
-  readonly args: ReadonlyArray<ArgSpecManifest>;
-  readonly returns: ReturnSpecManifest;
-  readonly lowering: LoweringSpecManifest;
-  readonly capabilities?: ReadonlyArray<string>;
-}

package/src/validate-contract.ts

@@ -0,0 +1,101 @@
+import { type } from 'arktype';
+import type { Contract } from './contract-types';
+import type { DomainContractShape } from './validate-domain';
+import { validateContractDomain } from './validate-domain';
+
+export type ContractValidationPhase = 'structural' | 'domain' | 'storage';
+
+export class ContractValidationError extends Error {
+  readonly code = 'CONTRACT.VALIDATION_FAILED';
+  readonly phase: ContractValidationPhase;
+
+  constructor(message: string, phase: ContractValidationPhase) {
+    super(message);
+    this.name = 'ContractValidationError';
+    this.phase = phase;
+  }
+}
+
+/**
+ * Family-provided storage validator.
+ * SQL validates tables/columns/FKs; Mongo validates collections/embedding.
+ */
+export type StorageValidator = (contract: Contract) => void;
+
+const ContractSchema = type({
+  target: 'string',
+  targetFamily: 'string',
+  roots: 'Record<string, string>',
+  models: 'Record<string, unknown>',
+  'valueObjects?': 'Record<string, unknown>',
+  storage: 'Record<string, unknown>',
+  capabilities: 'Record<string, Record<string, boolean>>',
+  extensionPacks: 'Record<string, unknown>',
+  meta: 'Record<string, unknown>',
+  'execution?': {
+    'executionHash?': 'string',
+    mutations: {
+      defaults: 'unknown[]',
+    },
+  },
+  profileHash: 'string',
+});
+
+function stripPersistenceFields(raw: Record<string, unknown>): Record<string, unknown> {
+  const { schemaVersion: _, _generated: _g, ...rest } = raw;
+  return rest;
+}
+
+function extractDomainShape(contract: Contract): DomainContractShape {
+  return {
+    roots: contract.roots,
+    models: contract.models,
+    ...(contract.valueObjects ? { valueObjects: contract.valueObjects } : {}),
+  };
+}
+
+/**
+ * Framework-level contract validation (ADR 182).
+ *
+ * Three-pass validation:
+ * 1. **Structural validation** (arktype): verifies required fields exist with
+ *    correct base types.
+ * 2. **Domain validation** (framework-owned): roots, relation targets,
+ *    variant/base consistency, discriminators, ownership, orphans.
+ * 3. **Storage validation** (family-provided): SQL validates tables/columns/FKs;
+ *    Mongo validates collections/embedding.
+ *
+ * JSON persistence fields (`schemaVersion`, `_generated`) are stripped before
+ * validation — they are not part of the in-memory contract representation.
+ *
+ * @template TContract  The fully-typed contract type (preserves literal types).
+ * @param value           Raw contract value (e.g. parsed from JSON).
+ * @param storageValidator  Family-specific storage validation function.
+ * @returns The validated contract with full literal types.
+ */
+export function validateContract<TContract extends Contract>(
+  value: unknown,
+  storageValidator: StorageValidator,
+): TContract {
+  if (typeof value !== 'object' || value === null) {
+    throw new ContractValidationError('Contract must be a non-null object', 'structural');
+  }
+
+  const stripped = stripPersistenceFields(value as Record<string, unknown>);
+
+  const parsed = ContractSchema(stripped);
+  if (parsed instanceof type.errors) {
+    throw new ContractValidationError(
+      `Invalid contract structure: ${parsed.summary}`,
+      'structural',
+    );
+  }
+
+  const contract = parsed as unknown as Contract;
+
+  validateContractDomain(extractDomainShape(contract));
+
+  storageValidator(contract);
+
+  return contract as unknown as TContract;
+}

package/src/validate-domain.ts

@@ -0,0 +1,227 @@
+import { ContractValidationError } from './validate-contract';
+
+export interface DomainModelShape {
+  readonly fields: Record<string, unknown>;
+  readonly relations?: Record<string, { readonly to: string }>;
+  readonly discriminator?: { readonly field: string };
+  readonly variants?: Record<string, unknown>;
+  readonly base?: string;
+  readonly owner?: string;
+}
+
+export interface DomainContractShape {
+  readonly roots: Record<string, string>;
+  readonly models: Record<string, DomainModelShape>;
+  readonly valueObjects?: Record<string, { readonly fields: Record<string, unknown> }>;
+}
+
+export function validateContractDomain(contract: DomainContractShape): void {
+  const errors: string[] = [];
+  const modelNames = new Set(Object.keys(contract.models));
+
+  validateRoots(contract, modelNames, errors);
+  validateVariantsAndBases(contract, modelNames, errors);
+  validateRelationTargets(contract, modelNames, errors);
+  validateDiscriminators(contract, errors);
+  validateOwnership(contract, modelNames, errors);
+  validateValueObjectReferences(contract, errors);
+  validateFieldModifiers(contract, errors);
+
+  if (errors.length > 0) {
+    throw new ContractValidationError(
+      `Contract domain validation failed:\n- ${errors.join('\n- ')}`,
+      'domain',
+    );
+  }
+}
+
+function validateRoots(
+  contract: DomainContractShape,
+  modelNames: Set<string>,
+  errors: string[],
+): void {
+  const seenValues = new Set<string>();
+  for (const [rootKey, modelName] of Object.entries(contract.roots)) {
+    if (seenValues.has(modelName)) {
+      errors.push(`Duplicate root value: "${modelName}" is mapped by multiple root keys`);
+    }
+    seenValues.add(modelName);
+
+    if (!modelNames.has(modelName)) {
+      errors.push(
+        `Root "${rootKey}" references model "${modelName}" which does not exist in models`,
+      );
+    }
+  }
+}
+
+function validateVariantsAndBases(
+  contract: DomainContractShape,
+  modelNames: Set<string>,
+  errors: string[],
+): void {
+  const models = new Map(Object.entries(contract.models));
+
+  for (const [modelName, model] of models) {
+    if (model.variants) {
+      for (const variantName of Object.keys(model.variants)) {
+        if (!modelNames.has(variantName)) {
+          errors.push(
+            `Model "${modelName}" lists variant "${variantName}" which does not exist in models`,
+          );
+          continue;
+        }
+        const variantModel = models.get(variantName);
+        if (!variantModel) continue;
+        if (variantModel.base !== modelName) {
+          errors.push(
+            `Variant "${variantName}" has base "${variantModel.base ?? '(none)'}" but expected "${modelName}"`,
+          );
+        }
+      }
+    }
+
+    if (model.base) {
+      if (!modelNames.has(model.base)) {
+        errors.push(`Model "${modelName}" has base "${model.base}" which does not exist in models`);
+        continue;
+      }
+      const baseModel = models.get(model.base);
+      if (!baseModel) continue;
+      if (!baseModel.variants || !Object.hasOwn(baseModel.variants, modelName)) {
+        errors.push(
+          `Model "${modelName}" has base "${model.base}" which does not list it as a variant`,
+        );
+      }
+    }
+  }
+}
+
+function validateRelationTargets(
+  contract: DomainContractShape,
+  modelNames: Set<string>,
+  errors: string[],
+): void {
+  for (const [modelName, model] of Object.entries(contract.models)) {
+    for (const [relName, relation] of Object.entries(model.relations ?? {})) {
+      if (!modelNames.has(relation.to)) {
+        errors.push(
+          `Relation "${relName}" on model "${modelName}" targets "${relation.to}" which does not exist in models`,
+        );
+      }
+    }
+  }
+}
+
+function validateDiscriminators(contract: DomainContractShape, errors: string[]): void {
+  for (const [modelName, model] of Object.entries(contract.models)) {
+    if (model.discriminator) {
+      if (!model.variants || Object.keys(model.variants).length === 0) {
+        errors.push(`Model "${modelName}" has discriminator but no variants`);
+      }
+      if (!Object.hasOwn(model.fields, model.discriminator.field)) {
+        errors.push(
+          `Discriminator field "${model.discriminator.field}" is not a field on model "${modelName}"`,
+        );
+      }
+    }
+
+    if (model.variants && Object.keys(model.variants).length > 0 && !model.discriminator) {
+      errors.push(`Model "${modelName}" has variants but no discriminator`);
+    }
+
+    if (model.base) {
+      if (model.discriminator) {
+        errors.push(`Model "${modelName}" has base and must not have discriminator`);
+      }
+      if (model.variants && Object.keys(model.variants).length > 0) {
+        errors.push(`Model "${modelName}" has base and must not have variants`);
+      }
+    }
+  }
+}
+
+function validateOwnership(
+  contract: DomainContractShape,
+  modelNames: Set<string>,
+  errors: string[],
+): void {
+  for (const [modelName, model] of Object.entries(contract.models)) {
+    if (!model.owner) continue;
+
+    if (model.owner === modelName) {
+      errors.push(`Model "${modelName}" cannot own itself`);
+    }
+
+    if (!modelNames.has(model.owner)) {
+      errors.push(`Model "${modelName}" has owner "${model.owner}" which does not exist in models`);
+    }
+
+    for (const [rootKey, rootModel] of Object.entries(contract.roots)) {
+      if (rootModel === modelName) {
+        errors.push(
+          `Owned model "${modelName}" must not appear in roots (found as root "${rootKey}")`,
+        );
+      }
+    }
+  }
+}
+
+interface FieldTypeLike {
+  readonly kind?: string;
+  readonly name?: string;
+  readonly members?: readonly FieldTypeLike[];
+}
+
+interface FieldLike {
+  readonly type?: FieldTypeLike;
+  readonly many?: boolean;
+  readonly dict?: boolean;
+}
+
+function forEachContractField(
+  contract: DomainContractShape,
+  callback: (field: unknown, location: string) => void,
+): void {
+  for (const [modelName, model] of Object.entries(contract.models)) {
+    for (const [fieldName, field] of Object.entries(model.fields)) {
+      callback(field, `Model "${modelName}" field "${fieldName}"`);
+    }
+  }
+  for (const [voName, vo] of Object.entries(contract.valueObjects ?? {})) {
+    for (const [fieldName, field] of Object.entries(vo.fields)) {
+      callback(field, `Value object "${voName}" field "${fieldName}"`);
+    }
+  }
+}
+
+function validateValueObjectReferences(contract: DomainContractShape, errors: string[]): void {
+  const voNames = new Set(Object.keys(contract.valueObjects ?? {}));
+
+  function checkType(type: FieldTypeLike | undefined, location: string): void {
+    if (!type) return;
+    if (type.kind === 'valueObject' && type.name && !voNames.has(type.name)) {
+      errors.push(
+        `${location} references value object "${type.name}" which does not exist in valueObjects`,
+      );
+      return;
+    }
+    if (type.kind === 'union') {
+      for (const member of type.members ?? []) checkType(member, location);
+    }
+  }
+
+  forEachContractField(contract, (field, location) => {
+    const f = field as FieldLike | undefined;
+    checkType(f?.type, location);
+  });
+}
+
+function validateFieldModifiers(contract: DomainContractShape, errors: string[]): void {
+  forEachContractField(contract, (field, location) => {
+    const f = field as FieldLike | undefined;
+    if (f?.many && f?.dict) {
+      errors.push(`${location} cannot have both "many" and "dict" modifiers`);
+    }
+  });
+}

package/dist/exports/framework-components.d.ts

@@ -1,3 +0,0 @@
-export type { AdapterDescriptor, AdapterInstance, AdapterPackRef, ComponentDescriptor, ComponentMetadata, ContractComponentRequirementsCheckInput, ContractComponentRequirementsCheckResult, DriverDescriptor, DriverInstance, DriverPackRef, ExtensionDescriptor, ExtensionInstance, ExtensionPackRef, FamilyDescriptor, FamilyInstance, PackRefBase, TargetBoundComponentDescriptor, TargetDescriptor, TargetInstance, TargetPackRef, } from '../framework-components';
-export { checkContractComponentRequirements } from '../framework-components';
-//# sourceMappingURL=framework-components.d.ts.map

package/dist/exports/framework-components.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"framework-components.d.ts","sourceRoot":"","sources":["../../src/exports/framework-components.ts"],"names":[],"mappings":"AAAA,YAAY,EAEV,iBAAiB,EAEjB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,uCAAuC,EACvC,wCAAwC,EACxC,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,8BAA8B,EAC9B,gBAAgB,EAChB,cAAc,EACd,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,kCAAkC,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/exports/framework-components.js

@@ -1,24 +0,0 @@
-// src/framework-components.ts
-function checkContractComponentRequirements(input) {
-  const providedIds = /* @__PURE__ */ new Set();
-  for (const id of input.providedComponentIds) {
-    providedIds.add(id);
-  }
-  const requiredExtensionPackIds = input.contract.extensionPacks ? Object.keys(input.contract.extensionPacks) : [];
-  const missingExtensionPackIds = requiredExtensionPackIds.filter((id) => !providedIds.has(id));
-  const expectedTargetFamily = input.expectedTargetFamily;
-  const contractTargetFamily = input.contract.targetFamily;
-  const familyMismatch = expectedTargetFamily !== void 0 && contractTargetFamily !== void 0 && contractTargetFamily !== expectedTargetFamily ? { expected: expectedTargetFamily, actual: contractTargetFamily } : void 0;
-  const expectedTargetId = input.expectedTargetId;
-  const contractTargetId = input.contract.target;
-  const targetMismatch = expectedTargetId !== void 0 && contractTargetId !== expectedTargetId ? { expected: expectedTargetId, actual: contractTargetId } : void 0;
-  return {
-    ...familyMismatch ? { familyMismatch } : {},
-    ...targetMismatch ? { targetMismatch } : {},
-    missingExtensionPackIds
-  };
-}
-export {
-  checkContractComponentRequirements
-};
-//# sourceMappingURL=framework-components.js.map