@prisma-next/contract 0.3.0-pr.99.3 → 0.3.0-pr.99.5

package/dist/framework-components-B-XOtXw3.d.mts

@@ -0,0 +1,854 @@
+import { t as ContractIR } from "./ir-B8zNqals.mjs";
+import { OperationRegistry } from "@prisma-next/operations";
+
+//#region src/types.d.ts
+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 extensionPacks: 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 codecId?: string;
+  readonly nativeType?: 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>;
+  /**
+   * Parameterized codec descriptors collected from adapters and extensions.
+   * Map of codecId → descriptor for quick lookup during type generation.
+   */
+  readonly parameterizedCodecs?: Map<string, ParameterizedCodecDescriptor>;
+}
+/**
+ * Context for rendering parameterized types during contract.d.ts generation.
+ * Passed to type renderers so they can reference CodecTypes by name.
+ */
+interface TypeRenderContext {
+  readonly codecTypesName: string;
+}
+/**
+ * A normalized type renderer for parameterized codecs.
+ * This is the interface expected by TargetFamilyHook.generateContractTypes.
+ */
+interface TypeRenderEntry {
+  readonly codecId: string;
+  readonly render: (params: Record<string, unknown>, ctx: TypeRenderContext) => string;
+}
+/**
+ * Additional options for generateContractTypes.
+ */
+interface GenerateContractTypesOptions {
+  /**
+   * Normalized parameterized type renderers, keyed by codecId.
+   * When a column has typeParams and a renderer exists for its codecId,
+   * the renderer is called to produce the TypeScript type expression.
+   */
+  readonly parameterizedRenderers?: Map<string, TypeRenderEntry>;
+  /**
+   * Type imports for parameterized codecs.
+   * These are merged with codec and operation type imports in contract.d.ts.
+   */
+  readonly parameterizedTypeImports?: ReadonlyArray<TypesImportSpec>;
+}
+/**
+ * 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 extension packs.
+   * @param ir - Contract IR to validate
+   * @param ctx - Validation context with operation registry and extension IDs
+   */
+  validateTypes(ir: ContractIR, ctx: ValidationContext): void;
+  /**
+   * Validates family-specific contract structure.
+   * @param ir - Contract IR to validate
+   */
+  validateStructure(ir: ContractIR): void;
+  /**
+   * Generates contract.d.ts file content.
+   * @param ir - Contract IR
+   * @param codecTypeImports - Array of codec type import specs
+   * @param operationTypeImports - Array of operation type import specs
+   * @param options - Additional options including parameterized type renderers
+   * @returns Generated TypeScript type definitions as string
+   */
+  generateContractTypes(ir: ContractIR, codecTypeImports: ReadonlyArray<TypesImportSpec>, operationTypeImports: ReadonlyArray<TypesImportSpec>, options?: GenerateContractTypesOptions): 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>;
+}
+/**
+ * Declarative type renderer that produces a TypeScript type expression.
+ *
+ * Renderers can be:
+ * - A template string with `{{paramName}}` placeholders (e.g., `Vector<{{length}}>`)
+ * - A function that receives typeParams and context and returns a type expression
+ *
+ * **Prefer template strings** for most cases:
+ * - Templates are JSON-serializable (safe for pack-ref metadata)
+ * - Templates can be statically analyzed by tooling
+ *
+ * Function renderers are allowed but have tradeoffs:
+ * - Require runtime execution during emission (the emitter runs code)
+ * - Not JSON-serializable (can't be stored in contract.json)
+ * - The emitted artifacts (contract.json, contract.d.ts) still contain no
+ *   executable code - this constraint applies to outputs, not the emission process
+ */
+type TypeRenderer$1 = string | ((params: Record<string, unknown>, ctx: RenderTypeContext) => string);
+/**
+ * Descriptor for a codec that supports type parameters.
+ *
+ * Parameterized codecs allow columns to carry additional metadata (typeParams)
+ * that affects the generated TypeScript types. For example:
+ * - A vector codec can use `{ length: 1536 }` to generate `Vector<1536>`
+ * - A decimal codec can use `{ precision: 10, scale: 2 }` to generate `Decimal<10, 2>`
+ *
+ * The SQL family emitter uses these descriptors to generate precise types
+ * without hard-coding knowledge of specific codec IDs.
+ *
+ * @example
+ * ```typescript
+ * const vectorCodecDescriptor: ParameterizedCodecDescriptor = {
+ *   codecId: 'pg/vector@1',
+ *   outputTypeRenderer: 'Vector<{{length}}>',
+ *   // Optional: paramsSchema for runtime validation
+ * };
+ * ```
+ */
+interface ParameterizedCodecDescriptor {
+  /** The codec ID this descriptor applies to (e.g., 'pg/vector@1') */
+  readonly codecId: string;
+  /**
+   * Renderer for the output (read) type.
+   * Can be a template string or function.
+   *
+   * This is the primary renderer used by SQL emission to generate
+   * model field types in contract.d.ts.
+   */
+  readonly outputTypeRenderer: TypeRenderer$1;
+  /**
+   * Optional renderer for the input (write) type.
+   * If not provided, outputTypeRenderer is used for both.
+   *
+   * **Reserved for future use**: Currently, SQL emission only uses
+   * outputTypeRenderer. This field is defined for future support of
+   * asymmetric codecs where input and output types differ (e.g., a
+   * codec that accepts `string | number` but always returns `number`).
+   */
+  readonly inputTypeRenderer?: TypeRenderer$1;
+  /**
+   * Optional import spec for types used by this codec's renderers.
+   * The emitter will add this import to contract.d.ts.
+   */
+  readonly typesImport?: TypesImportSpec;
+}
+//#endregion
+//#region src/framework-components.d.ts
+/**
+ * Context passed to type renderers during contract.d.ts generation.
+ */
+interface RenderTypeContext {
+  /** The name of the CodecTypes type alias (typically 'CodecTypes') */
+  readonly codecTypesName: string;
+}
+/**
+ * A template-based type renderer (structured form).
+ * Uses mustache-style placeholders (e.g., `Vector<{{length}}>`) that are
+ * replaced with typeParams values during rendering.
+ *
+ * @example
+ * ```ts
+ * { kind: 'template', template: 'Vector<{{length}}>' }
+ * // With typeParams { length: 1536 }, renders: 'Vector<1536>'
+ * ```
+ */
+interface TypeRendererTemplate {
+  readonly kind: 'template';
+  /** Template string with `{{key}}` placeholders for typeParams values */
+  readonly template: string;
+}
+/**
+ * A function-based type renderer for full control over type expression generation.
+ *
+ * @example
+ * ```ts
+ * {
+ *   kind: 'function',
+ *   render: (params, ctx) => `Vector<${params.length}>`
+ * }
+ * ```
+ */
+interface TypeRendererFunction {
+  readonly kind: 'function';
+  /** Render function that produces a TypeScript type expression */
+  readonly render: (params: Record<string, unknown>, ctx: RenderTypeContext) => string;
+}
+/**
+ * A raw template string type renderer (convenience form).
+ * Shorthand for TypeRendererTemplate - just the template string without wrapper.
+ *
+ * @example
+ * ```ts
+ * 'Vector<{{length}}>'
+ * // Equivalent to: { kind: 'template', template: 'Vector<{{length}}>' }
+ * ```
+ */
+type TypeRendererString = string;
+/**
+ * A raw function type renderer (convenience form).
+ * Shorthand for TypeRendererFunction - just the function without wrapper.
+ *
+ * @example
+ * ```ts
+ * (params, ctx) => `Vector<${params.length}>`
+ * // Equivalent to: { kind: 'function', render: ... }
+ * ```
+ */
+type TypeRendererRawFunction = (params: Record<string, unknown>, ctx: RenderTypeContext) => string;
+/**
+ * Union of type renderer formats.
+ *
+ * Supports both structured forms (with `kind` discriminator) and convenience forms:
+ * - `string` - Template string with `{{key}}` placeholders (manifest-safe, JSON-serializable)
+ * - `function` - Render function for full control (requires runtime execution)
+ * - `{ kind: 'template', template: string }` - Structured template form
+ * - `{ kind: 'function', render: fn }` - Structured function form
+ *
+ * Templates are normalized to functions during pack assembly.
+ * **Prefer template strings** for most cases - they are JSON-serializable.
+ */
+type TypeRenderer = TypeRendererString | TypeRendererRawFunction | TypeRendererTemplate | TypeRendererFunction;
+/**
+ * Normalized type renderer - always a function after assembly.
+ * This is the form received by the emitter.
+ */
+interface NormalizedTypeRenderer {
+  readonly codecId: string;
+  readonly render: (params: Record<string, unknown>, ctx: RenderTypeContext) => string;
+}
+/**
+ * Interpolates a template string with params values.
+ * Used internally by normalizeRenderer to compile templates to functions.
+ *
+ * @throws Error if a placeholder key is not found in params (except 'CodecTypes')
+ */
+declare function interpolateTypeTemplate(template: string, params: Record<string, unknown>, ctx: RenderTypeContext): string;
+/**
+ * Normalizes a TypeRenderer to function form.
+ * Called during pack assembly, not at emission time.
+ *
+ * Handles all TypeRenderer forms:
+ * - Raw string template: `'Vector<{{length}}>'`
+ * - Raw function: `(params, ctx) => ...`
+ * - Structured template: `{ kind: 'template', template: '...' }`
+ * - Structured function: `{ kind: 'function', render: fn }`
+ */
+declare function normalizeRenderer(codecId: string, renderer: TypeRenderer): NormalizedTypeRenderer;
+/**
+ * Declarative fields that describe component metadata.
+ * These fields are owned directly by descriptors (not nested under a manifest).
+ */
+interface ComponentMetadata {
+  /** Component version (semver) */
+  readonly version: string;
+  /**
+   * Capabilities this component provides.
+   *
+   * For adapters, capabilities must be declared on the adapter descriptor (so they are emitted into
+   * the contract) and also exposed in runtime adapter code (e.g. `adapter.profile.capabilities`);
+   * keep these declarations in sync. Targets are identifiers/descriptors and typically do not
+   * declare capabilities.
+   */
+  readonly capabilities?: Record<string, unknown>;
+  /** Type imports for contract.d.ts generation */
+  readonly types?: {
+    readonly codecTypes?: {
+      /**
+       * Base codec types import spec.
+       * Optional: adapters typically provide this, extensions usually don't.
+       */
+      readonly import?: TypesImportSpec;
+      /**
+       * Optional renderers for parameterized codecs owned by this component.
+       * Key is codecId (e.g., 'pg/vector@1'), value is the type renderer.
+       *
+       * Templates are normalized to functions during pack assembly.
+       * Duplicate codecId across descriptors is a hard error.
+       */
+      readonly parameterized?: Record<string, TypeRenderer>;
+      /**
+       * Optional type imports for parameterized codecs.
+       * These imports are added to contract.d.ts when parameterized renderers
+       * reference types from external packages.
+       */
+      readonly parameterizedImports?: ReadonlyArray<TypesImportSpec>;
+    };
+    readonly operationTypes?: {
+      readonly import: TypesImportSpec;
+    };
+    readonly storage?: ReadonlyArray<{
+      readonly typeId: string;
+      readonly familyId: string;
+      readonly targetId: string;
+      readonly nativeType?: string;
+    }>;
+  };
+  /** Operation manifests for building operation registries */
+  readonly operations?: ReadonlyArray<OperationManifest>;
+}
+/**
+ * Base descriptor for any framework component.
+ *
+ * All component descriptors share these fundamental properties that identify
+ * the component and provide its metadata. This interface is extended by
+ * specific descriptor types (FamilyDescriptor, TargetDescriptor, etc.).
+ *
+ * @template Kind - Discriminator literal identifying the component type.
+ *   Built-in kinds are 'family', 'target', 'adapter', 'driver', 'extension',
+ *   but the type accepts any string to allow ecosystem extensions.
+ *
+ * @example
+ * ```ts
+ * // All descriptors have these properties
+ * descriptor.kind     // The Kind type parameter (e.g., 'family', 'target', or custom kinds)
+ * descriptor.id       // Unique string identifier (e.g., 'sql', 'postgres')
+ * descriptor.version  // Component version (semver)
+ * ```
+ */
+interface ComponentDescriptor<Kind extends string> extends ComponentMetadata {
+  /** Discriminator identifying the component type */
+  readonly kind: Kind;
+  /** Unique identifier for this component (e.g., 'sql', 'postgres', 'pgvector') */
+  readonly id: string;
+}
+interface ContractComponentRequirementsCheckInput {
+  readonly contract: {
+    readonly target: string;
+    readonly targetFamily?: string | undefined;
+    readonly extensionPacks?: Record<string, unknown> | undefined;
+  };
+  readonly expectedTargetFamily?: string | undefined;
+  readonly expectedTargetId?: string | undefined;
+  readonly providedComponentIds: Iterable<string>;
+}
+interface ContractComponentRequirementsCheckResult {
+  readonly familyMismatch?: {
+    readonly expected: string;
+    readonly actual: string;
+  } | undefined;
+  readonly targetMismatch?: {
+    readonly expected: string;
+    readonly actual: string;
+  } | undefined;
+  readonly missingExtensionPackIds: readonly string[];
+}
+declare function checkContractComponentRequirements(input: ContractComponentRequirementsCheckInput): ContractComponentRequirementsCheckResult;
+/**
+ * Descriptor for a family component.
+ *
+ * A "family" represents a category of data sources with shared semantics
+ * (e.g., SQL databases, document stores). Families define:
+ * - Query semantics and operations (SELECT, INSERT, find, aggregate, etc.)
+ * - Contract structure (tables vs collections, columns vs fields)
+ * - Type system and codecs
+ *
+ * Families are the top-level grouping. Each family contains multiple targets
+ * (e.g., SQL family contains Postgres, MySQL, SQLite targets).
+ *
+ * Extended by plane-specific descriptors:
+ * - `ControlFamilyDescriptor` - adds `hook` for CLI/tooling operations
+ * - `RuntimeFamilyDescriptor` - adds runtime-specific factory methods
+ *
+ * @template TFamilyId - Literal type for the family identifier (e.g., 'sql', 'document')
+ *
+ * @example
+ * ```ts
+ * import sql from '@prisma-next/family-sql/control';
+ *
+ * sql.kind     // 'family'
+ * sql.familyId // 'sql'
+ * sql.id       // 'sql'
+ * ```
+ */
+interface FamilyDescriptor<TFamilyId extends string> extends ComponentDescriptor<'family'> {
+  /** The family identifier (e.g., 'sql', 'document') */
+  readonly familyId: TFamilyId;
+}
+/**
+ * Descriptor for a target component.
+ *
+ * A "target" represents a specific database or data store within a family
+ * (e.g., Postgres, MySQL, MongoDB). Targets define:
+ * - Native type mappings (e.g., Postgres int4 → TypeScript number)
+ * - Target-specific capabilities (e.g., RETURNING, LATERAL joins)
+ *
+ * Targets are bound to a family and provide the target-specific implementation
+ * details that adapters and drivers use.
+ *
+ * Extended by plane-specific descriptors:
+ * - `ControlTargetDescriptor` - adds optional `migrations` capability
+ * - `RuntimeTargetDescriptor` - adds runtime factory method
+ *
+ * @template TFamilyId - Literal type for the family identifier
+ * @template TTargetId - Literal type for the target identifier (e.g., 'postgres', 'mysql')
+ *
+ * @example
+ * ```ts
+ * import postgres from '@prisma-next/target-postgres/control';
+ *
+ * postgres.kind     // 'target'
+ * postgres.familyId // 'sql'
+ * postgres.targetId // 'postgres'
+ * ```
+ */
+interface TargetDescriptor<TFamilyId extends string, TTargetId extends string> extends ComponentDescriptor<'target'> {
+  /** The family this target belongs to */
+  readonly familyId: TFamilyId;
+  /** The target identifier (e.g., 'postgres', 'mysql', 'mongodb') */
+  readonly targetId: TTargetId;
+}
+/**
+ * Base shape for any pack reference.
+ * Pack refs are pure JSON-friendly objects safe to import in authoring flows.
+ */
+interface PackRefBase<Kind extends string, TFamilyId extends string> extends ComponentMetadata {
+  readonly kind: Kind;
+  readonly id: string;
+  readonly familyId: TFamilyId;
+  readonly targetId?: string;
+}
+type TargetPackRef<TFamilyId extends string = string, TTargetId extends string = string> = PackRefBase<'target', TFamilyId> & {
+  readonly targetId: TTargetId;
+};
+type AdapterPackRef<TFamilyId extends string = string, TTargetId extends string = string> = PackRefBase<'adapter', TFamilyId> & {
+  readonly targetId: TTargetId;
+};
+type ExtensionPackRef<TFamilyId extends string = string, TTargetId extends string = string> = PackRefBase<'extension', TFamilyId> & {
+  readonly targetId: TTargetId;
+};
+type DriverPackRef<TFamilyId extends string = string, TTargetId extends string = string> = PackRefBase<'driver', TFamilyId> & {
+  readonly targetId: TTargetId;
+};
+/**
+ * Descriptor for an adapter component.
+ *
+ * An "adapter" provides the protocol and dialect implementation for a target.
+ * Adapters handle:
+ * - SQL/query generation (lowering AST to target-specific syntax)
+ * - Codec registration (encoding/decoding between JS and wire types)
+ * - Type mappings and coercions
+ *
+ * Adapters are bound to a specific family+target combination and work with
+ * any compatible driver for that target.
+ *
+ * Extended by plane-specific descriptors:
+ * - `ControlAdapterDescriptor` - control-plane factory
+ * - `RuntimeAdapterDescriptor` - runtime factory
+ *
+ * @template TFamilyId - Literal type for the family identifier
+ * @template TTargetId - Literal type for the target identifier
+ *
+ * @example
+ * ```ts
+ * import postgresAdapter from '@prisma-next/adapter-postgres/control';
+ *
+ * postgresAdapter.kind     // 'adapter'
+ * postgresAdapter.familyId // 'sql'
+ * postgresAdapter.targetId // 'postgres'
+ * ```
+ */
+interface AdapterDescriptor<TFamilyId extends string, TTargetId extends string> extends ComponentDescriptor<'adapter'> {
+  /** The family this adapter belongs to */
+  readonly familyId: TFamilyId;
+  /** The target this adapter is designed for */
+  readonly targetId: TTargetId;
+}
+/**
+ * Descriptor for a driver component.
+ *
+ * A "driver" provides the connection and execution layer for a target.
+ * Drivers handle:
+ * - Connection management (pooling, timeouts, retries)
+ * - Query execution (sending SQL/commands, receiving results)
+ * - Transaction management
+ * - Wire protocol communication
+ *
+ * Drivers are bound to a specific family+target and work with any compatible
+ * adapter. Multiple drivers can exist for the same target (e.g., node-postgres
+ * vs postgres.js for Postgres).
+ *
+ * Extended by plane-specific descriptors:
+ * - `ControlDriverDescriptor` - creates driver from connection URL
+ * - `RuntimeDriverDescriptor` - creates driver with runtime options
+ *
+ * @template TFamilyId - Literal type for the family identifier
+ * @template TTargetId - Literal type for the target identifier
+ *
+ * @example
+ * ```ts
+ * import postgresDriver from '@prisma-next/driver-postgres/control';
+ *
+ * postgresDriver.kind     // 'driver'
+ * postgresDriver.familyId // 'sql'
+ * postgresDriver.targetId // 'postgres'
+ * ```
+ */
+interface DriverDescriptor<TFamilyId extends string, TTargetId extends string> extends ComponentDescriptor<'driver'> {
+  /** The family this driver belongs to */
+  readonly familyId: TFamilyId;
+  /** The target this driver connects to */
+  readonly targetId: TTargetId;
+}
+/**
+ * Descriptor for an extension component.
+ *
+ * An "extension" adds optional capabilities to a target. Extensions can provide:
+ * - Additional operations (e.g., vector similarity search with pgvector)
+ * - Custom types and codecs (e.g., vector type)
+ * - Extended query capabilities
+ *
+ * Extensions are bound to a specific family+target and are registered in the
+ * config alongside the core components. Multiple extensions can be used together.
+ *
+ * Extended by plane-specific descriptors:
+ * - `ControlExtensionDescriptor` - control-plane extension factory
+ * - `RuntimeExtensionDescriptor` - runtime extension factory
+ *
+ * @template TFamilyId - Literal type for the family identifier
+ * @template TTargetId - Literal type for the target identifier
+ *
+ * @example
+ * ```ts
+ * import pgvector from '@prisma-next/extension-pgvector/control';
+ *
+ * pgvector.kind     // 'extension'
+ * pgvector.familyId // 'sql'
+ * pgvector.targetId // 'postgres'
+ * ```
+ */
+interface ExtensionDescriptor<TFamilyId extends string, TTargetId extends string> extends ComponentDescriptor<'extension'> {
+  /** The family this extension belongs to */
+  readonly familyId: TFamilyId;
+  /** The target this extension is designed for */
+  readonly targetId: TTargetId;
+}
+/**
+ * Union type for target-bound component descriptors.
+ *
+ * Target-bound components are those that must be compatible with a specific
+ * family+target combination. This includes targets, adapters, drivers, and
+ * extensions. Families are not target-bound.
+ *
+ * This type is used in migration and verification interfaces to enforce
+ * type-level compatibility between components.
+ *
+ * @template TFamilyId - Literal type for the family identifier
+ * @template TTargetId - Literal type for the target identifier
+ *
+ * @example
+ * ```ts
+ * // All these components must have matching familyId and targetId
+ * const components: TargetBoundComponentDescriptor<'sql', 'postgres'>[] = [
+ *   postgresTarget,
+ *   postgresAdapter,
+ *   postgresDriver,
+ *   pgvectorExtension,
+ * ];
+ * ```
+ */
+type TargetBoundComponentDescriptor<TFamilyId extends string, TTargetId extends string> = TargetDescriptor<TFamilyId, TTargetId> | AdapterDescriptor<TFamilyId, TTargetId> | DriverDescriptor<TFamilyId, TTargetId> | ExtensionDescriptor<TFamilyId, TTargetId>;
+/**
+ * Base interface for family instances.
+ *
+ * A family instance is created by a family descriptor's `create()` method.
+ * This base interface carries only the identity; plane-specific interfaces
+ * add domain actions (e.g., `emitContract`, `verify` on ControlFamilyInstance).
+ *
+ * @template TFamilyId - Literal type for the family identifier (e.g., 'sql', 'document')
+ *
+ * @example
+ * ```ts
+ * const instance = sql.create({ target, adapter, driver, extensions });
+ * instance.familyId // 'sql'
+ * ```
+ */
+interface FamilyInstance<TFamilyId extends string> {
+  /** The family identifier (e.g., 'sql', 'document') */
+  readonly familyId: TFamilyId;
+}
+/**
+ * Base interface for target instances.
+ *
+ * A target instance is created by a target descriptor's `create()` method.
+ * This base interface carries only the identity; plane-specific interfaces
+ * add target-specific behavior.
+ *
+ * @template TFamilyId - Literal type for the family identifier
+ * @template TTargetId - Literal type for the target identifier (e.g., 'postgres', 'mysql')
+ *
+ * @example
+ * ```ts
+ * const instance = postgres.create();
+ * instance.familyId // 'sql'
+ * instance.targetId // 'postgres'
+ * ```
+ */
+interface TargetInstance<TFamilyId extends string, TTargetId extends string> {
+  /** The family this target belongs to */
+  readonly familyId: TFamilyId;
+  /** The target identifier (e.g., 'postgres', 'mysql', 'mongodb') */
+  readonly targetId: TTargetId;
+}
+/**
+ * Base interface for adapter instances.
+ *
+ * An adapter instance is created by an adapter descriptor's `create()` method.
+ * This base interface carries only the identity; plane-specific interfaces
+ * add adapter-specific behavior (e.g., codec registration, query lowering).
+ *
+ * @template TFamilyId - Literal type for the family identifier
+ * @template TTargetId - Literal type for the target identifier
+ *
+ * @example
+ * ```ts
+ * const instance = postgresAdapter.create();
+ * instance.familyId // 'sql'
+ * instance.targetId // 'postgres'
+ * ```
+ */
+interface AdapterInstance<TFamilyId extends string, TTargetId extends string> {
+  /** The family this adapter belongs to */
+  readonly familyId: TFamilyId;
+  /** The target this adapter is designed for */
+  readonly targetId: TTargetId;
+}
+/**
+ * Base interface for driver instances.
+ *
+ * A driver instance is created by a driver descriptor's `create()` method.
+ * This base interface carries only the identity; plane-specific interfaces
+ * add driver-specific behavior (e.g., `query`, `close` on ControlDriverInstance).
+ *
+ * @template TFamilyId - Literal type for the family identifier
+ * @template TTargetId - Literal type for the target identifier
+ *
+ * @example
+ * ```ts
+ * const instance = postgresDriver.create({ databaseUrl });
+ * instance.familyId // 'sql'
+ * instance.targetId // 'postgres'
+ * ```
+ */
+interface DriverInstance<TFamilyId extends string, TTargetId extends string> {
+  /** The family this driver belongs to */
+  readonly familyId: TFamilyId;
+  /** The target this driver connects to */
+  readonly targetId: TTargetId;
+}
+/**
+ * Base interface for extension instances.
+ *
+ * An extension instance is created by an extension descriptor's `create()` method.
+ * This base interface carries only the identity; plane-specific interfaces
+ * add extension-specific behavior.
+ *
+ * @template TFamilyId - Literal type for the family identifier
+ * @template TTargetId - Literal type for the target identifier
+ *
+ * @example
+ * ```ts
+ * const instance = pgvector.create();
+ * instance.familyId // 'sql'
+ * instance.targetId // 'postgres'
+ * ```
+ */
+interface ExtensionInstance<TFamilyId extends string, TTargetId extends string> {
+  /** The family this extension belongs to */
+  readonly familyId: TFamilyId;
+  /** The target this extension is designed for */
+  readonly targetId: TTargetId;
+}
+//#endregion
+export { TypesImportSpec as $, ContractBase as A, LoweringSpecManifest as B, TypeRenderer as C, interpolateTypeTemplate as D, checkContractComponentRequirements as E, DocumentStorage as F, PlanRefs as G, ParamDescriptor as H, ExecutionPlan as I, Source as J, ResultType as K, Expr as L, DocCollection as M, DocIndex as N, normalizeRenderer as O, DocumentContract as P, TypeRenderer$1 as Q, FieldType as R, TargetPackRef as S, TypeRendererTemplate as T, ParameterizedCodecDescriptor as U, OperationManifest as V, PlanMeta as W, TypeRenderContext as X, TargetFamilyHook as Y, TypeRenderEntry as Z, PackRefBase as _, ComponentMetadata as a, TargetDescriptor as b, DriverDescriptor as c, ExtensionDescriptor as d, ValidationContext as et, ExtensionInstance as f, NormalizedTypeRenderer as g, FamilyInstance as h, ComponentDescriptor as i, ContractMarkerRecord as j, ArgSpecManifest as k, DriverInstance as l, FamilyDescriptor as m, AdapterInstance as n, ContractComponentRequirementsCheckInput as o, ExtensionPackRef as p, ReturnSpecManifest as q, AdapterPackRef as r, ContractComponentRequirementsCheckResult as s, AdapterDescriptor as t, isDocumentContract as tt, DriverPackRef as u, RenderTypeContext as v, TypeRendererFunction as w, TargetInstance as x, TargetBoundComponentDescriptor as y, GenerateContractTypesOptions as z };
+//# sourceMappingURL=framework-components-B-XOtXw3.d.mts.map