@prisma-next/contract 0.3.0-dev.14 → 0.3.0-dev.141

package/src/hashing.ts

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { canonicalizeContract } from './canonicalization';
+import type { ExecutionHashBase, ProfileHashBase, StorageHashBase } from './types';
+
+const SCHEMA_VERSION = '1';
+
+function sha256(content: string): string {
+  const hash = createHash('sha256');
+  hash.update(content);
+  return `sha256:${hash.digest('hex')}`;
+}
+
+export function computeStorageHash(args: {
+  target: string;
+  targetFamily: string;
+  storage: Record<string, unknown>;
+}): StorageHashBase<string> {
+  const canonical = canonicalizeContract({
+    schemaVersion: SCHEMA_VERSION,
+    targetFamily: args.targetFamily,
+    target: args.target,
+    storage: args.storage,
+    roots: {},
+    models: {},
+    extensionPacks: {},
+    capabilities: {},
+    meta: {},
+  });
+  return sha256(canonical) as StorageHashBase<string>;
+}
+
+export function computeExecutionHash(args: {
+  target: string;
+  targetFamily: string;
+  execution: Record<string, unknown>;
+}): ExecutionHashBase<string> {
+  const canonical = canonicalizeContract({
+    schemaVersion: SCHEMA_VERSION,
+    targetFamily: args.targetFamily,
+    target: args.target,
+    execution: args.execution,
+    roots: {},
+    models: {},
+    storage: {},
+    extensionPacks: {},
+    capabilities: {},
+    meta: {},
+  });
+  return sha256(canonical) as ExecutionHashBase<string>;
+}
+
+export function computeProfileHash(args: {
+  target: string;
+  targetFamily: string;
+  capabilities: Record<string, Record<string, boolean>>;
+}): ProfileHashBase<string> {
+  const canonical = canonicalizeContract({
+    schemaVersion: SCHEMA_VERSION,
+    targetFamily: args.targetFamily,
+    target: args.target,
+    capabilities: args.capabilities,
+    roots: {},
+    models: {},
+    storage: {},
+    extensionPacks: {},
+    meta: {},
+  });
+  return sha256(canonical) as ProfileHashBase<string>;
+}

package/src/testing-factories.ts

@@ -0,0 +1,93 @@
+import type { Contract } from './contract-types';
+import type { ContractModel, ModelStorageBase } from './domain-types';
+import { computeExecutionHash, computeProfileHash, computeStorageHash } from './hashing';
+import type { ExecutionSection, ProfileHashBase, StorageBase } from './types';
+import { coreHash } from './types';
+
+type ContractOverrides<
+  TStorage extends StorageBase = StorageBase,
+  TModels extends Record<string, ContractModel> = Record<string, ContractModel>,
+> = {
+  target?: string;
+  targetFamily?: string;
+  roots?: Record<string, string>;
+  models?: TModels;
+  storage?: Omit<TStorage, 'storageHash'>;
+  capabilities?: Record<string, Record<string, boolean>>;
+  extensionPacks?: Record<string, unknown>;
+  execution?: Omit<ExecutionSection, 'executionHash'>;
+  profileHash?: ProfileHashBase<string>;
+  meta?: Record<string, unknown>;
+};
+
+const DUMMY_HASH = coreHash('sha256:test');
+
+export function createContract<
+  TStorage extends StorageBase = StorageBase,
+  TModels extends Record<string, ContractModel> = Record<string, ContractModel>,
+>(overrides: ContractOverrides<TStorage, TModels> = {}): Contract<TStorage, TModels> {
+  const target = overrides.target ?? 'postgres';
+  const targetFamily = overrides.targetFamily ?? 'sql';
+  const capabilities = overrides.capabilities ?? {};
+
+  const rawStorage =
+    overrides.storage ?? ({ tables: {} } as unknown as Omit<TStorage, 'storageHash'>);
+
+  const storageHash = computeStorageHash({
+    target,
+    targetFamily,
+    storage: rawStorage as Record<string, unknown>,
+  });
+
+  const storage = {
+    ...rawStorage,
+    storageHash,
+  } as TStorage;
+
+  const computedProfileHash =
+    overrides.profileHash ?? computeProfileHash({ target, targetFamily, capabilities });
+
+  return {
+    target,
+    targetFamily,
+    roots: overrides.roots ?? {},
+    models: (overrides.models ?? {}) as TModels,
+    storage,
+    capabilities,
+    extensionPacks: overrides.extensionPacks ?? {},
+    ...(overrides.execution !== undefined
+      ? {
+          execution: {
+            ...overrides.execution,
+            executionHash: computeExecutionHash({
+              target,
+              targetFamily,
+              execution: overrides.execution,
+            }),
+          },
+        }
+      : {}),
+    profileHash: computedProfileHash,
+    meta: overrides.meta ?? {},
+  };
+}
+
+type SqlStorageLike = StorageBase & {
+  readonly tables: Record<string, unknown>;
+  readonly types?: Record<string, unknown>;
+};
+
+type SqlModelLike = ContractModel<ModelStorageBase & { table: string }>;
+
+export function createSqlContract(
+  overrides: ContractOverrides<SqlStorageLike, Record<string, SqlModelLike>> = {},
+): Contract<SqlStorageLike, Record<string, SqlModelLike>> {
+  return createContract<SqlStorageLike, Record<string, SqlModelLike>>({
+    target: 'postgres',
+    targetFamily: 'sql',
+    storage: overrides.storage ?? { tables: {} },
+    ...overrides,
+  });
+}
+
+export { DUMMY_HASH };

