@prisma-next/contract 0.0.1

package/README.md

@@ -0,0 +1,233 @@
+# @prisma-next/contract
+
+Data contract type definitions and JSON schema for Prisma Next.
+
+## Overview
+
+This package provides TypeScript type definitions and JSON Schemas for Prisma Next data contracts. The data contract is the canonical description of an application's data model and storage layout, independent of any specific query language or database target.
+
+## Responsibilities
+
+- **Core Contract Types**: Defines framework-level contract types (`ContractBase`, `Source`) that are shared across all target families
+- **Document Family Types**: Provides TypeScript types for document target family contracts (`DocumentContract`)
+- **JSON Schema Validation**: Provides JSON Schemas for validating contract structure in IDEs and tooling
+- **Type Guards**: Provides runtime type guards for narrowing contract types (`isDocumentContract`)
+- **Emitter Types**: Defines emitter SPI types (`TargetFamilyHook`, `ValidationContext`, `TypesImportSpec`) that are shared between emitter and control plane
+
+The contract supports document target families:
+- **Document**: For document databases (MongoDB, Firestore, etc.)
+
+## Package Contents
+
+- **TypeScript Types**: Type definitions for `DocumentContract`, `ContractMarkerRecord`, and related types
+- **Emitter Types**: SPI types for emitter hooks (`TargetFamilyHook`, `ValidationContext`, `TypesImportSpec`)
+- **JSON Schemas**: Schema definitions for validating `contract.json` files in IDEs and tooling
+  - `data-contract-document-v1.json` (Document family)
+
+## Usage
+
+### TypeScript Types
+
+Import contract types in your TypeScript code:
+
+```typescript
+import type {
+  ContractMarkerRecord,
+  DocumentContract,
+  TargetFamilyHook,
+  TypesImportSpec,
+  ValidationContext,
+} from '@prisma-next/contract/types';
+import { isDocumentContract } from '@prisma-next/contract/types';
+
+// Use type guards to narrow the contract type
+function processContract(contract: DocumentContract) {
+  if (isDocumentContract(contract)) {
+    // contract is DocumentContract
+    console.log(contract.storage.document.collections);
+  }
+}
+
+// Use ContractMarkerRecord for database marker operations
+function processMarker(marker: ContractMarkerRecord) {
+  console.log(marker.coreHash, marker.profileHash);
+}
+
+// Use emitter types for implementing family hooks
+const myFamilyHook: TargetFamilyHook = {
+  id: 'my-family',
+  validateTypes: (ir, ctx: ValidationContext) => {
+    // Validation logic
+  },
+  validateStructure: (ir) => {
+    // Structure validation
+  },
+  generateContractTypes: (ir, codecTypeImports: TypesImportSpec[], operationTypeImports: TypesImportSpec[]) => {
+    // Type generation
+    return '// Generated types...';
+  },
+};
+```
+
+### JSON Schema Validation
+
+Reference the appropriate JSON schema in your `contract.json` files to enable IDE validation and autocomplete.
+
+#### Document Family
+
+For document targets (MongoDB, Firestore, etc.):
+
+```json
+{
+  "$schema": "node_modules/@prisma-next/contract/schemas/data-contract-document-v1.json",
+  "schemaVersion": "1",
+  "target": "mongodb",
+  "targetFamily": "document",
+  "coreHash": "sha256:...",
+  "storage": {
+    "document": {
+      "collections": {
+        "users": {
+          "name": "users",
+          "fields": {
+            "id": { "type": "objectId", "nullable": false },
+            "email": { "type": "string", "nullable": false }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Note:** For SQL contracts, use `@prisma-next/sql-query/schema-sql` instead:
+
+```json
+{
+  "$schema": "node_modules/@prisma-next/sql-query/schemas/data-contract-sql-v1.json",
+  "schemaVersion": "1",
+  "target": "postgres",
+  "targetFamily": "sql",
+  "coreHash": "sha256:...",
+  "storage": {
+    "tables": {
+      "user": {
+        "columns": {
+          "id": { "type": "int4", "nullable": false },
+          "email": { "type": "text", "nullable": false }
+        },
+        "primaryKey": {
+          "columns": ["id"],
+          "name": "user_pkey"
+        }
+      }
+    }
+  }
+}
+```
+
+After installing this package, IDEs like VS Code will automatically:
+- Validate your contract structure
+- Provide autocomplete for properties
+- Show descriptions and constraints in tooltips
+- Highlight errors for invalid configurations
+
+## Schema Reference
+
+### Common Header Fields
+
+All contracts share these common fields:
+
+- **`schemaVersion`** (required): Contract schema version (currently `"1"`)
+- **`target`** (required): Database target identifier (e.g., `"postgres"`, `"mongo"`, `"firestore"`)
+- **`targetFamily`** (required): Target family classification (`"document"` for document contracts)
+- **`coreHash`** (required): SHA-256 hash of the core schema structure
+- **`profileHash`** (optional): SHA-256 hash of the capability profile
+- **`capabilities`** (optional): Capability flags declared by the contract
+- **`extensions`** (optional): Extension packs and their configuration
+- **`meta`** (optional): Non-semantic metadata (excluded from hashing)
+- **`sources`** (optional): Read-only sources (views, etc.) available for querying
+
+### Document Family Structure
+
+- **`storage.document.collections`**: Object mapping collection names to collection definitions
+  - Each collection includes:
+    - **`name`**: Logical collection name
+    - **`id`** (optional): ID generation strategy (`auto`, `client`, `uuid`, `cuid`, `objectId`)
+    - **`fields`**: Field definitions using `FieldType` (supports nested objects and arrays)
+    - **`indexes`** (optional): Array of index definitions with keys and optional predicates
+    - **`readOnly`** (optional): Whether mutations are disallowed
+
+## Type System
+
+### Type Guards
+
+Use type guards to narrow the contract type:
+
+```typescript
+import { isDocumentContract } from '@prisma-next/contract/types';
+
+if (isDocumentContract(contract)) {
+  // TypeScript knows contract is DocumentContract
+  const collections = contract.storage.document.collections;
+}
+```
+
+## Exports
+
+- `./types`: TypeScript type definitions and type guards
+- `./schema-document`: Document family JSON Schema (`schemas/data-contract-document-v1.json`)
+
+## Architecture
+
+```mermaid
+flowchart TD
+    subgraph "Contract Package"
+        TYPES[Type Definitions]
+        SCHEMA[JSON Schemas]
+        GUARDS[Type Guards]
+    end
+
+    subgraph "Consumers"
+        EMITTER[Emitter]
+        RUNTIME[Runtime]
+        QUERY[Query Builder]
+    end
+
+    TYPES --> EMITTER
+    TYPES --> RUNTIME
+    TYPES --> QUERY
+    SCHEMA --> EMITTER
+    GUARDS --> RUNTIME
+    GUARDS --> QUERY
+```
+
+## Related Subsystems
+
+- **[Data Contract](../../docs/architecture%20docs/subsystems/1.%20Data%20Contract.md)**: Detailed subsystem specification
+- **[Contract Emitter & Types](../../docs/architecture%20docs/subsystems/2.%20Contract%20Emitter%20&%20Types.md)**: Contract emission
+
+## Related ADRs
+
+- [ADR 001 - Migrations as Edges](../../docs/architecture%20docs/adrs/ADR%20001%20-%20Migrations%20as%20Edges.md)
+- [ADR 004 - Core Hash vs Profile Hash](../../docs/architecture%20docs/adrs/ADR%20004%20-%20Core%20Hash%20vs%20Profile%20Hash.md)
+- [ADR 006 - Dual Authoring Modes](../../docs/architecture%20docs/adrs/ADR%20006%20-%20Dual%20Authoring%20Modes.md)
+- [ADR 010 - Canonicalization Rules](../../docs/architecture%20docs/adrs/ADR%20010%20-%20Canonicalization%20Rules.md)
+- [ADR 021 - Contract Marker Storage](../../docs/architecture%20docs/adrs/ADR%20021%20-%20Contract%20Marker%20Storage.md)
+
+## Dependencies
+
+- **`@prisma-next/operations`**: For `OperationRegistry` type used in `ValidationContext` and `TargetFamilyHook`
+- **Note**: This package depends on `@prisma-next/operations`, but `@prisma-next/operations` does not depend on this package (no cycle). The `OperationRegistry` type is used in emitter SPI types that are shared between migration-plane and shared-plane packages.
+
+**Dependents:**
+- **`@prisma-next/contract-authoring`**: Uses core contract types for authoring
+- **`@prisma-next/sql-contract`**: Extends core contract types for SQL family
+- **`@prisma-next/emitter`**: Uses contract types for emission
+- **`@prisma-next/runtime`**: Uses contract types for runtime execution
+- **`@prisma-next/sql-query`**: Uses contract types for query building
+
+## Related Packages
+
+- `@prisma-next/sql-query`: SQL query builder and plan types
+- `@prisma-next/runtime`: Runtime execution engine that consumes contracts

package/dist/exports/ir.d.ts

@@ -0,0 +1,77 @@
+/**
+ * ContractIR types and factories for building contract intermediate representation.
+ * ContractIR is family-agnostic and used by authoring, emitter, and no-emit runtime.
+ */
+/**
+ * ContractIR represents the intermediate representation of a contract.
+ * It is family-agnostic and contains generic storage, models, and relations.
+ * Note: coreHash and profileHash are computed by the emitter, not part of the IR.
+ */
+interface ContractIR<TStorage extends Record<string, unknown> = Record<string, unknown>, TModels extends Record<string, unknown> = Record<string, unknown>, TRelations extends Record<string, unknown> = Record<string, unknown>> {
+    readonly schemaVersion: string;
+    readonly targetFamily: string;
+    readonly target: string;
+    readonly models: TModels;
+    readonly relations: TRelations;
+    readonly storage: TStorage;
+    readonly extensions: Record<string, unknown>;
+    readonly capabilities: Record<string, Record<string, boolean>>;
+    readonly meta: Record<string, unknown>;
+    readonly sources: Record<string, unknown>;
+}
+/**
+ * Creates the header portion of a ContractIR.
+ * Contains schema version, target, target family, core hash, and optional profile hash.
+ */
+declare function irHeader(opts: {
+    target: string;
+    targetFamily: string;
+    coreHash: string;
+    profileHash?: string;
+}): {
+    readonly schemaVersion: string;
+    readonly target: string;
+    readonly targetFamily: string;
+    readonly coreHash: string;
+    readonly profileHash?: string;
+};
+/**
+ * Creates the meta portion of a ContractIR.
+ * Contains capabilities, extensions, meta, and sources with empty object defaults.
+ * If a field is explicitly `undefined`, it will be omitted (for testing validation).
+ */
+declare function irMeta(opts?: {
+    capabilities?: Record<string, Record<string, boolean>> | undefined;
+    extensions?: Record<string, unknown> | undefined;
+    meta?: Record<string, unknown> | undefined;
+    sources?: Record<string, unknown> | undefined;
+}): {
+    readonly capabilities: Record<string, Record<string, boolean>>;
+    readonly extensions: Record<string, unknown>;
+    readonly meta: Record<string, unknown>;
+    readonly sources: Record<string, unknown>;
+};
+/**
+ * Creates a complete ContractIR by combining header, meta, and family-specific sections.
+ * This is a family-agnostic factory that accepts generic storage, models, and relations.
+ */
+declare function contractIR<TStorage extends Record<string, unknown>, TModels extends Record<string, unknown>, TRelations extends Record<string, unknown>>(opts: {
+    header: {
+        readonly schemaVersion: string;
+        readonly target: string;
+        readonly targetFamily: string;
+        readonly coreHash: string;
+        readonly profileHash?: string;
+    };
+    meta: {
+        readonly capabilities: Record<string, Record<string, boolean>>;
+        readonly extensions: Record<string, unknown>;
+        readonly meta: Record<string, unknown>;
+        readonly sources: Record<string, unknown>;
+    };
+    storage: TStorage;
+    models: TModels;
+    relations: TRelations;
+}): ContractIR<TStorage, TModels, TRelations>;
+
+export { type ContractIR, contractIR, irHeader, irMeta };

package/dist/exports/ir.js

@@ -0,0 +1,35 @@
+// src/ir.ts
+function irHeader(opts) {
+  return {
+    schemaVersion: "1",
+    target: opts.target,
+    targetFamily: opts.targetFamily,
+    coreHash: opts.coreHash,
+    ...opts.profileHash !== void 0 && { profileHash: opts.profileHash }
+  };
+}
+function irMeta(opts) {
+  return {
+    capabilities: opts?.capabilities ?? {},
+    extensions: opts?.extensions ?? {},
+    meta: opts?.meta ?? {},
+    sources: opts?.sources ?? {}
+  };
+}
+function contractIR(opts) {
+  return {
+    schemaVersion: opts.header.schemaVersion,
+    target: opts.header.target,
+    targetFamily: opts.header.targetFamily,
+    ...opts.meta,
+    storage: opts.storage,
+    models: opts.models,
+    relations: opts.relations
+  };
+}
+export {
+  contractIR,
+  irHeader,
+  irMeta
+};
+//# sourceMappingURL=ir.js.map

package/dist/exports/ir.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ir.ts"],"sourcesContent":["/**\n * ContractIR types and factories for building contract intermediate representation.\n * ContractIR is family-agnostic and used by authoring, emitter, and no-emit runtime.\n */\n\n/**\n * ContractIR represents the intermediate representation of a contract.\n * It is family-agnostic and contains generic storage, models, and relations.\n * Note: coreHash and profileHash are computed by the emitter, not part of the IR.\n */\nexport interface ContractIR<\n  TStorage extends Record<string, unknown> = Record<string, unknown>,\n  TModels extends Record<string, unknown> = Record<string, unknown>,\n  TRelations extends Record<string, unknown> = Record<string, unknown>,\n> {\n  readonly schemaVersion: string;\n  readonly targetFamily: string;\n  readonly target: string;\n  readonly models: TModels;\n  readonly relations: TRelations;\n  readonly storage: TStorage;\n  readonly extensions: Record<string, unknown>;\n  readonly capabilities: Record<string, Record<string, boolean>>;\n  readonly meta: Record<string, unknown>;\n  readonly sources: Record<string, unknown>;\n}\n\n/**\n * Creates the header portion of a ContractIR.\n * Contains schema version, target, target family, core hash, and optional profile hash.\n */\nexport function irHeader(opts: {\n  target: string;\n  targetFamily: string;\n  coreHash: string;\n  profileHash?: string;\n}): {\n  readonly schemaVersion: string;\n  readonly target: string;\n  readonly targetFamily: string;\n  readonly coreHash: string;\n  readonly profileHash?: string;\n} {\n  return {\n    schemaVersion: '1',\n    target: opts.target,\n    targetFamily: opts.targetFamily,\n    coreHash: opts.coreHash,\n    ...(opts.profileHash !== undefined && { profileHash: opts.profileHash }),\n  };\n}\n\n/**\n * Creates the meta portion of a ContractIR.\n * Contains capabilities, extensions, meta, and sources with empty object defaults.\n * If a field is explicitly `undefined`, it will be omitted (for testing validation).\n */\nexport function irMeta(opts?: {\n  capabilities?: Record<string, Record<string, boolean>> | undefined;\n  extensions?: Record<string, unknown> | undefined;\n  meta?: Record<string, unknown> | undefined;\n  sources?: Record<string, unknown> | undefined;\n}): {\n  readonly capabilities: Record<string, Record<string, boolean>>;\n  readonly extensions: Record<string, unknown>;\n  readonly meta: Record<string, unknown>;\n  readonly sources: Record<string, unknown>;\n} {\n  return {\n    capabilities: opts?.capabilities ?? {},\n    extensions: opts?.extensions ?? {},\n    meta: opts?.meta ?? {},\n    sources: opts?.sources ?? {},\n  };\n}\n\n/**\n * Creates a complete ContractIR by combining header, meta, and family-specific sections.\n * This is a family-agnostic factory that accepts generic storage, models, and relations.\n */\nexport function contractIR<\n  TStorage extends Record<string, unknown>,\n  TModels extends Record<string, unknown>,\n  TRelations extends Record<string, unknown>,\n>(opts: {\n  header: {\n    readonly schemaVersion: string;\n    readonly target: string;\n    readonly targetFamily: string;\n    readonly coreHash: string;\n    readonly profileHash?: string;\n  };\n  meta: {\n    readonly capabilities: Record<string, Record<string, boolean>>;\n    readonly extensions: Record<string, unknown>;\n    readonly meta: Record<string, unknown>;\n    readonly sources: Record<string, unknown>;\n  };\n  storage: TStorage;\n  models: TModels;\n  relations: TRelations;\n}): ContractIR<TStorage, TModels, TRelations> {\n  // ContractIR doesn't include coreHash or profileHash (those are computed by emitter)\n  return {\n    schemaVersion: opts.header.schemaVersion,\n    target: opts.header.target,\n    targetFamily: opts.header.targetFamily,\n    ...opts.meta,\n    storage: opts.storage,\n    models: opts.models,\n    relations: opts.relations,\n  };\n}\n"],"mappings":";AA+BO,SAAS,SAAS,MAWvB;AACA,SAAO;AAAA,IACL,eAAe;AAAA,IACf,QAAQ,KAAK;AAAA,IACb,cAAc,KAAK;AAAA,IACnB,UAAU,KAAK;AAAA,IACf,GAAI,KAAK,gBAAgB,UAAa,EAAE,aAAa,KAAK,YAAY;AAAA,EACxE;AACF;AAOO,SAAS,OAAO,MAUrB;AACA,SAAO;AAAA,IACL,cAAc,MAAM,gBAAgB,CAAC;AAAA,IACrC,YAAY,MAAM,cAAc,CAAC;AAAA,IACjC,MAAM,MAAM,QAAQ,CAAC;AAAA,IACrB,SAAS,MAAM,WAAW,CAAC;AAAA,EAC7B;AACF;AAMO,SAAS,WAId,MAiB4C;AAE5C,SAAO;AAAA,IACL,eAAe,KAAK,OAAO;AAAA,IAC3B,QAAQ,KAAK,OAAO;AAAA,IACpB,cAAc,KAAK,OAAO;AAAA,IAC1B,GAAG,KAAK;AAAA,IACR,SAAS,KAAK;AAAA,IACd,QAAQ,KAAK;AAAA,IACb,WAAW,KAAK;AAAA,EAClB;AACF;","names":[]}

package/dist/exports/pack-manifest-types.d.ts

@@ -0,0 +1,3 @@
+export { A as ArgSpecManifest, E as ExtensionPack, a as ExtensionPackManifest, L as LoweringSpecManifest, O as OperationManifest, R as ReturnSpecManifest } from './types.js';
+import '@prisma-next/operations';
+import './ir.js';

package/dist/exports/pack-manifest-types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=pack-manifest-types.js.map

package/dist/exports/pack-manifest-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/exports/types.d.ts

@@ -0,0 +1,250 @@
+import { OperationRegistry } from '@prisma-next/operations';
+import { ContractIR } from './ir.js';
+
+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 extensions?: Record<string, unknown>;
+    readonly meta?: Record<string, unknown>;
+    readonly sources?: Record<string, Source>;
+}
+interface FieldType {
+    readonly type: string;
+    readonly nullable: boolean;
+    readonly items?: FieldType;
+    readonly properties?: Record<string, FieldType>;
+}
+interface Source {
+    readonly readOnly: boolean;
+    readonly projection: Record<string, FieldType>;
+    readonly origin?: Record<string, unknown>;
+    readonly capabilities?: Record<string, boolean>;
+}
+interface DocIndex {
+    readonly name: string;
+    readonly keys: Record<string, 'asc' | 'desc'>;
+    readonly unique?: boolean;
+    readonly where?: Expr;
+}
+type Expr = {
+    readonly kind: 'eq';
+    readonly path: ReadonlyArray<string>;
+    readonly value: unknown;
+} | {
+    readonly kind: 'exists';
+    readonly path: ReadonlyArray<string>;
+};
+interface DocCollection {
+    readonly name: string;
+    readonly id?: {
+        readonly strategy: 'auto' | 'client' | 'uuid' | 'cuid' | 'objectId';
+    };
+    readonly fields: Record<string, FieldType>;
+    readonly indexes?: ReadonlyArray<DocIndex>;
+    readonly readOnly?: boolean;
+}
+interface DocumentStorage {
+    readonly document: {
+        readonly collections: Record<string, DocCollection>;
+    };
+}
+interface DocumentContract extends ContractBase {
+    readonly targetFamily: string;
+    readonly storage: DocumentStorage;
+}
+interface ParamDescriptor {
+    readonly index?: number;
+    readonly name?: string;
+    readonly type?: string;
+    readonly nullable?: boolean;
+    readonly source: 'dsl' | 'raw';
+    readonly refs?: {
+        table: string;
+        column: string;
+    };
+}
+interface PlanRefs {
+    readonly tables?: readonly string[];
+    readonly columns?: ReadonlyArray<{
+        table: string;
+        column: string;
+    }>;
+    readonly indexes?: ReadonlyArray<{
+        readonly table: string;
+        readonly columns: ReadonlyArray<string>;
+        readonly name?: string;
+    }>;
+}
+interface PlanMeta {
+    readonly target: string;
+    readonly targetFamily?: string;
+    readonly coreHash: string;
+    readonly profileHash?: string;
+    readonly lane: string;
+    readonly annotations?: {
+        codecs?: Record<string, string>;
+        [key: string]: unknown;
+    };
+    readonly paramDescriptors: ReadonlyArray<ParamDescriptor>;
+    readonly refs?: PlanRefs;
+    readonly projection?: Record<string, string> | ReadonlyArray<string>;
+    /**
+     * Optional mapping of projection alias → column type ID (fully qualified ns/name@version).
+     * Used for codec resolution when AST+refs don't provide enough type info.
+     */
+    readonly projectionTypes?: Record<string, string>;
+}
+/**
+ * Canonical execution plan shape used by runtimes.
+ *
+ * - Row is the inferred result row type (TypeScript-only).
+ * - Ast is the optional, family-specific AST type (e.g. SQL QueryAst).
+ *
+ * The payload executed by the runtime is represented by the sql + params pair
+ * for now; future families can specialize this via Ast or additional metadata.
+ */
+interface ExecutionPlan<Row = unknown, Ast = unknown> {
+    readonly sql: string;
+    readonly params: readonly unknown[];
+    readonly ast?: Ast;
+    readonly meta: PlanMeta;
+    /**
+     * Phantom property to carry the Row generic for type-level utilities.
+     * Not set at runtime; used only for ResultType extraction.
+     */
+    readonly _row?: Row;
+}
+/**
+ * Utility type to extract the Row type from an ExecutionPlan.
+ * Example: `type Row = ResultType<typeof plan>`
+ *
+ * Works with both ExecutionPlan and SqlQueryPlan (SQL query plans before lowering).
+ * SqlQueryPlan includes a phantom `_Row` property to preserve the generic parameter
+ * for type extraction.
+ */
+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
+ */
+declare function isDocumentContract(contract: unknown): contract is DocumentContract;
+/**
+ * Contract marker record stored in the database.
+ * Represents the current contract identity for a database.
+ */
+interface ContractMarkerRecord {
+    readonly coreHash: string;
+    readonly profileHash: string;
+    readonly contractJson: unknown | null;
+    readonly canonicalVersion: number | null;
+    readonly updatedAt: Date;
+    readonly appTag: string | null;
+    readonly meta: Record<string, unknown>;
+}
+/**
+ * Specifies how to import TypeScript types from a package.
+ * Used in extension pack manifests to declare codec and operation type imports.
+ */
+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.
+ */
+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).
+ */
+interface TargetFamilyHook {
+    readonly id: string;
+    /**
+     * Validates that all type IDs in the contract come from referenced extensions.
+     * @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;
+}
+type ArgSpecManifest = {
+    readonly kind: 'typeId';
+    readonly type: string;
+} | {
+    readonly kind: 'param';
+} | {
+    readonly kind: 'literal';
+};
+type ReturnSpecManifest = {
+    readonly kind: 'typeId';
+    readonly type: string;
+} | {
+    readonly kind: 'builtin';
+    readonly type: 'number' | 'boolean' | 'string';
+};
+interface LoweringSpecManifest {
+    readonly targetFamily: 'sql';
+    readonly strategy: 'infix' | 'function';
+    readonly template: string;
+}
+interface OperationManifest {
+    readonly for: string;
+    readonly method: string;
+    readonly args: ReadonlyArray<ArgSpecManifest>;
+    readonly returns: ReturnSpecManifest;
+    readonly lowering: LoweringSpecManifest;
+    readonly capabilities?: ReadonlyArray<string>;
+}
+interface ExtensionPackManifest {
+    readonly id: string;
+    readonly version: string;
+    readonly targets?: Record<string, {
+        readonly minVersion?: string;
+    }>;
+    readonly capabilities?: Record<string, unknown>;
+    readonly types?: {
+        readonly codecTypes?: {
+            readonly import: TypesImportSpec;
+        };
+        readonly operationTypes?: {
+            readonly import: TypesImportSpec;
+        };
+        readonly storage?: readonly {
+            readonly typeId: string;
+            readonly familyId: string;
+            readonly targetId: string;
+            readonly nativeType?: string;
+        }[];
+    };
+    readonly operations?: ReadonlyArray<OperationManifest>;
+}
+interface ExtensionPack {
+    readonly manifest: ExtensionPackManifest;
+    readonly path: string;
+}
+
+export { type ArgSpecManifest as A, type ContractBase, type ContractMarkerRecord, type DocCollection, type DocIndex, type DocumentContract, type DocumentStorage, type ExtensionPack as E, type ExecutionPlan, type Expr, type FieldType, type LoweringSpecManifest as L, type OperationManifest as O, type ParamDescriptor, type PlanMeta, type PlanRefs, type ReturnSpecManifest as R, type ResultType, type Source, type TargetFamilyHook, type TypesImportSpec, type ValidationContext, type ExtensionPackManifest as a, isDocumentContract };

package/dist/exports/types.js

@@ -0,0 +1,8 @@
+// src/types.ts
+function isDocumentContract(contract) {
+  return typeof contract === "object" && contract !== null && "targetFamily" in contract && contract.targetFamily === "document";
+}
+export {
+  isDocumentContract
+};
+//# sourceMappingURL=types.js.map

package/dist/exports/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types.ts"],"sourcesContent":["import type { OperationRegistry } from '@prisma-next/operations';\nimport type { ContractIR } from './ir';\n\n// Shared header and neutral types\n// Note: Fields like targetFamily accept string to work with JSON imports,\n// which don't preserve literal types. Runtime validation ensures correct values\nexport interface ContractBase {\n  readonly schemaVersion: string;\n  readonly target: string;\n  readonly targetFamily: string;\n  readonly coreHash: string;\n  readonly profileHash?: string;\n  readonly capabilities?: Record<string, Record<string, boolean>>;\n  readonly extensions?: Record<string, unknown>;\n  readonly meta?: Record<string, unknown>;\n  readonly sources?: Record<string, Source>;\n}\n\nexport interface FieldType {\n  readonly type: string;\n  readonly nullable: boolean;\n  readonly items?: FieldType;\n  readonly properties?: Record<string, FieldType>;\n}\n\nexport interface Source {\n  readonly readOnly: boolean;\n  readonly projection: Record<string, FieldType>;\n  readonly origin?: Record<string, unknown>;\n  readonly capabilities?: Record<string, boolean>;\n}\n\n// Document family types\nexport interface DocIndex {\n  readonly name: string;\n  readonly keys: Record<string, 'asc' | 'desc'>;\n  readonly unique?: boolean;\n  readonly where?: Expr;\n}\n\nexport type Expr =\n  | { readonly kind: 'eq'; readonly path: ReadonlyArray<string>; readonly value: unknown }\n  | { readonly kind: 'exists'; readonly path: ReadonlyArray<string> };\n\nexport interface DocCollection {\n  readonly name: string;\n  readonly id?: {\n    readonly strategy: 'auto' | 'client' | 'uuid' | 'cuid' | 'objectId';\n  };\n  readonly fields: Record<string, FieldType>;\n  readonly indexes?: ReadonlyArray<DocIndex>;\n  readonly readOnly?: boolean;\n}\n\nexport interface DocumentStorage {\n  readonly document: {\n    readonly collections: Record<string, DocCollection>;\n  };\n}\n\nexport interface DocumentContract extends ContractBase {\n  // Accept string to work with JSON imports; runtime validation ensures 'document'\n  readonly targetFamily: string;\n  readonly storage: DocumentStorage;\n}\n\n// Plan types - target-family agnostic execution types\nexport interface ParamDescriptor {\n  readonly index?: number;\n  readonly name?: string;\n  readonly type?: string;\n  readonly nullable?: boolean;\n  readonly source: 'dsl' | 'raw';\n  readonly refs?: { table: string; column: string };\n}\n\nexport interface PlanRefs {\n  readonly tables?: readonly string[];\n  readonly columns?: ReadonlyArray<{ table: string; column: string }>;\n  readonly indexes?: ReadonlyArray<{\n    readonly table: string;\n    readonly columns: ReadonlyArray<string>;\n    readonly name?: string;\n  }>;\n}\n\nexport interface PlanMeta {\n  readonly target: string;\n  readonly targetFamily?: string;\n  readonly coreHash: string;\n  readonly profileHash?: string;\n  readonly lane: string;\n  readonly annotations?: {\n    codecs?: Record<string, string>; // alias/param → codec id ('ns/name@v')\n    [key: string]: unknown;\n  };\n  readonly paramDescriptors: ReadonlyArray<ParamDescriptor>;\n  readonly refs?: PlanRefs;\n  readonly projection?: Record<string, string> | ReadonlyArray<string>;\n  /**\n   * Optional mapping of projection alias → column type ID (fully qualified ns/name@version).\n   * Used for codec resolution when AST+refs don't provide enough type info.\n   */\n  readonly projectionTypes?: Record<string, string>;\n}\n\n/**\n * Canonical execution plan shape used by runtimes.\n *\n * - Row is the inferred result row type (TypeScript-only).\n * - Ast is the optional, family-specific AST type (e.g. SQL QueryAst).\n *\n * The payload executed by the runtime is represented by the sql + params pair\n * for now; future families can specialize this via Ast or additional metadata.\n */\nexport interface ExecutionPlan<Row = unknown, Ast = unknown> {\n  readonly sql: string;\n  readonly params: readonly unknown[];\n  readonly ast?: Ast;\n  readonly meta: PlanMeta;\n  /**\n   * Phantom property to carry the Row generic for type-level utilities.\n   * Not set at runtime; used only for ResultType extraction.\n   */\n  readonly _row?: Row;\n}\n\n/**\n * Utility type to extract the Row type from an ExecutionPlan.\n * Example: `type Row = ResultType<typeof plan>`\n *\n * Works with both ExecutionPlan and SqlQueryPlan (SQL query plans before lowering).\n * SqlQueryPlan includes a phantom `_Row` property to preserve the generic parameter\n * for type extraction.\n */\nexport type ResultType<P> = P extends ExecutionPlan<infer R, unknown>\n  ? R\n  : P extends { readonly _Row?: infer R }\n    ? R\n    : never;\n\n/**\n * Type guard to check if a contract is a Document contract\n */\nexport function isDocumentContract(contract: unknown): contract is DocumentContract {\n  return (\n    typeof contract === 'object' &&\n    contract !== null &&\n    'targetFamily' in contract &&\n    contract.targetFamily === 'document'\n  );\n}\n\n/**\n * Contract marker record stored in the database.\n * Represents the current contract identity for a database.\n */\nexport interface ContractMarkerRecord {\n  readonly coreHash: string;\n  readonly profileHash: string;\n  readonly contractJson: unknown | null;\n  readonly canonicalVersion: number | null;\n  readonly updatedAt: Date;\n  readonly appTag: string | null;\n  readonly meta: Record<string, unknown>;\n}\n\n// Emitter types - moved from @prisma-next/emitter to shared location\n/**\n * Specifies how to import TypeScript types from a package.\n * Used in extension pack manifests to declare codec and operation type imports.\n */\nexport interface TypesImportSpec {\n  readonly package: string;\n  readonly named: string;\n  readonly alias: string;\n}\n\n/**\n * Validation context passed to TargetFamilyHook.validateTypes().\n * Contains pre-assembled operation registry, type imports, and extension IDs.\n */\nexport interface ValidationContext {\n  readonly operationRegistry?: OperationRegistry;\n  readonly codecTypeImports?: ReadonlyArray<TypesImportSpec>;\n  readonly operationTypeImports?: ReadonlyArray<TypesImportSpec>;\n  readonly extensionIds?: ReadonlyArray<string>;\n}\n\n/**\n * SPI interface for target family hooks that extend emission behavior.\n * Implemented by family-specific emitter hooks (e.g., SQL family).\n */\nexport interface TargetFamilyHook {\n  readonly id: string;\n\n  /**\n   * Validates that all type IDs in the contract come from referenced extensions.\n   * @param ir - Contract IR to validate\n   * @param ctx - Validation context with operation registry and extension IDs\n   */\n  validateTypes(ir: ContractIR, ctx: ValidationContext): void;\n\n  /**\n   * Validates family-specific contract structure.\n   * @param ir - Contract IR to validate\n   */\n  validateStructure(ir: ContractIR): void;\n\n  /**\n   * Generates contract.d.ts file content.\n   * @param ir - Contract IR\n   * @param codecTypeImports - Array of codec type import specs\n   * @param operationTypeImports - Array of operation type import specs\n   * @returns Generated TypeScript type definitions as string\n   */\n  generateContractTypes(\n    ir: ContractIR,\n    codecTypeImports: ReadonlyArray<TypesImportSpec>,\n    operationTypeImports: ReadonlyArray<TypesImportSpec>,\n  ): string;\n}\n\n// Extension pack manifest types - moved from @prisma-next/core-control-plane to shared location\nexport type ArgSpecManifest =\n  | { readonly kind: 'typeId'; readonly type: string }\n  | { readonly kind: 'param' }\n  | { readonly kind: 'literal' };\n\nexport type ReturnSpecManifest =\n  | { readonly kind: 'typeId'; readonly type: string }\n  | { readonly kind: 'builtin'; readonly type: 'number' | 'boolean' | 'string' };\n\nexport interface LoweringSpecManifest {\n  readonly targetFamily: 'sql';\n  readonly strategy: 'infix' | 'function';\n  readonly template: string;\n}\n\nexport interface OperationManifest {\n  readonly for: string;\n  readonly method: string;\n  readonly args: ReadonlyArray<ArgSpecManifest>;\n  readonly returns: ReturnSpecManifest;\n  readonly lowering: LoweringSpecManifest;\n  readonly capabilities?: ReadonlyArray<string>;\n}\n\nexport interface ExtensionPackManifest {\n  readonly id: string;\n  readonly version: string;\n  readonly targets?: Record<string, { readonly minVersion?: string }>;\n  readonly capabilities?: Record<string, unknown>;\n  readonly types?: {\n    readonly codecTypes?: {\n      readonly import: TypesImportSpec;\n    };\n    readonly operationTypes?: {\n      readonly import: TypesImportSpec;\n    };\n    readonly storage?: readonly {\n      readonly typeId: string;\n      readonly familyId: string;\n      readonly targetId: string;\n      readonly nativeType?: string;\n    }[];\n  };\n  readonly operations?: ReadonlyArray<OperationManifest>;\n}\n\nexport interface ExtensionPack {\n  readonly manifest: ExtensionPackManifest;\n  readonly path: string;\n}\n"],"mappings":";AAgJO,SAAS,mBAAmB,UAAiD;AAClF,SACE,OAAO,aAAa,YACpB,aAAa,QACb,kBAAkB,YAClB,SAAS,iBAAiB;AAE9B;","names":[]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@prisma-next/contract",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Data contract type definitions and JSON schema for Prisma Next",
+  "dependencies": {
+    "@prisma-next/operations": "0.0.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.1",
+    "tsup": "^8.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.1",
+    "@prisma-next/test-utils": "0.0.1"
+  },
+  "files": [
+    "dist",
+    "schemas"
+  ],
+  "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"
+    },
+    "./schema-document": "./schemas/data-contract-document-v1.json"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --config-path ../../../biome.json --error-on-warnings",
+    "clean": "node ../../scripts/clean.mjs"
+  }
+}

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

@@ -0,0 +1,262 @@
+{
+  "$id": "https://prisma.dev/schemas/data-contract-document-v1.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Prisma Next Data Contract Document v1",
+  "description": "Schema for Prisma Next contract.json files for Document target family (mongo, firestore, etc.)",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Reference to this JSON schema for IDE validation"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "enum": ["1"],
+      "description": "Contract schema version"
+    },
+    "target": {
+      "type": "string",
+      "description": "Database target identifier (e.g., 'mongo', 'firestore')"
+    },
+    "targetFamily": {
+      "type": "string",
+      "enum": ["document"],
+      "description": "Target family classification"
+    },
+    "coreHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 hash of the core schema structure (models, fields, relations, storage layout)"
+    },
+    "profileHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 hash of the pinned capability profile (capability keys/variants and adapter pins)"
+    },
+    "capabilities": {
+      "type": "object",
+      "description": "Capability flags declared by the contract",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "boolean"
+        }
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Extension packs and their configuration",
+      "additionalProperties": true
+    },
+    "meta": {
+      "type": "object",
+      "description": "Non-semantic metadata (excluded from hashing)",
+      "additionalProperties": true
+    },
+    "sources": {
+      "type": "object",
+      "description": "Read-only sources (views, etc.) available for querying",
+      "additionalProperties": {
+        "$ref": "#/$defs/Source"
+      }
+    },
+    "storage": {
+      "type": "object",
+      "description": "Storage layout definition",
+      "additionalProperties": false,
+      "properties": {
+        "document": {
+          "type": "object",
+          "description": "Document storage definition",
+          "additionalProperties": false,
+          "properties": {
+            "collections": {
+              "type": "object",
+              "description": "Collection definitions keyed by collection name",
+              "additionalProperties": {
+                "$ref": "#/$defs/DocCollection"
+              }
+            }
+          },
+          "required": ["collections"]
+        }
+      },
+      "required": ["document"]
+    }
+  },
+  "required": ["schemaVersion", "target", "targetFamily", "coreHash", "storage"],
+  "$defs": {
+    "DocCollection": {
+      "type": "object",
+      "description": "Document collection definition with fields and indexes",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Logical collection name"
+        },
+        "id": {
+          "type": "object",
+          "description": "ID generation strategy",
+          "additionalProperties": false,
+          "properties": {
+            "strategy": {
+              "type": "string",
+              "enum": ["auto", "client", "uuid", "cuid", "objectId"],
+              "description": "ID generation strategy"
+            }
+          }
+        },
+        "fields": {
+          "type": "object",
+          "description": "Field definitions keyed by field name",
+          "additionalProperties": {
+            "$ref": "#/$defs/FieldType"
+          }
+        },
+        "indexes": {
+          "type": "array",
+          "description": "Index definitions",
+          "items": {
+            "$ref": "#/$defs/DocIndex"
+          }
+        },
+        "readOnly": {
+          "type": "boolean",
+          "description": "Whether mutations are disallowed (mirrors views concept)"
+        }
+      },
+      "required": ["name", "fields"]
+    },
+    "DocIndex": {
+      "type": "object",
+      "description": "Document index definition with keys and optional predicate",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Index name"
+        },
+        "keys": {
+          "type": "object",
+          "description": "Field keys and sort order",
+          "additionalProperties": {
+            "type": "string",
+            "enum": ["asc", "desc"]
+          }
+        },
+        "unique": {
+          "type": "boolean",
+          "description": "Whether the index enforces uniqueness"
+        },
+        "where": {
+          "$ref": "#/$defs/Expr",
+          "description": "Optional predicate expression for partial indexes"
+        }
+      },
+      "required": ["name", "keys"]
+    },
+    "Expr": {
+      "type": "object",
+      "description": "Portable predicate expression AST",
+      "additionalProperties": false,
+      "oneOf": [
+        {
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["eq"]
+            },
+            "path": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Field path as array of strings"
+            },
+            "value": {
+              "description": "Comparison value"
+            }
+          },
+          "required": ["kind", "path", "value"]
+        },
+        {
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["exists"]
+            },
+            "path": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Field path as array of strings"
+            }
+          },
+          "required": ["kind", "path"]
+        }
+      ]
+    },
+    "FieldType": {
+      "type": "object",
+      "description": "Neutral field type definition for sources and document fields",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Field type identifier (e.g., 'int4', 'text', 'bool', 'object', 'array', 'date', 'bytes', 'id')"
+        },
+        "nullable": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the field allows null values"
+        },
+        "items": {
+          "$ref": "#/$defs/FieldType",
+          "description": "Item type for array fields"
+        },
+        "properties": {
+          "type": "object",
+          "description": "Property definitions for object fields",
+          "additionalProperties": {
+            "$ref": "#/$defs/FieldType"
+          }
+        }
+      },
+      "required": ["type", "nullable"]
+    },
+    "Source": {
+      "type": "object",
+      "description": "Read-only source definition for views and other queryable sources",
+      "additionalProperties": false,
+      "properties": {
+        "readOnly": {
+          "type": "boolean",
+          "description": "Whether mutations (INSERT/UPDATE/DELETE) are disallowed"
+        },
+        "projection": {
+          "type": "object",
+          "description": "Field projection mapping column/field name to FieldType",
+          "additionalProperties": {
+            "$ref": "#/$defs/FieldType"
+          }
+        },
+        "origin": {
+          "type": "object",
+          "description": "Provenance link to pack-owned block (e.g., view, enum)",
+          "additionalProperties": true
+        },
+        "capabilities": {
+          "type": "object",
+          "description": "Feature flags relevant to this source",
+          "additionalProperties": {
+            "type": "boolean"
+          }
+        }
+      },
+      "required": ["readOnly", "projection"]
+    }
+  }
+}