@prisma-next/family-sql 0.0.1

package/README.md

@@ -0,0 +1,90 @@
+# @prisma-next/family-sql
+
+SQL family descriptor for Prisma Next.
+
+## Purpose
+
+Provides the SQL family descriptor (`ControlFamilyDescriptor`) that includes:
+- The SQL target family hook (`sqlTargetFamilyHook`)
+- Factory method (`create()`) to create family instances
+
+## Responsibilities
+
+- **Family Descriptor Export**: Exports the SQL `ControlFamilyDescriptor` for use in CLI configuration files
+- **Family Instance Creation**: Creates `SqlFamilyInstance` objects that implement control-plane domain actions (`verify`, `schemaVerify`, `introspect`, `emitContract`, `validateContractIR`)
+- **Family Hook Integration**: Integrates the SQL target family hook (`sqlTargetFamilyHook`) from `@prisma-next/sql-contract-emitter`
+- **Control Plane Entry Point**: Serves as the control plane entry point for the SQL family, enabling the CLI to select the family hook and create family instances
+
+## Usage
+
+```typescript
+import sql from '@prisma-next/family-sql/control';
+
+// sql is a ControlFamilyDescriptor with:
+// - kind: 'family'
+// - id: 'sql'
+// - familyId: 'sql'
+// - hook: TargetFamilyHook
+// - create: (options) => SqlFamilyInstance
+
+// Create a family instance for control-plane operations
+const familyInstance = sql.create({
+  target: postgresTargetDescriptor,
+  adapter: postgresAdapterDescriptor,
+  driver: postgresDriverDescriptor, // Required
+  extensions: [pgVectorExtensionDescriptor],
+});
+
+// Use instance methods for domain actions
+const contractIR = familyInstance.validateContractIR(contractJson);
+const verifyResult = await familyInstance.verify({ driver, contractIR, ... });
+const emitResult = await familyInstance.emitContract({ contractIR: rawContract }); // Handles stripping mappings and validation internally
+```
+
+## Architecture
+
+This package is the control plane entry point for the SQL family. It composes:
+- `@prisma-next/sql-contract-emitter` - Provides the SQL family hook
+- `@prisma-next/sql-operations` - SQL operation signature types
+- `@prisma-next/sql-contract-ts` - Contract validation
+
+The framework CLI uses this descriptor to:
+1. Create family instances for control-plane operations (via `create()`)
+
+Family instances implement domain actions:
+- **`validateContractIR(contractJson)`**: Validates and normalizes contract, returns ContractIR without mappings
+- **`verify()`**: Verifies database marker against contract (compares target, coreHash, profileHash)
+- **`schemaVerify()`**: Verifies database schema against contract (compares contract requirements vs live schema)
+- **`introspect()`**: Introspects database schema and returns `SqlSchemaIR`
+- **`toSchemaView(schema)`**: Projects `SqlSchemaIR` into `CoreSchemaView` for human-readable display. Always displays native database types (e.g., `int4`, `text`) rather than mapped codec IDs (e.g., `pg/int4@1`) to reflect actual database state.
+- **`emitContract({ contractIR })`**: Emits contract JSON and DTS as strings. Handles stripping mappings and validation internally. Uses preassembled state (operation registry, type imports, extension IDs).
+
+The descriptor is "pure data + factory" - it only provides the hook and factory method. All family-specific logic lives on the instance.
+
+## Package Structure
+
+- **`src/core/descriptor.ts`**: `SqlFamilyDescriptor` class implementing `ControlFamilyDescriptor` interface (pure data + factory)
+- **`src/core/instance.ts`**: `createSqlFamilyInstance` function that creates `SqlFamilyInstance` with domain action methods (`validateContractIR`, `verify`, `schemaVerify`, `introspect`, `toSchemaView`, `emitContract`). Contains `convertOperationManifest` function used internally by instance creation and test utilities in the same package.
+- **`src/core/assembly.ts`**: Assembly helpers for building operation registries and extracting type imports from descriptors. Test utilities import `convertOperationManifest` from the same package via relative path.
+- **`src/core/verify.ts`**: Verification helpers (`readMarker`, `collectSupportedCodecTypeIds`)
+- **`src/core/control-adapter.ts`**: SQL control adapter interface (`SqlControlAdapter`) for control-plane operations
+- **`src/exports/control.ts`**: Control plane entry point (exports `SqlFamilyDescriptor` instance)
+- **`src/exports/runtime.ts`**: Runtime entry point (placeholder for future functionality)
+
+## Entrypoints
+
+- **`./control`**: Control plane entry point for CLI/config usage (exports `SqlFamilyDescriptor`)
+- **`./control-adapter`**: SQL control adapter interface (`SqlControlAdapter`, `SqlControlAdapterDescriptor`) for target-specific adapters
+- **`./runtime`**: Runtime entry point (placeholder for future functionality)
+
+## Dependencies
+
+- **`@prisma-next/core-control-plane`**: Control plane types (`ControlFamilyDescriptor`, `ControlTargetDescriptor`, `ControlAdapterDescriptor`, `ControlDriverDescriptor`, `ControlExtensionDescriptor`, `ControlDriverInstance`, etc.)
+- **`@prisma-next/sql-contract-emitter`**: SQL target family hook (`sqlTargetFamilyHook`)
+- **`@prisma-next/sql-contract-ts`**: Contract validation (`validateContract`)
+- **`@prisma-next/sql-contract`**: SQL contract types (`SqlContract`, `SqlStorage`)
+- **`@prisma-next/sql-operations`**: SQL operation signature types (`SqlOperationSignature`)
+
+**Dependents:**
+- CLI configuration files import this package to register the SQL family
+