package/src/types.ts

@@ -1,16 +1,82 @@
-import type { OperationRegistry } from '@prisma-next/operations';
-import type { ContractIR } from './ir';
+import type { DomainModel } from './domain-types';
 
-export interface ContractBase {
+/**
+ * Unique symbol used as the key for branding types.
+ */
+export const $: unique symbol = Symbol('__prisma_next_brand__');
+
+/**
+ * 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 ContractBase<
+  TStorageHash extends StorageHashBase<string> = StorageHashBase<string>,
+  TExecutionHash extends ExecutionHashBase<string> = ExecutionHashBase<string>,
+  TProfileHash extends ProfileHashBase<string> = ProfileHashBase<string>,
+> {
   readonly schemaVersion: string;
   readonly target: string;
   readonly targetFamily: string;
-  readonly coreHash: string;
-  readonly profileHash?: string;
+  readonly storageHash: TStorageHash;
+  readonly executionHash?: TExecutionHash | undefined;
+  readonly profileHash?: TProfileHash | undefined;
   readonly capabilities: Record<string, Record<string, boolean>>;
   readonly extensionPacks: Record<string, unknown>;
   readonly meta: Record<string, unknown>;
   readonly sources: Record<string, Source>;
+  readonly execution?: ExecutionSection;
+  readonly roots: Record<string, string>;
+  readonly models: Record<string, DomainModel>;
 }
 
 export interface FieldType {
@@ -20,6 +86,79 @@ 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 TaggedBigInt = { readonly $type: 'bigint'; readonly value: string };
+
+export function isTaggedBigInt(value: unknown): value is TaggedBigInt {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { $type?: unknown }).$type === 'bigint' &&
+    typeof (value as { value?: unknown }).value === 'string'
+  );
+}
+
+export function bigintJsonReplacer(_key: string, value: unknown): unknown {
+  if (typeof value === 'bigint') {
+    return { $type: 'bigint', value: value.toString() } satisfies TaggedBigInt;
+  }
+  return value;
+}
+
+export type TaggedRaw = { readonly $type: 'raw'; readonly value: JsonValue };
+
+export function isTaggedRaw(value: unknown): value is TaggedRaw {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { $type?: unknown }).$type === 'raw' &&
+    'value' in (value as object)
+  );
+}
+
+export type TaggedLiteralValue = TaggedBigInt | TaggedRaw;
+
+export type ColumnDefaultLiteralValue = JsonValue | TaggedLiteralValue;
+
+export type ColumnDefaultLiteralInputValue = ColumnDefaultLiteralValue | bigint | 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,7 +181,7 @@ 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>;
@@ -55,7 +194,11 @@ export interface DocumentStorage {
   };
 }
 
-export interface DocumentContract extends ContractBase {
+export interface DocumentContract<
+  TStorageHash extends StorageHashBase<string> = StorageHashBase<string>,
+  TExecutionHash extends ExecutionHashBase<string> = ExecutionHashBase<string>,
+  TProfileHash extends ProfileHashBase<string> = ProfileHashBase<string>,
+> extends ContractBase<TStorageHash, TExecutionHash, TProfileHash> {
   // Accept string to work with JSON imports; runtime validation ensures 'document'
   readonly targetFamily: string;
   readonly storage: DocumentStorage;
@@ -68,7 +211,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 +228,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?: {
@@ -151,7 +294,7 @@ export function isDocumentContract(contract: unknown): contract is DocumentContr
  * 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 +302,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,93 @@
+import { type } from 'arktype';
+import type { Contract } from './contract-types';
+import type { DomainContractShape, DomainValidationResult } from './validate-domain';
+import { validateContractDomain } from './validate-domain';
+
+/**
+ * Family-provided storage validator.
+ * SQL validates tables/columns/FKs; Mongo validates collections/embedding.
+ */
+export type StorageValidator = (contract: Contract) => void;
+
+export interface ValidateContractResult {
+  readonly warnings: string[];
+}
+
+const ContractSchema = type({
+  target: 'string',
+  targetFamily: 'string',
+  roots: 'Record<string, string>',
+  models: '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: _, sources: _s, ...rest } = raw;
+  return rest;
+}
+
+function extractDomainShape(contract: Contract): DomainContractShape {
+  return {
+    roots: contract.roots,
+    models: contract.models,
+  };
+}
+
+/**
+ * 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`, `sources`) 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 & ValidateContractResult {
+  if (typeof value !== 'object' || value === null) {
+    throw new Error('Contract must be a non-null object');
+  }
+
+  const stripped = stripPersistenceFields(value as Record<string, unknown>);
+
+  const parsed = ContractSchema(stripped);
+  if (parsed instanceof type.errors) {
+    throw new Error(`Invalid contract structure: ${parsed.summary}`);
+  }
+
+  // Arktype verified the structural shape; Contract adds branded hash types and
+  // ContractModel generics that can't be expressed in the schema.
+  const contract = parsed as unknown as Contract;
+
+  const domainResult: DomainValidationResult = validateContractDomain(extractDomainShape(contract));
+
+  storageValidator(contract);
+
+  // TContract narrows Contract with literal types from the caller's contract.d.ts;
+  // the runtime object is the same — the cast preserves the caller's type parameter.
+  return Object.assign(contract as unknown as TContract, {
+    warnings: domainResult.warnings,
+  });
+}