@prisma-next/sql-schema-ir 0.0.1

package/README.md

@@ -0,0 +1,147 @@
+# @prisma-next/sql-schema-ir
+
+SQL Schema Intermediate Representation (IR) types for Prisma Next.
+
+## Overview
+
+This package defines the core types for the SQL Schema IR, a target-agnostic representation of SQL database schemas. This IR is used for schema verification, migration planning, and other tooling operations within the SQL family.
+
+## Purpose
+
+- **Provide a canonical in-memory representation** of SQL schemas that is independent of specific database implementations
+- **Decouple schema introspection from verification logic** - adapters produce `SqlSchemaIR`, verification logic consumes it
+- **Enable extensible metadata** via annotations for targets and extension packs
+- **Support future migration planning** by providing a structured representation of schema differences
+
+## Responsibilities
+
+- **Type Definitions**: Provides core types for SQL Schema IR (`SqlSchemaIR`, `SqlTableIR`, `SqlColumnIR`, etc.)
+- **Shared Plane Package**: Located in the shared plane, making it accessible to both migration-plane and runtime-plane packages
+- **Extensibility**: Supports annotations for targets and extension packs to attach metadata without modifying core IR structure
+- **Type Safety**: Provides TypeScript types for schema representation with proper nullability and constraint modeling
+
+## Dependencies
+
+- **`@prisma-next/contract`**: For `ContractIR` type (used in `SqlContractIR`)
+
+**Dependents:**
+- **Migration Plane**:
+  - `@prisma-next/core-control-plane` - Core verification logic
+  - `@prisma-next/adapter-postgres` - Postgres introspection
+  - `@prisma-next/extension-pgvector` - Extension verification hooks
+- **Runtime Plane** (future):
+  - Migration planning logic
+  - Schema diff utilities
+
+## Types
+
+### Core Types
+
+- **`SqlSchemaIR`** - Complete database schema representation with tables, extensions, and annotations
+- **`SqlTableIR`** - Table representation with columns, constraints, indexes, and annotations
+- **`SqlColumnIR`** - Column representation with `typeId` (codec ID), `nativeType` (DB-specific type), nullability, and annotations
+- **`SqlForeignKeyIR`** - Foreign key constraint representation
+- **`SqlUniqueIR`** - Unique constraint representation
+- **`SqlIndexIR`** - Index representation
+- **`SqlAnnotations`** - Namespaced extensibility metadata (e.g., `{ pg: { version: '15' } }`)
+
+### Key Design Decisions
+
+1. **`typeId` vs `nativeType`**: Columns include both a codec ID (`typeId`, e.g., `'pg/int4@1'`) and an optional native database type (`nativeType`, e.g., `'integer'`). The codec ID provides target-agnostic type information, while `nativeType` enables verification of extension-specific types (e.g., `'vector'` for pgvector).
+
+2. **Annotations**: All IR types support optional `annotations` for extensibility. This allows targets and extensions to attach metadata without modifying the core IR structure.
+
+3. **Shared Plane**: This package is in the **shared plane**, meaning it can be safely imported by both migration-plane (verification, migration planning) and runtime-plane code.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import type { SqlSchemaIR, SqlTableIR, SqlColumnIR } from '@prisma-next/sql-schema-ir/types';
+
+const schemaIR: SqlSchemaIR = {
+  tables: {
+    user: {
+      name: 'user',
+      columns: {
+        id: {
+          name: 'id',
+          typeId: 'pg/int4@1',
+          nativeType: 'integer',
+          nullable: false,
+        },
+        email: {
+          name: 'email',
+          typeId: 'pg/text@1',
+          nativeType: 'text',
+          nullable: false,
+        },
+      },
+      primaryKey: { columns: ['id'] },
+      foreignKeys: [],
+      uniques: [{ columns: ['email'] }],
+      indexes: [],
+    },
+  },
+  extensions: ['vector'],
+  annotations: {
+    pg: {
+      version: '15',
+    },
+  },
+};
+```
+
+### Schema Introspection
+
+Adapters produce `SqlSchemaIR` by querying database catalogs:
+
+```typescript
+// In Postgres adapter
+import postgresAdapter from '@prisma-next/adapter-postgres/control';
+import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+
+const controlAdapter = postgresAdapter.createControlInstance();
+const schemaIR: SqlSchemaIR = await controlAdapter.introspect(driver, contract);
+```
+
+### Schema Verification
+
+The core control plane compares contracts against `SqlSchemaIR`:
+
+```typescript
+// In core-control-plane
+import { verifyDatabaseSchema } from '@prisma-next/core-control-plane/verify-database-schema';
+import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+
+const result = await verifyDatabaseSchema({
+  driver,
+  contractIR,
+  schemaIR, // Produced by family.introspectSchema
+  family,
+  target,
+  adapter,
+  extensions,
+  strict: false,
+});
+```
+
+## Architecture
+
+### Package Location
+
+- **Domain**: `sql`
+- **Layer**: `core`
+- **Plane**: `shared`
+
+This package sits at the core layer in the shared plane, making it accessible to both migration-plane (authoring, tooling, targets) and runtime-plane (lanes, runtime, adapters) packages.
+
+
+## Related Documentation
+
+- `docs/briefs/11-schema-ir.md` - Schema IR project brief
+- `docs/briefs/SQL Schema IR and Verification.md` - Detailed design document
+- `packages/framework/core-control-plane/src/actions/verify-database-schema.ts` - Core verification action
+- `packages/targets/postgres-adapter/src/exports/introspect.ts` - Postgres introspection implementation
+

package/dist/exports/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * SQL Schema IR types for target-agnostic schema representation.
+ *
+ * These types represent the canonical in-memory representation of SQL schemas
+ * for the SQL family, used for verification and future migration planning.
+ */
+/**
+ * Primary key definition matching ContractIR format.
+ * Defined here to avoid circular dependency with sql-contract.
+ */
+type PrimaryKey = {
+    readonly columns: readonly string[];
+    readonly name?: string;
+};
+/**
+ * Namespaced annotations for extensibility.
+ * Each namespace (e.g., 'pg', 'pgvector') owns its annotations.
+ */
+type SqlAnnotations = {
+    readonly [namespace: string]: unknown;
+};
+/**
+ * SQL column IR representing a column in a table.
+ */
+type SqlColumnIR = {
+    readonly name: string;
+    readonly typeId: string;
+    readonly nativeType?: string;
+    readonly nullable: boolean;
+    readonly annotations?: SqlAnnotations;
+};
+/**
+ * SQL foreign key IR.
+ */
+type SqlForeignKeyIR = {
+    readonly columns: readonly string[];
+    readonly referencedTable: string;
+    readonly referencedColumns: readonly string[];
+    readonly name?: string;
+    readonly annotations?: SqlAnnotations;
+};
+/**
+ * SQL unique constraint IR.
+ */
+type SqlUniqueIR = {
+    readonly columns: readonly string[];
+    readonly name?: string;
+    readonly annotations?: SqlAnnotations;
+};
+/**
+ * SQL index IR.
+ */
+type SqlIndexIR = {
+    readonly columns: readonly string[];
+    readonly name?: string;
+    readonly unique: boolean;
+    readonly annotations?: SqlAnnotations;
+};
+/**
+ * SQL table IR representing a table in the schema.
+ * Primary key format matches ContractIR for consistency.
+ */
+type SqlTableIR = {
+    readonly name: string;
+    readonly columns: Record<string, SqlColumnIR>;
+    readonly primaryKey?: PrimaryKey;
+    readonly foreignKeys: readonly SqlForeignKeyIR[];
+    readonly uniques: readonly SqlUniqueIR[];
+    readonly indexes: readonly SqlIndexIR[];
+    readonly annotations?: SqlAnnotations;
+};
+/**
+ * SQL Schema IR representing the complete database schema.
+ * This is the target-agnostic representation used for verification and migration planning.
+ */
+type SqlSchemaIR = {
+    readonly tables: Record<string, SqlTableIR>;
+    readonly extensions: readonly string[];
+    readonly annotations?: SqlAnnotations;
+};
+/**
+ * SQL type metadata for control-plane and execution-plane type availability and mapping.
+ * This abstraction provides a read-only view of type information without encode/decode behavior.
+ */
+interface SqlTypeMetadata {
+    /**
+     * Namespaced type identifier in format 'namespace/name@version'
+     * Examples: 'pg/int4@1', 'pg/text@1', 'pg/timestamptz@1'
+     */
+    readonly typeId: string;
+    /**
+     * Contract scalar type IDs that this type can handle.
+     * Examples: ['text'], ['int4', 'float8'], ['timestamp', 'timestamptz']
+     */
+    readonly targetTypes: readonly string[];
+    /**
+     * Native database type name (target-specific).
+     * Examples: 'integer', 'text', 'character varying', 'timestamp with time zone'
+     * This is optional because not all types have a native database representation.
+     */
+    readonly nativeType?: string;
+}
+/**
+ * Registry interface for SQL type metadata.
+ * Provides read-only iteration over type metadata entries.
+ */
+interface SqlTypeMetadataRegistry {
+    /**
+     * Returns an iterator over all type metadata entries.
+     */
+    values(): IterableIterator<SqlTypeMetadata>;
+}
+
+export type { PrimaryKey, SqlAnnotations, SqlColumnIR, SqlForeignKeyIR, SqlIndexIR, SqlSchemaIR, SqlTableIR, SqlTypeMetadata, SqlTypeMetadataRegistry, SqlUniqueIR };

package/dist/exports/types.js

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

package/dist/exports/types.js.map

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@prisma-next/sql-schema-ir",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "SQL Schema IR types for schema introspection and verification",
+  "dependencies": {
+    "@prisma-next/contract": "0.0.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.1",
+    "tsup": "^8.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.1"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./types": {
+      "types": "./dist/exports/types.d.ts",
+      "import": "./dist/exports/types.js"
+    }
+  },
+  "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"
+  }
+}