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

package/package.json

@@ -1,51 +1,50 @@
 {
   "name": "@prisma-next/contract",
-  "version": "0.3.0-dev.14",
+  "version": "0.3.0-dev.141",
   "type": "module",
   "sideEffects": false,
   "description": "Data contract type definitions and JSON schema for Prisma Next",
   "dependencies": {
-    "@prisma-next/operations": "0.3.0-dev.14"
+    "arktype": "^2.1.29",
+    "@prisma-next/utils": "0.3.0-dev.141"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.0.16",
-    "tsup": "8.5.1",
+    "tsdown": "0.18.4",
     "typescript": "5.9.3",
-    "vitest": "4.0.16",
-    "@prisma-next/test-utils": "0.0.1"
+    "vitest": "4.0.17",
+    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
     "dist",
     "src",
     "schemas"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "exports": {
-    "./types": {
-      "types": "./dist/exports/types.d.ts",
-      "import": "./dist/exports/types.js"
-    },
-    "./pack-manifest-types": {
-      "types": "./dist/exports/pack-manifest-types.d.ts",
-      "import": "./dist/exports/pack-manifest-types.js"
-    },
-    "./ir": {
-      "types": "./dist/exports/ir.d.ts",
-      "import": "./dist/exports/ir.js"
-    },
-    "./framework-components": {
-      "types": "./dist/exports/framework-components.d.ts",
-      "import": "./dist/exports/framework-components.js"
-    },
-    "./schema-document": "./schemas/data-contract-document-v1.json"
+    "./hashing": "./dist/hashing.mjs",
+    "./testing": "./dist/testing.mjs",
+    "./types": "./dist/types.mjs",
+    "./validate-contract": "./dist/validate-contract.mjs",
+    "./validate-domain": "./dist/validate-domain.mjs",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/0-foundation/shared/contract"
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts && tsc --project tsconfig.build.json",
+    "build": "tsdown",
     "test": "vitest run --passWithNoTests",
     "test:coverage": "vitest run --coverage --passWithNoTests",
     "typecheck": "tsc --project tsconfig.json --noEmit",
     "lint": "biome check . --error-on-warnings",
     "lint:fix": "biome check --write .",
     "lint:fix:unsafe": "biome check --write --unsafe .",
-    "clean": "node ../../../../../scripts/clean.mjs"
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
   }
 }

package/schemas/data-contract-document-v1.json

@@ -24,10 +24,10 @@
       "enum": ["document"],
       "description": "Target family classification"
     },
-    "coreHash": {
+    "storageHash": {
       "type": "string",
       "pattern": "^sha256:[a-f0-9]{64}$",
-      "description": "SHA-256 hash of the core schema structure (models, fields, relations, storage layout)"
+      "description": "SHA-256 hash of the storage section (DB-satisfied expectations)"
     },
     "profileHash": {
       "type": "string",
@@ -44,7 +44,7 @@
         }
       }
     },
-    "extensions": {
+    "extensionPacks": {
       "type": "object",
       "description": "Extension packs and their configuration",
       "additionalProperties": true
@@ -85,7 +85,7 @@
       "required": ["document"]
     }
   },