package/dist/exports/control-adapter.d.ts

@@ -0,0 +1,44 @@
+import { ControlAdapterInstance, ControlDriverInstance } from '@prisma-next/core-control-plane/types';
+import { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+
+/**
+ * SQL control adapter interface for control-plane operations.
+ * Implemented by target-specific adapters (e.g., Postgres, MySQL).
+ *
+ * @template TTarget - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface SqlControlAdapter<TTarget extends string = string> extends ControlAdapterInstance<'sql', TTarget> {
+    /**
+     * The target ID this adapter implements.
+     * Used for type tracking and runtime validation.
+     * @deprecated Use targetId from ControlAdapterInstance instead
+     */
+    readonly target: TTarget;
+    /**
+     * Introspects a database schema and returns a raw SqlSchemaIR.
+     *
+     * This is a pure schema discovery operation that queries the database catalog
+     * and returns the schema structure without type mapping or contract enrichment.
+     * Type mapping and enrichment are handled separately by enrichment helpers.
+     *
+     * @param driver - ControlDriverInstance instance for executing queries (target-specific)
+     * @param contractIR - Optional contract IR for contract-guided introspection (filtering, optimization)
+     * @param schema - Schema name to introspect (defaults to 'public')
+     * @returns Promise resolving to SqlSchemaIR representing the live database schema
+     */
+    introspect(driver: ControlDriverInstance<TTarget>, contractIR?: unknown, schema?: string): Promise<SqlSchemaIR>;
+}
+/**
+ * SQL control adapter descriptor interface.
+ * Provides a factory method to create control adapter instances.
+ *
+ * @template TTarget - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface SqlControlAdapterDescriptor<TTarget extends string = string> {
+    /**
+     * Creates a SQL control adapter instance for control-plane operations.
+     */
+    create(): SqlControlAdapter<TTarget>;
+}
+
+export type { SqlControlAdapter, SqlControlAdapterDescriptor };

package/dist/exports/control-adapter.js

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

package/dist/exports/control-adapter.js.map

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

package/dist/exports/control.d.ts