-  "required": ["schemaVersion", "target", "targetFamily", "coreHash", "storage"],
+  "required": ["schemaVersion", "target", "targetFamily", "storageHash", "storage"],
   "$defs": {
     "DocCollection": {
       "type": "object",
@@ -103,7 +103,7 @@
           "properties": {
             "strategy": {
               "type": "string",
-              "enum": ["auto", "client", "uuid", "cuid", "objectId"],
+              "enum": ["auto", "client", "uuid", "objectId"],
               "description": "ID generation strategy"
             }
           }

package/src/canonicalization.ts

@@ -0,0 +1,286 @@
+import { isArrayEqual } from '@prisma-next/utils/array-equal';
+
+import type { StorageBase } from './types';
+import { bigintJsonReplacer } from './types';
+
+const TOP_LEVEL_ORDER = [
+  'schemaVersion',
+  'canonicalVersion',
+  'targetFamily',
+  'target',
+  'profileHash',
+  'roots',
+  'models',
+  'storage',
+  'execution',
+  'capabilities',
+  'extensionPacks',
+  'meta',
+] as const;
+
+function isDefaultValue(value: unknown): boolean {
+  if (value === false) return true;
+  if (value === null) return false;
+  if (value instanceof Date) return false;
+  if (Array.isArray(value) && value.length === 0) return true;
+  if (typeof value === 'object' && value !== null) {
+    const keys = Object.keys(value);
+    return keys.length === 0;
+  }
+  return false;
+}
+
+function omitDefaults(obj: unknown, path: readonly string[]): unknown {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (obj instanceof Date) {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => omitDefaults(item, path));
+  }
+
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    const currentPath = [...path, key];
+
+    if (key === '_generated') {
+      continue;
+    }
+
+    if (key === 'nullable' && value === false) {
+      continue;
+    }
+
+    if (key === 'generated' && value === false) {
+      continue;
+    }
+
+    if ((key === 'onDelete' || key === 'onUpdate') && value === 'noAction') {
+      continue;
+    }
+
+    if (isDefaultValue(value)) {
+      const isRequiredModels = isArrayEqual(currentPath, ['models']);
+      const isRequiredTables = isArrayEqual(currentPath, ['storage', 'tables']);
+      const isRequiredCollections = isArrayEqual(currentPath, ['storage', 'collections']);
+      const isCollectionEntry =
+        currentPath.length === 3 &&
+        isArrayEqual([currentPath[0], currentPath[1]], ['storage', 'collections']);
+      const isRequiredRoots = isArrayEqual(currentPath, ['roots']);
+      const isRequiredExtensionPacks = isArrayEqual(currentPath, ['extensionPacks']);
+      const isRequiredCapabilities = isArrayEqual(currentPath, ['capabilities']);
+      const isRequiredMeta = isArrayEqual(currentPath, ['meta']);
+      const isRequiredExecutionDefaults = isArrayEqual(currentPath, [
+        'execution',
+        'mutations',
+        'defaults',
+      ]);
+      const isExtensionNamespace = currentPath.length === 2 && currentPath[0] === 'extensionPacks';
+      const isModelRelations =
+        currentPath.length === 3 &&
+        isArrayEqual([currentPath[0], currentPath[2]], ['models', 'relations']);
+      const isModelStorage =
+        currentPath.length === 3 &&
+        isArrayEqual([currentPath[0], currentPath[2]], ['models', 'storage']);
+      const isTableUniques =
+        currentPath.length === 4 &&
+        isArrayEqual(
+          [currentPath[0], currentPath[1], currentPath[3]],
+          ['storage', 'tables', 'uniques'],
+        );
+      const isTableIndexes =
+        currentPath.length === 4 &&
+        isArrayEqual(
+          [currentPath[0], currentPath[1], currentPath[3]],
+          ['storage', 'tables', 'indexes'],
+        );
+      const isTableForeignKeys =
+        currentPath.length === 4 &&
+        isArrayEqual(
+          [currentPath[0], currentPath[1], currentPath[3]],
+          ['storage', 'tables', 'foreignKeys'],
+        );
+
+      const isFkBooleanField =
+        currentPath.length === 5 &&
+        currentPath[0] === 'storage' &&
+        currentPath[1] === 'tables' &&
+        currentPath[3] === 'foreignKeys' &&
+        (key === 'constraint' || key === 'index');
+
+      if (
+        !isRequiredModels &&
+        !isRequiredTables &&
+        !isRequiredCollections &&
+        !isCollectionEntry &&
+        !isRequiredRoots &&
+        !isRequiredExtensionPacks &&
+        !isRequiredCapabilities &&
+        !isRequiredMeta &&
+        !isRequiredExecutionDefaults &&
+        !isExtensionNamespace &&
+        !isModelRelations &&
+        !isModelStorage &&
+        !isTableUniques &&
+        !isTableIndexes &&
+        !isTableForeignKeys &&
+        !isFkBooleanField
+      ) {
+        continue;
+      }
+    }
+
+    result[key] = omitDefaults(value, currentPath);
+  }
+
+  return result;
+}
+
+function sortObjectKeys(obj: unknown): unknown {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (obj instanceof Date) {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => sortObjectKeys(item));
+  }
+
+  const sorted: Record<string, unknown> = {};
+  const keys = Object.keys(obj).sort();
+  for (const key of keys) {
+    sorted[key] = sortObjectKeys((obj as Record<string, unknown>)[key]);
+  }
+
+  return sorted;
+}
+
+type StorageObject = {
+  tables?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+type TableObject = {
+  indexes?: unknown[];
+  uniques?: unknown[];
+  [key: string]: unknown;
+};
+
+function sortIndexesAndUniques(storage: unknown): unknown {
+  if (!storage || typeof storage !== 'object') {
+    return storage;
+  }
+
+  const storageObj = storage as StorageObject;
+  if (!storageObj.tables || typeof storageObj.tables !== 'object') {
+    return storage;
+  }
+
+  const tables = storageObj.tables;
+  const result: StorageObject = { ...storageObj };
+
+  result.tables = {};
+  const sortedTableNames = Object.keys(tables).sort();
+  for (const tableName of sortedTableNames) {
+    const table = tables[tableName];
+    if (!table || typeof table !== 'object') {
+      result.tables[tableName] = table;
+      continue;
+    }
+
+    const tableObj = table as TableObject;
+    const sortedTable: TableObject = { ...tableObj };
+
+    if (Array.isArray(tableObj.indexes)) {
+      sortedTable.indexes = [...tableObj.indexes].sort((a, b) => {
+        const nameA = (a as { name?: string })?.name || '';
+        const nameB = (b as { name?: string })?.name || '';
+        return nameA.localeCompare(nameB);
+      });
+    }
+
+    if (Array.isArray(tableObj.uniques)) {
+      sortedTable.uniques = [...tableObj.uniques].sort((a, b) => {
+        const nameA = (a as { name?: string })?.name || '';
+        const nameB = (b as { name?: string })?.name || '';
+        return nameA.localeCompare(nameB);
+      });
+    }
+
+    result.tables[tableName] = sortedTable;
+  }
+
+  return result;
+}
+
+function orderTopLevel(obj: Record<string, unknown>): Record<string, unknown> {
+  const ordered: Record<string, unknown> = {};
+  const remaining = new Set(Object.keys(obj));
+
+  for (const key of TOP_LEVEL_ORDER) {
+    if (remaining.has(key)) {
+      ordered[key] = obj[key];
+      remaining.delete(key);
+    }
+  }
+
+  for (const key of Array.from(remaining).sort()) {
+    ordered[key] = obj[key];
+  }
+
+  return ordered;
+}
+
+export type CanonicalContractInput = {
+  readonly schemaVersion?: string | undefined;
+  readonly targetFamily: string;
+  readonly target: string;
+  readonly profileHash?: string | undefined;
+  readonly roots: Record<string, string>;
+  readonly models: Record<string, unknown>;
+  // StorageBase is an interface without an index signature, so it is not
+  // assignable to Record<string, unknown>. The union allows callers to pass
+  // either the typed StorageBase or a plain record.
+  readonly storage: StorageBase | Record<string, unknown>;
+  readonly execution?: Record<string, unknown> | undefined;
+  readonly extensionPacks: Record<string, unknown>;
+  readonly capabilities: Record<string, Record<string, boolean>>;
+  readonly meta: Record<string, unknown>;
+};
+
+export function canonicalizeContractToObject(
+  input: CanonicalContractInput,
+): Record<string, unknown> {
+  const i = input as Record<string, unknown>;
+  const normalized: Record<string, unknown> = {
+    ...(i['schemaVersion'] !== undefined ? { schemaVersion: i['schemaVersion'] } : {}),
+    targetFamily: i['targetFamily'],
+    target: i['target'],
+    ...(i['profileHash'] !== undefined ? { profileHash: i['profileHash'] } : {}),
+    roots: i['roots'],
+    models: i['models'],
+    storage: i['storage'],
+    ...(i['execution'] !== undefined ? { execution: i['execution'] } : {}),
+    extensionPacks: i['extensionPacks'],
+    capabilities: i['capabilities'],
+    meta: i['meta'],
+  };
+
+  const withDefaultsOmitted = omitDefaults(normalized, []) as Record<string, unknown>;
+  const withSortedIndexes = sortIndexesAndUniques(withDefaultsOmitted['storage']);
+  const withSortedStorage = { ...withDefaultsOmitted, storage: withSortedIndexes };
+  const withSortedKeys = sortObjectKeys(withSortedStorage) as Record<string, unknown>;
+  return orderTopLevel(withSortedKeys);
+}
+
+export function canonicalizeContract(input: CanonicalContractInput): string {
+  return JSON.stringify(canonicalizeContractToObject(input), bigintJsonReplacer, 2);
+}

package/src/contract-types.ts

@@ -0,0 +1,54 @@
+import type { ContractModel } from './domain-types';
+import type {
+  ExecutionHashBase,
+  ExecutionMutationDefault,
+  ProfileHashBase,
+  StorageBase,
+} from './types';
+
+/**
+ * Execution section for the unified contract (ADR 182).
+ *
+ * Unlike the legacy {@link import('./types').ExecutionSection}, this type
+ * requires `executionHash` — when an execution section is present, its
+ * hash must be too (consistent with `StorageBase.storageHash`).
+ *
+ * @template THash  Literal hash string type for type-safe hash tracking.
+ */
+export type ContractExecutionSection<THash extends string = string> = {
+  readonly executionHash: ExecutionHashBase<THash>;
+  readonly mutations: {
+    readonly defaults: ReadonlyArray<ExecutionMutationDefault>;
+  };
+};
+
+/**
+ * Unified contract representation (ADR 182).
+ *
+ * A `Contract` is the canonical in-memory representation of a data contract.
+ * It is model-first (domain models carry their own storage bridge) and
+ * family-parameterized (SQL, Mongo, etc. specialize via `TStorage` and model
+ * storage generics on `ContractModel`).
+ *
+ * JSON persistence fields (`schemaVersion`, `sources`) are not represented
+ * here — they are handled at the serialization boundary.
+ *
+ * @template TStorage  Family-specific storage block (extends {@link StorageBase}).
+ * @template TModels   Record of model name → {@link ContractModel} with
+ *                     family-specific model storage.
+ */
+export interface Contract<
+  TStorage extends StorageBase = StorageBase,
+  TModels extends Record<string, ContractModel> = Record<string, ContractModel>,
+> {
+  readonly target: string;
+  readonly targetFamily: string;
+  readonly roots: Record<string, string>;
+  readonly models: TModels;
+  readonly storage: TStorage;
+  readonly capabilities: Record<string, Record<string, boolean>>;
+  readonly extensionPacks: Record<string, unknown>;
+  readonly execution?: ContractExecutionSection;
+  readonly profileHash: ProfileHashBase<string>;
+  readonly meta: Record<string, unknown>;
+}

package/src/domain-types.ts

@@ -0,0 +1,85 @@
+export type ContractField = {
+  readonly nullable: boolean;
+  readonly codecId: string;
+};
+
+export type ContractRelationOn = {
+  readonly localFields: readonly string[];
+  readonly targetFields: readonly string[];
+};
+
+export type ContractReferenceRelation = {
+  readonly to: string;
+  readonly cardinality: '1:1' | '1:N' | 'N:1';
+  readonly on: ContractRelationOn;
+};
+
+export type ContractEmbedRelation = {
+  readonly to: string;
+  readonly cardinality: '1:1' | '1:N';
+};
+
+export type ContractRelation = ContractReferenceRelation | ContractEmbedRelation;
+
+export type ContractDiscriminator = {
+  readonly field: string;
+};
+
+export type ContractVariantEntry = {
+  readonly value: string;
+};
+
+export type ModelStorageBase = Readonly<Record<string, unknown>>;
+
+export interface ContractModel<TModelStorage extends ModelStorageBase = ModelStorageBase> {
+  readonly fields: Record<string, ContractField>;
+  readonly relations: Record<string, ContractRelation>;
+  readonly storage: TModelStorage;
+  readonly discriminator?: ContractDiscriminator;
+  readonly variants?: Record<string, ContractVariantEntry>;
+  readonly base?: string;
+  readonly owner?: string;
+}
+
+// ── Backward-compatible aliases ──────────────────────────────────────────────
+
+/** @deprecated Use {@link ContractField} */
+export type DomainField = ContractField;
+/** @deprecated Use {@link ContractRelationOn} */
+export type DomainRelationOn = ContractRelationOn;
+/** @deprecated Use {@link ContractReferenceRelation} */
+export type DomainReferenceRelation = ContractReferenceRelation;
+/** @deprecated Use {@link ContractEmbedRelation} */
+export type DomainEmbedRelation = ContractEmbedRelation;
+/** @deprecated Use {@link ContractRelation} */
+export type DomainRelation = ContractRelation;
+/** @deprecated Use {@link ContractDiscriminator} */
+export type DomainDiscriminator = ContractDiscriminator;
+/** @deprecated Use {@link ContractVariantEntry} */
+export type DomainVariantEntry = ContractVariantEntry;
+/** @deprecated Use {@link ContractModel} */
+export type DomainModel = ContractModel;
+
+// ── Relation key helpers ─────────────────────────────────────────────────────
+
+type HasModelsWithRelations = {
+  readonly models: Record<string, { readonly relations: Record<string, ContractRelation> }>;
+};
+
+export type ReferenceRelationKeys<
+  TContract extends HasModelsWithRelations,
+  ModelName extends string & keyof TContract['models'],
+> = {
+  [K in keyof TContract['models'][ModelName]['relations']]: TContract['models'][ModelName]['relations'][K] extends ContractReferenceRelation
+    ? K
+    : never;
+}[keyof TContract['models'][ModelName]['relations']];
+
+export type EmbedRelationKeys<
+  TContract extends HasModelsWithRelations,
+  ModelName extends string & keyof TContract['models'],
+> = {
+  [K in keyof TContract['models'][ModelName]['relations']]: TContract['models'][ModelName]['relations'][K] extends ContractReferenceRelation
+    ? never
+    : K;
+}[keyof TContract['models'][ModelName]['relations']];

package/src/exports/hashing.ts

@@ -0,0 +1,6 @@
+export {
+  type CanonicalContractInput,
+  canonicalizeContract,
+  canonicalizeContractToObject,
+} from '../canonicalization';
+export { computeExecutionHash, computeProfileHash, computeStorageHash } from '../hashing';

package/src/exports/testing.ts

@@ -0,0 +1 @@
+export { createContract, createSqlContract, DUMMY_HASH } from '../testing-factories';

package/src/exports/types.ts

@@ -1,26 +1,65 @@
-// Shared types
-// Document family types
-// Plan types - target-family agnostic execution types
-// Emitter types (moved from @prisma-next/emitter)
+export type { Contract, ContractExecutionSection } from '../contract-types';
 export type {
+  ContractDiscriminator,
+  ContractEmbedRelation,
+  ContractField,
+  ContractModel,
+  ContractReferenceRelation,
+  ContractRelation,
+  ContractRelationOn,
+  ContractVariantEntry,
+  DomainDiscriminator,
+  DomainEmbedRelation,
+  DomainField,
+  DomainModel,
+  DomainReferenceRelation,
+  DomainRelation,
+  DomainRelationOn,
+  DomainVariantEntry,
+  EmbedRelationKeys,
+  ModelStorageBase,
+  ReferenceRelationKeys,
+} from '../domain-types';
+export type {
+  $,
+  Brand,
+  ColumnDefault,
+  ColumnDefaultLiteralInputValue,
+  ColumnDefaultLiteralValue,
   ContractBase,
   ContractMarkerRecord,
   DocCollection,
   DocIndex,
   DocumentContract,
   DocumentStorage,
+  ExecutionHashBase,
+  ExecutionMutationDefault,
+  ExecutionMutationDefaultValue,
   ExecutionPlan,
+  ExecutionSection,
   Expr,
   FieldType,
-  OperationManifest,
+  GeneratedValueSpec,
+  JsonPrimitive,
+  JsonValue,
   ParamDescriptor,
   PlanMeta,
   PlanRefs,
+  ProfileHashBase,
   ResultType,
   Source,
-  TargetFamilyHook,
-  TypesImportSpec,
-  ValidationContext,
+  StorageBase,
+  StorageHashBase,
+  TaggedBigInt,
+  TaggedLiteralValue,
+  TaggedRaw,
+} from '../types';
+export {
+  bigintJsonReplacer,
+  coreHash,
+  executionHash,
+  isDocumentContract,
+  isTaggedBigInt,
+  isTaggedRaw,
+  profileHash,
 } from '../types';
-// Type guards
-export { isDocumentContract } from '../types';

package/src/exports/validate-contract.ts

@@ -0,0 +1,5 @@
+export {
+  type StorageValidator,
+  type ValidateContractResult,
+  validateContract,
+} from '../validate-contract';

package/src/exports/validate-domain.ts

@@ -0,0 +1,6 @@
+export {
+  type DomainContractShape,
+  type DomainModelShape,
+  type DomainValidationResult,
+  validateContractDomain,
+} from '../validate-domain';