@@ -0,0 +1,148 @@
+import * as _prisma_next_sql_contract_types from '@prisma-next/sql-contract/types';
+import * as _prisma_next_contract from '@prisma-next/contract';
+import * as _prisma_next_contract_ir from '@prisma-next/contract/ir';
+import { ContractIR } from '@prisma-next/contract/ir';
+import { ExtensionPackManifest } from '@prisma-next/contract/pack-manifest-types';
+import { ControlFamilyInstance, ControlDriverInstance, VerifyDatabaseResult, VerifyDatabaseSchemaResult, SignDatabaseResult, EmitContractResult, ControlFamilyDescriptor, ControlTargetDescriptor, ControlAdapterDescriptor, ControlDriverDescriptor, ControlExtensionDescriptor } from '@prisma-next/core-control-plane/types';
+import { TypesImportSpec } from '@prisma-next/contract/types';
+import { CoreSchemaView } from '@prisma-next/core-control-plane/schema-view';
+import { O as OperationRegistry } from './index-Bi3Sr19r.js';
+import { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+
+/**
+ * Type metadata for SQL storage types.
+ * Maps contract storage type IDs to native database types.
+ */
+interface SqlTypeMetadata {
+    readonly typeId: string;
+    readonly familyId: 'sql';
+    readonly targetId: string;
+    readonly nativeType?: string;
+}
+/**
+ * Registry mapping type IDs to their metadata.
+ * Keyed by contract storage type ID (e.g., 'pg/int4@1').
+ */
+type SqlTypeMetadataRegistry = Map<string, SqlTypeMetadata>;
+/**
+ * State fields for SQL family instance that hold assembly data.
+ */
+interface SqlFamilyInstanceState {
+    readonly operationRegistry: OperationRegistry;
+    readonly codecTypeImports: ReadonlyArray<TypesImportSpec>;
+    readonly operationTypeImports: ReadonlyArray<TypesImportSpec>;
+    readonly extensionIds: ReadonlyArray<string>;
+    readonly typeMetadataRegistry: SqlTypeMetadataRegistry;
+}
+/**
+ * SQL control family instance interface.
+ * Extends ControlFamilyInstance with SQL-specific domain actions.
+ */
+interface SqlControlFamilyInstance extends ControlFamilyInstance<'sql'>, SqlFamilyInstanceState {
+    /**
+     * Validates a contract JSON and returns a validated ContractIR (without mappings).
+     * Mappings are runtime-only and should not be part of ContractIR.
+     */
+    validateContractIR(contractJson: unknown): unknown;
+    /**
+     * Verifies the database marker against the contract.
+     * Compares target, coreHash, and profileHash.
+     */
+    verify(options: {
+        readonly driver: ControlDriverInstance;
+        readonly contractIR: unknown;
+        readonly expectedTargetId: string;
+        readonly contractPath: string;
+        readonly configPath?: string;
+    }): Promise<VerifyDatabaseResult>;
+    /**
+     * Verifies the database schema against the contract.
+     * Compares contract requirements against live database schema.
+     */
+    schemaVerify(options: {
+        readonly driver: ControlDriverInstance;
+        readonly contractIR: unknown;
+        readonly strict: boolean;
+        readonly contractPath: string;
+        readonly configPath?: string;
+    }): Promise<VerifyDatabaseSchemaResult>;
+    /**
+     * Signs the database with the contract marker.
+     * Writes or updates the contract marker if schema verification passes.
+     * This operation is idempotent - if the marker already matches, no changes are made.
+     */
+    sign(options: {
+        readonly driver: ControlDriverInstance;
+        readonly contractIR: unknown;
+        readonly contractPath: string;
+        readonly configPath?: string;
+    }): Promise<SignDatabaseResult>;
+    /**
+     * Introspects the database schema and returns a family-specific schema IR.
+     *
+     * This is a read-only operation that returns a snapshot of the live database schema.
+     * The method is family-owned and delegates to target/adapter-specific introspectors
+     * to perform the actual schema introspection.
+     *
+     * @param options - Introspection options
+     * @param options.driver - Control plane driver for database connection
+     * @param options.contractIR - Optional contract IR for contract-guided introspection.
+     *   When provided, families may use it for filtering, optimization, or validation
+     *   during introspection. The contract IR does not change the meaning of "what exists"
+     *   in the database - it only guides how introspection is performed.
+     * @returns Promise resolving to the family-specific Schema IR (e.g., `SqlSchemaIR` for SQL).
+     *   The IR represents the complete schema snapshot at the time of introspection.
+     */
+    introspect(options: {
+        readonly driver: ControlDriverInstance;
+        readonly contractIR?: unknown;
+    }): Promise<SqlSchemaIR>;
+    /**
+     * Projects a SQL Schema IR into a core schema view for CLI visualization.
+     * Converts SqlSchemaIR (tables, columns, indexes, extensions) into a tree structure.
+     */
+    toSchemaView(schema: SqlSchemaIR): CoreSchemaView;
+    /**
+     * Emits contract JSON and DTS as strings.
+     * Uses the instance's preassembled state (operation registry, type imports, extension IDs).
+     * Handles stripping mappings and validation internally.
+     */
+    emitContract(options: {
+        readonly contractIR: ContractIR | unknown;
+    }): Promise<EmitContractResult>;
+}
+
+/**
+ * SQL family descriptor implementation.
+ * Provides the SQL family hook and factory method.
+ */
+declare class SqlFamilyDescriptor implements ControlFamilyDescriptor<'sql', SqlControlFamilyInstance> {
+    readonly kind: "family";
+    readonly id = "sql";
+    readonly familyId: "sql";
+    readonly manifest: ExtensionPackManifest;
+    readonly hook: {
+        readonly id: "sql";
+        readonly validateTypes: (ir: _prisma_next_contract_ir.ContractIR, ctx: _prisma_next_contract.ValidationContext) => void;
+        readonly validateStructure: (ir: _prisma_next_contract_ir.ContractIR) => void;
+        readonly generateContractTypes: (ir: _prisma_next_contract_ir.ContractIR, codecTypeImports: ReadonlyArray<_prisma_next_contract.TypesImportSpec>, operationTypeImports: ReadonlyArray<_prisma_next_contract.TypesImportSpec>) => string;
+        readonly generateStorageType: (storage: _prisma_next_sql_contract_types.SqlStorage) => string;
+        readonly generateModelsType: (models: Record<string, _prisma_next_sql_contract_types.ModelDefinition> | undefined, storage: _prisma_next_sql_contract_types.SqlStorage) => string;
+        readonly generateRelationsType: (relations: Record<string, unknown> | undefined) => string;
+        readonly generateMappingsType: (models: Record<string, _prisma_next_sql_contract_types.ModelDefinition> | undefined, storage: _prisma_next_sql_contract_types.SqlStorage, codecTypes: string, operationTypes: string) => string;
+    };
+    create<TTargetId extends string>(options: {
+        readonly target: ControlTargetDescriptor<'sql', TTargetId>;
+        readonly adapter: ControlAdapterDescriptor<'sql', TTargetId>;
+        readonly driver: ControlDriverDescriptor<'sql', TTargetId>;
+        readonly extensions: readonly ControlExtensionDescriptor<'sql', TTargetId>[];
+    }): SqlControlFamilyInstance;
+}
+
+/**
+ * SQL family descriptor for control plane (CLI/config).
+ * Provides the SQL family hook and conversion helpers.
+ */
+declare const _default: SqlFamilyDescriptor;
+
+export { _default as default };